gocage/README.md

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:  
<pre><code>
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           |                |  
+-----+----------+---------+-------------+----------------+  
</code></pre>

See [cmd/struct.go](https://git.nosd.in/yo/gocage/src/branch/master/cmd/struct.go) for field names.


Filter jails  
----------

### By name
Just add name on gocage list command :  
<pre><code>
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    |
+-----+---------+-----------------+-----------------------+---------+
</pre></code>

### By field value
You can filter jails with -f option, followed by key=value. Suppose you want to see only active at boot jails:  
<pre><code>
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           |                |
+-----+----------+---------+-------------+----------------+
</pre></code>

Now, only active at boot and running :  
<pre><code>
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           |
+-----+----------+---------+-------------+
</pre></code>

Sort jails  
----------
Use -s switch followed by sort criteria. Criteria is a field name, prefixed with + or - for sort order (increase/decrease):  
<pre><code>
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           |
+-----+----------+---------+-------------+
</pre></code>

You can use up to 3 criteria, delimited with comma.  
As an example, you want to list boot priorities of automatically starting jails:  
<pre><code>
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    |
+-----+--------------+-----------------------+-----------------+-------------+---------+
</pre></code>


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 :
<pre><code>
datastore:
  - /iocage
  - /fastiocage
</pre></code>

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

### List datastores
<pre><code>
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    |
+------------+-------------+------------+-----------+----------+------------+
</pre></code>

#### Filter datastores  
As with jails and snapshots, you can filter by name:  
<pre><code>
gocage datastore list iocage
+============+=============+============+===========+==========+============+
| Name       | Mountpoint  | ZFSDataset | Available | Used     | Referenced |
+============+=============+============+===========+==========+============+
| iocage     | /iocage     | hdd/iocage | 1.6 TB    | 414.9 GB | 27.5 KB    |
+------------+-------------+------------+-----------+----------+------------+
</pre></code>

#### Sort datastores  
You can sort datastores:  
<pre><code>
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    |
+------------+-------------+------------+-----------+----------+------------+
</pre></code>

See [cmd/struct.go](https://git.nosd.in/yo/gocage/src/branch/master/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.  

<pre><code>
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
</pre></code>