nrun
====

nrun will run a single command or script on a multiple of target servers
synchronously.  ncopy will copy a file or directory to multiple target servers.

the underlying remote access mechanism is exchangeable. as of now, ssh, nsh, rsh
and local execution modes are implemented.

the return code and all command output will be logged.

Copyright 2013 Timo Benk <benk@b1-systems.de>

nrun is free software: you can redistribute it and/or modify it under the terms
of the GNU General Public License as published by the Free Software Foundation,
either version 3 of the License, or (at your option) any later version.

nrun is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY;
without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR
PURPOSE.  See the GNU General Public License for more details.

installation
============

installation is straight forward:

# perl Makefile.PL
# make install

if desired it is possible to change the installation prefix using the
parameter INSTALLATION_BASE:

# perl Makefile.PL INSTALLATION_BASE=~/applications

usage
=====

usage: nrun -c <CMD> [-h <HOSTS>] <HOST1> <HOST2> ...
--hosts-file,-h <HOSTS>    file containing the target hosts (one host per line).
--command,-c <CMD>         command to be executed.
--arguments,-a <ARGS>      the arguments that should be passed to command.
--parallel,-p <MAX>        number of parallel connections (defaults to 5).
--dump-results             instead of dumping the command output, dump the exit
                           status.
--log-directory,-l <DIR>   base directory for the log files.
--timeout,-t <SEC>         timeout for each command execution (defaults to 60).
--version                  print the version string and exit.
--copy                     copy command to target host before execution.
--no-hostname              omit hostname prefix.
--no-logfile               do not generate any log files.
--skip-ping-check          skip checking if the host answers on ping.
--skip-ns-check            skip checking if the hostname is resolvable.
--mode <MODE>              remote execution mode:
                           nsh - nsh based remote execution
                           rsh - rsh based remote execution
                           ssh - ssh based remote execution
                           local - execute the script locally, set TARGET_HOST
                           on each execution

usage: ncopy -s <SRC> -d <DST> [-h <HOSTS>] <HOST1> <HOST2> ...
--hosts-file,-h <HOSTS>    file containing the target hosts (one host per line).
--source,-s <SRC>          the file to be copied.
--destination,-d <DST>     destination the file should be copied to.
--parallel,-p <MAX>        number of parallel connections (defaults to 5).
--dump-results             instead of dumping the command output, dump the exit
                           status.
--log-directory,-l <DIR>   base directory for the log files.
--timeout,-t <SEC>         timeout for each command execution (defaults to 60).
--version                  print the version string and exit.
--no-hostname              omit hostname prefix.
--no-logfile               do not generate any log files.
--skip-ping-check          skip checking if the host answers on ping.
--skip-ns-check            skip checking if the hostname is resolvable.
--mode <MODE>              remote execution mode:
                           nsh - nsh based remote execution
                           rsh - rsh based remote execution
                           ssh - ssh based remote execution
                           local - execute the script locally, set TARGET_HOST
                           on each execution

examples
========

1. run the command "ls" on host1 and host2.

$ nrun --command ls host1 host2

2. run the command "ls -al" on host1, host2 and all hosts in the file <HOSTS.LST>.

$ nrun --hosts-file <HOSTS.LST> --command ls --arguments "-al" host1 host2

3. run the command "ls" on all hosts in the file <HOSTS.LST> - mode "ssh".

$ nrun --hosts-file <HOSTS.LST> --command ls --mode ssh

4. copy the script bin/script.sh to each target hosts and execute it.

$ nrun --hosts-file <HOSTS.LST> --command bin/script.sh --copy

5. execute the local script test.sh for each target host

$ nrun --hosts-file <HOSTS.LST> --command ./test.sh --mode local

6. copy file test.tar to all hosts in the file <HOSTS.LST>

$ ncopy --hosts-file <HOSTS.LST> --source test.tar --destination /tmp

configuration
=============

special configuration options for the different modes and additional all
commandline options can be given in a configuration file. the following three
places will be searched for configuration files (values in the last
configuration file will overwrite values in the first configuration file):

- $FindBin::Bin/../etc/nrun.config
- /etc/nrun.config
- $HOME/.nrun.config

