← Back to branch summary

~ubuntu-branches/ubuntu/utopic/libnet-openssh-perl/utopic

« back to all changes in this revision

Viewing changes to lib/Net/OpenSSH.pm

  • Committer: Package Import Robot
  • Author(s): Florian Schlichting, Salvatore Bonaccorso, Florian Schlichting
  • Date: 2013-04-30 23:44:13 UTC
  • mfrom: (1.1.1)
  • Revision ID: package-import@ubuntu.com-20130430234413-ox0512zbclrs71g9
Tags: 0.60-1
[ Salvatore Bonaccorso ]
* Change Vcs-Git to canonical URI (git://anonscm.debian.org)
* Change search.cpan.org based URIs to metacpan.org based URIs

[ Florian Schlichting ]
* Imported Upstream version 0.60
* Email change: Florian Schlichting -> fsfs@debian.org
* Bumped Standards-Version to 3.9.4 (use copyright-format 1.0)
* Bumped copyright years
* Dropped fix_pod_spelling.patch, applied upstream
* New spelling.patch

Show diffs side-by-side

added added

removed removed

Lines of Context:
lib/Net/OpenSSH.pm
1
1
package Net::OpenSSH;
2
2
 
3
 
our $VERSION = '0.57';
 
3
our $VERSION = '0.60';
4
4
 
5
5
use strict;
6
6
use warnings;
240
240
    my $ssh_cmd = _first_defined delete $opts{ssh_cmd}, 'ssh';
241
241
    my $rsync_cmd = _first_defined delete $opts{rsync_cmd}, 'rsync';
242
242
    my $scp_cmd = delete $opts{scp_cmd};
 
243
    my $sshfs_cmd = _first_defined delete $opts{sshfs_cmd}, 'sshfs';
 
244
    my $sftp_server_cmd = _first_defined delete $opts{sftp_server_cmd},
 
245
                                         '/usr/lib/openssh/sftp-server';
243
246
    my $timeout = delete $opts{timeout};
244
247
    my $kill_ssh_on_timeout = delete $opts{kill_ssh_on_timeout};
245
248
    my $strict_mode = _first_defined delete $opts{strict_mode}, 1;
252
255
        _first_defined delete $opts{default_stream_encoding}, $default_encoding;
253
256
    my $default_argument_encoding =
254
257
        _first_defined delete $opts{default_argument_encoding}, $default_encoding;
 
258
    my $forward_agent = delete $opts{forward_agent};
 
259
    $forward_agent and $passphrase and
 
260
        croak "agent forwarding can not be used when a passphrase has also been given";
255
261
 
256
262
    my ($master_opts, @master_opts,
257
263
        $master_stdout_fh, $master_stderr_fh,
311
317
    push @ssh_opts, -p => $port if defined $port;
312
318
 
313
319
    my $home = do {
314
 
        local $SIG{__DIE__};
315
 
        local $@;
 
320
        local ($@, $SIG{__DIE__});
316
321
        eval { Cwd::realpath((getpwuid $>)[7]) }
317
322
    };
318
323
 
329
334
                 _ssh_cmd => $ssh_cmd,
330
335
                 _scp_cmd => $scp_cmd,
331
336
                 _rsync_cmd => $rsync_cmd,
 
337
                 _sshfs_cmd => $sshfs_cmd,
 
338
                 _sftp_server_cmd => $sftp_server_cmd,
332
339
                 _pid => undef,
333
340
                 _host => $host,
334
341
                 _host_squared => $host_squared,
344
351
                 _kill_ssh_on_timeout => $kill_ssh_on_timeout,
345
352
                 _batch_mode => $batch_mode,
346
353
                 _home => $home,
 
354
                 _forward_agent => $forward_agent,
347
355
                 _external_master => $external_master,
348
356
                 _default_ssh_opts => $default_ssh_opts,
349
357
                 _default_stdin_fh => $default_stdin_fh,
357
365
                 _default_stream_encoding => $default_stream_encoding,
358
366
                 _default_argument_encoding => $default_argument_encoding,
359
367
                 _expand_vars => $expand_vars,
360
 
                 _vars => $vars };
 
368
                 _vars => $vars,
 
369
               };
361
370
    bless $self, $class;
362
371
 
363
372
    # default file handles are opened so late in order to have the
492
501
        }
493
502
        my ($mode, $uid) = (stat $dir)[2, 4];
494
503
        $debug and $debug & 2 and _debug "_is_secure_path(dir: $dir, file mode: $mode, file uid: $uid, euid: $>";
495
 
        return undef unless(($uid == $> or $uid == 0 ) and (($mode & 022) == 0));
 
