Dmitry Shalnoff's Git Repository - ETG_Helmet/blob - SOFTWARE/UTILS/sshpass/src/sshpass.1

   1 .TH SSHPASS 1 "August 6, 2011" "Lingnu Open Source Consulting" "Sshpass User Manual"
   2 .\" Please adjust this date whenever revising the manpage.
   3 .SH NAME
   4 sshpass \- noninteractive ssh password provider
   5 .SH SYNOPSIS
   6 .B sshpass
   7 .RB [ -f\fIfilename | -d\fInum | -p\fIpassword | -e ]
   8 .RI [ options ] " command arguments"
   9 .br
  10 .SH DESCRIPTION
  11 This manual page documents the \fBsshpass\fP command.
  12 .PP
  13 \fBsshpass\fP is a utility designed for running \fBssh\fP using the mode referred
  14 to as "keyboard-interactive" password authentication, but in non-interactive mode.
  15 .PP
  16 ssh uses direct TTY access to make sure that the password is indeed issued by
  17 an interactive keyboard user. Sshpass runs ssh in a dedicated tty, fooling it
  18 into thinking it is getting the password from an interactive user.
  19 .PP
  20 The command to run is specified after sshpass' own options. Typically it will be
  21 "ssh" with arguments, but it can just as well be any other command. The password
  22 prompt used by ssh is, however, currently hardcoded into sshpass.
  23 .SH Options
  24 If no option is given, sshpass reads the password from the standard input. The
  25 user may give at most one alternative source for the password:
  26 .TP
  27 .B \-p\fIpassword\fP
  28 The password is given on the command line. Please note the section titled
  29 "\fBSECURITY CONSIDERATIONS\fP".
  30 .TP
  31 .B \-f\fIfilename\fP
  32 The password is the first line of the file \fIfilename\fP.
  33 .TP
  34 .B \-d\fInumber\fP
  35 \fInumber\fP is a file descriptor inherited by sshpass from the runner. The
  36 password is read from the open file descriptor.
  37 .TP
  38 .B \-e
  39 The password is taken from the environment variable "SSHPASS".
  40 .SH SECURITY CONSIDERATIONS
  41 .P
  42 First and foremost, users of sshpass should realize that ssh's insistance on
  43 only getting the password interactively is not without reason. It is close to
  44 impossible to securely store the password, and users of sshpass should consider
  45 whether ssh's public key authentication provides the same end-user experience,
  46 while involving less hassle and being more secure.
  47 .P
  48 The \-p option should be considered the least secure of all of sshpass's options.
  49 All system users can see the password in the command line with a simple "ps"
  50 command. Sshpass makes a minimal attempt to hide the password, but such attempts are doomed to create
  51 race conditions without actually solving the problem. Users of sshpass are
  52 encouraged to use one of the other password passing techniques, which are all
  53 more secure.
  54 .P
  55 In particular, people writing programs that are meant to communicate the password
  56 programatically are encouraged to use an anonymous pipe and pass the pipe's reading
  57 end to sshpass using the \-d option.
  58 .SH RETURN VALUES
  59 As with any other program, sshpass returns 0 on success. In case of failure, the following
  60 return codes are used:
  61 .TP
  62 1
  63 Invalid command line argument
  64 .TP
  65 2
  66 Conflicting arguments given
  67 .TP
  68 3
  69 General runtime error
  70 .TP
  71 4
  72 Unrecognized response from ssh (parse error)
  73 .TP
  74 5
  75 Invalid/incorrect password
  76 .TP
  77 6
  78 Host public key is unknown. sshpass exits without confirming the new key.
  79 .P
  80 In addition, ssh might be complaining about a man in the middle attack. This
  81 complaint does not go to the tty. In other words, even with sshpass, the error
  82 message from ssh is printed to standard error. In such a case ssh's return code
  83 is reported back. This is typically an unimaginative (and non-informative) "255"
  84 for all error cases.
  85 .SH EXAMPLES
  86 .P
  87 Run rsync over SSH using password authentication, passing the password on the
  88 command line:
  89 .PP
  90 rsync \-\-rsh='sshpass \-p 12345 ssh \-l test' host.example.com:path .
  91 .P
  92 To do the same from a bourne shell script in a marginally less exposed way:
  93 .PP
  94 SSHPASS=12345 rsync \-\-rsh='sshpass \-e ssh \-l test' host.example.com:path .
  95 .SH BUGS
  96 .P
  97 Sshpass is in its infancy at the moment. As such, bugs are highly possible. In
  98 particular, if the password is read from stdin (no password option at all), it
  99 is possible that some of the input aimed to be passed to ssh will be read by
 100 sshpass and lost.
 101 .P
 102 Sshpass utilizes the \fBpty\fR(7) interface to control the TTY for ssh. This interface,
 103 at least on Linux, has a misfeature where if no slave file descriptors are open, the
 104 master pty returns \fBEIO\fR. This is the normal behavior, except a slave pty may
 105 be born at any point by a program opening \fB/dev/tty\fR. This makes it impossible
 106 to reliably wait for events without consuming 100% of the CPU.
 107 .P
 108 Over the various versions different approaches were attempted at solving this problem.
 109 Any given version of sshpass is released with the belief that it is working, but experience
 110 has shown that these things do, occasionally, break. This happened with OpenSSH version 5.6.
 111 As of this writing, it is believed that sshpass is, again, working properly.