/ 
App-nrun-v1.0.0_6
River stage zero No dependents
/ ncopy

NAME

ncopy - copy a file or directory to multiple target servers.

SYNOPSIS

ncopy -t HOST1[,HOST2,...] [-p MAX] [-l DIR] [--timeout SEC] [--mode MODE] [--dump-output] [--no-hostname] [--no-logfile] [--skip-ping-check] [--skip-ns-check] [--version] [--async] -- SRC DST

DESCRIPTION

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.

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). indentation does matter.

- $FindBin::Bin/../etc/nrunrc

- /etc/nrunrc

- $HOME/.nrunrc

---
# mode ssh options
ssh_copy: >
    /usr/bin/scp
    -o User=root
    -o PreferredAuthentications=hostbased,publickey
    -o StrictHostKeyChecking=no
    -o UserKnownHostsFile=/dev/null
    -o LogLevel=FATAL
    SOURCE HOSTNAME:TARGET

ssh_exec: >
    /usr/bin/ssh
    -o User=root
    -o PreferredAuthentications=hostbased,publickey
    -o StrictHostKeyChecking=no
    -o UserKnownHostsFile=/dev/null
    -o LogLevel=FATAL
    HOSTNAME COMMAND ARGUMENTS

ssh_delete: >
    /usr/bin/ssh
    -o User=root
    -o PreferredAuthentications=hostbased,publickey
    -o StrictHostKeyChecking=no
    -o UserKnownHostsFile=/dev/null
    -o LogLevel=FATAL
    HOSTNAME rm -f "FILE"

# additional commandline options
arg_mode: ssh
arg_parallel: 5
arg_timeout: 60

# alias definitions
alias:
    production:
        - host1
        - host2
    development:
        - host3
        - host4
    all:
        - production
        - development

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

MODES

mode ssh

use ssh as the underlying remote access mechanism.

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

'ssh_exec' - commandline for remote execution (COMMAND, ARGUMENTS, HOSTNAME will be replaced)

'ssh_copy' - commandline for remote copying (SOURCE, TARGET, HOSTNAME will be replaced)

'ssh_delete' - commandline for remote deletion (FILE, HOSTNAME will be replaced)

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 User=root
-o PreferredAuthentications=hostbased,publickey
-o StrictHostKeyChecking=no
-o UserKnownHostsFile=/dev/null
-o LogLevel=FATAL

mode rsh

use rsh as the underlying remote access mechanism.

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

'rsh_exec' - commandline for remote execution (COMMAND, ARGUMENTS, HOSTNAME will be replaced)

'rsh_copy' - commandline for remote copying (SOURCE, TARGET, HOSTNAME will be replaced)

'rsh_delete' - commandline for remote deletion (FILE, HOSTNAME will be replaced)

mode local

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

'local_exec' - commandline for local execution (COMMAND, ARGUMENTS, HOSTNAME will be replaced)

mode nsh

use nsh as the underlying remote access mechanism.

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

'nsh_exec' - commandline for remote execution (COMMAND, ARGUMENTS, HOSTNAME will be replaced)

'nsh_copy' - commandline for remote copying (SOURCE, TARGET, HOSTNAME will be replaced)

'nsh_delete' - commandline for remote deletion (FILE, HOSTNAME will be replaced)

'nsh_check' - commandline for the agentinfo check command (HOSTNAME will be replaced)

mode generic

this is a special generic mode the can be used for arbitrary remote execution mechanisms.

'cmdline_exec' - commandline for remote execution (COMMAND, ARGUMENTS, HOSTNAME will be replaced)

'cmdline_copy' - commandline for remote copying (SOURCE, TARGET, HOSTNAME will be replaced)

'cmdline_delete' - commandline for remote deletion (FILE, HOSTNAME will be replaced)

an example that resembles the mode ssh would look the following way:

generic_copy: >
    /usr/bin/scp
    -o User=root
    -o PreferredAuthentications=hostbased,publickey
    -o StrictHostKeyChecking=no
    -o UserKnownHostsFile=/dev/null
    -o LogLevel=FATAL
    SOURCE HOSTNAME:TARGET

generic_exec: >
    /usr/bin/ssh
    -o User=root
    -o PreferredAuthentications=hostbased,publickey
    -o StrictHostKeyChecking=no
    -o UserKnownHostsFile=/dev/null
    -o LogLevel=FATAL
    HOSTNAME COMMAND ARGUMENTS

generic_delete: >
    /usr/bin/ssh
    -o User=root
    -o PreferredAuthentications=hostbased,publickey
    -o StrictHostKeyChecking=no
    -o UserKnownHostsFile=/dev/null
    -o LogLevel=FATAL
    HOSTNAME rm -f "FILE"

OPTIONS

--async,-a asynchronous output mode.

--dump-output,-d instead of dumping the exit status, dump the command output.

--log-directory,-l DIR base directory for the log files.

--mode,-m MODE remote execution mode (see MODES)

--no-hostname omit hostname prefix.

--no-logfile do not generate any log files.

--parallel,-p MAX number of parallel connections (defaults to 5).

--skip-ping-check skip checking if the host answers on ping.

--skip-ns-check skip checking if the hostname is resolvable.

--target,-t HOST1[,HOST2,...] comma separated list of target hosts (see TARGETS).

--timeout SEC timeout for each command execution (defaults to 60).

--version,-v print the version string and exit.

EXAMPLES

1. copy file test.tar to host1, host2 and all hosts in the file HOSTS.LST

$ ncopy --target HOSTS.LST -- test.tar /tmp

TARGETS

a target name may be either a filename containing the target hosts, one per line, an alias definition in the configuration file or simply a hostname.

if there is a conflict, for example an alias named identically as an existing file, the alias will always overrule the filename and the filename will always overrule the hostname.

an alias can be defined in the configuration file the following way. an alias definition may contain additional alias names, filenames or simply hostnames. indentation does matter.

# alias definitions
alias:
    production:
        - host1
        - host2
    development:
        - host3
        - host4
    all:
        - production
        - development

NOTES

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 log directory trace_<%Y%m%d_%H_%M_%S>.log.

the integer in square brackets is the pid of the perl process.

$ kill -USR1 1234
host1[14760]: (31800) /usr/bin/ssh -o User=root localhost sleep 120
host1[14760]: 1
host1[14760]: 2
host1[14760]: SIGUSR1 received
host1[14756]: (31801) /usr/bin/ssh -o User=root localhost sleep 120
host2[14756]: 1
host2[14756]: 2
host2[14756]: SIGUSR1 received

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 -t HOSTS.LST --mode local --timeout 120 -- ./put_pubkey KEY USER PWD

AUTHOR

Timo Benk <benk@b1-systems.de>

SEE ALSO

nrun(1), dsh(1)