Table of Contents

Name

checkhosts -- scan a list of hosts and run a given script on them

Synopsis

checkhosts [-HIPSbh] [-A authmode] [-o dir] [-r script] -f file

Description

For every host in the input, the checkhosts utility will check whether or not the host pings, check if sshd is listening on port 22 of the remote host, and finally tries to run the specified script on the remote host. The script is piped into the ssh command, and executed on the remote side via bash(1) . The output from the script is collected in the output file, prepended with the hostname (and IP address) that checkhosts used to connect to this host. Any and all other output formatting is the responsibility of the remote script or the post-processing script.

The following options are supported:

-A authmode
Specify the authentication mode. Valid options are “all", “password” and “pubkey". Specifying this option will cause ssh(1) to be instructed to only use the given authentication mechanism with no others.

-H
Do not use a headless user. Per default, checkhosts will assume that the ssh connections it establishes are for a headless and hence disables password authentication explicitly (it relies on the invoking user having access to the required ssh key for this user).

-I
Do not use IP addresses to ssh to. Per default, checkhosts will use the IP address (or rather the second field of the input line) to connect to.

-P
Do not try to ping the hosts. Per default, checkhosts will try to ping each host before trying to ssh to it. If a host fails to ping, it is skipped.

-S
Do not check if sshd is listening on port 22 on the hosts. Per default, checkhosts will try to connect to port 22 on the remote host and checks if it gets an SSH version string back. If not, the host is skipped.

-b
The script is run in the background. This slightly changes the default behaviour and should normally only be set by the invoking scanhosts(1) script.

-f file
Read the list of hosts from file. Multiple -f file are allowed.

-h
Print a usage message and exit.

-o dir
Put the output files into dir. Per default, output is generated in TMPDIR.

-r script
Run this script on the remote host. The script is executed on the remote host via bash(1) . Per default, the file ‘./remote.sh’ is used. See the section SCRIPT for more details.

Script

The script executed on the remote side is executed with bash(1) (either explicitly or via the headless user’s shell). Hence, it needs to be a valid bash script, though due to different versions of bash found on different hosts, it is recommended to have the script be /bin/sh compatible. The script can be as simple or complex as you like, and in theory you should be able to let it perform any possible task you can script (including generating code in another language, storing it in another file, compiling it if needed and executing it).

Please note that if the script contains sudo(8) invocations, the password will actually be echoed back on the terminal! This is due to the way sudo(8) and ssh(1) interact when called from a script. Please take care to not let anybody shoulder-surf and do not store the output in any files readable by anybody else.

Input

Input can be provided via the -f file flag. Multiple -f filename are allowed. The input format of the file is two fields per line, the first field being the hostname, the second the IP address of the host. Lines starting with a # are treated as comments and ignored.

Output

Output is generated into the following distinct files:

hosts_checked The list of hosts that checkhosts attempted to connect to.

hosts_exit_N
The list of hosts (including output of the script) on which the given script was executed, but returned a nonzero exit status. The output of the script will be prepended with the hostname, but otherwise the format of the output file is determined by the output generated by the script.

hosts_noping
The list of hosts that did not respond to ping(1) (unless -P was given).

hosts_nossh
The list of hosts that were unable to be reached via ssh(1) . There are numerous reasons why a host may fail. Among them are: the user does not have an account on the host; the machine can not be reached due to firewall (ACL) issues; the host refuses logins via ssh by way of /etc/hosts.allow;

hosts_nosshd
The list of hosts that were found not to have an ssh daemon listening on port 22 (unless -S was given).

hosts_ok
The list of hosts on which the given script was successfully executed, together with the output of the script. The output of the script will be prepended with the hostname, but otherwise the format of the output file is determined by the output generated by the script.

Ssh Processes

checkhosts spawns a large number of ssh processes, and sometimes it can be necessary to monitor them to ensure they are not hung. ssh(1) is invoked by checkhosts via a wrapper named “.checkhosts-ssh” in the output directory to ensure that its connections can easily be distinguished from normal ssh connections.

The use of the tkill(1) utility is recommended to periodically prune any possibly hung ssh processes.

Caveats

If you run checkhosts with password authentication enabled, then it will, not very surprisingly, prompt you for your password. It will do that for every ssh connection it makes. To get around this, use your favorite password injector expect script (let’s call it ‘autopw’) to invoke checkhosts. This tool specifically does not attempt to ‘cache’ your passwords for you.

Examples

The following examples illustrate common usage of this tool.

This runs the scans without checking if a host pings, reads input from the file /tmp/input and puts the output into the directory ./output/20070227 under the current working directory:

$ autopw checkhosts -P -f /tmp/input -o ./output/20070227

This runs the script ~/bin/myscript.sh on the hosts given on the commandline. Output is placed into TMPDIR (or /tmp, if that variable is not set):

$ autopw checkhosts -r ~/bin/myscript.sh host1 host2 host3 ... hostN

Assuming a headless user named ‘headless’ exists and uses the ssh key found in ~/.ssh/headless.privkey use the SSHOPTS environment variable as follows:

$ autopw env SSHOPTS="-l headless -i ~/.ssh/headkess.privkey” \ checkhosts <other options>

Exit Status

The checkhosts utility exits 0 on success, and >0 if an error occurs.

Environment

checkhosts will pass the value of the variable SSHOPTS on to ssh(1) after any options it passes itself. This allows the user to overwrite any options normally used by checkhosts and is particularly useful to specify the username and location of ssh keys different from the defaults.

See Also

scanhosts(1), sigsh(1), tkill(1)

History

The checkhosts utility was originally written by Jan Schaumann <jschauma@yahoo-inc.com> in January 2007. It’s original task was to check hosts if they were able to deal with the new Daylight Saving Time instituted in the USA in 2007.

Bugs

Please reports bugs or feature requests to the author.

Table of Contents