504
        return undef unless(($uid == $> or $uid == 0 ) and (($mode & 022) == 0 or ($mode & 01000)));
496
505
        return 1 if (defined $home and $home eq $dir);
497
506
    }
498
507
    return 1;
503
512
    my @before = @{shift || []};
504
513
    my @args = ($self->{_ssh_cmd}, @before,
505
514
                -S => $self->{_ctl_path},
506
 
                @{$self->{_ssh_opts}}, $self->{_host_squared},
 
515
                @{$self->{_ssh_opts}}, $self->{_host},
507
516
                '--',
508
517
                (@_ ? "@_" : ()));
509
518
    $debug and $debug & 8 and _debug_dump 'call args' => \@args;
655
664
        push @master_opts, -i => $self->{_key_path};
656
665
    }
657
666
 
 
667
    if (defined $self->{_forward_agent}) {
 
668
        push @master_opts, ($self->{_forward_agent} ? '-A' : '-a');
 
669
    }
 
670
 
658
671
    my $proxy_command = $self->{_proxy_command};
659
672
 
660
673
    my $gateway;
701
714
        return undef;
702
715
    }
703
716
    unless ($pid) {
 
717
        if ($debug and $debug & 512) {
 
718
            require Net::OpenSSH::OSTracer;
 
719
            Net::OpenSSH::OSTracer->trace;
 
720
        }
 
721
 
704
722
        $mpty->make_slave_controlling_terminal if $mpty;
705
723
 
706
724
        $self->_master_redirect('STDOUT');
707
725
        $self->_master_redirect('STDERR');
708
726
 
709
 
        if (defined $self->{_passwd}) {
710
 
            delete $ENV{SSH_ASKPASS};
711
 
            delete $ENV{SSH_AUTH_SOCK};
712
 
        }
 
727
        delete $ENV{SSH_ASKPASS} if defined $self->{_passwd};
 
728
        delete $ENV{SSH_AUTH_SOCK} if defined $self->{_passphrase};
713
729
 
714
730
        local $SIG{__DIE__};
715
731
        eval { exec @call };
894
910
            return undef;
895
911
        }
896
912
        if ($state eq 'waiting_for_login_handler') {
897
 
            local $SIG{__DIE__};
898
 
            local $@;
 
913
            local ($@, $SIG{__DIE__});
899
914
            if (eval { $login_handler->($self, $mpty, $bout) }) {
900
915
                $state = 'waiting_for_mux_socket';
901
916
                next;
956
971
                     stderr_to_stdout => 1, ssh_opts => [-O => $cmd]});
957
972
}
958
973
 
 
974
sub stop {
 
975
    # FIXME: this method currently fails because of a bug in ssh.
 
976
    my ($self, $timeout) = @_;
 
977
    my $pid = $self->{_pid};
 
978
    $self->_master_ctl('stop');
 
979
    if (not $self->error           and
 
980
        $pid                       and
 
981
        $self->{_perl_pid} == $$   and
 
982
        $self->{_thread_generation} == $thread_generation) {
 
983
 
 
984
        local $self->{_kill_ssh_on_timeout};
 
985
        if ($self->_waitpid($pid, $timeout)) {
 
986
            delete $self->{_pid};
 
987
            $self->_set_error(OSSH_MASTER_FAILED, "master ssh connection stopped");
 
988
            return 1;
 
989
        }
 
990
        else {
 
991
            return $self->_kill_master;
 
992
        }
 
993
    }
 
994
    undef;
 
995
}
 
996
 
