WebSVN – zfs_utils – Diff – /trunk/sneakernet/sneakernet

 # Optionally uses symmetric encryption to encrypt datasets during transport.
 # On the target server, can optionally use GELI to encrypt the datasets on disk.
 # Requires a configuration file in YAML format next to the script.
 # Author: R. W. Rodlico <rodo@dailydata.net>
 # Created: December 2025
+#
 # Revision History:
-# Version: 0.1 2025-12-10 Initial version
+# Version: 0.1 RWR 2025-12-10
+# Development version
+#
+# Version: 1.0 RWR 2025-12-15
+# Tested and ready for initial release
 use strict;
 use warnings;
-our $VERSION = '0.1';
+our $VERSION = '1.0';
 use File::Basename;
 use FindBin;
 use lib "$FindBin::Bin/..";
 use Data::Dumper;
          'dataset' => 'files_share',
       },
+   }
 };
-# read the status file and return as list. If the file doesn't exits, returns an empty list
+## Read the status file and return its lines as an ARRAYREF.
+##
+## Arguments:
+##   $filename - path to the status file (string)
+##
+## Behavior:
+##   - If the file exists and is readable, reads all lines, chomps newlines and returns an ARRAYREF
+##     containing the lines (each line generally holds a fully qualified snapshot name).
+##   - If the file does not exist or cannot be opened, logs a message and returns an empty ARRAYREF.
+##
+## Returns: ARRAYREF of lines (possibly empty).
 sub getStatusFile {
    my $filename = shift;
    # read in history/status file
    my @lines = ();
    if ( -e $filename && open my $fh, '<', $filename ) {
       logMsg("Error: could not read status file '$filename', assuming a fresh start: $!");
+   }
    return \@lines;
+}
-# write the status list to file
+## Write the status list to disk safely.
+##
+## Arguments:
+##   $filename   - path to the status file to write
+##   $statusList - ARRAYREF of lines to write into the file
+##
+## Behavior:
+##   - If an existing file is present, renames it to `$filename.bak` as a simple backup.
+##   - Writes the provided lines to `$filename` (one per line).
+##   - Logs the written contents. Dies on failure to backup or write the file.
 sub writeStatusFile {
    my ( $filename, $statusList ) = @_;
    # backup existing status file
    if ( -e $filename ) {
       rename( $filename, "$filename.bak" ) or do {
       logMsg("Error: could not write status file '$filename': $!");
       die;
+   }
+}
-# simple sub to take root/dataset/datset/dataset and turn it into
+## Convert a path-like dataset name into a filename-safe string.
+##
+## Examples:
+##   'pool/fs/sub' => 'pool.fs.sub' (default)
+##
+## Arguments:
-# dataset.dataset.dataset
+##   $string       - input string to convert
+##   $delimiter    - input delimiter to split on (default: '/')
+##   $substitution - output separator to join with (default: '.')
+##
+## Returns: a joined string suitable for use as a filename.
 sub dirnameToFileName {
    my ( $string, $delimiter, $substitution ) = @_;
    $delimiter //= '/';
    $substitution //= '.';
    my @parts = split( /\Q$delimiter\E/, $string );
    return join( $substitution, @parts );
+}
-# perform replication on source server
+## Perform replication for all configured datasets on the source server.
+##
-# $config - configuration hashref
+## Arguments:
+##   $config     - configuration HASHREF (loaded from YAML). Must contain `datasets` and `transport` entries.
-# $statusList - list of last snapshots replicated for each dataset in previous replications
+##   $statusList - ARRAYREF of previously replicated snapshot full names (used to compute incremental sends)
+##
+## Behavior:
-# return new status list after replication containing updated last snapshots
+##   - Iterates over datasets defined in `$config->{datasets}`.
-# this script will actually replicate the datasets to the sneakernet disk
+##   - For each dataset, enumerates available snapshots on the source and calls
+##     `makeReplicateCommands` to produce zfs send commands.
+##   - Commands are optionally piped through `openssl enc` when `transport.encryption.key` is set.
+##   - The output is written to files on the transport mount point (one file per dataset snapshot set).
+##   - Respects `$config->{dryrun}`: no commands are executed when dryrun is enabled.
+##
+## Returns: ARRAYREF `$newStatus` containing updated status lines (latest snapshots per dataset).
 sub doSourceReplication {
    my ($config, $statusList) = @_;
    my $newStatus = [];
    foreach my $dataset ( sort keys %{$config->{datasets}} ) {
       logMsg("Processing dataset '$dataset'");
       # get list of all snapshots on dataset
       my $sourceList;
-#      print Dumper( $config ) . "\n";
-#      print "$dataset\n";
-#      print Dumper( $config->{datasets}->{$dataset} ) . "\n";
-#      die;
       if ( -e "$scriptDirectory/test.status") {
          $sourceList = getStatusFile( "$scriptDirectory/test.status" );
       } else {
          $sourceList = [ runCmd( "zfs list -rt snap -H -o name $config->{datasets}->{$dataset}->{source}" ) ];
+      }
                      );
       if ( %$commands ) {
          foreach my $cmd ( keys %$commands ) {
             my $command = $commands->{$cmd};
             my $outputFile = $cmd;
-            $outputFile = replaceSlashWithDot($outputFile);
+            my $outfile = dirnameToFileName( $cmd );
             $command .= " | openssl enc -aes-256-cbc -K $config->{transport}->{encryption}->{key} -iv $config->{transport}->{encryption}->{IV} " if $config->{transport}->{encryption}->{key};
-            $command .= " > $config->{transport}->{mount_point}/" . dirnameToFileName( $cmd );
+            $command .= " > $config->{transport}->{mount_point}/$outfile";
             logMsg("Running command: $command");
             runCmd(  $command  ) unless $config->{dryrun};
+         }
       } else {
          logMsg( "Nothing to do for $dataset" );
+      }
+   }
    return $newStatus;
+}
-# perform cleanup actions
+## Perform cleanup and final reporting after replication.
+##
+## Arguments:
-# $config - configuration hashref
+##   $config  - configuration HASHREF (required)
-# $message - optional message to include in the report
+##   $message - OPTIONAL message to include in the report
-#
+##
+## Behavior:
+##   - Logs disk usage for the transport mount and zpool list for diagnostics.
+##   - Ensures the report subject and message are populated, then attempts to unmount
+##     the transport drive and send the report (via `sendReport`).
+##   - If `shutdown_after_replication` is set in the running role's config, attempts
+##     to shut down the machine (honors `$config->{dryrun}`).
 sub cleanup{
    my ( $config, $message ) = @_;
    # add disk space utilization information on transport to the log
    logMsg( "Disk space utilization on transport disk:\n" . runCmd( "df -h $config->{transport}->{mount_point}" ) . "\n" );
    # add information about the server (zpools) to the log
       logMsg( "Shutting down target server as per configuration" );
       runCmd( "shutdown -p now" ) unless $config->{dryrun};
+   }
+}
-# update the target datasets from the files on the transport drive
+## Update the target zfs datasets from files on the transport drive.
+##
+## Arguments:
+##   $config - configuration HASHREF containing `transport` and `datasets` entries.
+##
+## Behavior:
+##   - Reads all regular files from the transport mount point (via `getDirectoryList`).
+##   - For each file, determines the intended target dataset based on the filename and
+##     the `datasets` mapping in the config, optionally decrypts via `openssl enc -d`,
+##     and pipes the stream into `zfs receive -F` to update the target dataset.
+##   - Uses `runCmd` to execute the receive commands and logs the executed command string.
 sub updateTarget {
    my $config = shift;
    my $files = getDirectoryList( $config->{transport}->{mount_point});
    foreach my $filename ( @$files ) {
       my $targetDataset = basename( $filename );

Subversion Repositories zfs_utils

(root)/trunk/sneakernet/sneakernet – Rev 46 → 48