process_children_only keeps sanoid from messing with empty parent datasets; improved docs in default conf files

CHANGELIST

@@ -1,4 +1,7 @@
-1.2.0 added monitor-children-only parameter to sanoid.conf for use with recursive definitions - in cases where container dataset is kept empty
+1.3.0 changed monitor_children_only to process_children_only. which keeps sanoid from messing around with empty parent datasets at all.
+      also more thoroughly documented features in default config files.
+
+1.2.0 added monitor_children_only parameter to sanoid.conf for use with recursive definitions - in cases where container dataset is kept empty
 
 1.1.0 woooo - working recursive definitions in Sanoid!  Also intelligent config errors in Sanoid; will die with errors if unknown config value is set.
 

README.md

@@ -3,7 +3,7 @@
 
 Sanoid is a policy-driven snapshot management tool for ZFS filesystems.
 
-You can use Sanoid to create, automatically thin, and monitor snapshots and pool health from a single eminently human-readable TOML config file at /etc/sanoid/sanoid.conf.  A typical Sanoid system would have a single cron job:
+You can use Sanoid to create, automatically thin, and monitor snapshots and pool health from a single eminently human-readable TOML config file at /etc/sanoid/sanoid.conf.  (Sanoid also requires a "defaults" file located at /etc/sanoid/sanoid.defaults.conf, which is not user-editable.)  A typical Sanoid system would have a single cron job:
 
 ```
 * * * * * /usr/local/bin/sanoid --cron
@@ -14,10 +14,11 @@ And its /etc/sanoid/sanoid.conf might look something like this:
 ```
 [data/home]
 	use_template = production
-[data/images/win2012]
-	use_template = production
-[data/images/win7-spice]
+[data/images]
 	use_template = production
+	recursive = yes
+	process_children_only = yes
+[data/images/win7]
 	hourly = 4
 
 #############################
@@ -33,7 +34,7 @@ And its /etc/sanoid/sanoid.conf might look something like this:
         autoprune = yes
 ```
 
-Which would be enough to tell sanoid to take and keep 36 hourly snapshots, 30 dailies, 3 monthlies, and no yearlies.  Except in the case of data/images/win7-spice, which only keeps 4 hourlies for whatever reason.
+Which would be enough to tell sanoid to take and keep 36 hourly snapshots, 30 dailies, 3 monthlies, and no yearlies for all datasets under data/images (but not data/images itself, since process_children_only is set).  Except in the case of data/images/win7-spice, which follows the same template (since it's a child of data/images) but only keeps 4 hourlies for whatever reason.
 
 Sanoid also includes a replication tool, syncoid, which facilitates the asynchronous incremental replication of ZFS filesystems.  A typical syncoid command might look like this:
 
@@ -55,4 +56,4 @@ syncoid root@remotehost:data/images/vm backup/images/vm
 
 Which would pull-replicate the filesystem from the remote host to the local system over an SSH tunnel.
 
-Syncoid supports and uses mbuffer buffering, lzop compression, and pv progress bars if the utilities are available on the systems used.
+Syncoid supports recursive replication (replication of a dataset and all its child datasets) and uses mbuffer buffering, lzop compression, and pv progress bars if the utilities are available on the systems used.

VERSION

@@ -1 +1 @@
-1.2.0
+1.3.0

sanoid

@@ -106,7 +106,7 @@ sub monitor_snapshots() {
 	foreach my $section (keys %config) {
 		if ($section =~ /^template/) { next; }
 		if (! $config{$section}{'monitor'}) { next; }
-		if ($config{$section}{'monitor_children_only'}) { next; }		
+		if ($config{$section}{'process_children_only'}) { next; }		
 
 		my $path = $config{$section}{'path'};
 		push @paths, $path;
@@ -178,6 +178,7 @@ sub prune_snapshots {
 	foreach my $section (keys %config) {
 		if ($section =~ /^template/) { next; }
 		if (! $config{$section}{'autoprune'}) { next; }
+		if ($config{$section}{'process_children_only'}) { next; }
 
 		my $path = $config{$section}{'path'};
 
@@ -256,6 +257,7 @@ sub take_snapshots {
 	foreach my $section (keys %config) {
 		if ($section =~ /^template/) { next; }
 		if (! $config{$section}{'autosnap'}) { next; }
+		if ($config{$section}{'process_children_only'}) { next; }		
 
 		my $path = $config{$section}{'path'};
 
@@ -531,7 +533,7 @@ sub init {
 	tie my %ini, 'Config::IniFiles', ( -file => $conf_file ) or die "FATAL: cannot load $conf_file - please create a valid local config file before running sanoid!";
 
 	# we'll use these later to normalize potentially true and false values on any toggle keys
-	my @toggles = ('autosnap','autoprune','monitor_dont_warn','monitor_dont_crit','monitor','recursive','monitor_children_only');
+	my @toggles = ('autosnap','autoprune','monitor_dont_warn','monitor_dont_crit','monitor','recursive','process_children_only');
 	my @istrue=(1,"true","True","TRUE","yes","Yes","YES","on","On","ON");
 	my @isfalse=(0,"false","False","FALSE","no","No","NO","off","Off","OFF");
 	
@@ -615,7 +617,7 @@ sub init {
 			foreach my $dataset(@datasets) {
 				chomp $dataset;
 				foreach my $key (keys %{$config{$section}} ) {
-					if (! ($key =~ /template|recursive|monitor_children_only/)) {
+					if (! ($key =~ /template|recursive|children_only/)) {
 						if ($args{'debug'}) { print "DEBUG: recursively setting $key from $section to $dataset.\n"; }
 						$config{$dataset}{$key} = $config{$section}{$key};
 					}

sanoid.conf

@@ -14,6 +14,21 @@
 	hourly = 12
 	monthly = 1
 
+# you can also handle datasets recursively.
+[zpoolname/parent]
+	use_template = production
+	recursive = yes
+	# if you want sanoid to manage the child datasets but leave this one alone, set process_children_only.
+	process_children_only = yes
+
+# you can selectively override settings for child datasets which already fall under a recursive definition.
+[zpoolname/parent/child]
+	# child datasets already initialized won't be wiped out, so if you use a new template, it will
+	# only override the values already set by the parent template, not replace it completely.
+	use_template = demo
+
+
+
 
 #############################
 # templates below this line #

sanoid.defaults.conf

@@ -14,7 +14,7 @@
 path =
 recursive =
 use_template =
-monitor_children_only = 
+process_children_only =
 
 # If any snapshot type is set to 0, we will not take snapshots for it - and will immediately
 # prune any of those type snapshots already present.

syncoid

@@ -4,7 +4,7 @@
 # from http://www.gnu.org/licenses/gpl-3.0.html on 2014-11-17.  A copy should also be available in this
 # project's Git repository at https://github.com/jimsalterjrs/sanoid/blob/master/LICENSE.
 
-my $version = '1.2.0';
+my $version = '1.3.0';
 
 use strict;
 use Data::Dumper;