zogftw cmd command-to-execute
Execute the command-to-execute in the context of zogftw. Useful to call zogftw functions that arent reachable through their own subcommands. Use zogftw help -v to see which functions are available.
Show the configuration variables and their content. Useful to confirm that the configuration file is interpreted as expected.
zogftw create zpool-name device-to-label
Create a new external ZFS pool that can be managed with zogftw. The device-to-label is labeled zpool-name using glabel, the labeled device is initialized with geli using the optional ZOGFTW_GELI_INIT_FLAGS, afterwards it is attached and used as vdev for the newly created ZFS pool zpool-name.
A geli passphrase and keyfile are read from the locations documented in the zogftw import section. If the files do not exist at the expected locations, no keyfile is used and the passphrase has to be entered manually. If ZOGFTW_CREATE_ENCRYPTED_GELI_PASSPHRASE_FILE is set to 1 and the passphrase file doesnt exist yet, it will be created.
The ZFS pool is created with the zpool flags specified with ZOGFTW_ZPOOL_CREATE_FLAGS.
The dataset ZOGFTW_DEST_POOL_PREFIX is created to mark the ZFS pool as receiving target for zogftw sync, the datasets compression property is set to ZOGFTW_BACKUP_DATASET_COMPRESSION.
Finally the ZFS pool is exported and the geli provider detached.
As the ZFS pool only has a single vdev, there is no redundancy by default. Instead, the recommendation is to use multiple independent devices with the same content on their own ZFS pools, that can be stored in different locations and accessed independently.
zogftw export [-f] [zpool-to-export]
Export either zpool-to-export or all attached ZFS pools that are stored on a encrypted vdev on a label with the same name as the ZFS pool. If the -f flag is specified, pools are exported forcefully.
zogftw help [-v]
Show the available subcommands. If the -v flag is specified, the internal functions and their parameter names are listed as well. They can be accessed through the subcommands cmd or directly from the shell after sourcing zogftw.
Create the directories and configuration files expected by zogftw as shown by zogftw config without second-guessing their locations or the users umask settings. Using this subcommand or creating the files manually is optional, but a configuration file has to exist unless ZOGFTW_CONFIG_FILE is set to an empty string through the environment.
zogftw import [zpool-to-import]
Attach the label zpool-to-import with geli and import the ZFS pool on it. If no zpool-to-import is specified, all labeled devices are attached and imported.
If ZOGFTW_GELI_PASSPHRASE_DIR/zpool-to-import.gpg exists, it is decrypted using gpg and the content used as geli passphrase. If gpg-agent is being used, this allows to attach multiple devices without having to enter the passphrase manually for each device.
If ZOGFTW_GELI_KEYFILE_DIR/zpool-to-import.key exists, it is used a geli keyfile.
This is an alias for zogftw source. Can be used when modifying the subcommand through a hook that implements a custom subcommand to prevent a syntax warning.
zogftw snap[shot] [dataset-to-snapshot-specified-by-name-or-path]
Create a ZFS snapshot on the dataset specified by name or path. A timestamp is used as snapshot name to make sure that ordering the snapshots by name reflects the chronological order as well.
If no dataset is specified, a ZFS snapshot is created on all datasets specified by ZOGFTW_DEFAULT_SNAPSHOT_DATASETS.
Exit after reading the configuration file without executing one of the other subcommands.
Useful to source zogftw in the current shell to directly access its functions later on without having to prefix them with zogftw cmd and rereading the configuration file each time.
Note that not all shells support passing parameters to sourced scripts, though.
zogftw sync [receiving-zpool]
Send the last snapshots on the configured datasets to the receiving-zpool. If no ZFS pool is specified, send to all attached ZFS pools with a layout as created by zogftw create.
mbuffer is used with the flags specified with ZOGFTW_MBUFFER_FLAGS in the pipe between zfs send and zfs receive.
Snapshots are received below receiving-zpool/ZOGFTW_DEST_POOL_PREFIX.
Snapshots on datasets specified with ZOGFTW_REQUIRED_SRC_DATASETS will be sent to the receiving ZFS pool unless they already exist there or the property de.fabiankeil:zogftw:new_datasets is set on receiving-zpool/ZOGFTW_DEST_POOL_PREFIX and does not contain the value yes.
If the dataset doesnt already exist it is created, otherwise an incremental snapshot is sent. Intermediary snapshots are sent as well, provided the receiving ZFS pool is bigger than ZOGFTW_MAX CONSTRAINED_ZPOOL_SIZE.
Incremental snapshots are received using the zfs flags specified with ZOGFTW_ZFS_INCREMENTAL_RECEIVE_FLAGS, in case of non-incremental snapshots the zfs flags specified with ZOGFTW_ZFS_NON_INCREMENTAL_RECEIVE_FLAGS are used instead. If the system supports it (FreeBSD r289362 or later and pool feature extensible_dataset enabled), adding the -s flag is highly recommended as it allows zogftw to resume failed transfers the next time the sync command is being used.
Datasets specified with ZOGFTW_OPTIONAL_SRC_DATASETS are treated like required datasets, except that they are only sent if the dataset itself already exists on the receiving ZFS pool and contains at least one snapshot.
Datasets specified with ZOGFTW_EXTERNAL_SRC_DATASETS are treated like optional source datasets but do not have to be available on the source at the time the synchronization occurs.
To figure out which snapshots are missing, zogftw by default lets zfs list them sorted in chronological order. If it is known that sorting them by name keeps them in chronological order, ZOGFTW_SORTING_SNAPSHOTS_BY_NAME_KEEPS_CHRONOLOGICAL_ORDER can be set to 1 to significantly speed up the listing on recent FreeBSD-based systems.
In case of syncronization errors, zogftw sync exits right away (without syncing other pools) to increase the chances that the user notices the problem.
zogftw zcmd function-without-prefix-to-execute
Works like zogftw cmd, but the command is prefixed with zogftw_ so the prefix doesnt need to be typed manually.
zogftw zpool subcommand [prefix_args] [postfix_args]
For each imported ZFS pool that is managed by zogftw, execute zpool with the specified subcommand using the optional arguments before and after the pool name.