GoCage

Jail management tool for FreeBSD, written in Go.
Support iocage jails, so they can coexist.
Gocage is meant to be a complete jail management tool with network, snapshots, jail cloning support and a web interface. This is the hypothetic future.
Gocage can handle multiple datastores, so you can have jails on HDD storage and jails on SSD storage.

List jails

Nothing fancy, just use
gocage list

Specify fields to display

Use -o to specify which fields you want to display:

gocage list -o JID,Name,Running,Config.Boot,Config.Comment  
+=====+==========+=========+=============+================+  
| JID | Name     | Running | Config.Boot | Config.Comment |  
+=====+==========+=========+=============+================+  
| 183 | test     | true    | 1           | none           |  
+-----+----------+---------+-------------+----------------+  
| 29  | srv-irc  | true    | 1           |                |  
+-----+----------+---------+-------------+----------------+  
|     | srv-web  | false   | 0           |                |  
+-----+----------+---------+-------------+----------------+  
| 22  | srv-dns1 | true    | 1           |                |  
+-----+----------+---------+-------------+----------------+  

See cmd/struct.go for field names.

Filter jails

By name

Just add name on gocage list command :

gocage list srv-bdd srv-web
+=====+=========+=================+=======================+=========+
| JID | Name    | Config.Release  | Config.Ip4_addr       | Running |
+=====+=========+=================+=======================+=========+
| 98  | srv-db  | 13.0-RELEASE-p5 | vnet0|192.168.1.56/24 | true    |
+-----+---------+-----------------+-----------------------+---------+
| 41  | srv-web | 13.0-RELEASE-p4 | vnet0|192.168.1.26/24 | true    |
+-----+---------+-----------------+-----------------------+---------+

By field value

You can filter jails with -f option, followed by key=value. Suppose you want to see only active at boot jails:

gocage list -f Config.Boot=1 -o JID,Name,Running,Config.Boot,Config.Comment
+=====+==========+=========+=============+================+
| JID | Name     | Running | Config.Boot | Config.Comment |
+=====+==========+=========+=============+================+
| 183 | test     | true    | 1           | none           |
+-----+----------+---------+-------------+----------------+
| 29  | srv-irc  | true    | 1           |                |
+-----+----------+---------+-------------+----------------+
|     | srv-db   | false   | 1           | none           |
+-----+----------+---------+-------------+----------------+
| 22  | srv-dns1 | true    | 1           |                |
+-----+----------+---------+-------------+----------------+

Now, only active at boot and running :

gocage list -f Config.Boot=1,Running=true -o JID,Name,Running,Config.Boot
+=====+==========+=========+=============+
| JID | Name     | Running | Config.Boot |
+=====+==========+=========+=============+
| 183 | test     | true    | 1           |
+-----+----------+---------+-------------+
| 29  | srv-irc  | true    | 1           |
+-----+----------+---------+-------------+
| 22  | srv-dns1 | true    | 1           |
+-----+----------+---------+-------------+

Sort jails

Use -s switch followed by sort criteria. Criteria is a field name, prefixed with + or - for sort order (increase/decrease):

gocage list -f Config.Boot=1,Running=true -o JID,Name,Running,Config.Boot -s +JID
+=====+==========+=========+=============+
| JID | Name     | Running | Config.Boot |
+=====+==========+=========+=============+
| 22  | srv-dns1 | true    | 1           |
+-----+----------+---------+-------------+
| 29  | bdd-tst  | true    | 1           |
+-----+----------+---------+-------------+
| 183 | test     | true    | 1           |
+-----+----------+---------+-------------+

You can use up to 3 criteria, delimited with comma.
As an example, you want to list boot priorities of automatically starting jails:

gocage list -o JID,Name,Config.Ip4_addr,Config.Priority,Config.Boot,Running -s -Config.Priority,-Config.Boot -f Running=true
+=====+==============+=======================+=================+=============+=========+
| JID | Name         | Config.Ip4_addr       | Config.Priority | Config.Boot | Running |
+=====+==============+=======================+=================+=============+=========+
| 1   | srv-dhcp     | vnet0|192.168.1.2/24  | 99              | 1           | true    |
+-----+--------------+-----------------------+-----------------+-------------+---------+
| 8   | srv-dns      | vnet0|192.168.1.1/24  | 80              | 1           | true    |
+-----+--------------+-----------------------+-----------------+-------------+---------+
| 7   | srv-random   | vnet0|192.168.1.12/24 | 20              | 1           | true    |
+-----+--------------+-----------------------+-----------------+-------------+---------+
| 4   | coincoin     | vnet0|192.168.1.9/24  | 20              | 0           | true    |
+-----+--------------+-----------------------+-----------------+-------------+---------+

Stop jails

gocage stop test

Multi datastore

A datastore is a ZFS dataset mounted. It should be declared in gocage.conf.yml, specifying its ZFS mountpoint :

datastore:
  - /iocage
  - /fastiocage

In gocage commands, datastore name is the mountpoint without its "/" prefix.

List datastores

gocage datastore list 
+============+=============+============+===========+==========+============+
| Name       | Mountpoint  | ZFSDataset | Available | Used     | Referenced |
+============+=============+============+===========+==========+============+
| iocage     | /iocage     | hdd/iocage | 1.6 TB    | 414.9 GB | 27.5 KB    |
+------------+-------------+------------+-----------+----------+------------+
| fastiocage | /fastiocage | ssd/iocage | 1.5 TB    | 65.3 KB  | 34.6 KB    |
+------------+-------------+------------+-----------+----------+------------+

Filter datastores

As with jails and snapshots, you can filter by name:

gocage datastore list iocage
+============+=============+============+===========+==========+============+
| Name       | Mountpoint  | ZFSDataset | Available | Used     | Referenced |
+============+=============+============+===========+==========+============+
| iocage     | /iocage     | hdd/iocage | 1.6 TB    | 414.9 GB | 27.5 KB    |
+------------+-------------+------------+-----------+----------+------------+

Sort datastores

You can sort datastores:

gocage datastore list -s -Available
+============+=============+============+===========+==========+============+
| Name       | Mountpoint  | ZFSDataset | Available | Used     | Referenced |
+============+=============+============+===========+==========+============+
| iocage     | /iocage     | hdd/iocage | 1.6 TB    | 415.0 GB | 27.5 KB    |
+------------+-------------+------------+-----------+----------+------------+
| fastiocage | /fastiocage | ssd/iocage | 1.5 TB    | 65.3 KB  | 34.6 KB    |
+------------+-------------+------------+-----------+----------+------------+

See cmd/struct.go for field names.

Migrating jails

With multi datastore comes the need to migrate a jail between datastores.
Migration can be done with a minimal downtime, using zfs differential send/receive.
Source jail datasets are sent to the destination datastore, jail is stopped and a last differential sync is done before starting jail on new datastore.

gocage migrate -d fastiocage srv-random
Snapshot data/iocage/jails/srv-random: Done
Snapshot data/iocage/jails/srv-random/root: Done
Migrate jail config dataset to fastdata/iocage/jails/srv-random: Done
Migrate jail filesystem dataset to fastdata/iocage/jails/srv-random/root: Done