Of course! (head slap) :)

I was already gathering the info, but didn't think of using it to automatically pull the error:

my $ssh_debug = 0;  # verbose logging: 0-3
...
    my $session_log_name = "ssh_$host.log";
    open( my $session_log_fh, ">", $session_log_name )
        or die "Failed to create logfile $session_log_name: $!";
    binmode( $session_log_fh, ":unix" );  # unbuffer log file
...
    $ssh_session{$host} = Net::OpenSSH->new(
        # host
        $host,
        # automatically add new host keys to the user known hosts file
+s
        # enable verbosity, if enabled
        master_opts => ($ssh_debug)
        ? [ -o => "StrictHostKeyChecking=no", "-" . "v" x $ssh_debug ]
        : [ -o => "StrictHostKeyChecking=no" ],
        # authentication
        user             => $username,
        password         => $password,
        # logging
        master_stderr_fh => $session_log_fh,
        # connection parameters
        timeout          => $loginTO,
        port             => $ssh_port,
        async            => 1
    );
}
[download]

The '-v' to enable debugging is not required in this case, as the error message (or nothing) will be written to the file with $ssh_debug = 0. I believe the important concept here is the cause of error message always appears to be the last line output to the master_stderr_fh file. Something like the following (combined with the above) appears to provide a more accurate error message:

        elsif ( $ssh->error ) {
            # handle connection error
            my $lasterr = File::ReadBackwards->new("ssh_$host.log")->r
+eadline;
            # ... something that outputs or logs the error message
        }
[download]

It should be noted there will be a linefeed on the end of $lasterr (it's left up to the user to chomp it off if they don't want it).

It should also be noted that master_stderr_fh cannot be assigned to an in-memory file, or the following error will be received:

Not a GLOB reference at /usr/local/share/perl/5.14.2/Net/OpenSSH.pm li
+ne 614.

 612 sub _check_is_system_fh {
 613     my ($name, $fh) = @_;
 614     my $fn = fileno(defined $fh ? $fh : $name);
 615     defined $fn and $fn >= 0 and return;
 616     croak "child process $name is not a real system file handle";
 617 }
[download]

Thanks again. The full solution will be posted when it is done (I'm juggling a couple of other things while doing this, so sorry it's taking a while).