--<snip>--
###
# global options
$options->{ssh_binary}   = "/usr/bin/ssh";
$options->{scp_binary}   = "/usr/bin/scp";
$options->{ssh_args}     = "-o PreferredAuthentications=publickey";
$options->{ssh_user}     = "root";
$options->{scp_args}     = "-o PreferredAuthentications=publickey";
$options->{scp_user}     = "root";
$options->{arg_mode}     = "ssh";
$options->{arg_parallel} = 5;
$options->{arg_timeout}  = 60;

1;
--<snap>--

logging
=======

on each execution run, the command output and exit code will be saved inside the
logging directory. the default logging directory is $HOME/.nrun.

- $LOGDIR/results.log - will contain the exit codes
- $LOGDIR/output.log - will contain the complete command output for all hosts
- $LOGDIR/hosts/<HOSTNAME>.log - will contain the command output for a single
  host

mode ssh
========

use ssh as the underlying remote access mechanism.

the following configuration options must be set in the configuration file:

'ssh_args'   - arguments supplied to the ssh binary
'scp_args'   - arguments supplied to the scp binary
'ssh_binary' - ssh binary to be executed
'scp_binary' - scp binary to be executed
'ssh_user'   - ssh login user
'scp_user'   - scp login user

for passwordless login ssh-agent can be used:

# ssh-keygen
# scp .ssh/id_rsa.pub $USER@$HOST:.ssh/authorized_keys

# eval `ssh-agent` 
# ssh-add

to prevent any ssh interaction the following ssh command paramters are
suggested:

-o PreferredAuthentications=hostbased,publickey
-o StrictHostKeyChecking=no
-o UserKnownHostsFile=/dev/null
-q

mode local
==========

execute the script locally for each host and set the environment variable
TARGET_HOST on each execution.

mode nsh
========

use nsh as the underlying remote access mechanism.

the following configuration options must be set in the configuration file:

'agentinfo_args'   - arguments supplied to the agentinfo binary
'nexec_args'       - arguments supplied to the nexec binary
'ncp_args'         - arguments supplied to the ncp binary
'agentinfo_binary' - agentinfo binary to be executed
'nexec_binary'     - nexec binary to be executed
'ncp_binary'       - ncp binary to be executed

mode rsh
========

use rsh as the underlying remote access mechanism.

the following configuration options must be set in the configuration file:

'rsh_args'   - arguments supplied to the rsh binary
'rcp_args'   - arguments supplied to the rcp binary
'rsh_binary' - rsh binary to be executed
'rcp_binary' - rcp binary to be executed
'rsh_user'   - rsh login user
'rcp_user'   - rcp login user

inspecting long running processes

it is possible to signal nrun with USR1 and USR2 to dump, resp. save the currently
running processes. if nrun is signaled with USR2, it will create a file in
the directory it was started in called trace.txt.

the integer in square brackets is the pid of the perl process and the integer in
round brackets is the pid of the executed process.

$ kill -USR1 1234
[14760]: (14761) TARGET_HOST=localhost /tmp/test.sh
[14760]: 1
[14760]: 2
[14756]: (14757) TARGET_HOST=qn439 /tmp/test.sh
[14756]: 1
[14756]: 2

transferring the public key
===========================

the helper script misc/put_pubkey can be used to transfer the ssh public key
to the target hosts without supplying a password for each login. it is meant
to be executed by the nrun script in mode local.

$ nrun -h <HOSTS.LST> -c ./put_pubkey -a "<KEY> <USER> <PWD>" --mode local -t 120

a note on the git repository
============================

$ git clone https://github.com/tbenk/nrun
$ ln -s ../../.git_hooks/commit-msg .git/hooks

to enable keyword substitution:
$ git config --local filter.keywords.clean ".git_filters/keywords -m clean -f %f"
$ git config --local filter.keywords.smudge ".git_filters/keywords -m smudge -f %f"

to disable keyword substitution:
$ git config --local filter.keywords.smudge "cat"

after git keyword substitution is enabled, the following command will replace
all keywords in the source files:

$ git checkout HEAD .

for keyword substitution to work at least git version v1.7.3.4-599-ga2b665d is
necessary.

