From 4ab023b63d0869918d4922674ed67f446f6e7d66 Mon Sep 17 00:00:00 2001 From: cb Date: Sat, 10 Feb 2024 23:24:29 +0100 Subject: [PATCH] syncoid: systemd.unit + debian TODOs --- .gitignore | 1 + packages/debian/changelog | 6 ++ packages/debian/control | 9 +- packages/debian/findoid.8 | 24 +++++ packages/debian/rules | 28 ------ packages/debian/sanoid-prune.service | 2 + packages/debian/sanoid.8 | 66 +++++++++++++ packages/debian/sanoid.examples | 3 + packages/debian/sanoid.install | 7 ++ packages/debian/sanoid.manpages | 3 + packages/debian/syncoid.8 | 133 +++++++++++++++++++++++++++ packages/debian/syncoid.conf | 32 +++++++ packages/debian/syncoid.service | 14 +++ packages/debian/syncoid.timer | 15 +++ 14 files changed, 314 insertions(+), 29 deletions(-) create mode 100644 .gitignore create mode 100644 packages/debian/findoid.8 create mode 100644 packages/debian/sanoid.8 create mode 100644 packages/debian/sanoid.examples create mode 100644 packages/debian/sanoid.install create mode 100644 packages/debian/sanoid.manpages create mode 100644 packages/debian/syncoid.8 create mode 100644 packages/debian/syncoid.conf create mode 100644 packages/debian/syncoid.service create mode 100644 packages/debian/syncoid.timer diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..226d5b4 --- /dev/null +++ b/.gitignore @@ -0,0 +1 @@ +/debian diff --git a/packages/debian/changelog b/packages/debian/changelog index 00c0c07..8e9d501 100644 --- a/packages/debian/changelog +++ b/packages/debian/changelog @@ -1,3 +1,9 @@ +sanoid (2.2.1) unstable; urgency=medium + + [syncoid] add simple systemd.units + + -- Christopher Bock Sat, 10 Feb 2023 23:15:00 +0200 + sanoid (2.2.0) unstable; urgency=medium [overall] documentation updates, small fixes (@azmodude, @deviantintegral, @jimsalterjrs, @alexhaydock, @cbreak-black, @kd8bny, @JavaScriptDude, @veeableful, @rsheasby, @Topslakr, @mavhc, @adam-stamand, @joelishness, @jsoref, @dodexahedron, @phreaker0) diff --git a/packages/debian/control b/packages/debian/control index 1dfe087..c876662 100644 --- a/packages/debian/control +++ b/packages/debian/control @@ -20,4 +20,11 @@ Recommends: gzip, mbuffer, openssh-client | ssh-client, pv -Description: Policy-driven snapshot management and replication tools +Description: Policy-driven ZFS snapshot management and replication tool + Sanoid is a policy-driven snapshot management and replication tool for ZFS + filesystems. + . + More prosaically, you can use Sanoid to create, automatically thin, and + monitor snapshots and pool health from a single eminently human-readable + TOML config file. Sanoid also includes a replication tool, syncoid, which + facilitates the asynchronous incremental replication of ZFS filesystems. diff --git a/packages/debian/findoid.8 b/packages/debian/findoid.8 new file mode 100644 index 0000000..4fcad5b --- /dev/null +++ b/packages/debian/findoid.8 @@ -0,0 +1,24 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH FINDOID "8" "February 2024" "findoid version 2.2.0" "System Administration Utilities" +.SH NAME +findoid \- manual page for findoid version 2.2.0 +.SH DESCRIPTION +.SS "Usage:" +.IP +findoid [options] FILE +.TP +FILE +local path to file for version listing +.IP +Options: +.TP +\fB\-\-path\fR=\fI\,FILE\/\fR +alternative to specify file path to list versions for +.TP +\fB\-\-help\fR +Prints this helptext +.TP +\fB\-\-version\fR +Prints the version number +.PP +(Getopt::Long::GetOptions version 2.52; Perl version 5.36.0) diff --git a/packages/debian/rules b/packages/debian/rules index 51e52af..4f303af 100755 --- a/packages/debian/rules +++ b/packages/debian/rules @@ -6,31 +6,3 @@ %: dh $@ - -DESTDIR = $(CURDIR)/debian/sanoid -override_dh_auto_install: - install -d $(DESTDIR)/etc/sanoid - install -m 664 sanoid.defaults.conf $(DESTDIR)/etc/sanoid - - install -d $(DESTDIR)/lib/systemd/system - install -m 664 debian/sanoid-prune.service debian/sanoid.timer \ - $(DESTDIR)/lib/systemd/system - - install -d $(DESTDIR)/usr/sbin - install -m 775 \ - findoid sanoid sleepymutex syncoid \ - $(DESTDIR)/usr/sbin - - install -d $(DESTDIR)/usr/share/doc/sanoid - install -m 664 sanoid.conf \ - $(DESTDIR)/usr/share/doc/sanoid/sanoid.conf.example - -override_dh_installinit: - dh_installinit --noscripts - -override_dh_systemd_enable: - dh_systemd_enable sanoid.timer - dh_systemd_enable sanoid-prune.service - -override_dh_systemd_start: - dh_systemd_start sanoid.timer diff --git a/packages/debian/sanoid-prune.service b/packages/debian/sanoid-prune.service index f28dfef..acb511f 100644 --- a/packages/debian/sanoid-prune.service +++ b/packages/debian/sanoid-prune.service @@ -3,6 +3,8 @@ Description=Cleanup ZFS Pool Requires=zfs.target After=zfs.target sanoid.service ConditionFileNotEmpty=/etc/sanoid/sanoid.conf +Before=syncoid.service +Wants=syncoid.service [Service] Environment=TZ=UTC diff --git a/packages/debian/sanoid.8 b/packages/debian/sanoid.8 new file mode 100644 index 0000000..fbf59ad --- /dev/null +++ b/packages/debian/sanoid.8 @@ -0,0 +1,66 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH SANOID "8" "February 2024" "sanoid version 2.2.0" "System Administration Utilities" +.SH NAME +sanoid \- manual page for sanoid version 2.2.0 +.SH DESCRIPTION +.SS "Usage:" +.IP +sanoid [options] +.IP +Assumes \fB\-\-cron\fR \fB\-\-verbose\fR if no other arguments (other than configdir) +are specified +.IP +Options: +.TP +\fB\-\-configdir\fR=\fI\,DIR\/\fR +Specify a directory to find config file sanoid.conf +.TP +\fB\-\-cache\-dir\fR=\fI\,DIR\/\fR +Specify a directory to store the zfs snapshot cache +.TP +\fB\-\-run\-dir\fR=\fI\,DIR\/\fR +Specify a directory for temporary files such as lock files +.TP +\fB\-\-cron\fR +Creates snapshots and purges expired snapshots +.TP +\fB\-\-verbose\fR +Prints out additional information during a sanoid run +.TP +\fB\-\-readonly\fR +Simulates creation/deletion of snapshots +.TP +\fB\-\-quiet\fR +Suppresses non\-error output +.TP +\fB\-\-force\-update\fR +Clears out sanoid's zfs snapshot cache +.TP +\fB\-\-monitor\-health\fR +Reports on zpool "health", in a Nagios compatible format +.TP +\fB\-\-monitor\-capacity\fR +Reports on zpool capacity, in a Nagios compatible format +.TP +\fB\-\-monitor\-snapshots\fR +Reports on snapshot "health", in a Nagios compatible format +.TP +\fB\-\-take\-snapshots\fR +Creates snapshots as specified in sanoid.conf +.TP +\fB\-\-prune\-snapshots\fR +Purges expired snapshots as specified in sanoid.conf +.TP +\fB\-\-force\-prune\fR +Purges expired snapshots even if a send/recv is in progress +.TP +\fB\-\-help\fR +Prints this helptext +.TP +\fB\-\-version\fR +Prints the version number +.TP +\fB\-\-debug\fR +Prints out a lot of additional information during a sanoid run +.PP +(Getopt::Long::GetOptions version 2.52; Perl version 5.36.0) diff --git a/packages/debian/sanoid.examples b/packages/debian/sanoid.examples new file mode 100644 index 0000000..453332f --- /dev/null +++ b/packages/debian/sanoid.examples @@ -0,0 +1,3 @@ +sanoid.conf +debian/syncoid.conf +debian/syncoid.timer diff --git a/packages/debian/sanoid.install b/packages/debian/sanoid.install new file mode 100644 index 0000000..f57d908 --- /dev/null +++ b/packages/debian/sanoid.install @@ -0,0 +1,7 @@ +syncoid /usr/sbin/ +sanoid /usr/sbin/ +findoid /usr/sbin/ +sanoid.defaults.conf /usr/share/sanoid/ +debian/sanoid-prune.service /lib/systemd/system +debian/syncoid.service /lib/systemd/system +CHANGELIST /usr/share/doc/sanoid/changelog diff --git a/packages/debian/sanoid.manpages b/packages/debian/sanoid.manpages new file mode 100644 index 0000000..50bb0ec --- /dev/null +++ b/packages/debian/sanoid.manpages @@ -0,0 +1,3 @@ +debian/findoid.8 +debian/sanoid.8 +debian/syncoid.8 diff --git a/packages/debian/syncoid.8 b/packages/debian/syncoid.8 new file mode 100644 index 0000000..41d3a90 --- /dev/null +++ b/packages/debian/syncoid.8 @@ -0,0 +1,133 @@ +.\" DO NOT MODIFY THIS FILE! It was generated by help2man 1.49.3. +.TH SYNCOID "8" "February 2024" "syncoid version 2.2.0" "System Administration Utilities" +.SH NAME +syncoid \- manual page for syncoid version 2.2.0 +.SH DESCRIPTION +.SS "Usage:" +.IP +syncoid [options]... SOURCE TARGET +or syncoid [options]... SOURCE [[USER]@]HOST:TARGET +or syncoid [options]... [[USER]@]HOST:SOURCE TARGET +or syncoid [options]... [[USER]@]HOST:SOURCE [[USER]@]HOST:TARGET +.TP +SOURCE +Source ZFS dataset. Can be either local or remote +.TP +TARGET +Target ZFS dataset. Can be either local or remote +.IP +Options: +.TP +\fB\-\-compress\fR=\fI\,FORMAT\/\fR +Compresses data during transfer. Currently accepted options are gzip, pigz\-fast, pigz\-slow, zstd\-fast, zstd\-slow, lz4, xz, lzo (default) & none +.TP +\fB\-\-identifier\fR=\fI\,EXTRA\/\fR +Extra identifier which is included in the snapshot name. Can be used for replicating to multiple targets. +.TP +\fB\-\-recursive\fR|r +Also transfers child datasets +.TP +\fB\-\-skip\-parent\fR +Skips syncing of the parent dataset. Does nothing without '\-\-recursive' option. +.TP +\fB\-\-source\-bwlimit=\fR +Bandwidth limit in bytes/kbytes/etc per second on the source transfer +.TP +\fB\-\-target\-bwlimit=\fR +Bandwidth limit in bytes/kbytes/etc per second on the target transfer +.TP +\fB\-\-mbuffer\-size\fR=\fI\,VALUE\/\fR +Specify the mbuffer size (default: 16M), please refer to mbuffer(1) manual page. +.TP +\fB\-\-pv\-options\fR=\fI\,OPTIONS\/\fR +Configure how pv displays the progress bar, default '\-p \fB\-t\fR \fB\-e\fR \fB\-r\fR \fB\-b\fR' +.TP +\fB\-\-no\-stream\fR +Replicates using newest snapshot instead of intermediates +.TP +\fB\-\-no\-sync\-snap\fR +Does not create new snapshot, only transfers existing +.TP +\fB\-\-keep\-sync\-snap\fR +Don't destroy created sync snapshots +.TP +\fB\-\-create\-bookmark\fR +Creates a zfs bookmark for the newest snapshot on the source after replication succeeds (only works with \fB\-\-no\-sync\-snap\fR) +.TP +\fB\-\-use\-hold\fR +Adds a hold to the newest snapshot on the source and target after replication succeeds and removes the hold after the next successful replication. The hold name includes the identifier if set. This allows for separate holds in case of multiple targets +.HP +\fB\-\-preserve\-recordsize\fR Preserves the recordsize on initial sends to the target +.HP +\fB\-\-preserve\-properties\fR Preserves locally set dataset properties similar to the zfs send \fB\-p\fR flag but this one will also work for encrypted datasets in non raw sends +.TP +\fB\-\-no\-rollback\fR +Does not rollback snapshots on target (it probably requires a readonly target) +.HP +\fB\-\-delete\-target\-snapshots\fR With this argument snapshots which are missing on the source will be destroyed on the target. Use this if you only want to handle snapshots on the source. +.TP +\fB\-\-exclude\fR=\fI\,REGEX\/\fR +DEPRECATED. Equivalent to \fB\-\-exclude\-datasets\fR, but will be removed in a future release. Ignored if \fB\-\-exclude\-datasets\fR is also provided. +.HP +\fB\-\-exclude\-datasets\fR=\fI\,REGEX\/\fR Exclude specific datasets which match the given regular expression. Can be specified multiple times +.HP +\fB\-\-exclude\-snaps\fR=\fI\,REGEX\/\fR Exclude specific snapshots that match the given regular expression. Can be specified multiple times. If a snapshot matches both the exclude\-snaps and include\-snaps patterns, then it will be excluded. +.HP +\fB\-\-include\-snaps\fR=\fI\,REGEX\/\fR Only include snapshots that match the given regular expression. Can be specified multiple times. If a snapshot matches both the exclude\-snaps and include\-snaps patterns, then it will be excluded. +.HP +\fB\-\-sendoptions\fR=\fI\,OPTIONS\/\fR Use advanced options for zfs send (the arguments are filtered as needed), e.g. syncoid \fB\-\-sendoptions=\fR"Lc e" sets zfs send \fB\-L\fR \fB\-c\fR \fB\-e\fR ... +.HP +\fB\-\-recvoptions\fR=\fI\,OPTIONS\/\fR Use advanced options for zfs receive (the arguments are filtered as needed), e.g. syncoid \fB\-\-recvoptions=\fR"ux recordsize o compression=lz4" sets zfs receive \fB\-u\fR \fB\-x\fR recordsize \fB\-o\fR compression=lz4 ... +.TP +\fB\-\-sshconfig\fR=\fI\,FILE\/\fR +Specifies an ssh_config(5) file to be used +.TP +\fB\-\-sshkey\fR=\fI\,FILE\/\fR +Specifies a ssh key to use to connect +.TP +\fB\-\-sshport\fR=\fI\,PORT\/\fR +Connects to remote on a particular port +.TP +\fB\-\-sshcipher\fR|c=CIPHER +Passes CIPHER to ssh to use a particular cipher set +.TP +\fB\-\-sshoption\fR|o=OPTION +Passes OPTION to ssh for remote usage. Can be specified multiple times +.TP +\fB\-\-insecure\-direct\-connection\fR=\fI\,IP\/\fR:PORT[,IP:PORT] +WARNING: DATA IS NOT ENCRYPTED. First address pair is for connecting to the target and the second for listening at the target +.TP +\fB\-\-help\fR +Prints this helptext +.TP +\fB\-\-version\fR +Prints the version number +.TP +\fB\-\-debug\fR +Prints out a lot of additional information during a syncoid run +.TP +\fB\-\-monitor\-version\fR +Currently does nothing +.TP +\fB\-\-quiet\fR +Suppresses non\-error output +.TP +\fB\-\-dumpsnaps\fR +Dumps a list of snapshots during the run +.TP +\fB\-\-no\-command\-checks\fR +Do not check command existence before attempting transfer. Not recommended +.TP +\fB\-\-no\-resume\fR +Don't use the ZFS resume feature if available +.TP +\fB\-\-no\-clone\-handling\fR +Don't try to recreate clones on target +.TP +\fB\-\-no\-privilege\-elevation\fR +Bypass the root check, for use with ZFS permission delegation +.TP +\fB\-\-force\-delete\fR +Remove target datasets recursively, if there are no matching snapshots/bookmarks (also overwrites conflicting named snapshots) +.PP +(Getopt::Long::GetOptions version 2.52; Perl version 5.36.0) diff --git a/packages/debian/syncoid.conf b/packages/debian/syncoid.conf new file mode 100644 index 0000000..f3a8c22 --- /dev/null +++ b/packages/debian/syncoid.conf @@ -0,0 +1,32 @@ +# syncoid config example for simple one target/source synchronization +# +# syntax: VARIABLE='foo' # don't forget the '' +# keep in mind that the syncoid.service will call +# ExecStart=/usr/sbin/syncoid $DEBUG $OPTS $EXCLUDES $INCLUDES $SSHOPTS $SOURCE $TARGET +# there are so many variables so we don't have to write an gigantic line +# and as i couldn't use e.g. --exclude-datasets="" it can't be used otherwise +# +# TODO: write syncoid-generator and probably a template syncoid@.service which +# is driven by configuration files in /etc/sanoid/syncoid/$JOB.conf? +# hint: systemd.path(5) PathChanged= for automatic config change detection +# this will get rid of those disgusting variables +# +# all variables should be set, so don't comment them out! +# DEBUG='--debug' +DEBUG='' +# OPTS="--compress=zstd-fast --delete-target-snapshots --force-delete --no-privilege-elevation --recursive" +OPTS='' +# SOURCE='rpool/home' +# SOURCE='user@host:pool/data/set' +SOURCE='' +# TARGET='pool1/data/set' +# TARGET='user@host:pool' +TARGET='' +# SSHOPTS='--sshkey=/path/to/.ssh/id_rsa --sshport=22' +SSHOPTS='' +# EXCLUDES="--exclude-datasets='.*nosnap.*'" +EXCLUDES='' +# INCLUDES="--include-datasets= +INCLUDES='' +# mbuffer behaves icky because env HOME isn't available +MBUFFERRC='/etc/mbuffer.rc' diff --git a/packages/debian/syncoid.service b/packages/debian/syncoid.service new file mode 100644 index 0000000..78fb902 --- /dev/null +++ b/packages/debian/syncoid.service @@ -0,0 +1,14 @@ +[Unit] +Description=Transfer ZFS Snapshots +Documentation=man:syncoid(8) +Requires=local-fs.target sanoid.service +After=local-fs.target sanoid-prune.service +ConditionFileNotEmpty=/etc/sanoid/syncoid.conf + +[Service] +EnvironmentFile=/etc/sanoid/syncoid.conf +Type=oneshot +ExecStart=/usr/sbin/syncoid $DEBUG $OPTS $EXCLUDES $INCLUDES $SSHOPTS $SOURCE $TARGET + +[Install] +WantedBy=sanoid.service diff --git a/packages/debian/syncoid.timer b/packages/debian/syncoid.timer new file mode 100644 index 0000000..a3e07fc --- /dev/null +++ b/packages/debian/syncoid.timer @@ -0,0 +1,15 @@ +[Unit] +Description=Transfer ZFS Snapshots +Documentation=man:syncoid(8) +Documentation=man:systemd.time(7) + +[Install] +WantedBy=timers.target + +[Timer] +RandomizeDelaySec=60 +OnBootSec=5m +#OnUnitActiveSec=20m +OnCalendar=*-*-* */2:00:00 +Persistent=true +Unit=syncoid.service