diff --git a/tsshbatch.rst b/tsshbatch.rst index cb96cd7..14e668a 100644 --- a/tsshbatch.rst +++ b/tsshbatch.rst @@ -9,7 +9,7 @@ -------- :: - tsshbatch.py [-NSehkvy -G 'file dest' -P 'file dest' -f cmdfile -n name -p pw ] -H 'host ..' | hostlistfile [command arg ... ] + tsshbatch.py [-NSehktvxy -G 'file dest' -P 'file dest' -f cmdfile -n name -p pw ] -H 'host ..' | hostlistfile [command arg ... ] DESCRIPTION @@ -91,8 +91,23 @@ -p pw Password to use when logging in and/or doing sudo + -t Test mode: Only show what *would* be done but don't + actually do it. This also prints diagnostic + information about any variable definitions, the list + of hosts, any ``GET`` and ``PUT`` requests, and final + command strings after all variable substitutions have + been applied. + -v Print detailed program version information and exit + -x Override any previous ``-t`` specifications and + actually execute the commands. This is useful + if you want to put ``-t`` in the ``$TSSHBATCH`` + environment variable so that the default is + always run the program in test mode. Then, when + you're ready to actually run commands, you can + override it with ``-x`` on the command line. + -y Turn on 'noisy' reporting for additional detail on every line, instead of just at the top of the ``stdout`` and ``stderr`` reporting. This is @@ -126,6 +141,10 @@ you've defined on the command line. It is always the last command run on each host. +You can put as many ``-f`` arguments as you wish on the command +line and the contents of these files will be run in the order +they appeared from left-to-right on the command line. + ``tsshbatch`` does all the ``GETs``, then all the ``PUTs`` before attempting to do any command processing. If no ``GETs``, ``PUTs``, or commands have been specified, ``tsshbatch`` will exit silently, since @@ -386,7 +405,7 @@ forces the files you ``GET`` to be uniquely named by prepending the hostname and a ":" to the actual file name:: - tssbatch.py -H myhost -G "foo ./" + tsshbatch.py -H myhost -G "foo ./" This saves the file ``myhost:foo`` in the ``./`` on your local machine. @@ -398,6 +417,18 @@ multiple files. You cannot, however, use filename wildcards to specify multi-file operations. + You can put multiple ``GETs`` or ``PUTs`` on the command line + for the same file. They do not override each other but are + *cummulative*. So this:: + + tsshbatch.py -P"foo ./" -P"foo /tmp" ... + + Would put local file ``foo`` in both ``./`` and ``/tmp`` on each + host specified. Similarly, you can specify multiple files to ``GET`` + from remote hosts and place them in the same local directory:: + + tsshbatch.py -G"/etc/fstab ./tmp" -G"/etc/rc.conf ./tmp" ... + If any file transfer fails, for any reason, the program is aborted and no further work is done. @@ -448,9 +479,126 @@ created. +8) Include Paths + + ``tsshbatch`` supports the ablity to search paths to find + files you've referenced. The search path for ``cmdfiles`` + is specified in the ``$TSSHBATCHCMDS`` environment + variable. The ``hostlistfiles`` search path is + specified in the ``$TSSHBATCHHOSTS`` environment variable. + These are both in standard path delimited format for + your operating system. For example, on Unix-like systems + these look like this:: + + export TSSHBATCHCMDS="/usr/local/etc/.tsshbatch/commands:/home/me/.tsshbatch/commands" + + And so forth. + + These paths are honored both for any files you specify + on the command line as well as for any files you + reference in a ``.include`` directive. This allows + you to maintain libraries of standard commands and + host lists in well known locations and ``.include`` + the ones you need. + + ``tsshbatch`` will always first check to see if a file + you've specified is in your local (invoking) directory + and/or whether it is a fully qualified file name before + attempting to look down a search path. If a file exist + in several locations, the first instance found "wins". + + ``tsshbatch`` also checks for so-called "circular + includes" which would cause an infinite inclusion loop. + It will abort upon discovering this, prior to any + file tranfers or commands being executed. + +9) Defining Variables + + ``tsshbatch`` allows you to define variables which will then be + used to replace matching strings in both ``cmdfiles`` and + ``hostlistfiles``. For example, suppose you have this in a + ``hostlistfile``:: + + .define DOMAIN=.my.own.domain.com + + host1DOMAIN + host2DOMAIN + host3DOMAIN + + At runtime, the program will actually connect to + ``host1.my.own.domain.com``, ``host1.my.domain.com``, + and so on. This allows for ease of modularization + and maintenance of your files. + + Similarly, you might want define ``MYCMD=some_long_string`` + so you don't have to type ``some_long_string`` over and + over again in a ``cmdfile``. + + There are some "gotchas" to this: + + - The general form of a variable definition is:: + + .define name = value + + You have to have a name but the value is optional. + ``.define FOO=`` simply replaces any subsequent + ``FOO`` strings with .. nothing, effectively + removing them. + + Any ``=`` symbols to the right of the one right + after ``name`` are just considered part of the + variables value. + + Whitespace around the ``=`` symbol is optional but allowed. + + - Variables are substituted in the order they appear:: + + .define LS = ls -alr + LS /etc # ls -alr /etc + .define LS = ls -1 + LS /foo # ls -1 /foo + + - Variables may be defined in either ``cmdfiles`` or + ``hostlistfiles`` but they are *global*. ``cmdfiles`` are read + before any ``hostlistfiles`` so any variables you've defined + that happen to match a string in your list of hosts will be + substituted so be careful. + + - Variable names and values are *case sensitive*. + + OTHER ----- +Comments can go anywhere. + +Directives like ``.define`` and ``.include`` must +be the first non-whitespace text on the left end +of a line. If you do this in a ``cmdfile``:: + + foo .include bar + +``tsshbatch`` thinks you want to run the command ``foo`` +with an argument of ``.include bar``. If you do it +in a ``hostlistfile``, the program thinks you're +tryingto contact a host called ``foo .include bar``. In +neither case is this likely to be quite what you had in +mind. Simularly, everything to the right of the directive +is considered its argument (up to any comment character). + +Whitespace is not significant at the beginning or end of +a line but it is preserved within ``.define`` and ``.include`` +directive arguments as well as within commmand definitions. + +Strictly speaking, you do not have to have whitespace +after a directive. This is recognized:: + + .includesomefileofmine + .definemyvar=foo + +But this is *strongly* discouraged because it's really +hard to read. + ``tsshbatch`` writes the ``stdout`` of the remote host(s) to ``stdout`` on the local machine. It similarly writes remote ``stderr`` output to the local machine's ``stderr``. If you wish to @@ -517,7 +665,7 @@ :: - $Id: tsshbatch.rst,v 1.123 2013/10/24 19:08:20 tundra Exp $ + $Id: tsshbatch.rst,v 1.124 2013/10/29 01:01:15 tundra Exp $ You can find the latest version of this program at: