diff --git a/tsshbatch.rst b/tsshbatch.rst index 9bd6b36..7fccd35 100644 --- a/tsshbatch.rst +++ b/tsshbatch.rst @@ -5,6 +5,27 @@ **tsshbatch** - Run Commands On Batches Of Machines +.. WARNING:: ``tsshbatch`` is a powerful tool for automating activities + on many servers at a time. This also gives you to power + *to make many mistakes at a time!* This is especially + true if you have ``sudo`` privilege promotion + capabilities on the systems in your care. *So be careful + out there!* + + We therefore STRONGLY recommend you do the following + things to mitigate this risk: + + - Read This Fine Manual from beginning to end. + + - Practice using ``tsshbatch`` on test machines or + VMs that can easily be recovered or reimaged if you + break someting. + + - Make heavy use of test mode (which is the default) + to see what the program *would* do if it actually + ran in execution mode. + + SYNOPSIS -------- :: @@ -191,8 +212,8 @@ variables. Their use is described later in this document. -USE CASES ---------- +FEATURES AND USE CASES +---------------------- 1) Different Ways To Specify Targeted Hostnames @@ -409,12 +430,12 @@ reimplementation of the shell quoting and aliasing features. For example, if you invoke an alias on the remote machine that resolves to a ``sudo`` command, or - you run a script with a ``sudo`` command in it, ``tsshbatch`` - has no way to determine what you're trying to do. For - complex applications, it's best to write a true shell - script, push it all the machines in question via ``-P``, - and then have ``tsshbatch`` remotely invoke it with - ``sudo myscript`` or something similar. + you run a script with a ``sudo`` command in it, + ``tsshbatch`` has no way to determine what you're trying + to do. For complex applications, it's best to write a + true shell script, push it all the machines in question + via ``-P``, and then have ``tsshbatch`` remotely invoke + it with ``sudo myscript`` or something similar. As always, the best way to figure out what the program thinks you're asking for is to run it in test mode @@ -446,8 +467,8 @@ "path-to-source-file path-to-destination-directory" Note that this means the file will always be stored under - its original name in the destination directory. Renaming - isn't possible during file transfer. + its original name in the destination directory. *Renaming + isn't possible during file transfer*. However, ``tsshbatch`` always does ``GETs`` then ``PUTs`` *then* any outstanding command (if any) at the end of the command line. This @@ -724,74 +745,91 @@ OTHER ----- -Comments can go anywhere. +- 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``:: +- 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 + 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 trying to contact a host called ``foo .include -bar``. In neither case is this likely to be quite what you had in -mind. Similarly, everything to the right of the directive is -considered its argument (up to any comment character). + ``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 trying to contact a host called ``foo + .include bar``. In neither case is this likely to be quite what you + had in mind. Similarly, 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. +- 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:: +- Strictly speaking, you do not have to have whitespace after a + directive. This is recognized:: - .includesomefileofmine - .definemyvar=foo + .includesomefileofmine + .definemyvar=foo -But this is *strongly* discouraged because it's really -hard to read. + 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 -suppress ``stderr`` output, either redirect it on your local command -line or use the ``-e`` option to turn it off entirely. +- ``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 + suppress ``stderr`` output, either redirect it on your local command + line or use the ``-e`` option to turn it off entirely. If you want + everything to go to your local ``stdout``, use the ``-E`` option. -You will not be able to run remote ``sudo`` commands if the host -in question enables the ``Defaults requiretty`` in its ``sudoers`` -configuration. +- You must have a reasonably current version of Python 2.x installed. + It almost certainly will not work on Python 3.x because it uses the + deprecated ``commands`` module. This decision was made to make the + program as backward compatible with older versions of Python as + possible (there is way more 2.x around than there is 3.x). -You must have a reasonably current version of Python installed. If -your Python installation does not install ``paramiko`` you'll have to -install it manually, since ``tsshbatch`` requires these libraries as -well. +- If your Python installation does not install ``paramiko`` you'll + have to install it manually, since ``tsshbatch`` requires these + libraries as well. + +- ``tsshbatch`` has been run extensively from Unix-like systems (Linux, + FreeBSD) and has had no testing whatsoever on Microsoft Windows. If + you have experience using it on Windows, do please share with the + class using the email address below. While we do not officially + support this tool on Windows, if the changes needed to make it work + properly are small enough, we'd consider updating the code + accordingly. BUGS AND MISFEATURES -------------------- -When ``sudo`` is presented a bad password, it ordinarily prints a -string indicating something is wrong. ``tsshbatch`` looks for this to -let you know that you've got a problem and then terminates further -operation. This is so that you do not attempt to log in -with a bad password across all the hosts you have targeted. (Many -enterprises have policies to lock out a user ID after some small -number of failed login/access attempts.) +- You will not be able to run remote ``sudo`` commands if the host in + question enables the ``Defaults requiretty`` in its ``sudoers`` + configuration. Some overzealous InfoSec folks seem to think this is + a brilliant way to secure your system (they're wrong) and there's + nothing ``tsshbatch`` can do about it. -However, some older versions of ``sudo`` (noted on a RHEL 4 host -running ``sudo`` 1.6.7p5) do not return any feedback when presented -with a bad password. This means that ``tsshbatch`` cannot tell the -difference between a successful ``sudo`` and a system waiting for you -to reenter a proper password. In this situation, if you enter a bad -password, the *the program will hang*. Why? ``tsshbatch`` thinks -nothing is wrong and waits for the ``sudo`` command to complete. At -the same time, ``sudo`` itself is waiting for an updated password. In -this case, you have to kill ``tsshbatch`` and start over. This -typically requires you to put the program in background (```Ctrl-Z`` -in most shells) and then killing that job from the command line. +- When ``sudo`` is presented a bad password, it ordinarily prints a + string indicating something is wrong. ``tsshbatch`` looks for this + to let you know that you've got a problem and then terminates + further operation. This is so that you do not attempt to log in + with a bad password across all the hosts you have targeted. (Many + enterprises have policies to lock out a user ID after some small + number of failed login/access attempts.) -There is no known workaround for this problem. + However, some older versions of ``sudo`` (noted on a RHEL 4 host + running ``sudo`` 1.6.7p5) do not return any feedback when presented + with a bad password. This means that ``tsshbatch`` cannot tell the + difference between a successful ``sudo`` and a system waiting for + you to reenter a proper password. In this situation, if you enter a + bad password, the *the program will hang*. Why? ``tsshbatch`` + thinks nothing is wrong and waits for the ``sudo`` command to + complete. At the same time, ``sudo`` itself is waiting for an + updated password. In this case, you have to kill ``tsshbatch`` and + start over. This typically requires you to put the program in + background (```Ctrl-Z`` in most shells) and then killing that job + from the command line. + + There is no known workaround for this problem. COPYRIGHT AND LICENSING ----------------------- @@ -818,7 +856,7 @@ :: - $Id: tsshbatch.rst,v 1.143 2014/12/03 15:53:04 tundra Exp $ + $Id: tsshbatch.rst,v 1.144 2014/12/04 19:40:40 tundra Exp $ You can find the latest version of this program at: