NAME

reggae — REGister Globaly Access Everywhere is a package which helps in common DevOps tasks

SYNOPSIS

DESCRIPTION

Reggae is an open source package which relays on base FreeBSD and/or CBSD to provide lower level management for jails and virtual machines.

If you have ever used Vagrant or Docker Compose, Reggae is best described as an alternative to those. It enables you easy development inside jail while code editing is done on the host. It makes transition from development to production easier by using provisioners. It makes host clean of all requirements of development and puts them inside jail which is easily stopped, started, provisioned, and destroyed.

To initialize Reggae, first edit /usr/local/etc/reggae.conf and add:

It will set directory to be shared with virtual machines, like directory containing your projects. If you don't need such a directory, you can set it to /var/empty.

If you want to run Reggae with base jails, no need to do any other edits, but if you'd like to use CBSD as the backend, you need to add

run the following as root:

PF is initialized only if /etc/pf.conf doesn't exist already. In those cases PF services should be restarted.

Through config file in /usr/local/etc/reggae.conf you can change values for anything Reggae is using. Ater reggae network-init, you'll get jail containing DHCP and DNS. They are used to lease IPs to jails and virtual machines and to register all resources in DNS so that you can use FQDN instead of IP addresses. This jail IP is used in /etc/resolvconf.conf if host has dynamic IP on egress, so that changes of network parameters are passed to the appropriate jail. Also, host will use DNS jail IP in /etc/resolv.conf. In short, it enables you to not remember jail IPs when you have to use them, but use <jail name>.<domain> to reference them.

PROJECT

A project consists of:

• Makefile - configured for use with project

One project can contain many services, and that's going to be shown in the generated Makefile. The SERVICES variable in it will be commented but populated with example services. All services when downloaded will be in services/<service> directory. You can use preexisting services if you define USE = <service>. For example, you can write the following:

This project will set Wordpress in a jail.

You can run make <target> on the project:

• destroy
• devel
• fetch
• init
• login service=<service>
• provision
• setup
• up

Special note for the devel target: your repo must have bin/devel.sh which will be run on the host. All project targets can be suffixed with service=<service> but in the above list only those which require a service are explicitely mentioned. If the service is passed as an argument, the target will be executed only on that service/jail.

ANSIBLE

A service with ansible provisioner consists of:

• Makefile - configured for use with Ansible
• playbook - containing group_vars, inventory and roles directories as placeholders for files generated on the fly, but can be used to configure your playbook
• requirements.yml - list of requirements, with only one initially. All requirements from this file are downloaded from Ansible Galaxy templates/site.yml.tpl - this file should be edited to add/remove roles, playbooks, etc.

When ran with this configuration, reggae will first check if ansible executable is available on the host, and if it isn't, it will run pkg install ansible. If you use Python's virtual environments, for example, you can avoid having ansible available to everyone on the system.

CHEF

A service with chef provisioner consists of:

• Makefile - configured for use with chef
• playbook - containing cookbooks/core/recipes/default.rb dummy script

When ran with this configuration, reggae will first check if chef executable is available, and if it isn't, it will run pkg install -y chef inside jail. Then it will mount playbook directory on /root/chef inside jail. To do actual provisioning, Reggae uses chef-client --local-mode.

PUPPET

A service with puppet provisioner consists of:

• Makefile - configured for use with puppet
• playbook - containing cookbooks/core/recipes/default.rb dummy script

When ran with this configuration, reggae will first check if puppet executable is available inside jail, and if it isn't, it will install it from packages. Then it will mount playbook directory on /usr/local/etc/puppet/manifests inside jail. To do actual provisioning, Reggae uses puppet apply.

SALT STACK

A service with salt provisioner consists of:

• Makefile - configured for use with salt
• playbook - containing top.sls and core.sls playbooks

When ran with this configuration, reggae will first check if salt executable is available, and if it isn't, it will run pkg install -y py36-salt inside jail. Then it will mount playbook directory on /usr/local/etc/salt/states inside jail. To do actual provisioning, Reggae uses salt-call --local state.apply.

SHELL

A service with shell provisioner consists of:

• Makefile - configured for use with shell
• playbook - containing dummy provision.sh to start with

When ran with this configuration, reggae will first mount playbook directory on /root/shell inside jail. To do actual provisioning, Reggae will run /root/shell/provision.sh.

EXAMPLES

Quickest way to get basic project is:

Quickest way to get basic service provisioned with Ansible is:

You can have multiple provisioners, and the order they are declared on the command line is the order they will be executed in.

SEE ALSO

jail(8) bhyve(8)

BUGS

Report bugs to https://github.com/cbsd/reggae/issues.

AUTHORS

Goran Mekić <meka@tilda.center>