yo/gocage
1
0
Fork 0
Code Issues Pull Requests Projects Releases 1 Wiki Activity

Update README

Browse Source
This commit is contained in:
yo 2024-09-22 19:35:46 +02:00
parent fb5c4690bf
commit ca1c7bea5f
1 changed files with 17 additions and 33 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

50
README.md
View File

@ -8,8 +8,7 @@ Gocage can handle multiple datastores, so you can have jails on HDD storage and
From v0.33b, due to multi ZFS pool support, gocage is no longer 100% compatible with iocage. From v0.33b, due to multi ZFS pool support, gocage is no longer 100% compatible with iocage.
Zfs datasets now should be specified with the ZFS pool. e.g. : Zfs datasets now should be specified with the ZFS pool. e.g. :
<pre><code> <pre><code>Config.Jail_zfs = 1
Config.Jail_zfs = 1
Config.Jail_zfs_dataset = myzfspool/poudriere Config.Jail_zfs_dataset = myzfspool/poudriere
Config.Jail_zfs_mountpoint = none Config.Jail_zfs_mountpoint = none
</code></pre> </code></pre>
@ -17,13 +16,11 @@ Config.Jail_zfs_mountpoint = none
Create jails Create jails
------------ ------------
You need to specify release, and optional configuration: You need to specify release, and optional configuration:
<pre><code> <pre><code>gocage create jail1 -r 13.2-RELEASE -p "Config.Ip4_addr='vnet0|192.168.1.91/24',Config.Ip6=none,Config.Boot=1"
gocage create jail1 -r 13.2-RELEASE -p "Config.Ip4_addr='vnet0|192.168.1.91/24',Config.Ip6=none,Config.Boot=1"
</code></pre> </code></pre>
Create basejail. A basejail is a jail based on a release: system will be nullfs read-only mounted from the release directory. Main advantage is that release updates will immediately apply to jails based on this release. Another advantage is that jail system is mounted read-only, a plus from a security perspective: Create basejail. A basejail is a jail based on a release: system will be nullfs read-only mounted from the release directory. Main advantage is that release updates will immediately apply to jails based on this release. Another advantage is that jail system is mounted read-only, a plus from a security perspective:
<pre><code> <pre><code>gocage create -b -r 14.0-RELEASE basejail1
gocage create -b -r 14.0-RELEASE basejail1
</code></pre> </code></pre>
@ -34,8 +31,7 @@ List jails
### Specify fields to display ### Specify fields to display
Use -o to specify which fields you want to display: Use -o to specify which fields you want to display:
<pre><code> <pre><code>gocage list -o JID,Name,Running,Config.Boot,Config.Comment
gocage list -o JID,Name,Running,Config.Boot,Config.Comment
+=====+==========+=========+=============+================+ +=====+==========+=========+=============+================+
| JID | Name | Running | Config.Boot | Config.Comment | | JID | Name | Running | Config.Boot | Config.Comment |
+=====+==========+=========+=============+================+ +=====+==========+=========+=============+================+
@ -57,8 +53,7 @@ Filter jails
### By name ### By name
Just add name on gocage list command : Just add name on gocage list command :
<pre><code> <pre><code>gocage list srv-bdd srv-web
gocage list srv-bdd srv-web
+=====+=========+=================+=======================+=========+ +=====+=========+=================+=======================+=========+
| JID | Name | Config.Release | Config.Ip4_addr | Running | | JID | Name | Config.Release | Config.Ip4_addr | Running |
+=====+=========+=================+=======================+=========+ +=====+=========+=================+=======================+=========+
@ -70,8 +65,7 @@ gocage list srv-bdd srv-web
### By field value ### By field value
You can filter jails with -f option, followed by key=value. Suppose you want to see only active at boot jails: You can filter jails with -f option, followed by key=value. Suppose you want to see only active at boot jails:
<pre><code> <pre><code>gocage list -f Config.Boot=1 -o JID,Name,Running,Config.Boot,Config.Comment
gocage list -f Config.Boot=1 -o JID,Name,Running,Config.Boot,Config.Comment
+=====+==========+=========+=============+================+ +=====+==========+=========+=============+================+
| JID | Name | Running | Config.Boot | Config.Comment | | JID | Name | Running | Config.Boot | Config.Comment |
+=====+==========+=========+=============+================+ +=====+==========+=========+=============+================+
@ -86,8 +80,7 @@ gocage list -f Config.Boot=1 -o JID,Name,Running,Config.Boot,Config.Comment
</pre></code> </pre></code>
Now, only active at boot and running : Now, only active at boot and running :
<pre><code> <pre><code>gocage list -f Config.Boot=1,Running=true -o JID,Name,Running,Config.Boot
gocage list -f Config.Boot=1,Running=true -o JID,Name,Running,Config.Boot
+=====+==========+=========+=============+ +=====+==========+=========+=============+
| JID | Name | Running | Config.Boot | | JID | Name | Running | Config.Boot |
+=====+==========+=========+=============+ +=====+==========+=========+=============+
@ -102,8 +95,7 @@ gocage list -f Config.Boot=1,Running=true -o JID,Name,Running,Config.Boot
Sort jails Sort jails
---------- ----------
Use -s switch followed by sort criteria. Criteria is a field name, prefixed with + or - for sort order (increase/decrease): Use -s switch followed by sort criteria. Criteria is a field name, prefixed with + or - for sort order (increase/decrease):
<pre><code> <pre><code>gocage list -f Config.Boot=1,Running=true -o JID,Name,Running,Config.Boot -s +JID
gocage list -f Config.Boot=1,Running=true -o JID,Name,Running,Config.Boot -s +JID
+=====+==========+=========+=============+ +=====+==========+=========+=============+
| JID | Name | Running | Config.Boot | | JID | Name | Running | Config.Boot |
+=====+==========+=========+=============+ +=====+==========+=========+=============+
@ -117,8 +109,7 @@ gocage list -f Config.Boot=1,Running=true -o JID,Name,Running,Config.Boot -s +JI
You can use up to 3 criteria, delimited with comma. You can use up to 3 criteria, delimited with comma.
As an example, you want to list boot priorities of automatically starting jails: As an example, you want to list boot priorities of automatically starting jails:
<pre><code> <pre><code>gocage list -o JID,Name,Config.Ip4_addr,Config.Priority,Config.Boot,Running -s -Config.Priority,-Config.Boot -f Running=true
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 | | JID | Name | Config.Ip4_addr | Config.Priority | Config.Boot | Running |
+=====+==============+=======================+=================+=============+=========+ +=====+==============+=======================+=================+=============+=========+
@ -160,13 +151,12 @@ Upgrading basejails currently needs to be done manually, for each jail.
The idea is to stop the jail, change the content of its fstab file to point to the new release, then start jail. The idea is to stop the jail, change the content of its fstab file to point to the new release, then start jail.
If one change the fstab while the jail is running, its system directories won't be unmounted at stop time and this will provoke stop errors. If one change the fstab while the jail is running, its system directories won't be unmounted at stop time and this will provoke stop errors.
To minimize downtime, the change could be scripted: To minimize downtime, the change could be scripted:
<code> <pre><code>gocage stop jail1
gocage stop jail1
sed -i .bak 's/14.0-RELEASE/14.1-RELEASE/' /iocage/jails/jail1/fstab sed -i .bak 's/14.0-RELEASE/14.1-RELEASE/' /iocage/jails/jail1/fstab
# Avoid race-condition by waiting for the update in fstab # Avoid race-condition by waiting for the update in fstab
until grep -q 14.1-RELEASE /iocage/jails/jail1/fstab; do sleep 0.2; done until grep -q 14.1-RELEASE /iocage/jails/jail1/fstab; do sleep 0.2; done
gocage start jail1 gocage start jail1
</code> </code></pre>
You can now update ports. You can now update ports.
@ -178,8 +168,7 @@ Delete jails
Multi datastore Multi datastore
---------- ----------
A datastore is a ZFS dataset mounted. It should be declared in gocage.conf.yml, specifying its ZFS mountpoint : A datastore is a ZFS dataset mounted. It should be declared in gocage.conf.yml, specifying its ZFS mountpoint :
<pre><code> <pre><code>datastore:
datastore:
- /iocage - /iocage
- /fastiocage - /fastiocage
</pre></code> </pre></code>
@ -187,8 +176,7 @@ datastore:
In gocage commands, datastore name is the mountpoint without its "/" prefix. In gocage commands, datastore name is the mountpoint without its "/" prefix.
### List datastores ### List datastores
<pre><code> <pre><code>gocage datastore list
gocage datastore list
+============+=============+============+===========+==========+============+ +============+=============+============+===========+==========+============+
| Name | Mountpoint | ZFSDataset | Available | Used | Referenced | | Name | Mountpoint | ZFSDataset | Available | Used | Referenced |
+============+=============+============+===========+==========+============+ +============+=============+============+===========+==========+============+
@ -200,8 +188,7 @@ gocage datastore list
### Filter datastores ### Filter datastores
As with jails and snapshots, you can filter by name: As with jails and snapshots, you can filter by name:
<pre><code> <pre><code>gocage datastore list iocage
gocage datastore list iocage
+============+=============+============+===========+==========+============+ +============+=============+============+===========+==========+============+
| Name | Mountpoint | ZFSDataset | Available | Used | Referenced | | Name | Mountpoint | ZFSDataset | Available | Used | Referenced |
+============+=============+============+===========+==========+============+ +============+=============+============+===========+==========+============+
@ -211,8 +198,7 @@ gocage datastore list iocage
### Sort datastores ### Sort datastores
You can sort datastores: You can sort datastores:
<pre><code> <pre><code>gocage datastore list -s -Available
gocage datastore list -s -Available
+============+=============+============+===========+==========+============+ +============+=============+============+===========+==========+============+
| Name | Mountpoint | ZFSDataset | Available | Used | Referenced | | Name | Mountpoint | ZFSDataset | Available | Used | Referenced |
+============+=============+============+===========+==========+============+ +============+=============+============+===========+==========+============+
@ -235,8 +221,7 @@ Be aware the moment you migrate a jail to another datastore than /iocage default
Then you need to disable iocage service, and enable gocage so the jails will start automatically at boot. Then you need to disable iocage service, and enable gocage so the jails will start automatically at boot.
Also make sure, if you don't destroy source jail, that it won't have the "boot" property set or you will have the 2 jails up at boot. Also make sure, if you don't destroy source jail, that it won't have the "boot" property set or you will have the 2 jails up at boot.
<pre><code> <pre><code>gocage migrate -d fastiocage srv-random
gocage migrate -d fastiocage srv-random
Snapshot data/iocage/jails/srv-random: Done Snapshot data/iocage/jails/srv-random: Done
Snapshot data/iocage/jails/srv-random/root: Done Snapshot data/iocage/jails/srv-random/root: Done
Migrate jail config dataset to fastdata/iocage/jails/srv-random: Done Migrate jail config dataset to fastdata/iocage/jails/srv-random: Done
@ -248,8 +233,7 @@ Fetch
---------- ----------
Files can be fetched from custom repository, or from local directory with "from" option. Files can be fetched from custom repository, or from local directory with "from" option.
For example if you destroyed releases/12.3-RELEASE and still have the downloaded files in /iocage/download/12.3-RELEASE: For example if you destroyed releases/12.3-RELEASE and still have the downloaded files in /iocage/download/12.3-RELEASE:
<pre><code> <pre><code>gocage fetch -r 12.3 -d iocage -f file:/iocage/download
gocage fetch -r 12.3 -d iocage -f file:/iocage/download
</pre></code> </pre></code>