diff --git a/tsshbatch.rst b/tsshbatch.rst index 6af4edf..606da94 100644 --- a/tsshbatch.rst +++ b/tsshbatch.rst @@ -7,8 +7,9 @@ SYNOPSIS -------- +:: -tsshbatch.py [-NSehkv -G 'file dest' -P 'file dest' -f file -n name -p pw ] -H 'host ..' | hostlistfile [command arg ... ] + tsshbatch.py [-NSehkv -G 'file dest' -P 'file dest' -f cmdfile -n name -p pw ] -H 'host ..' | hostlistfile [command arg ... ] DESCRIPTION @@ -38,58 +39,59 @@ on either the command line or in the ``$TSSHBATCH`` environment variable: - -G spec GET file on host and write local dest directory. - ``spec`` is a quoted pair of strings. The first - specifies the path of the source file (on the - remote machine) to copy. The second, specifies - the destination *directory* (on the local - machine):: + -G spec GET file on host and write local dest directory. + ``spec`` is a quoted pair of strings. The first + specifies the path of the source file (on the + remote machine) to copy. The second, specifies + the destination *directory* (on the local + machine):: - tsshbatch.py -G "/foo/bar/baz /tmp" hostlist + tsshbatch.py -G "/foo/bar/baz /tmp" hostlist - This copies ``/foo/bar/baz`` from every machine in - ``hostlist`` to the local ``/tmp/`` directory. Since all - the files have the same name, they would overwrite - each other if copied into the same directory. So, - ``tsshbatch`` prepends the string ``hostname:`` to - the name of each file it saves locally. + This copies ``/foo/bar/baz`` from every machine in + ``hostlistfile`` to the local ``/tmp/`` directory. + Since all the files have the same name, they would + overwrite each other if copied into the same + directory. So, ``tsshbatch`` prepends the string + ``hostname:`` to the name of each file it saves + locally. - -H hostlist List of hosts on which to run the command. This should - be enclosed in *quotes* so that the list of hosts - is handed to the -H option as a single argument:: + -H hostlistfile List of hosts on which to run the command. This should + be enclosed in *quotes* so that the list of hosts + is handed to the -H option as a single argument:: -H 'host1 host2 host3' - -N Force interactive username dialog + -N Force interactive username dialog - -P spec PUT file from local machine to remote machine destination - directory. ``spec`` is a quoted pair of strings. - The first specifies the path of the source file (on - the local machine) to copy. The second, specifies - the destination *directory* (on the remote machine):: + -P spec PUT file from local machine to remote machine destination + directory. ``spec`` is a quoted pair of strings. + The first specifies the path of the source file (on + the local machine) to copy. The second, specifies + the destination *directory* (on the remote machine):: - tsshbatch.py -P "/foo/bar/baz /tmp" hostlist + tsshbatch.py -P "/foo/bar/baz /tmp" hostlist - This copies ``/foo/bar/baz`` on the local - machine to ``/tmp/`` on every host in ``hostlist``. + This copies ``/foo/bar/baz`` on the local + machine to ``/tmp/`` on every host in ``hostlist``. - -S Force prompting for sudo password + -S Force prompting for sudo password - -e Don't report remote host stderr output + -e Don't report remote host stderr output - -f file Read commands from a file. This file can be commented - freely with the ``#`` character. Leading- and - trailing whitespace on a line are ignored. + -f cmdfile Read commands from a file. This file can be commented + freely with the ``#`` character. Leading- and + trailing whitespace on a line are ignored. - -h Print help information + -h Print help information - -k Use ssh keys instead of name/password credentials + -k Use ssh keys instead of name/password credentials - -n name Login name to use + -n name Login name to use - -p pw Password to use when logging in and/or doing sudo + -p pw Password to use when logging in and/or doing sudo - -v Print detailed program version information and exit + -v Print detailed program version information and exit If the ``-H`` option is not selected, the item immediately following the options is understood to be the name of the ``hostlistfile``. @@ -111,7 +113,7 @@ your local shell will interfere with them being properly conveyed to the remote machine. -If you've specified a file containing the commands you want run via +If you've specified a ``cmdfile`` containing the commands you want run via the ``-f`` option, these commands will run *before* the command you've defined on the command line. It is always the last command run on each host. @@ -330,10 +332,10 @@ You can force ``tsshbatch`` to ask you for a ``sudo`` password with the ``-S`` option. This allows you to have one password for - intitial login, and a different one for ``sudo`` promotion. + initial login, and a different one for ``sudo`` promotion. Any time you a prompted for a ``sudo`` password and a login - password has been provided (interactive of ``-p``), you can accept + password has been provided (interactive or ``-p``), you can accept this as the ``sudo`` password by just hitting ``Enter``. @@ -345,7 +347,7 @@ 1. Key exchange 2. Forced prompting for name via -N - 3. Command Line/$TSSHBATCH env variable sets name + 3. Command Line/$TSSHBATCH environment variable sets name 4. Name picked up from $USER (Default behavior) If try to use Key Exchange and ``tsshbatch`` detects a command @@ -381,12 +383,61 @@ This saves the file ``myhost:foo`` in the ``./`` on your local machine. - The commands do not recognize any special directory - shortcut symbols like ``~/``. You must name file and - directory locations using ordinary pathing conventions. + The commands do not recognize any special directory shortcut symbols + like ``~/``. You must name file and directory locations using + ordinary pathing conventions. You can put as many of these requests + on the command line as you like to enable ``GETs`` and ``PUTs`` of + multiple files. You cannot, however, use filename wildcards to + specify multi-file operations. - If any file transfer fails, for any reason, the program - is aborted and no further work is done. + If any file transfer fails, for any reason, the program is aborted + and no further work is done. + +7) File Commenting And Includes + + Both the ``cmdfile`` and ``hostlistfile`` can be freely commented + using the ``#`` character. Everything from that character to the + end of that line is ignored. Similarly, you can use whitespace + freely, except in cases where it would change the syntax of a + command or host name. + + You may also include other files as you wish with the + ``.include filename`` directive anywhere in the ``cmdfile`` or + ``hostlistfile``. This is useful for breaking up long lists + of things into smaller parts. For example, suppose you + have three host lists, one for each major production areas + of your network:: + + hosts-development + hosts-stage + host-production + + You might typically run different ``tsshbatch`` jobs on each + of these sets of hosts. But suppose you now want to run a + job on all of them. Instead of copying them all into a + master file (which would be instantly obsolete if you + changed anything in one of the above files), you could + create ``hosts-all`` with this content:: + + .include hosts-development + .include hosts-stage + .include hosts-production + + That way if you edited any of the underlying files, the + ``hosts-all`` would reflect the change. + + Similarly you can do the same thing with the ``cmdfile`` to + group similar commands into separate files and include them. + + ``tsshbatch`` does not enforce a limit on how deeply nested + ``.includes`` can be. An included file can include another file and + so on. However, if a circular include is detected, the program will + notify you and abort. This happens if, say, file1 includes file2, + file2 includes file3, and file3 includes file1. This would create + an infinite loop of includes if permitted. You can, of course, + include the same file multiple times, either in a single file or + throughout other included files, so long as no circular include is + created. OTHER @@ -458,7 +509,7 @@ :: - $Id: tsshbatch.rst,v 1.118 2013/10/23 19:28:17 tundra Exp $ + $Id: tsshbatch.rst,v 1.119 2013/10/24 02:54:00 tundra Exp $ You can find the latest version of this program at: