From 8c232a30f4da36b5e201af0b83d2ea24f6294b73 Mon Sep 17 00:00:00 2001
From: erdgeist <de@gsmk.de>
Date: Tue, 10 Jun 2014 02:34:47 +0200
Subject: Document the snapshot command

---
 man5/ezjail.conf.5  |  9 +++++++++
 man7/ezjail.7       | 31 +++++++++++++++++++++++++++++++
 man8/ezjail-admin.8 | 27 +++++++++++++++++++++++++++
 3 files changed, 67 insertions(+)

diff --git a/man5/ezjail.conf.5 b/man5/ezjail.conf.5
index a86db07..f35d412 100755
--- a/man5/ezjail.conf.5
+++ b/man5/ezjail.conf.5
@@ -196,6 +196,15 @@ for details. ADVANCED, be very careful!
 .br
 Default:
 .Em none .
+.It ezjail_default_retention_policy (str)
+Policy for the
+.Cm ezjail-admin snapshot
+subcommand to keep older snapshots. See
+.Xr ezjail-admin 1
+for details.
+.br
+Default:
+.Em none .
 .El
 .Sh FILES
 EZJAIL_PREFIX/etc/ezjail.conf
diff --git a/man7/ezjail.7 b/man7/ezjail.7
index 83a920b..2cb6a88 100644
--- a/man7/ezjail.7
+++ b/man7/ezjail.7
@@ -409,6 +409,37 @@ rc.d/ezjail can be used to start and stop jails by prepending
 Refer to
 .Xr rc 8
 for details.
+.Ss Snapshots and retention policies
+Jails residing in their own zfs and their corresponding zfs data sets can be
+automatically snapshot by the
+.Cm ezjail-admin snapshot
+subcommand. Taking snapshots of all jails before a major update is considered
+best practise. However, when taking snapshots regularly, the amount of disc
+space used can be considerable.
+.Pp
+Therefore ezjail allows you to set retention policies that describe how many
+of your snapshots you want to keep for one or all jails or a particular zfs. See
+the description of the snapshot command in
+.Xr ezjail-admin 5
+for details.
+.Pp
+A retention policy consists of one or multiple windows for which ezjail guarantees
+to keep at least one and at most two snapshots. A simple example:
+.D1 $ezjail_default_retention_policy="1d 2w 1y"
+will ensure ONE snapshot for the last day, for the last two weeks before that day and
+then for one snapshot in the year before the two-week window. Valid multipliers are
+(m)inutes, (h)ours, (d)ays, (w)eeks and (y)ears.
+.Pp
+Windows can be repeated by prepending them with a number and the letter x:
+.D1 $ezjail_test_com_retention_policy="24x1h 6x1d 3x1w 11x4w KEEP"
+will set the retention policy for jail test.com to keep hourly snapshots for one
+day, then daily snapshots for the rest of the week, weekly snapshots for the rest of
+the month, monthly snapshots for the rest of the year.
+.Pp
+The magic keyword KEEP at the end of the list will make ezjail not delete snapshots
+older than the oldest window. It is your responsibility to keep the list in an order
+that makes keeping snapshots possible, i.e. not placing one-hour-windows after
+one-year-windows.
 .Ss Remarks & Tips
 Jails can be either accessed from the network, for instance by using
 .Xr ssh 1 ,
diff --git a/man8/ezjail-admin.8 b/man8/ezjail-admin.8
index 8382e44..7e809cf 100644
--- a/man8/ezjail-admin.8
+++ b/man8/ezjail-admin.8
@@ -54,6 +54,9 @@
 .Op Fl d Ar archivedir
 .Ar archive | jailname...
 .Nm
+.Cm snapshot
+.Ar [jailname...]
+.Nm
 .Cm update
 .Op Fl s Ar sourcetree | sourceosversion
 .Op Fl p
@@ -518,6 +521,30 @@ where it was archived. Be default,
 will refuse to restore an archive if the archived host system's hostname,
 its FreeBSD version or CPU architecture do not match the current host.
 .El
+.Ss Nm Cm snapshot [jailname...]
+Takes zfs snapshots of some or all (zfs) ezjails and their zfs datasets and
+optionally destroys older snapshots according to a configured retention
+policy.
+.Pp
+The zfs snapshots will be named @ez-autosnap- with the date appended in format
+“%Y%m%d%H%M”. List all auto snapshots with
+.Dq Li /sbin/zfs list -H -t snapshot | grep @ez-autosnap- .
+.Pp
+You can set (and override in that order) the retention policy globally in your
+.Dq Li $ezjail_default_retention_policy
+.Xr ezjail.conf 5
+variable, set them per jail in its config file with their
+.Dq Li $ezjail_retention_policy 
+variable or set a User property with the name
+.Dq Li ezjail:autosnap_retention 
+on the respective file systems.
+.Pp
+The policy is described by a pattern of space separated
+.Dq Li repeat x window
+entries with the algorithm guaranteeing at least one and at most two snapshots
+in each of the windows, if mathematically possible. See
+.Xr ezjail 7
+for details.
 .Ss Nm Cm update
 Updates ezjail's basejail, or in the
 .Fl b
-- 
cgit v1.2.3