WebSVN – zfs_utils – Diff – /trunk/ZFS_Utils.pm

 use Data::Dumper;
 use POSIX qw(strftime);
 use File::Path qw(make_path);
 # library of ZFS related utility functions
-# Copyright 2024 Daily Data Inc. <rodo@dailydata.net>
+# Copyright 2025 Daily Data Inc. <rodo@dailydata.net>
 # currently used for sneakernet scripts, but plans to expand to other ZFS related tasks
 # functions include:
-#   runCmd: execute a command and return its output
+#   runCmd: execute a command and return its output (captures exit status in $lastRunError;
+#           supports optional stderr merge via $merge_stderr)
-#   shredFile: securely delete a file using gshred
+#   shredFile: securely delete a file using gshred (note: not effective on ZFS due to COW)
-#   logMsg: log messages to a log file and optionally to console
+#   logMsg: timestamped logging to a file and optionally to console
+#   loadConfig: load a YAML configuration file into a hashref; will create the file from a
+#           provided default hashref if the file does not exist (uses YAML::XS or YAML::Tiny)
-#   mountDriveByLabel: find and mount a drive by its GPT label
+#   mountDriveByLabel: find and mount a drive by its GPT label (supports ufs/msdos; waits
-#   loadConfig: load a YAML configuration file into a hashref
+#           for device and creates mountpoint)
+#   unmountDriveByLabel: unmount a drive found by GPT label and remove the mountpoint if empty
-#   mountGeli: decrypt and mount a GELI encrypted ZFS pool
+#   mountGeli: high level orchestrator to decrypt multiple GELI devices and import/mount a ZFS pool
+#   decryptAndMountGeli: attach GELI devices, optionally build a combined key, import the pool
+#           and mount ZFS datasets
-#   makeGeliKey: create a GELI key by XOR'ing a remote binary keyfile and a local hex key
+#   makeGeliKey: create a GELI key by XOR'ing a remote binary keyfile and a local 256-bit hex key;
-#   decryptAndMountGeli: decrypt GELI disks and mount the ZFS pool
+#           writes a 32-byte binary key file with mode 0600
-#   findGeliDisks: find available disks for GELI/ZFS use
+#   findGeliDisks: discover candidate disks suitable for GELI on the host
-#   makeReplicateCommands: create zfs send commands for replication based on snapshot lists
+#   makeReplicateCommands: build zfs send/receive command lists from snapshot lists and prior status
+#   sendReport: helper to deliver replication reports (email/file) — exported for scripts to implement
+#   fatalError: helper to log a fatal condition and die (convenience wrapper)
+#   getDirectoryList: utility to list directory contents with optional filters
+#   cleanDirectory: safe directory cleaning utility used by snapshot pruning helpers
+#   exported package variables: $logFileName, $displayLogsOnConsole, $lastRunError
+# v1.0 RWR 20251215
+# This is the initial, tested release
 # Exported functions and variables
 our @EXPORT_OK = qw(loadConfig shredFile mountDriveByLabel unmountDriveByLabel mountGeli logMsg runCmd makeReplicateCommands sendReport fatalError getDirectoryList cleanDirectory $logFileName $displayLogsOnConsole $lastRunError);
+our $VERSION = '1.0';
-our $VERSION = '0.2';
+# these are variables which affect the flow of the program and are exported so they can be modified by the caller
 our $logFileName = '/tmp/zfs_utils.log'; # this can be overridden by the caller, and turned off with empty string
 our $displayLogsOnConsole = 1; # if non-zero, log messages are also printed to console
 our $merge_stderr = 0; # if set to 1, stderr is captured in runCmd
 our $lastRunError = 0; # tracks the last error code from runCmd
    return $yaml;
