.\" $YahooCvsId: checkhosts.1,v 1.12 2009/01/23 21:16:52 Exp $ .\" $Source: /CVSROOT/.../checkhosts.1,v $ .\" .\" This manual page was originally written by Jan Schaumann .\" in February 2007. .Dd January 22, 2009 .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 IPSbh .Op Fl o Ar dir .Op Fl r Ar script .Fl f Ar file .Sh DESCRIPTION For every host in the input, the .Nm utility will check whether or not the host pings (unless the .Fl P flag is used), 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 r_script_ .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 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. .Sh SCRIPT The script executed on the remote side is executed with .Xr bash 1 . 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. Multiple .Fl f Ar 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. .Sh OUTPUT Output is generated into five distinct files: .Bl -tag -width hosts_checked .It hosts_checked The list of hosts that .Nm attempted to connect to. .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 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 sh 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 sh checkhosts -r ~/bin/myscript.sh host1 host2 host3 ... hostN .Ed .Sh EXIT STATUS .Ex -std .Sh REQUIRED PACKAGES The .Nm utility requires the following .Xr yinst 1 packages: .Bl -tag -width autopw .It Sy autopw To allow users to connect to the given hosts without having to type their password. .El .Sh SEE ALSO .Xr autopw 1 , .Xr scanhosts 1 , .Xr tkill 1 .Sh HISTORY The .Nm utility was originally written by .An Jan Schaumann .Aq jschauma@ 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 file bugs and feature requests via bugzilla at http:///enter_bug.cgi?product=NSS%20Architecture&component=scanmaster .