From b4fd7caca72c5a5d22354edae897e5ee9ecd0fa5 Mon Sep 17 00:00:00 2001
From: yo <johan@nosd.in>
Date: Sat, 18 Jun 2022 16:07:29 +0200
Subject: [PATCH] Update readme

---
 README.md | 66 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 65 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 5967cab..aa79f17 100644
--- a/README.md
+++ b/README.md
@@ -4,8 +4,9 @@ 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.  
+
 
-At present time, it list and stops jails.  
 
 List jails
 ----------
@@ -118,3 +119,66 @@ 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>