upstream: apply a lick of paint; tweaks/ok dtucker
OpenBSD-Commit-ID: 518a6736338045e0037f503c21027d958d05e703
diff --git a/ssh-keyscan.1 b/ssh-keyscan.1
index b6bee17..edefe76 100644
--- a/ssh-keyscan.1
+++ b/ssh-keyscan.1
@@ -1,4 +1,4 @@
-.\" $OpenBSD: ssh-keyscan.1,v 1.42 2018/02/23 07:38:09 jmc Exp $
+.\" $OpenBSD: ssh-keyscan.1,v 1.43 2018/03/02 21:40:15 jmc Exp $
.\"
.\" Copyright 1995, 1996 by David Mazieres <dm@lcs.mit.edu>.
.\"
@@ -6,26 +6,23 @@
.\" permitted provided that due credit is given to the author and the
.\" OpenBSD project by leaving this copyright notice intact.
.\"
-.Dd $Mdocdate: February 23 2018 $
+.Dd $Mdocdate: March 2 2018 $
.Dt SSH-KEYSCAN 1
.Os
.Sh NAME
.Nm ssh-keyscan
-.Nd gather ssh public keys
+.Nd gather SSH public keys
.Sh SYNOPSIS
.Nm ssh-keyscan
-.Bk -words
.Op Fl 46cDHv
.Op Fl f Ar file
.Op Fl p Ar port
.Op Fl T Ar timeout
.Op Fl t Ar type
.Op Ar host | addrlist namelist
-.Ar ...
-.Ek
.Sh DESCRIPTION
.Nm
-is a utility for gathering the public ssh host keys of a number of
+is a utility for gathering the public SSH host keys of a number of
hosts.
It was designed to aid in building and verifying
.Pa ssh_known_hosts
@@ -39,19 +36,41 @@
parallel, so it is very efficient.
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.
+hosts are down or do not run
+.Xr sshd 8 .
For scanning, one does not need
login access to the machines that are being scanned, nor does the
scanning process involve any encryption.
.Pp
+Input is expected in the format:
+.Bd -literal -offset 3n
+1.2.3.4,1.2.4.4 name.my.domain,name,n.my.domain,n,1.2.3.4,1.2.4.4
+.Ed
+.Pp
+The output format is:
+.Bd -literal -offset 3n
+host-or-namelist keytype base64-encoded-key
+.Ed
+.Pp
+Where
+.Ar keytype
+is either
+.Dq ecdsa-sha2-nistp256 ,
+.Dq ecdsa-sha2-nistp384 ,
+.Dq ecdsa-sha2-nistp521 ,
+.Dq ssh-ed25519 ,
+.Dq ssh-dss
+or
+.Dq ssh-rsa .
+.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl 4
-Forces
+Force
.Nm
to use IPv4 addresses only.
.It Fl 6
-Forces
+Force
.Nm
to use IPv6 addresses only.
.It Fl c
@@ -69,32 +88,32 @@
.Ar file ,
one per line.
If
-.Pa -
+.Sq -
is supplied instead of a filename,
.Nm
-will read hosts or
-.Dq addrlist namelist
-pairs from the standard input.
+will read from the standard input.
.It Fl H
Hash all hostnames and addresses in the output.
Hashed names may be used normally by
-.Nm ssh
+.Xr ssh 1
and
-.Nm sshd ,
+.Xr sshd 8 ,
but they do not reveal identifying information should the file's contents
be disclosed.
.It Fl p Ar port
-Port to connect to on the remote host.
+Connect to
+.Ar port
+on the remote host.
.It Fl T Ar timeout
Set the timeout for connection attempts.
If
.Ar timeout
seconds have elapsed since a connection was initiated to a host or since the
-last time anything was read from that host, then the connection is
+last time anything was read from that host, the connection is
closed and the host in question considered unavailable.
-Default is 5 seconds.
+The default is 5 seconds.
.It Fl t Ar type
-Specifies the type of the key to fetch from the scanned hosts.
+Specify the type of the key to fetch from the scanned hosts.
The possible values are
.Dq dsa ,
.Dq ecdsa ,
@@ -109,12 +128,10 @@
.Dq ed25519
keys.
.It Fl v
-Verbose mode.
-Causes
-.Nm
-to print debugging messages about its progress.
+Verbose mode:
+print debugging messages about progress.
.El
-.Sh SECURITY
+.Pp
If an ssh_known_hosts file is constructed using
.Nm
without verifying the keys, users will be vulnerable to
@@ -125,40 +142,18 @@
can help in the detection of tampered keyfiles or man in the middle
attacks which have begun after the ssh_known_hosts file was created.
.Sh FILES
-Input format:
-.Bd -literal
-1.2.3.4,1.2.4.4 name.my.domain,name,n.my.domain,n,1.2.3.4,1.2.4.4
-.Ed
-.Pp
-Output format for RSA, DSA, ECDSA, and Ed25519 keys:
-.Bd -literal
-host-or-namelist keytype base64-encoded-key
-.Ed
-.Pp
-Where
-.Ar keytype
-is either
-.Dq ecdsa-sha2-nistp256 ,
-.Dq ecdsa-sha2-nistp384 ,
-.Dq ecdsa-sha2-nistp521 ,
-.Dq ssh-ed25519 ,
-.Dq ssh-dss
-or
-.Dq ssh-rsa .
-.Pp
.Pa /etc/ssh/ssh_known_hosts
.Sh EXAMPLES
-Print the rsa host key for machine
+Print the RSA host key for machine
.Ar hostname :
-.Bd -literal
-$ ssh-keyscan hostname
-.Ed
+.Pp
+.Dl $ ssh-keyscan -t rsa hostname
.Pp
Find all hosts from the file
.Pa ssh_hosts
which have new or different keys from those in the sorted file
.Pa ssh_known_hosts :
-.Bd -literal
+.Bd -literal -offset indent
$ ssh-keyscan -t rsa,dsa,ecdsa,ed25519 -f ssh_hosts | \e
sort -u - ssh_known_hosts | diff ssh_known_hosts -
.Ed
@@ -176,8 +171,3 @@
wrote the initial version, and
.An Wayne Davison Aq Mt wayned@users.sourceforge.net
added support for protocol version 2.
-.Sh BUGS
-It generates "Connection closed by remote host" messages on the consoles
-of all the machines it scans if the server is older than version 2.9.
-This is because it opens a connection to the ssh port, reads the public
-key, and drops the connection as soon as it gets the key.