+}
-# Mount a GELI-encrypted ZFS pool.
+## Mount a GELI-encrypted ZFS pool (high-level orchestration).
+##
+## Arguments:
-# $geliConfig - hashref containing configuration for geli
+##   $geliConfig - HASHREF containing GELI/ZFS mounting configuration. Expected keys include:
+##       poolname        - name of the zpool to import
+##       secureKey       - HASHREF with { label, keyfile, path } describing the keyfile disk
+##       target          - path where the combined keyfile will be written
+##       diskList        - OPTIONAL arrayref of disk device names (eg: ['ada0','ada1'])
+##
+## Behavior:
+##   - Mounts the keyfile disk (using mountDriveByLabel), builds the combined key (makeGeliKey),
+##     then calls decryptAndMountGeli to attach geli devices and import/mount the zpool.
+##
+## Returns:
-# Returns the pool name on success, empty string on error.
+##   Pool name (string) on success, empty string on error.
 sub mountGeli {
    my $geliConfig = shift;
    logMsg( "geli config detected, attempting to mount geli disks" );
    # Can't continue at all if no pool name
    my $poolname = decryptAndMountGeli( $geliConfig );
    return $poolname;
+}
-# find all disks which are candidates for use with geli/zfs
+## Discover disks suitable for GELI/ZFS use on the host.
+##
+## Returns an array of device names (eg: qw( ada0 ada1 )) that appear free for use.
-# Grabs all disks on the system, then removes those with partitions
+## The routine collects all disks, excludes disks with existing partitions and those
-# and those already used in zpools.
+## referenced by active zpools.
 sub findGeliDisks {
    logMsg("Finding available disks for GELI/ZFS use");
    # get all disks in system
    my %allDisks = map{ chomp $_ ; $_ => 1 } runCmd( "geom disk list | grep 'Geom name:' | rev | cut -d' ' -f1 | rev" );
    # get the disks with partitions
    # return only the disks which are free (value 1)
    return grep{ $allDisks{$_} == 1 } keys %allDisks;
+}
+## Decrypt GELI-encrypted disks and import/mount the ZFS pool.
+##
+## Arguments:
+##   $geliConfig - HASHREF expected to contain:
+##       poolname - zpool name to import
+##       target   - path to the combined GELI keyfile created by makeGeliKey
+##       diskList - OPTIONAL arrayref of disk device names (if omitted, findGeliDisks() is used)
+##
+## Behavior:
+##   - Ensures the pool is not already imported
-## Decrypt each GELI disk from $geliConfig->{'diskList'} using the keyfile,
+##   - Attaches (geli attach) each supplied disk using the keyfile
-## then import and mount the ZFS pool specified in $geliConfig->{'poolname'}.
+##   - Attempts to import the specified pool and runs `zfs mount -a` to mount datasets
 ##
+## Returns:
-## Returns the pool name on success, empty on error.
+##   Pool name (string) on success; empty string on failure.
 sub decryptAndMountGeli {
    my ($geliConfig) = shift;
    # if no list of disks provided, try to find them
    $geliConfig->{'diskList'} //= [ findGeliDisks() ];
    return $poolname;
+}
 ## Create a GELI key by XOR'ing a remote binary keyfile and a local key (hex string).
 ##
-## Arguments:
+## Expected input (via $geliConfig HASHREF):
-##   $remote_keyfile - path to binary keyfile (32 bytes)
+##   $geliConfig->{secureKey}->{path} - directory where the remote keyfile resides
+##   $geliConfig->{secureKey}->{keyfile} - filename of the remote 32-byte binary key
-##   $localKeyHexOrPath - hex string (64 hex chars) or path to file containing hex
+##   $geliConfig->{localKey} - 64-hex char string OR path to a file containing the hex
-##   $target - path to write the resulting 32-byte binary key
+##   $geliConfig->{target} - path to write the resulting 32-byte binary key
+##
+## Behavior:
+##   - Reads 32 bytes from the remote binary key
+##   - Reads/cleans the 64-hex local key and converts it to 32 bytes
+##   - XORs the two 32-byte buffers and writes the 32-byte result to $target with mode 0600
 ##
