home | help 
ZOGFTW(8)							       ZOGFTW(8)

NAME
     zogftw - Creates redundant backups on encrypted external ZFS pools

SYNOPSIS
     zogftw cmd command-to-execute
     zogftw config
     zogftw create zpool-name device-to-label
     zogftw export [-f] [zpool-to-export]
     zogftw help [-v]
     zogftw init
     zogftw import [-f] [-N] [zpool-to-import]
     zogftw snap[shot] [dataset-to-snapshot-specified-by-name-or-path]
     zogftw source
     zogftw sync [receiving-zpool]
     zogftw update-last-snapshot-properties zpool
     zogftw zcmd function-without-prefix-to-execute
     zogftw zpool subcommand [prefix_args] [postfix_args]

DESCRIPTION
     zogftw makes managing backups on multiple external ZFS storage pools on en-
     crypted devices more convenient. Currently most of its subcommands are only
     expected to work on FreeBSD and FreeBSD-based systems like ElectroBSD.

     zogftw  is configured through variables that are provided through the envi-
     ronment or the configuration file ZOGFTW_CONFIG_FILE  that  is  sourced  as
     shell script. They are uppercased and prefixed with ZOGFTW_.

     zogftw's  behaviour can be further customized by providing hooks, which are
     shell functions that are called in certain events, or  by	overwriting  any
     other  internal  function	providing  the	behaviour expected by the caller
     isn't affected.

     All of  zogftw's  internal  functions  are  lowercased  and  prefixed  with
     zogftw_, hooks are additionally postfixed with _hook.

     zogftw  uses  sudo  for operations that are expected to require root privi-
     leges. Running zogftw itself as root is neither necessary nor recommended.

OPTIONS
     zogftw cmd command-to-execute

     Execute the command-to-execute in the context of  zogftw.	Useful	to  call
     zogftw  functions	that aren't reachable through their own subcommands. Use
     zogftw help -v to see which functions are available.

     zogftw config

     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 de-
     vice-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 doesn't 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 re-
     ceiving target for zogftw sync, the dataset's 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  loca-
     tions 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  ac-
     cessed  through the subcommands cmd or directly from the shell after sourc-
     ing zogftw.

     zogftw init

     Create the directories and configuration files expected by zogftw as  shown
     by  zogftw  config  without  second-guessing  their locations or the user's
     umask settings. Using this subcommand or creating the files manually is op-
     tional, but a configuration file has to exist unless ZOGFTW_CONFIG_FILE  is
     set to an empty string through the environment.

     zogftw import [-f] [-N] [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  the  -f  flag  is  specified, pools a forceful import is at-
     tempted. This is required to import pools that were previously imported  by
     another  system.  If  the	-N flag is specified, pools are imported without
     mounting any file systems.

     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.

     zogftw nop

     This is an alias for zogftw source. Can be used when modifying the  subcom-
     mand 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 spec-
     ified by ZOGFTW_DEFAULT_SNAPSHOT_DATASETS.

     zogftw source

     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 func-
     tions 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. ZOGFTW_ZFS_SEND_FLAGS can be	used  to  enable
     zfs send flags like -L or -e. The appropriate incremental flags are set au-
     tomatically and should not be included in the ZOGFTW_ZFS_SEND_FLAGS.

     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 prop-
     erty     de.fabiankeil:zogftw:new_datasets     is	   set	   on	 receiv-
     ing-zpool/ZOGFTW_DEST_POOL_PREFIX and does not contain the value yes.

     If the dataset doesn't already exist it is created, otherwise an  incremen-
     tal snapshot is sent. Intermediary snapshots are sent as well, provided the
     receiving	ZFS pool is bigger than ZOGFTW_MAX_SPACE_CONSTRAINED_ZPOOL_SIZE.
     This logic can be overridden by setting the  de.fabiankeil:zogftw:incremen-
     tal-mode property on the receiving dataset to -i or -I.

     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 recom-
     mended 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 re-
     quired datasets, except that they are only sent if the dataset  itself  al-
     ready exists on the receiving ZFS pool and contains at least one snapshot.

     Datasets  specified  with ZOGFTW_EXTERNAL_SRC_DATASETS are treated like op-
     tional 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_SNAP-
     SHOTS_BY_NAME_KEEPS_CHRONOLOGICAL_ORDER  can  be  set to 1 to significantly
     speed up the listing on recent FreeBSD-based systems.

     In case of synchronization errors, zogftw sync exits  right  away	(without
     syncing  other  pools)  to  increase  the chances that the user notices the
     problem.

     zogftw update-last-snapshot-properties zpool

     Update the de.fabiankeil:zogftw:last_snapshot properties on the given pool.
     Useful if the zpool has been created before the property was introduced  or
     has  been	updated with ZOGFTW_STORE_LAST_SNAPSHOT_AS_PROPERTY being set to
     0. Running zogftw sync automatically creates or updates  the  property  but
     only does it for datasets that receive updates.

     zogftw zcmd function-without-prefix-to-execute

     Works like zogftw cmd, but the command is prefixed with zogftw_ so the pre-
     fix doesn't 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.

EXIT STATUS
     Everything but 0 is an error, 0 usually means success.

BUGS
     The  documentation  is poorly formatted and incomplete. The OPTIONS section
     should be called SUBCOMMANDS. The system used to  build  the  documentation
     doesn't  support  this  without  fiddling, though, and as the documentation
     system will hopefully be replaced in the near future,  said  fiddling  cur-
     rently doesn't seem like time well spent.

     ZFS  permissions  aren't  consistently checked when figuring out whether or
     not a command requires sudo.

     zogftw create currently does not put an unencrypted  ElectroBSD  system  on
     the  beginning  of  the  disk that plays a selection of Die ~Arzte - 5 6 7 8
     Bullenstaat in a loop when booted, to entertain whoever gets hold of it  by
     tricking a judge into signing a search warrant.

SEE ALSO
     gpg2(1), gpg-agent(1), zfs(8), zpool(8)

AUTHOR
     Fabian Keil <fk@fabiankeil>

RESOURCES
     https://www.fabiankeil.de/gehacktes/zogftw/

				   02/23/2025			       ZOGFTW(8)
home | help