pec2 0.3.2 → 0.4.0

data/exe/man/man1/pssh.1

@@ -0,0 +1,368 @@
+.\" Man page for pssh.  See "man 7 man" and "man man-pages" for formatting info.
+.TH pssh 1 "January 24, 2012"
+
+.SH NAME
+pssh \(em parallel ssh program
+
+
+.SH SYNOPSIS
+.B pssh
+.RB [ \-vAiIP ]
+.RB [ \-h
+.IR hosts_file ]
+.RB [ \-H
+.RI [ user @] host [: port ]]
+.RB [ \-l
+.IR user ]
+.RB [ \-p
+.IR par ]
+.RB [ \-o
+.IR outdir ]
+.RB [ \-e
+.IR errdir ]
+.RB [ \-t
+.IR timeout ]
+.RB [ \-O
+.IR options ]
+.RB [ \-x
+.IR args ]
+.RB [ \-X
+.IR arg ]
+.I command ...
+
+.B pssh \-I
+.RB [ \-vAiIP ]
+.RB [ \-h
+.IR hosts_file ]
+.RB [ \-H
+.RI [ user @] host [: port ]]
+.RB [ \-l
+.IR user ]
+.RB [ \-p
+.IR par ]
+.RB [ \-o
+.IR outdir ]
+.RB [ \-e
+.IR errdir ]
+.RB [ \-t
+.IR timeout ]
+.RB [ \-O
+.IR options ]
+.RB [ \-x
+.IR args ]
+.RB [ \-X
+.IR arg ]
+.RI [ command
+.IR ... ]
+
+
+.SH DESCRIPTION
+.PP
+.B pssh
+is a program for executing ssh in parallel on a number of hosts.  It provides
+features such as sending input to all of the processes, passing a password
+to ssh, saving output to files, and timing out.
+
+The PSSH_NODENUM and PSSH_HOST environment variables are sent to the remote
+host.  The PSSH_NODENUM variable is assigned a unique number for each ssh
+connection, starting with 0 and counting up.  The PSSH_HOST variable is
+assigned the name of the host as specified in the hosts list.  Note that sshd
+drops environment variables by default, so sshd_config on the remote host must
+include the line:
+.RS
+AcceptEnv PSSH_NODENUM PSSH_HOST
+.RE
+
+.SH OPTIONS
+
+.TP
+.BI \-h " host_file"
+.PD 0
+.TP
+.BI \-\-hosts " host_file"
+Read hosts from the given
+.IR host_file .
+Lines in the host file are of the form
+.RI [ user @] host [: port ]
+and can include blank lines and comments (lines beginning with "#").
+If multiple host files are given (the
+.B \-h
+option is used more than once), then pssh behaves as though these files
+were concatenated together.
+If a host is specified multiple times, then pssh will connect the
+given number of times.
+
+.TP
+.B \-H
+.RI [ user @] host [: port ]
+.PD 0
+.TP
+.B \-\-host
+.RI [ user @] host [: port ]
+.PD 0
+.TP
+.B \-H
+.RI \(dq[ user @] host [: port ]
+[
+.RI [ user @] host [: port
+] ... ]\(dq
+.PD 0
+.TP
+.B \-\-host
+.RI \(dq[ user @] host [: port ]
+[
+.RI [ user @] host [: port
+] ... ]\(dq
+.PD 0
+.IP
+Add the given host strings to the list of hosts.  This option may be given
+multiple times, and may be used in conjunction with the
+.B \-h
+option.
+
+.TP
+.BI \-l " user"
+.PD 0
+.TP
+.BI \-\-user " user"
+Use the given username as the default for any host entries that don't
+specifically specify a user.
+
+.TP
+.BI \-p " parallelism"
+.PD 0
+.TP
+.BI \-\-par " parallelism"
+Use the given number as the maximum number of concurrent connections.
+
+.TP
+.BI \-t " timeout"
+.PD 0
+.TP
+.BI \-\-timeout " timeout"
+Make connections time out after the given number of seconds.  With a value
+of 0, pssh will not timeout any connections.
+
+.TP
+.BI \-o " outdir"
+.PD 0
+.TP
+.BI \-\-outdir " outdir"
+Save standard output to files in the given directory.  Filenames are of the
+form
+.RI [ user @] host [: port ][. num ]
+where the user and port are only included for hosts that explicitly
+specify them.  The number is a counter that is incremented each time for hosts
+that are specified more than once.
+
+.TP
+.BI \-e " errdir"
+.PD 0
+.TP
+.BI \-\-errdir " errdir"
+Save standard error to files in the given directory.  Filenames are of the
+same form as with the
+.B \-o
+option.
+
+.TP
+.BI \-x " args"
+.PD 0
+.TP
+.BI \-\-extra-args " args"
+Passes extra SSH command-line arguments (see the
+.BR ssh (1)
+man page for more information about SSH arguments).
+This option may be specified multiple times.
+The arguments are processed to split on whitespace, protect text within
+quotes, and escape with backslashes.
+To pass arguments without such processing, use the
+.B \-X
+option instead.
+
+.TP
+.BI \-X " arg"
+.PD 0
+.TP
+.BI \-\-extra-arg " arg"
+Passes a single SSH command-line argument (see the
+.BR ssh (1)
+man page for more information about SSH arguments).  Unlike the
+.B \-x
+option, no processing is performed on the argument, including word splitting.
+To pass multiple command-line arguments, use the option once for each
+argument.
+
+.TP
+.BI \-O " options"
+.PD 0
+.TP
+.BI \-\-options " options"
+SSH options in the format used in the SSH configuration file (see the
+.BR ssh_config (5)
+man page for more information).  This option may be specified multiple
+times.
+
+.TP
+.B \-A
+.PD 0
+.TP
+.B \-\-askpass
+Prompt for a password and pass it to ssh.  The password may be used for
+either to unlock a key or for password authentication.
+The password is transferred in a fairly secure manner (e.g., it will not show
+up in argument lists).  However, be aware that a root user on your system
+could potentially intercept the password.
+
+.TP
+.B \-i
+.PD 0
+.TP
+.B \-\-inline
+Display standard output and standard error as each host completes.
+
+.TP
+.B \-\-inline\-stdout
+Display standard output (but not standard error) as each host completes.
+
+.TP
+.B \-v
+.PD 0
+.TP
+.B \-\-verbose
+Include error messages from ssh with the
+.B \-i
+and
+.B \e
+options.
+
+.TP
+.B \-I
+.PD 0
+.TP
+.B \-\-send-input
+Read input and send to each ssh process.  Since ssh allows a command script to
+be sent on standard input, the
+.B \-I
+option may be used in lieu of the command argument.
+
+.TP
+.B \-P
+.PD 0
+.TP
+.B \-\-print
+Display output as it arrives.  This option is of limited usefulness because
+output from different hosts are interleaved.
+
+
+.SH EXAMPLES
+
+.PP
+Connect to host1 and host2, and print "hello, world" from each:
+.RS
+pssh -i -H "host1 host2" echo "hello, world"
+.RE
+
+.PP
+Print "hello, world" from each host specified in the file hosts.txt:
+.RS
+pssh -i -h hosts.txt echo "hello, world"
+.RE
+
+.PP
+Run a command as root with a prompt for the root password:
+.RS
+pssh -i -h hosts.txt -A -l root echo hi
+.RE
+
+.PP
+Run a long command without timing out:
+.RS
+pssh -i -h hosts.txt -t 0 sleep 10000
+.RE
+
+.PP
+If the file hosts.txt has a large number of entries, say 100, then the
+parallelism option may also be set to 100 to ensure that the commands are run
+concurrently:
+.RS
+pssh -i -h hosts.txt -p 100 -t 0 sleep 10000
+.RE
+
+.PP
+Run a command without checking or saving host keys:
+.RS
+pssh -i -H host1 -H host2 -x "-O StrictHostKeyChecking=no -O UserKnownHostsFile=/dev/null -O GlobalKnownHostsFile=/dev/null" echo hi
+.RE
+
+.PP
+Print the node number for each connection (this will print 0, 1, and 2):
+.RS
+pssh -i -H host1 -H host1 -H host2 'echo $PSSH_NODENUM'
+.RE
+
+.SH TIPS
+
+.PP
+If you have a set of hosts that you connect to frequently with specific
+options, it may be helpful to create an alias such as:
+.RS
+alias pssh_servers="pssh -h /path/to/server_list.txt -l root -A"
+.RE
+
+.PP
+The ssh_config file can include an arbitrary number of Host sections.  Each
+host entry specifies ssh options which apply only to the given host.  Host
+definitions can even behave like aliases if the HostName option is included.
+This ssh feature, in combination with pssh host files, provides a tremendous
+amount of flexibility.
+
+
+.SH EXIT STATUS
+
+.PP
+The exit status codes from pssh are as follows:
+
+.TP
+.B 0
+Success
+
+.TP
+.B 1
+Miscellaneous error
+
+.TP
+.B 2
+Syntax or usage error
+
+.TP
+.B 3
+At least one process was killed by a signal or timed out.
+
+.TP
+.B 4
+All processes completed, but at least one ssh process reported an error
+(exit status 255).
+
+.TP
+.B 5
+There were no ssh errors, but at least one remote command had a non-zero exit
+status.
+
+
+.SH AUTHORS
+.PP
+Written by
+Brent N. Chun <bnc@theether.org> and
+Andrew McNabb <amcnabb@mcnabbs.org>.
+
+http://code.google.com/p/parallel-ssh/
+
+
+.SH SEE ALSO
+.BR ssh (1),
+.BR ssh_config(5),
+.BR pscp (1),
+.BR prsync (1),
+.BR pslurp (1),
+.BR pnuke (1),

data/exe/psshlib/askpass_client.py

@@ -0,0 +1,102 @@
+#!/usr/bin/env python
+# -*- Mode: python -*-
+
+# Copyright (c) 2009-2012, Andrew McNabb
+
+"""Implementation of SSH_ASKPASS to get a password to ssh from pssh.
+
+The password is read from the socket specified by the environment variable
+PSSH_ASKPASS_SOCKET.  The other end of this socket is pssh.
+
+The ssh man page discusses SSH_ASKPASS as follows:
+    If ssh needs a passphrase, it will read the passphrase from the current
+    terminal if it was run from a terminal.  If ssh does not have a terminal
+    associated with it but DISPLAY and SSH_ASKPASS are set, it will execute
+    the program specified by SSH_ASKPASS and open an X11 window to read the
+    passphrase.  This is particularly useful when calling ssh from a .xsession
+    or related script.  (Note that on some machines it may be necessary to
+    redirect the input from /dev/null to make this work.)
+"""
+
+import os
+import socket
+import sys
+import textwrap
+
+bin_dir = os.path.dirname(os.path.abspath(sys.argv[0]))
+askpass_bin_path = os.path.join(bin_dir, 'pssh-askpass')
+ASKPASS_PATHS = (askpass_bin_path,
+        '/usr/libexec/pssh/pssh-askpass',
+        '/usr/local/libexec/pssh/pssh-askpass',
+        '/usr/lib/pssh/pssh-askpass',
+        '/usr/local/lib/pssh/pssh-askpass')
+
+_executable_path = None
+
+def executable_path():
+    """Determines the value to use for SSH_ASKPASS.
+
+    The value is cached since this may be called many times.
+    """
+    global _executable_path
+    if _executable_path is None:
+        for path in ASKPASS_PATHS:
+            if os.access(path, os.X_OK):
+                _executable_path = path
+                break
+        else:
+            _executable_path = ''
+            sys.stderr.write(textwrap.fill("Warning: could not find an"
+                    " executable path for askpass because PSSH was not"
+                    " installed correctly.  Password prompts will not work."))
+            sys.stderr.write('\n')
+    return _executable_path
+
+def askpass_main():
+    """Connects to pssh over the socket specified at PSSH_ASKPASS_SOCKET."""
+
+    verbose = os.getenv('PSSH_ASKPASS_VERBOSE')
+
+    # It's not documented anywhere, as far as I can tell, but ssh may prompt
+    # for a password or ask a yes/no question.  The command-line argument
+    # specifies what is needed.
+    if len(sys.argv) > 1:
+        prompt = sys.argv[1]
+        if verbose:
+            sys.stderr.write('pssh-askpass received prompt: "%s"\n' % prompt)
+        if not prompt.strip().lower().endswith('password:'):
+            sys.stderr.write(prompt)
+            sys.stderr.write('\n')
+            sys.exit(1)
+    else:
+        sys.stderr.write('Error: pssh-askpass called without a prompt.\n')
+        sys.exit(1)
+
+    address = os.getenv('PSSH_ASKPASS_SOCKET')
+    if not address:
+        sys.stderr.write(textwrap.fill("pssh error: SSH requested a password."
+                " Please create SSH keys or use the -A option to provide a"
+                " password."))
+        sys.stderr.write('\n')
+        sys.exit(1)
+
+    sock = socket.socket(socket.AF_UNIX)
+    try:
+        sock.connect(address)
+    except socket.error:
+        _, e, _ = sys.exc_info()
+        message = e.args[1]
+        sys.stderr.write("Couldn't bind to %s: %s.\n" % (address, message))
+        sys.exit(2)
+
+    try:
+        password = sock.makefile().read()
+    except socket.error:
+        sys.stderr.write("Socket error.\n")
+        sys.exit(3)
+
+    print(password)
+
+
+if __name__ == '__main__':
+    askpass_main()