-## Returns true on success, dies on fatal error.
+## Returns: 1 on success. Dies on unrecoverable errors.
 sub makeGeliKey {
    my ( $geliConfig ) = @_;
    $geliConfig->{secureKey}->{keyfile} //= '';
    $geliConfig->{localKey} //= '';
       $reportConfig->{subject} //= 'Replication Report from ' . `hostname`;
       sendEmailReport( $reportConfig->{email}, $reportConfig->{subject}, $message, $logFile );
+   }
+}
-# Copy the report log file to the specified mount point.
+## Copy the report log file to a mounted target drive.
+##
+## Arguments:
-# $logFile is the path to the log file to copy.
+##   $logFile    - path to the log file to copy (must exist)
-# $mountPoint is the mount point of the target drive.
+##   $mountPoint - mount point of the target drive (must be a directory)
+##
+## Behavior:
-# Does nothing if log file or mount point are invalid.
+##   - Copies the log file into the root of $mountPoint using File::Copy::copy
+##   - Logs success/failure via logMsg
 sub copyReportToDrive {
    my ( $logFile, $mountPoint ) = @_;
    return unless defined $logFile && -e $logFile;
    return unless defined $mountPoint && -d $mountPoint;
    unless ( copy( $logFile, $targetFile ) ) {
       logMsg( "Could not copy report log file to target drive: $!" );
+   }
+}
-# Send an email report with the contents of the log file.
+## Send an email report with an attached log body.
+##
+## Arguments:
-# $to is the recipient email address.
+##   $to      - recipient email address (string)
-# $subject is the email subject.
+##   $subject - subject line (string)
+##   $message - optional message body (string)
+##   $logFile - optional path to log file whose contents will be appended to the email body
+##
+## Behavior:
+##   - Opens /usr/sbin/sendmail -t and writes a simple plain-text email including the
-# $logFile is the path to the log file to send.
+##     supplied message and the contents of $logFile (if present).
-# Does nothing if any parameter is invalid.
+##   - Logs failures to open sendmail or read the log file.
 sub sendEmailReport {
    my ( $to, $subject, $message, $logFile ) = @_;
    return unless defined $to && $to ne '';
    $subject //= 'Sneakernet Replication Report from ' . `hostname`;
    $message //= '';
    };
    close $mailfh;
+}
-# Get all file names (not directories) from a directory
+## Return list of regular files in a directory (non-recursive).
+##
+## Arguments:
-# $dirname is directory to scan
+##   $dirname - directory to scan
+##
-# returns arrayref
+## Returns: ARRAYREF of full-path filenames on success, 0 on error (matching prior behavior).
 sub getDirectoryList {
    my $dirname = shift;
    opendir( my $dh, $dirname ) || return 0;
    # get all file names, but leave directories alone
    my @files = map{ $dirname . "/$_" } grep { -f "$dirname/$_" } readdir($dh);
    closedir $dh;
    return \@files;
+}
-# clean all files from a directory, but not any subdirectories
+## Remove all regular files from the specified directory (non-recursive).
+##
+## Arguments:
+##   $dirname - directory to clean
+##
+## Behavior:
+##   - Calls getDirectoryList to obtain files and unlinks each file. Directories are left untouched.
+##   - Logs the cleanup operation via logMsg.
+##
+## Returns: 1 on completion. Note: individual unlink failures are currently reported via warn.
 sub cleanDirectory {
    my $dirname = shift;
    logMsg( "Cleaning up $dirname of all files" );
    my $files = getDirectoryList( $dirname );
    # clean up a directory
       unlink $file or warn "Could not unlink $file: #!\n";
+   }
    return 1;
+}
-# handle fatal error by logging message and dying
+## Handle a fatal error: log, optionally run a cleanup routine, then die.
+##
+## Arguments:
-# message - message to log, and also sent via email if applicable
+##   $message        - string message describing the fatal condition
-# config - configuration hashref (optional)
+##   $config         - OPTIONAL configuration HASHREF (passed to cleanupRoutine)
-# cleanupRoutine - code reference to cleanup routine (optional)
+##   $cleanupRoutine - OPTIONAL CODE ref to run prior to dying; will be called as
+##                     $cleanupRoutine->($config, $message)
+##
+## Behavior:
-# if cleanupRoutine is provided, it will be called before dying passing it the config hashref
+##   - Logs the fatal message via logMsg, runs the cleanup code if provided (errors in the cleanup
+##     are logged), then terminates the process via die.
 sub fatalError {
    my ( $message, $config, $cleanupRoutine ) = @_;
    logMsg( "FATAL ERROR: $message" );
    if ( defined $cleanupRoutine && ref $cleanupRoutine eq 'CODE' ) {
       logMsg( "Running cleanup routine before fatal error" );

Subversion Repositories zfs_utils

(root)/trunk/ZFS_Utils.pm – Rev 46 → 48