init_backup_zfs.sh(8)

NAME

init_backup_zfs.sh - create and NFS-share the per-pool backup datasets

SYNOPSIS

/opt/omnicube/sbin/init_backup_zfs.sh ADMIN_ZONE

DESCRIPTION

init_backup_zfs.sh prepares the /srv/backups hierarchy on a node: one ZFS dataset per zone pool, each shared over NFS to a single administrative host. It is a one-shot initialisation command, run in the global zone after a node is built or after a new zone pool has been imported, and it is idempotent - a pool that already has a backup dataset is left alone.

Two levels of dataset are created.

Node level: If the node's own pool has no dataset whose recursive listing mentions backups, the command creates shorthost/srv with mountpoint=/srv and shorthost/srv/backups with mountpoint=/srv/backups, and shares the latter. The shorthost name is the output of hostname(1) truncated at the first -, which is the OmniCube convention for the node's local pool.
Pool level: Every pool reported by zpool list -H -o name except rpool and those whose name contains shorthost is examined. If the pool has no dataset mounted under /backups, the command creates pool/backups with mountpoint=/srv/backups/pool and shares it.

The share is set with

pfexec zfs set sharenfs=sec=sys,rw=${ADMIN_ZONE},root=${ADMIN_ZONE} <dataset>

so only ADMIN_ZONE may write, and it does so with root privileges preserved.

init_backup_zfs.sh does not source /opt/omnicube/lib/common/utils.sh: it carries its own copy of the run-level guard and has no lock directory, no snapshot policy and no syslog tagging. Progress is not logged; failures are whatever zfs prints on standard error.

Run-level guard

The guard is evaluated at start-up and again before each pool, so a node that starts shutting down mid-run stops without creating further datasets. It exits 0 silently when /etc/nologin exists or the run level reported by who -r is 0, 1, 5, 6, S or s. OC_IGNORE_RUNLEVEL overrides it.

OPERANDS

ADMIN_ZONE: Host name of the administrative zone or host allowed to mount the shares. Mandatory. It must match [a-zA-Z0-9][a-zA-Z0-9._-]*, because the value is interpolated into the sharenfs option string, where a , or : would append further share options and could widen rw= to other hosts. It must also resolve: the command runs dig ADMIN_ZONE +short and aborts if that produces no answer.

USAGE

The sample crontab in /opt/omnicube/share/README has no entry for init_backup_zfs.sh, because it is a one-shot setup command, not a periodic job. The backup jobs it prepares storage for are the ones listed there, for example:

20 3 * * * /opt/omnicube/sbin/zone_save.sh

Initialise the backup datasets, granting access to the admin zone zadm01.example.com:

pfexec /opt/omnicube/sbin/init_backup_zfs.sh zadm01.example.com

Verify the result:

zfs list -o name,mountpoint,sharenfs -r zethosmariadb01
zfs get -H -o value sharenfs zethosmariadb01/backups

Re-run it after importing a new zone pool; existing datasets are skipped:

pfexec zpool import fserv01-01
pfexec /opt/omnicube/sbin/init_backup_zfs.sh zadm01.example.com

EXIT STATUS

0: The datasets exist and are shared, or nothing needed doing. Also returned silently when the run-level guard aborts the run.
1: No ADMIN_ZONE operand was given ("No admin zone provided"), the name failed validation ("Invalid admin zone name"), or dig could not resolve it ("is not known, aborting").

FILES

/srv/backups: Mount point of the node-level backup dataset.
/srv/backups/pool: Mount point of each zone pool's backups dataset.
/etc/nologin: Presence aborts the run (shutdown in progress).

ENVIRONMENT

OC_IGNORE_RUNLEVEL: When non-empty, bypasses the run-level guard, allowing the command to run in single-user state.
PATH: dig must be on the path, and /usr/bin/ggrep must exist: the existence tests call it by absolute path.

SECURITY

Dataset creation and sharenfs changes run under pfexec, so the caller needs the OmniCube RBAC profile from /etc/security/prof_attr.d/omnicube and /etc/security/exec_attr.d/omnicube. The ADMIN_ZONE validation is the only barrier between an operator typo and an NFS share exported more widely than intended, which is why an unresolvable or oddly punctuated name is a hard error rather than a warning.

NOTES

The "already initialised" tests are substring matches on a recursive zfs list of the pool (backups at node level, /backups at pool level). An unrelated dataset or mount point whose name happens to contain that text suppresses creation for the whole pool, and no message is printed.

Only one ADMIN_ZONE can be granted access per run, and re-running with a different name does not update the shares of datasets that already exist - the pool-level loop skips them. Adjust those with zfs set sharenfs by hand.

The command must be run in the global zone: it manipulates pool-level datasets and NFS shares. It does not check this itself, unlike zone_save.sh(8).