959
997
sub _make_pipe {
960
998
    my $self = shift;
961
999
    my ($r, $w);
975
1013
    my ($module, $version) = @_;
976
1014
    $loaded_module{$module} ||= do {
977
1015
        do {
978
 
            local $SIG{__DIE__};
979
 
            local $@;
 
1016
            local ($@, $SIG{__DIE__});
980
1017
            eval "require $module; 1"
981
1018
        } or croak "unable to load Perl module $module";
982
1019
        1
983
1020
    };
984
1021
    if (defined $version) {
985
 
        local $SIG{__DIE__};
986
 
        local $@;
 
1022
        local ($@, $SIG{__DIE__});
987
1023
        my $mv = eval "\$${module}::VERSION" || 0;
988
1024
        (my $mv1 = $mv) =~ s/_\d*$//;
989
1025
        croak "$module version $version required, $mv is available"
1117
1153
    my @ssh_opts = _array_or_scalar_to_list delete $opts{ssh_opts};
1118
1154
    my $tty = delete $opts{tty};
1119
1155
    push @ssh_opts, ($tty ? '-qtt' : '-T') if defined $tty;
 
1156
    if ($self->{_forward_agent}) {
 
1157
        my $forward_agent = delete $opts{forward_agent};
 
1158
        push @ssh_opts, ($forward_agent ? '-A' : '-a') if defined $forward_agent;
 
1159
    }
1120
1160
    my $tunnel = delete $opts{tunnel};
1121
1161
    my (@args);
1122
1162
    if ($tunnel) {
1206
1246
    $self->wait_for_master or return;
1207
1247
    my %opts = (ref $_[0] eq 'HASH' ? %{shift()} : ());
1208
1248
    my $tunnel = delete $opts{tunnel};
1209
 
    my ($stdinout_socket, $stdinout_dpipe_is_parent);
 
1249
    my ($stdinout_socket, $stdinout_dpipe_make_parent);
1210
1250
    my $stdinout_dpipe = delete $opts{stdinout_dpipe};
1211
1251
    if ($stdinout_dpipe) {
1212
 
        $stdinout_dpipe_is_parent = delete $opts{stdinout_dpipe_is_parent};
 
1252
        $stdinout_dpipe_make_parent = delete $opts{stdinout_dpipe_make_parent};
1213
1253
        $stdinout_socket = 1;
1214
1254
    }
1215
1255
    else {
1243
1283
      $stderr_file = delete $opts{stderr_file} );
1244
1284
 
1245
1285
    my $argument_encoding = $self->_delete_argument_encoding(\%opts);
1246
 
 
1247
1286
    my $ssh_opts = delete $opts{ssh_opts};
1248
1287
    $ssh_opts = $self->{_default_ssh_opts} unless defined $ssh_opts;
1249
1288
    my @ssh_opts = $self->_expand_vars(_array_or_scalar_to_list $ssh_opts);
1250
1289
 
 
1290
    if ($self->{_forward_agent}) {
 
1291
        my $forward_agent = delete $opts{forward_agent};
 
1292
        push @ssh_opts, ($forward_agent ? '-A' : '-a') if defined $forward_agent;
 
1293
    }
 
1294
 
1251
1295
    my ($cmd, $close_slave_pty, @args);
1252
1296
    if ($tunnel) {
1253
1297
        @_ == 2 or croak 'bad number of arguments for tunnel, use $ssh->method(\\%opts, $host, $port)';
1363
1407
            my $pid1 = fork;
1364
1408
            defined $pid1 or POSIX::_exit(255);
1365
1409
 
1366
 
            unless ($pid1 xor $stdinout_dpipe_is_parent) {
 
1410
            unless ($pid1 xor $stdinout_dpipe_make_parent) {
1367
1411
                eval { $self->_exec_dpipe($stdinout_dpipe, $win, $werr) };
1368
1412
                POSIX::_exit(255);
1369
1413
            }
1454
1498
    my $self = shift;
1455
1499
    my $enc = shift;
1456
1500
    if (defined $enc and @_) {
1457
 
        local $@;
 
1501
        local ($@, $SIG{__DIE__});
1458
1502
        eval {
1459
1503
            for (@_) {
1460
1504
                defined or next;
1484
1528
sub _decode {
1485
1529
    my $self = shift;
1486
1530
    my $enc = shift;
1487
 
    local $@;
 
1531
    local ($@, $SIG{__DIE__});
1488
1532
    eval {
1489
1533
        for (@_) {
1490
1534
            defined or next;
1621
1665
 
1622
1666
_sub_options spawn => qw(stderr_to_stdout stdin_discard stdin_fh stdin_file stdout_discard
1623
1667
                         stdout_fh stdout_file stderr_discard stderr_fh stderr_file
1624
 
                         stdinout_dpipe stdintout_dpipe_is_parent quote_args tty ssh_opts tunnel
1625
 
                         encoding argument_encoding);
 
1668
                         stdinout_dpipe stdinout_dpipe_make_parent quote_args tty ssh_opts tunnel
 
1669
                         encoding argument_encoding forward_agent);
1626
1670
sub spawn {
1627
1671
    ${^TAINT} and &_catch_tainted_args;
1628
1672
    my $self = shift;
1633
1677
}
1634
1678
 
1635
1679
_sub_options open2 => qw(stderr_to_stdout stderr_discard stderr_fh stderr_file quote_args
1636
 
                         tty ssh_opts tunnel encoding argument_encoding);
 
1680
                         tty ssh_opts tunnel encoding argument_encoding forward_agent);
1637
1681
sub open2 {
1638
1682
    ${^TAINT} and &_catch_tainted_args;
1639
1683
    my $self = shift;
1648
1692
}
1649
1693
 
1650
1694
_sub_options open2pty => qw(stderr_to_stdout stderr_discard stderr_fh stderr_file quote_args tty
1651
 
                            close_slave_pty ssh_opts encoding argument_encoding);
 
1695
                            close_slave_pty ssh_opts encoding argument_encoding forward_agent);
1652
1696
sub open2pty {
1653
1697
    ${^TAINT} and &_catch_tainted_args;
1654
1698
    my $self = shift;
1664
1708
}
1665
1709
 
1666
1710
_sub_options open2socket => qw(stderr_to_stdout stderr_discard stderr_fh stderr_file quote_args tty
1667
 
                               ssh_opts tunnel encoding argument_encoding);
 
1711
                               ssh_opts tunnel encoding argument_encoding forward_agent);
1668
1712
sub open2socket {
1669
1713
    ${^TAINT} and &_catch_tainted_args;
1670
1714
    my $self = shift;
1677
1721
    return ($socket, $pid);
1678
1722
}
1679
1723
 
1680
 
_sub_options open3 => qw(quote_args tty ssh_opts encoding argument_encoding);
 
1724
_sub_options open3 => qw(quote_args tty ssh_opts encoding argument_encoding forward_agent);
1681
1725
sub open3 {
1682
1726
    ${^TAINT} and &_catch_tainted_args;
1683
1727
    my $self = shift;
1694
1738
}
1695
1739
 
1696
1740
_sub_options open3pty => qw(quote_args tty close_slave_pty ssh_opts
1697
 
                            encoding argument_encoding);
 
1741
                            encoding argument_encoding forward_agent);
1698
1742
sub open3pty {
1699
1743
    ${^TAINT} and &_catch_tainted_args;
1700
1744
    my $self = shift;
1713
1757
 
1714
1758
_sub_options system => qw(stdout_discard stdout_fh stdin_discard stdout_file stdin_fh stdin_file
1715
1759
                          quote_args stderr_to_stdout stderr_discard stderr_fh stderr_file
1716
 
                          stdinout_dpipe stdinout_dpipe_is_parent tty ssh_opts tunnel encoding
1717
 
                          argument_encoding);
 
1760
                          stdinout_dpipe stdinout_dpipe_make_parent tty ssh_opts tunnel encoding
 
1761
                          argument_encoding forward_agent);
1718
1762
sub system {
1719
1763
    ${^TAINT} and &_catch_tainted_args;
1720
1764
    my $self = shift;
1742
1786
 
1743
1787
_sub_options test => qw(stdout_discard stdout_fh stdin_discard stdout_file stdin_fh stdin_file
1744
1788
                        quote_args stderr_to_stdout stderr_discard stderr_fh stderr_file
1745
 
                        stdinout_dpipe stdinout_dpipe_is_parent stdtty ssh_opts timeout stdin_data
1746
 
                        encoding stream_encoding argument_encoding);
 
1789
                        stdinout_dpipe stdinout_dpipe_make_parent tty ssh_opts timeout stdin_data
 
1790
                        encoding stream_encoding argument_encoding forward_agent);
1747
1791
sub test {
1748
1792
    ${^TAINT} and &_catch_tainted_args;
1749
1793
    my $self = shift;
1768
1812
 
1769
1813
_sub_options capture => qw(stderr_to_stdout stderr_discard stderr_fh stderr_file
1770
1814
                           stdin_discard stdin_fh stdin_file quote_args tty ssh_opts tunnel
1771
 
                           encoding argument_encoding);
 
1815
                           encoding argument_encoding forward_agent);
1772
1816
sub capture {
1773
1817
    ${^TAINT} and &_catch_tainted_args;
1774
1818
    my $self = shift;
1795
1839
    $output
1796
1840
}
1797
1841
 
1798
 
_sub_options capture2 => qw(stdin_discard stdin_fh stdin_file quote_args tty ssh_opts encoding argument_encoding);
 
1842
_sub_options capture2 => qw(stdin_discard stdin_fh stdin_file
 
1843
                            quote_args tty ssh_opts encoding
 
1844
                            argument_encoding forward_agent);
1799
1845
sub capture2 {
1800
1846
    ${^TAINT} and &_catch_tainted_args;
1801
1847
    my $self = shift;
1819
1865
    wantarray ? @capture : $capture[0];
1820
1866
}
1821
1867
 
1822
 
_sub_options open_tunnel => qw(ssh_opts stderr_discard stderr_fh stderr_file encoding argument_encoding);
 
1868
_sub_options open_tunnel => qw(ssh_opts stderr_discard stderr_fh stderr_file encoding argument_encoding forward_agent);
1823
1869
sub open_tunnel {
1824
1870
    ${^TAINT} and &_catch_tainted_args;
1825
1871
    my $self = shift;
1833
1879
 
1834
1880
_sub_options capture_tunnel => qw(ssh_opts stderr_discard stderr_fh stderr_file stdin_discard
1835
1881
                                  stdin_fh stdin_file stdin_data timeout encoding stream_encoding
1836
 
                                  argument_encoding);
 
1882
                                  argument_encoding forward_agent);
1837
1883
sub capture_tunnel {
1838
1884
    ${^TAINT} and &_catch_tainted_args;
1839
1885
    my $self = shift;
1918
1964
sub scp_put {
1919
1965
    ${^TAINT} and &_catch_tainted_args;
1920
1966
    my ($self, $opts, $target, @src) = _scp_put_args @_;
 
1967
    return unless $self;
1921
1968
    $self->_scp($opts, @src, $target);
1922
1969
}
1923
1970
 
1924
1971
sub rsync_put {
1925
1972
    ${^TAINT} and &_catch_tainted_args;
1926
1973
    my ($self, $opts, $target, @src) = _scp_put_args @_;
 
1974
    return unless $self;
1927
1975
    $self->_rsync($opts, @src, $target);
1928
1976
}
1929
1977
 
1930
1978
_sub_options _scp => qw(stderr_to_stdout stderr_discard stderr_fh
1931
1979
                        stderr_file stdout_discard stdout_fh
1932
 
                        stdout_file encoding argument_encoding);
 
1980
                        stdout_file encoding argument_encoding
 
1981
                        forward_agent);
1933
1982
sub _scp {
1934
1983
    my $self = shift;
1935
1984
    my %opts = (ref $_[0] eq 'HASH' ? %{shift()} : ());
2060
2109
}
2061
2110
 
2062
2111
_sub_options sftp => qw(autoflush timeout argument_encoding encoding block_size
2063
 
                        queue_size late_set_perm);
 
2112
                        queue_size late_set_perm forward_agent);
2064
2113
 
2065
2114
sub sftp {
2066
2115
    ${^TAINT} and &_catch_tainted_args;
2094
2143
    $sftp
2095
2144
}
2096
2145
 
 
2146
_sub_options sshfs_import => qw(stderr_discard stderr_fh stderr_file
 
2147
                                ssh_opts argument_encoding sshfs_opts);
 
2148
sub sshfs_import {
 
2149
    ${^TAINT} and &_catch_tainted_args;
 
2150
    my $self = shift;
 
2151
    my %opts = (ref $_[0] eq 'HASH' ? %{shift()} : ());
 
2152
    @_ == 2 or croak 'Usage: $ssh->sshfs_import(\%opts, $remote, $local)';
 
2153
    my ($from, $to) = @_;
 
2154
    my @sshfs_opts = ( -o => 'slave',
 
2155
                       _array_or_scalar_to_list delete $opts{sshfs_opts} );
 
2156
    _croak_bad_options %opts;
 
2157
 
 
2158
    $opts{ssh_opts} = ['-s', _array_or_scalar_to_list delete $opts{ssh_opts}];
 
2159
    $opts{stdinout_dpipe} = [$self->{_sshfs_cmd}, "$self->{_host_squared}:$from", $to, @sshfs_opts];
 
2160
    $opts{stdinout_dpipe_make_parent} = 1;
 
2161
    $self->spawn(\%opts, 'sftp');
 
2162
}
 
2163
 
 
2164
_sub_options sshfs_export => qw(stderr_discard stderr_fh stderr_file
 
2165
                                ssh_opts argument_encoding sshfs_opts);
 
2166
sub sshfs_export {
 
2167
    ${^TAINT} and &_catch_tainted_args;
 
2168
    my $self = shift;
 
2169
    my %opts = (ref $_[0] eq 'HASH' ? %{shift()} : ());
 
2170
    @_ == 2 or croak 'Usage: $ssh->sshfs_export(\%opts, $local, $remote)';
 
2171
    my ($from, $to) = @_;
 
2172
    my @sshfs_opts = ( -o => 'slave',
 
2173
                       _array_or_scalar_to_list delete $opts{sshfs_opts} );
 
2174
    _croak_bad_options %opts;
 
2175
    $opts{stdinout_dpipe} = $self->{_sftp_server_cmd};
 
2176
 
 
2177
    my $hostname = eval {
 
2178
        require Sys::Hostname;
 
2179
        Sys::Hostname::hostname();
 
2180
    };
 
2181
    $hostname = 'remote' if (not defined $hostname   or
 
2182
                             not length $hostname    or
 
2183
                             $hostname=~/^localhost\b/);
 
2184
    $self->spawn(\%opts, $self->{_sshfs_cmd}, "$hostname:$from", $to, @sshfs_opts);
 
2185
}
 
2186
 
2097
2187
sub DESTROY {
2098
2188
    my $self = shift;
2099
2189
    my $pid = $self->{_pid};
2100
 
    local $@;
 
2190
    local ($@, $SIG{__DIE__});
2101
2191
    $debug and $debug & 2 and _debug("DESTROY($self, pid: ", $pid, ")");
2102
2192
    if ($pid and $self->{_perl_pid} == $$ and $self->{_thread_generation} == $thread_generation) {
2103
2193
        $debug and $debug & 32 and _debug("killing master");
2104
 
        local $?;
2105
 
        local $!;
2106
 
 
 
2194
        local ($?, $!);
2107
2195
        unless ($self->{_wfm_state}) {
2108
2196
            # we have successfully created the master connection so we
2109
2197
            # can send control commands:
2315
2403
bad idea. When possible, you should use public key authentication
2316
2404
instead.
2317
2405
 
 
2406
 
2318
2407
=item passphrase => $passphrase
2319
2408
 
2320
 
Uses given passphrase to open private key.
 
2409
X<passphrase>Uses given passphrase to open private key.
2321
2410
 
2322
2411
=item key_path => $private_key_path
2323
2412
 
2436
2525
For instance:
2437
2526
 
2438
2527
  my $ssh = Net::OpenSSH->new($host,
2439
 
      default_ssh_options => [-o => "ConnectionAttempts=0"]);
 
2528
      default_ssh_opts => [-o => "ConnectionAttempts=0"]);
 
2529
 
 
2530
=item forward_agent => 1
 
2531
 
 
2532
Enables forwarding of the authentication agent.
 
2533
 
 
2534
This option can not be used when passing a passphrase (via
 
2535
L</passphrase>) to unlock the login private key.
2440
2536
 
2441
2537
=item default_stdin_fh => $fh
2442
2538
 
2710
2806
 
2711
2807
See L</"Shell quoting"> below.
2712
2808
 
 
2809
=item forward_agent => $bool
 
2810
 
 
2811
Enables/disables forwarding of the authentication agent.
 
2812
 
 
2813
This option can only be used when agent forwarding has been previously
 
2814
requested on the constructor.
 
2815
 
2713
2816
=item ssh_opts => \@opts
2714
2817
 
2715
2818
List of extra options for the C<ssh> command.
2864
2967
returns the output broken into lines (it honors C<$/>, see
2865
2968
L<perlvar/"$/">).
2866
2969
 
 
2970
The exit status of the remote command is returned in C<$?>.
 
2971
 
2867
2972
When an error happens while capturing (for instance, the operation
2868
2973
times out), the partial captured output will be returned. Error
2869
2974
conditions have to be explicitly checked using the L</error>
3057
3162
=item quiet => 0
3058
3163
 
3059
3164
By default, C<scp> is called with the quiet flag C<-q> enabled in
3060
 
order to suppress progress information. This option allows reenabling
3061
 
the progress indication bar.
 
3165
order to suppress progress information. This option allows one to
 
3166
re-enable the progress indication bar.
3062
3167
 
3063
3168
=item verbose => 1
3064
3169
 
3085
3190
 
3086
3191
=item bwlimit => $Kbits
3087
3192
 
3088
 
Limits the used bandwith, specified in Kbit/s.
 
3193
Limits the used bandwidth, specified in Kbit/s.
3089
3194
 
3090
3195
=item timeout => $secs
3091
3196
 
3158
3263
 
3159
3264
=item $sftp = $ssh->sftp(%sftp_opts)
3160
3265
 
3161
 
Creates a new L<Net::SFTP::Foreign|Net::SFTP::Foreign> object for SFTP interaction that
3162
 
runs through the ssh master connection.
 
3266
Creates a new L<Net::SFTP::Foreign|Net::SFTP::Foreign> object for SFTP
 
3267
interaction that runs through the ssh master connection.
3163
3268
 
3164
 
=item @call = $ssh->make_remote_command(%opts, @cmd)
 
3269
=item @call = $ssh->make_remote_command(\%opts, @cmd)
3165
3270
 
3166
3271
=item $call = $ssh->make_remote_command(\%opts, @cmd)
3167
3272
 
3177
3282
  my $remote = $ssh->make_remote_comand("cd /tmp/ && tar xf -");
3178
3283
  system "tar cf - . | $remote";
3179
3284
 
 
3285
The options accepted are as follows:
 
3286
 
 
3287
=over 4
 
3288
 
 
3289
=item tty => $bool
 
3290
 
 
3291
Enables/disables allocation of a tty on the remote side.
 
3292
 
 
3293
=item forward_agent => $bool
 
3294
 
 
3295
Enables/disables forwarding of authentication agent.
 
3296
 
 
3297
This option can only be used when agent forwarding has been previously
 
3298
requested on the constructor.
 
3299
 
 
3300
=item tunnel => 1
 
3301
 
 
3302
Return a command to create a connection to some TCP server reachable
 
3303
from the remote host. In that case the arguments are the destination
 
3304
address and port. For instance:
 
3305
 
 
3306
  $cmd = $ssh->make_remote_command({tunnel => 1}, $host, $port);
 
3307
 
 
3308
=back
 
3309
 
3180
3310
=item $ssh->wait_for_master($async)
3181
3311
 
3182
3312
When the connection has been established by calling the constructor
3265
3395
the OS could reassign the PID to a new unrelated process and the
3266
3396
module would try to kill it at object destruction time.
3267
3397
 
 
3398
=item $pid = $ssh->sshfs_import(\%opts, $remote_fs, $local_mnt_point)
 
3399
 
 
3400
=item $pid = $ssh->sshfs_export(\%opts, $local_fs, $remote_mnt_point)
 
3401
 
 
3402
These methods use L<sshfs(1)> to import or export a file system
 
3403
through the SSH connection.
 
3404
 
 
3405
They return the C<$pid> of the C<sshfs> process or of the slave C<ssh>
 
3406
process used to proxy it. Killing that process unmounts the file
 
3407
system, though, it may be probably better to use L<fusermount(1)>.
 
3408
 
 
3409
The options acepted are as follows:
 
3410
 
 
3411
=over
 
3412
 
 
3413
=item ssh_opts => \@ssh_opts
 
3414
 
 
3415
Options passed to the slave C<ssh> process.
 
3416
 
 
3417
=item sshfs_opts => \@sshfs_opts
 
3418
 
 
3419
Options passed to the C<sshfs> command. For instance, to mount the file
 
3420
system in read-only mode:
 
3421
 
 
3422
  my $pid = $ssh->sshfs_export({sshfs_opts => [-o => 'ro']},
 
3423
                               "/", "/mnt/foo");
 
3424
 
 
3425
=back
 
3426
 
 
3427
Note that this command requires a recent version of C<sshfs> to work (at
 
3428
the time of writing, it requires the yet unreleased version available
 
3429
from the FUSE git repository!).
 
3430
 
 
3431
See also the L<sshfs(1)> man page and the C<sshfs> and FUSE web sites
 
3432
at L<http://fuse.sourceforge.net/sshfs.html> and
 
3433
L<http://fuse.sourceforge.net/> respectively.
 
3434
 
3268
3435
=back
3269
3436
 
3270
3437
=head2 Shell quoting
3437
3604
=head2 Tunnels
3438
3605
 
3439
3606
Besides running commands on the remote host, Net::OpenSSH also allows
3440
 
to tunnel TCP connections to remote machines reachable from the SSH
3441
 
server.
 
3607
one to tunnel TCP connections to remote machines reachable from the
 
3608
SSH server.
3442
3609
 
3443
3610
That feature is made available through the C<tunnel> option of the
3444
3611
L</open_ex> method, and also through wrapper methods L</open_tunnel>
3596
3763
L<mod_perl> and L<mod_perl2> tie STDIN and STDOUT to objects that are
3597
3764
not backed up by real file descriptors at the operative system
3598
3765
level. Net::OpenSSH will fail if any of these handles is used
3599
 
explicetly or implicitly when calling some remote command.
 
3766
explicitly or implicitly when calling some remote command.
3600
3767
 
3601
3768
The workaround is to redirect them to C</dev/null> or to some file:
3602
3769
 
3791
3958
 
3792
3959
=back
3793
3960
 
 
3961
=head1 DEBUGGING
 
3962
 
 
3963
Debugging of Net::OpenSSH internals is controlled through the variable
 
3964
C<$Net::OpenSSH::debug>.  Every bit of this variable activates
 
3965
debugging of some subsystem as follows:
 
3966
 
 
3967
=over 4
 
3968
 
 
3969
=item bit 1 - errors
 
3970
 
 
3971
Dumps changes on the internal object attribute where errors are stored.
 
3972
 
 
3973
=item bit 2 - ctl_path
 
3974
 
 
3975
Dumps information about ctl_path calculation and the tests performed
 
3976
on that directory in order to decide if it is secure to place the
 
3977
multiplexing socket inside.
 
3978
 
 
3979
=item bit 4 - connecting
 
3980
 
 
3981
Dumps information about the establishment of new master connections.
 
3982
 
 
3983
=item bit 8 - commands and arguments
 
3984
 
 
3985
Dumps the command and arguments for every system/exec call.
 
3986
 
 
3987
=item bit 16 - command execution
 
3988
 
 
3989
Dumps information about the progress of command execution.
 
3990
 
 
3991
=item bit 32 - destruction
 
3992
 
 
3993
Dumps information about the destruction of Net::OpenSSH objects and
 
3994
the termination of the SSH master processes.
 
3995
 
 
3996
=item bit 64 - IO loop
 
3997
 
 
3998
Dumps information about the progress of the IO loop on capture
 
3999
operations.
 
4000
 
 
4001
=item bit 128 - IO hexdumps
 
4002
 
 
4003
Generates hexdumps of the information that travels through the SSH
 
4004
streams inside capture operations.
 
4005
 
 
4006
=item bit 512 - OS tracing of the master process
 
4007
 
 
4008
Use the module L<Net::OpenSSH::OSTracer> to trace the SSH master
 
4009
process at the OS level.
 
4010
 
 
4011
=back
 
4012
 
 
4013
For instance, in order to activate all the debugging flags, you can
 
4014
use:
 
4015
 
 
4016
  $Net::OpenSSH::debug = ~0;
 
4017
 
 
4018
Note that the meaning of the flags and the information generated is
 
4019
only intended for debugging of the module and may change without
 
4020
notice between releases.
 
4021
 
3794
4022
=head1 FAQ
3795
4023
 
3796
4024
Frequent questions about the module:
3997
4225
with the C<-k> flag. You may also like to use the C<-p> flag to tell
3998
4226
C<sudo> to print an empty prompt. For instance:
3999
4227
 
4000
 
  my @out = $ssh->capture({stdin_data => $sudo_passwd},
 
4228
  my @out = $ssh->capture({stdin_data => "$sudo_passwd\n"},
4001
4229
                          'sudo', '-Sk',
4002
4230
                          '-p', '',
4003
4231
                          '--',
4004
4232
                          @cmd);
4005
4233
 
 
4234
If the version of sudo installed on the remote host does not support
 
4235
the C<-S> flag (it tells sudo to read the password from its STDIN
 
4236
stream), you can do it as follows:
 
4237
 
 
4238
  my @out = $ssh->capture({tty => 1,
 
4239
                           stdin_data => "$sudo_passwd\n"},
 
4240
                           'sudo', '-k',
 
4241
                           '-p', '',
 
4242
                           '--',
 
4243
                           @cmd);
 
4244
 
 
4245
This may generate an spurious and harmless warning from the SSH master
 
4246
connection (because we are requesting allocation of a tty on the
 
4247
remote side and locally we are attaching it to a regular pair of
 
4248
pipes).
 
4249
 
 
4250
If for whatever reason the methods described above fail, you can
 
4251
always revert to using Expect to talk to the remote C<sudo>. See the
 
4252
C<sample/expect.pl> script from this module distribution.
 
4253
 
4006
4254
=back
4007
4255
 
4008
4256
=head1 SEE ALSO
4039
4287
 
4040
4288
Other Perl SSH clients: L<Net::SSH::Perl|Net::SSH::Perl>,
4041
4289
L<Net::SSH2|Net::SSH2>, L<Net::SSH|Net::SSH>,
4042
 
L<Net::SSH::Expect|Net::SSH::Expect>, L<Net::SCP|Net::SCP>.
 
4290
L<Net::SSH::Expect|Net::SSH::Expect>, L<Net::SCP|Net::SCP>,
 
4291
L<Net::SSH::Mechanize|Net::SSH::Mechanize>.
4043
4292
 
4044
4293
L<Net::OpenSSH::Compat> is a package offering a set of compatibility
4045
4294
layers for other SSH modules on top of Net::OpenSSH.
4071
4320
the CPAN bug tracking system at L<http://rt.cpan.org>.
4072
4321
 
4073
4322
B<Post questions related to how to use the module in Perlmonks>
4074
 
L<http://perlmoks.org/>, you will probably get faster responses than
 
4323
L<http://perlmonks.org/>, you will probably get faster responses than
4075
4324
if you address me directly and I visit Perlmonks quite often, so I
4076
4325
will see your question anyway.
4077
4326
 
4118
4367
 
4119
4368
=head1 COPYRIGHT AND LICENSE
4120
4369
 
4121
 
Copyright (C) 2008-2011 by Salvador FandiE<ntilde>o
 
4370
Copyright (C) 2008-2013 by Salvador FandiE<ntilde>o
4122
4371
(sfandino@yahoo.com)
4123
4372
 
4124
4373
This library is free software; you can redistribute it and/or modify