185 lines
8.0 KiB
Markdown
185 lines
8.0 KiB
Markdown
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>
|