Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
branch: master
Fetching contributors…

Cannot retrieve contributors at this time

268 lines (266 sloc) 8.18 kb
.\" This manual page was originally written by Jan Schaumann
.\" <jschauma@yahoo-inc.com> in February 2007.
.Dd February 03, 2012
.Dt CHECKHOSTS 1
.Os
.Sh NAME
.Nm checkhosts
.Nd scan a list of hosts and run a given script on them
.Sh SYNOPSIS
.Nm
.Op Fl HIPSbeh
.Op Fl A Ar authmode
.Op Fl o Ar dir
.Op Fl r Ar script
.Op Fl f Ar file
.Op Ar hostname Oo Ar ... Oc
.Sh DESCRIPTION
For every host in the input, the
.Nm
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
.Xr bash 1 .
The output from the script is collected in the output file, prepended with
the hostname (and IP address) that
.Nm
used to connect to this host.
Any and all other output formatting is the responsibility of the remote
script or the post-processing script.
.Pp
The following options are supported:
.Bl -tag -width A_authmode_
.It Fl A Ar authmode
Specify the authentication mode.
Valid options are "all", "password" and "pubkey".
Specifying this option will cause
.Xr ssh 1
to be instructed to only use the given authentication mechanism with no
others.
.It Fl H
Do not use a headless user.
Per default,
.Nm
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).
.It Fl I
Do not use IP addresses to ssh to.
Per default,
.Nm
will use the IP address (or rather the second field of the input line) to
connect to.
.It Fl P
Do not try to ping the hosts.
Per default,
.Nm
will try to ping each host before trying to ssh to it.
If a host fails to ping, it is skipped.
.It Fl S
Do not check if sshd is listening on port 22 on the hosts.
Per default,
.Nm
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.
.It Fl b
The script is run in the background.
This slightly changes the default behaviour and should normally only be
set by the invoking
.Xr scanhosts 1
script.
.It Fl e
Print errors relating to host reachability to stderr.
That is, instead of sorting hosts that don't ping, don't listen on port 22
or cannot be reached into different output files, simply report them on
stderr.
(Hosts that were successfully processed will then not be reported at all.)
.It Fl f Ar file
Read the list of hosts from
.Ar file .
Multiple
.Fl f Ar file
are allowed.
.It Fl h
Print a usage message and exit.
.It Fl o Ar dir
Put the output files into
.Ar dir .
Per default, output is generated in TMPDIR.
.It Fl r Ar script
Run this script on the remote host.
The script is executed on the remote host via
.Xr bash 1 .
Per default, the file './remote.sh' is used.
See the section
.Xr SCRIPT
for more details.
.El
.Sh SCRIPT
The script executed on the remote side is executed with
.Xr 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).
.Pp
Please note that if the script contains
.Xr sudo 8
invocations, the password will actually be echoed back on the terminal!
This is due to the way
.Xr sudo 8
and
.Xr 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.
.Sh INPUT
Input can be provided via the
.Fl f Ar file
flag, as arguments the command-line or from stdin.
Multiple
.Fl f Ar filename
are allowed.
.Pp
Hostnames or IP addresses provided as arguments on the command-line are
processed first.
Next,
.Nm
will process all input files.
If (and only if!) no input files are provided and no arguments were given
on the command-line,
.Nm
will read lines to process from stdin.
.Pp
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.
.Pp
If no files are given, then
.Nm
will read input lines from stdin.
.Pp
.Sh OUTPUT
Unless the
.Fl e
flag is given, output will be generated into the following distinct files:
.Bl -tag -width hosts_checked
.It hosts_checked
The list of hosts that
.Nm
attempted to connect to.
.It hosts_exit_N
The list of hosts (including output of the script) on which the given
script was executed, but returned a non-zero 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.
.It hosts_noping
The list of hosts that did not respond to
.Xr ping 1
(unless
.Fl P
was given).
.It hosts_nossh
The list of hosts that were unable to be reached via
.Xr 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;
.It hosts_nosshd
The list of hosts that were found not to have an ssh daemon listening on
port 22 (unless
.Fl S
was given).
.It 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.
.El
.Sh SSH PROCESSES
.Nm
spawns a large number of ssh processes, and sometimes it can be necessary to
monitor them to ensure they are not hung.
.Xr ssh 1
is invoked by
.Nm
via a wrapper named ".checkhosts-ssh" in the output directory to ensure
that its connections can easily be distinguished from normal ssh
connections.
.Pp
The use of the
.Xr tkill 1
utility is recommended to periodically prune any possibly hung ssh
processes.
.Sh CAVEATS
If you run
.Nm
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
.Nm .
This tool specifically does not attempt to 'cache' your passwords for you.
.Sh EXAMPLES
The following examples illustrate common usage of this tool.
.Pp
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:
.Pp
.Bd -literal -offset indent
$ autopw checkhosts -P -f /tmp/input -o ./output/20070227
.Ed
.Pp
This runs the script ~/bin/myscript.sh on the hosts given on the command-line.
Output is placed into TMPDIR (or /tmp, if that variable is not set):
.Pp
.Bd -literal -offset indent
$ autopw checkhosts -r ~/bin/myscript.sh host1 host2 host3 ... hostN
.Ed
.Pp
Assuming a headless user named 'headless' exists and uses the ssh key
found in ~/.ssh/headless.privkey use the SSHOPTS environment variable as
follows:
.Pp
.Bd -literal -offset indent
$ autopw env SSHOPTS="-l headless -i ~/.ssh/headkess.privkey" \\
checkhosts <other options>
.Ed
.Sh EXIT STATUS
.Ex -std
.Sh ENVIRONMENT
.Nm
will pass the value of the variable SSHOPTS on to
.Xr ssh 1
after any options it passes itself.
This allows the user to overwrite any options normally used by
.Nm
and is particularly useful to specify the username and location of ssh
keys different from the defaults.
.Sh SEE ALSO
.Xr scanhosts 1 ,
.Xr sigsh 1 ,
.Xr tkill 1
.Sh HISTORY
The
.Nm
utility was originally written by
.An Jan Schaumann
.Aq 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.
.Sh BUGS
Please reports bugs or feature requests to the author.
Jump to Line
Something went wrong with that request. Please try again.