$Id: README,v 1.2 1995/11/30 11:44:08 dm Exp $

			     ssh-keyscan

			    David Mazieres
			   <dm@lcs.mit.edu>


DESCRIPTION

This is ssh-keyscan, a utility for gathering the ssh public keys of a
number of hosts.  It was designed to aid in building and verifying
ssh_known_hosts files.  It is easy to write perl and shell scripts for
most kinds of ssh_known_hosts file manipulations.  The one difficulty
is that fetching a host's ssh public key from a script is difficult,
and doing it efficiently is almost impossible.  Ssh-keyscan is
intended to provide a minimal interface to fetching public keys, to
fix this difficulty in developing scripts.  With the included utility
"make-host-list", ssh-keyscan can also be used to generate
ssh_known_hosts files orders of magnitude more quickly than with
ssh-make-known-hosts.

Ssh-keyscan uses non-blocking socket I/O to contact as many hosts as
possible in parallel, and as such it is very efficient.  Using
ssh-keyscan, the keys from a domain of 1,000 hosts can be collected in
tens of seconds, even when some of those hosts are down or do not run
ssh.  A domain of 15,000 hosts can be scanned in just a few minutes.
Ssh-keyscan does not require you to be able to log into the machines
you are scanning, nor does perform any encryption during the scan
process.

My intention in writing ssh-keyscan was to write something which was
to make-ssh-known-hosts what the fping program is to ping: Easier to
use in scripts and more efficient on large numbers of hosts.  On the
other hand, ssh-keyscan may be less useful as a quick command-line
utility.  Instead of "make-ssh-known-hosts my.domain" you must now
type "make-host-list my.domain | ssh-keyscan -f-".  If you want to
select hosts by regexp or some other property, you will need to write
your own filter and put it in the pipeline.  If, however, your main
reason for filtering was speed, it is still faster to run ssh-keyscan
on your whole domain than make-ssh-known-hosts on a subset of your
domain.

The usage of ssh-keyscan is:

   ssh-keyscan { [--] { host  | "host namelist" } | -f file } ...

where multiple hosts and files can be passed on the same command line,
and the filename "-" designates the standard input.  Each file simply
contains a list of hosts or "host namelist" pairs, one per line.  For
instance, for a hypothetical host "long-name.my.domain", with IP
address 1.2.3.4 and a CNAME of "ln.my.domain", you would probably want
a host and namelist pair like:

   1.2.3.4   long-name.my.domain,ln.my.domain,long-name,ln,1.2.3.4

The output of ssh-keyscan will be one line of the form

   host-or-namelist bits exponent modulus

for each host that appeared to be running ssh.  The first field will
contain the host unless a namelist was specified for that host, in
which case the first field will be the namelist.

The intention is that a system administrator will set up a file of
"host hostlist" pairs, and periodically run ssh-keyscan to make sure
no one has changed the host keys on all the hosts in a network.  The
included perl script make-host-list will print all hosts and
corresponding namelists from a particular domain, which can be useful
in setting up such files.  The usage is:

   make-host-list [-d] domain [dns-server]

By default the host name "host.my.domain" will also be included as
simply "host" in the list, but the "-d" flag will disable this
behavior.  There is no way to "grep" for particular types of hosts to
ignore, as in make-ssh-known-hosts.  However, ssh-keyscan is fast
enough that you no longer need to worry about this if speed was the
only reason for filtering.  If you do wish to filter, you can simply
write your own script to build the ssh-keyscan input file.


INSTALLATION

To build ssh-keyscan, you must have built ssh and have the build tree
still around.

Edit the Makefile, and set the variable SSH to point to the location
of your ssh build tree (default is ../ssh-1.2.12).

Type "make" to build.  Then type

   ./make-host-list your.domain | ./ssh-keyscan -f-

to see if it works.

If it works and you like it, install it by hand.  It's such beta
software that I've not yet put an install target in the Makefile.


SECURITY

If you make an ssh_known_hosts file using ssh-keyscan and without
verifying the keys, you will be vulnerable to man in the middle
attacks.  On the other hand, if your security model allows such a
risk, ssh-keyscan can help you detect tampered keyfiles or man in the
middle attacks which have begun after you created your ssh_known_hosts
file.


BUGS

I just wrote this software today, so it's quick and a little bit
dirty.  There are certainly many bugs.  Please let me know.

Ssh-keyscan sometimes misses some hosts that are up, particularly
the second time if you run it twice in rapid succession.

Ssh-keyscan generates "Connection closed by remote host" messages on
the consoles of all the machines it scans.  This is because it opens a
connection to the ssh port to read the public key, but then drops the
connection as soon as it has gotten the key.


COPYING

These files are Copyright 1995 by David Mazieres <dm@lcs.mit.edu>.

Make-host-list contains code Copyright 1995 by Tero Kivinen, which you
may use and distribute under the terms of version 2 of the GNU General
Public License.

The other code you may use and distribute under either the terms of
version 2 of the GNU GPL, or the copying conditions on the most recent
version of ssh, at your option.
