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.  

At present time, it list and stops jails.  

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`