ZNAPZENDZETUP(1)

📦 version 0.23.2, in nixpkgs unstable

✨ ZNAPZENDZETUP(1) ✨

okay bestie, welcome to the znapzend manual, page ZNAPZENDZETUP(1) — this is the setup utility for znapzend and it's lowkey the whole control room for your snapshot vibes 💅

💖 NAME 💖

znapzendzetup — the znapzend setup utility 🎀

🦋 SYNOPSIS 🦋

znapzendzetup command [common-options...] [command-options...]

so the deal is: common-options come first (they must precede command-options — no skipping the line, bestie 🚧), and they're a mix of these:

            [--rootExec={pfexec|sudo}] \
            [--features={x,y,...}] \
                {lowmemRecurse zfsGetType} \
            [--debug]

and then command + its unique options is one of the following, and yes there are a lot of them, so buckle up 🌈:

    create  [--recursive] [--mbuffer=<path>[:<port>]] [--mbuffersize=<size>] \
            [--pre-snap-command=<command>] \
            [--post-snap-command=<command>] \
            [--tsformat=<format>] --donotask \
            [--send-delay=<time>] \
            SRC plan dataset [src_mbuffer_path [src_mbuffer_size]] \
            [ DST[:key] plan [[user@]host:]dataset
                [pre-send-command] [post-send-command] \
                [dst_mbuffer_path[:port]] [dst_mbuffer_size] ]
🚨 NOTE, READ THIS FR FR: if you specify [user@]host:dataset for remote replication over SSH, make use of ~/.ssh/config for any advanced options (custom ports, keys to use, etc.). See the znapzend README for ideas — it's giving exactly where you should look, iykyk 👀
    delete  [--dst=key] <src_dataset>
    edit    [--recursive=on|off] \
            [--mbuffer=<path>[:<port>]|off] [--mbuffersize=<size>] \
            [--pre-snap-command=<command>|off] \
            [--post-snap-command=<command>|off] \
            [--tsformat=<format>] --donotask \
            [--send-delay=<time>] \
            SRC [plan] dataset [src_mbuffer_path [src_mbuffer_size]] \
            [ DST:key [plan] [dataset] \
                [pre-send-command|off] [post-send-command|off] \
                [dst_mbuffer_path[:port]|off] [dst_mbuffer_size] ]
    edit    <src_dataset>
    enable  <src_dataset>
    disable <src_dataset>
    enable-dst  <src_dataset> <DST_key>
    disable-dst <src_dataset> <DST_key>
    enable-dst-autocreation  <src_dataset> <DST_key>
    disable-dst-autocreation <src_dataset> <DST_key>
    inherit-dst-autocreation  <src_dataset> <DST_key>
    list    [--recursive] [--inherited] [src_dataset...]
    export  <src_dataset>
    import  [--write] [--prop <property>=<value>, [--prop ...] ...]
            <src_dataset> [<prop_dump_file>]
    help
    man

and that's the lineup, bestie — literally all the entry points laid out like a fit check 👑✨

