diff options
authorerdgeist <>2014-06-10 02:34:47 +0200
committererdgeist <>2014-06-10 02:34:47 +0200
commit8c232a30f4da36b5e201af0b83d2ea24f6294b73 (patch)
parent0601e306e7ff30498a03a62b748e417262630dcf (diff)
Document the snapshot command
3 files changed, 67 insertions, 0 deletions
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!
197Default: 197Default:
198.Em none . 198.Em none .
199.It ezjail_default_retention_policy (str)
200Policy for the
201.Cm ezjail-admin snapshot
202subcommand to keep older snapshots. See
203.Xr ezjail-admin 1
204for details.
207.Em none .
199.El 208.El
200.Sh FILES 209.Sh FILES
201EZJAIL_PREFIX/etc/ezjail.conf 210EZJAIL_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
409Refer to 409Refer to
410.Xr rc 8 410.Xr rc 8
411for details. 411for details.
412.Ss Snapshots and retention policies
413Jails residing in their own zfs and their corresponding zfs data sets can be
414automatically snapshot by the
415.Cm ezjail-admin snapshot
416subcommand. Taking snapshots of all jails before a major update is considered
417best practise. However, when taking snapshots regularly, the amount of disc
418space used can be considerable.
420Therefore ezjail allows you to set retention policies that describe how many
421of your snapshots you want to keep for one or all jails or a particular zfs. See
422the description of the snapshot command in
423.Xr ezjail-admin 5
424for details.
426A retention policy consists of one or multiple windows for which ezjail guarantees
427to keep at least one and at most two snapshots. A simple example:
428.D1 $ezjail_default_retention_policy="1d 2w 1y"
429will ensure ONE snapshot for the last day, for the last two weeks before that day and
430then for one snapshot in the year before the two-week window. Valid multipliers are
431(m)inutes, (h)ours, (d)ays, (w)eeks and (y)ears.
433Windows can be repeated by prepending them with a number and the letter x:
434.D1 $ezjail_test_com_retention_policy="24x1h 6x1d 3x1w 11x4w KEEP"
435will set the retention policy for jail to keep hourly snapshots for one
436day, then daily snapshots for the rest of the week, weekly snapshots for the rest of
437the month, monthly snapshots for the rest of the year.
439The magic keyword KEEP at the end of the list will make ezjail not delete snapshots
440older than the oldest window. It is your responsibility to keep the list in an order
441that makes keeping snapshots possible, i.e. not placing one-hour-windows after
412.Ss Remarks & Tips 443.Ss Remarks & Tips
413Jails can be either accessed from the network, for instance by using 444Jails can be either accessed from the network, for instance by using
414.Xr ssh 1 , 445.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 @@
54.Op Fl d Ar archivedir 54.Op Fl d Ar archivedir
55.Ar archive | jailname... 55.Ar archive | jailname...
56.Nm 56.Nm
57.Cm snapshot
58.Ar [jailname...]
57.Cm update 60.Cm update
58.Op Fl s Ar sourcetree | sourceosversion 61.Op Fl s Ar sourcetree | sourceosversion
59.Op Fl p 62.Op Fl p
@@ -518,6 +521,30 @@ where it was archived. Be default,
518will refuse to restore an archive if the archived host system's hostname, 521will refuse to restore an archive if the archived host system's hostname,
519its FreeBSD version or CPU architecture do not match the current host. 522its FreeBSD version or CPU architecture do not match the current host.
520.El 523.El
524.Ss Nm Cm snapshot [jailname...]
525Takes zfs snapshots of some or all (zfs) ezjails and their zfs datasets and
526optionally destroys older snapshots according to a configured retention
529The zfs snapshots will be named @ez-autosnap- with the date appended in format
530“%Y%m%d%H%M”. List all auto snapshots with
531.Dq Li /sbin/zfs list -H -t snapshot | grep @ez-autosnap- .
533You can set (and override in that order) the retention policy globally in your
534.Dq Li $ezjail_default_retention_policy
535.Xr ezjail.conf 5
536variable, set them per jail in its config file with their
537.Dq Li $ezjail_retention_policy
538variable or set a User property with the name
539.Dq Li ezjail:autosnap_retention
540on the respective file systems.
542The policy is described by a pattern of space separated
543.Dq Li repeat x window
544entries with the algorithm guaranteeing at least one and at most two snapshots
545in each of the windows, if mathematically possible. See
546.Xr ezjail 7
547for details.
521.Ss Nm Cm update 548.Ss Nm Cm update
522Updates ezjail's basejail, or in the 549Updates ezjail's basejail, or in the
523.Fl b 550.Fl b