(part 1 done — more coming, don't wander off 💜)

✨ DESCRIPTION ✨

ok so znapzendzetup is literally the command you use to set up all your backup tasks, bestie. the cli is modeled after the zfs commandline — you know, that whole vibes.

after you change the config, you have to send a HUP signal to your znapzend daemon so it re-reads the configuration. no cap, it will not notice otherwise. 🫶

the common options include:

  • --features=feature1,feature2,... — turns on a few enhanced zfs module features so things are on par with those used by the znapzend command (but far fewer of them are relevant for znapzendzetup, jsyk).

these are the available features:

  • lowmemRecurse — use 'lowmemRecurse' on systems where you have too many datasets, so that a recursive listing of attributes to find backup plans exhausts the memory available to znapzend(zetup). instead it goes the slower way: first list all the impacted dataset names, and then query their configs one by one. 😮‍💨
  • zfsGetType — use 'zfsGetType' if your 'zfs get' supports a -t argument for filtering by dataset type at all (e.g. the one in Solaris 10 does **not`), AND it lists properties for snapshots by default when recursing (e.g. the one in Solaris 10u8 already does) — because then there's just too much data to process while searching for backup plans.

if these two conditions apply to your system, the time needed for a --recursive listing of backup plans can literally differ by hundreds of times (depending on the amount of snapshots in that dataset tree… and a decent backup plan will ensure you have a lot of those, bestie). so you would highkey benefit from requesting this feature. 🔥

this feature should not impact the default (non---recursive) listings however.

below, a few notes on the main commands. 👑

🎀 create 🎀

the heart of the znapzend backup is the plan. the plan specifies how often to backup and for how long to keep the backups. a plan is required both for the source and the destination datasets. no plan, no slay.

the plan consists of a series of retention periods to interval associations:

retA=>intA,retB=>intB,...

both intervals and retention periods are expressed in standard units of time or multiples of them. you can use both the full name or a shortcut, according to the following table:

second|sec|s
minute|min
hour|h
day|d
week|w
month|mon|m
year|y

to keep one copy every 30 minutes for one week, specify:

1week=>30min

to keep one copy every two days for 10 years:

10year=>2day

in a minimal setup, you just specify a plan for the SRC fileset. this will cause snapshots to be taken and destroyed according to the plan. you can then add one or several destinations (DST), both local (preferably on a different pool) or remote. 🌈

when adding multiple DST entries, each will get labeled for later identification — and optionally you can specify your own label. cute.

  • --tsformat=limited-strftime-format — the --tsformat option specifies how the names of the snapshots are constructed.

the syntax is strftime-like. the string must consist of the mandatory

%Y %m %d %H %M %S %z

optionally, these characters

- _ . :

as well as any alphanumeric character are allowed.

if not specified, --tsformat defaults to "%Y-%m-%d-%H%M%S".

if the --tsformat string is suffixed by a 'Z', times will be in UTC. e.g.:

--tsformat='%Y-%m-%dT%H:%M:%SZ'
NOTE: that windoz will probably not like the ":" characters. so if you intend to browse the snapshots with windoz, you may want to use a different separator. 💀
  • --mbuffer=/usr/bin/mbuffer — DEPRECATED: specify the path to your copy of the mbuffer utility.
NOTE: with this option, the same path would be used for all remote destinations — this can misfire if they run different operating systems. 🙈

it is currently recommended to define individual dst_mbuffer_path options for each separate destination in each dataset configuration. the --mbuffer value would be used as a fallback default for those.

per legacy-default behavior, the mbuffer program was not used by the sender (unless using a dedicated port, see below). nowadays it is possible to specify it instead of (or in addition to) a destination side mbuffer, using the src_mbuffer_path in each source dataset configuration.

  • --mbuffer=/usr/bin/mbuffer:31337 — DEPRECATED: specify the path to your copy of the mbuffer utility and the port used on the destination. ⚠️ caution: znapzend will use SSH to set up the remote mbuffer receiver, but will send the snapshot data stream directly from source mbuffer to destination mbuffer. in other words, the data stream is not encrypted. use this only in a trusted LAN or over VPN, where you can safely avoid the overheads of an SSH tunnel.
NOTE: with this option, the same path would be used for all remote destinations as well as the source system — this can misfire if they run different operating systems. 🙈

it is currently recommended to define individual *_mbuffer_path options for each source and each separate destination in each dataset configuration. the --mbuffer value would be used as a fallback default for those (with only the path component for the source).

  • --mbuffersize=number{b|k|M|G} — the size of the mbuffer can be set with the --mbuffersize option. it supports the following units:
b, k, M, G

to specify a mbuffer size of 100MB:

--mbuffersize=100M

if not set, the buffer size defaults to 1GB. 🍓

it is currently suggested to define individual mbuffer_size options for each source and each separate destination in each dataset configuration. the --mbuffer-size value would be used as a fallback default for those.

  • --donotask — apply changes immediately. without being asked if the config is as you intended it to be. main character energy: no confirmation, just vibes. 💅
  • --pre-snap-command=/path/bin args, --post-snap-command=/path/bin args — run commands/scripts before and after snapshots are taken on source. e.g. for database locking/flushing (pre) and unlocking (post).

if you deal with a mariadb/mysql database, you can use

  pre-snap-command  = /opt/oep/mariadb/bin/mysql -e "set autocommit=0;flush tables with read lock;\\! /bin/sleep 600" &  /usr/bin/echo $! > /tmp/mariadblock.pid ; sleep 10
  post-snap-command = /usr/bin/kill `/usr/bin/cat /tmp/mariadblock.pid`;/usr/bin/rm /tmp/mariadblock.pid

to make sure that the on-disk data is consistent when snapshotting. the lock stays in place only for the duration of the lingering connection to mysql we need to employ, or until the snapshotting attempt times out. for this to work, add the root password of your mariadb/mysql database setup into ~root/.my.cnf and make sure the file permissions are tight… 🔐

the pre and post snapshot commands can find the name and time of the snapshot in the environment variables ZNAP_NAME and ZNAP_TIME.

  • --send-delay — specify delay (in seconds) before sending snaps to the destination. may be useful if you want to control sending time. ⏰
  • pre-send-command=/path/bin args, post-send-command=/path/bin args — run command/script before and after sending the snapshot to the destination. intended to run a remote script via ssh on the destination, e.g. to bring up a backup disk or server. or to put a zpool online/offline:
"ssh root@bserv zpool import -Nf tank"
"ssh root@bserv zpool export tank"

🦋 delete 🦋

to remove configuration from a dataset just give its name:

znapzendzetup delete I<dataset>

the delete function understands the following options:

  • --dst=key — to only remove a destination, specify the key of the destination. use the list function to see the keys. iykyk. 🔑

🌸 edit 🌸

modify the configuration of a dataset. see the descriptions in the create function for details.

if edit is used with a source dataset as single argument, properties can be edited in an editor. ✏️

🧚 export 🧚

dumps the backup configuration of a dataset:

znapzendzetup export I<dataset>

👑 import 👑

reads configuration data from a file or STDIN and prints it content.

  • --write — actually store the new configuration into the dataset given on the command line.
  • --prop key="value" [ --prop ... ] — may be called multiple times to override properties in the imported config.

🔥 EXAMPLES 🔥

create a complex backup task:

znapzendzetup create --recursive --mbuffer=/opt/omni/bin/mbuffer \
   --mbuffersize=1G --tsformat='%Y-%m-%d-%H%M%S' \
   --pre-snap-command="/bin/sh /usr/local/bin/lock_flush_db.sh" \
   --post-snap-command="/bin/sh /usr/local/bin/unlock_db.sh" \
   SRC '7d=>1h,30d=>4h,90d=>1d' tank/home \
      "/usr/bin/mbuffer" "128M" \
   DST:a '7d=>1h,30d=>4h,90d=>1d,1y=>1w,10y=>1month' backup/home \
   DST:b '7d=>1h,30d=>4h,90d=>1d,1y=>1w,10y=>1month' \
      root@bserv:backup/home \
      "/root/znapzend.sh dst_b pool on" \
      "/root/znapzend.sh dst_b pool off" \
      "/opt/bin64/mbuffer" "4G"

copy the setup from one fileset to another:

znapzendzetup export tank/home | znapzendzetup import --write tank/new_home

💜 RUNNING AS AN UNPRIVILEGED USER 💜

in order to allow a non-privileged user to use it, the following permissions are required on the ZFS filesystems:

Sending end: destroy,hold,mount,send,snapshot,userprop Receiving end: create,mount,receive,userprop

Copyright (c) 2014 by OETIKER+PARTNER AG. All rights reserved.

⭐ LICENSE ⭐

this program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

this program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. see the GNU General Public License for more details.

you should have received a copy of the GNU General Public License along with this program. if not, see <http://www.gnu.org/licenses/>.

🫶 AUTHOR 🫶

Tobias Oetiker <tobi@oetiker.ch> Dominik Hassler <hadfl@cpan.org>

🌟 HISTORY 🌟

2016-09-23 ron Destination pre and post send/receive commands
2014-07-22 had Pre and post snapshot commands
2014-06-29 had Flexible snapshot time format
2014-06-01 had Multi destination backup
2014-05-30 had Initial Version

and that's the whole page, bestie — this was version 0.23.2, dated 2024-06-27, and honestly? it ate. go configure your backups. 💖✨🎀

📦 where this page comes from