blob: 572751f66a35211cb6faef4511f687d609d10a9a [file] [log] [blame]
Damien Millerf1ce5052003-06-11 22:04:39 +10001.\" $OpenBSD: ssh-keyscan.1,v 1.17 2003/06/10 09:12:11 jmc Exp $
Ben Lindstromb22c2b82001-03-05 06:50:47 +00002.\"
3.\" Copyright 1995, 1996 by David Mazieres <dm@lcs.mit.edu>.
4.\"
5.\" Modification and redistribution in source and binary forms is
6.\" permitted provided that due credit is given to the author and the
Ben Lindstroma238f6e2001-06-09 01:30:39 +00007.\" OpenBSD project by leaving this copyright notice intact.
Ben Lindstrom36579d32001-01-29 07:39:26 +00008.\"
Ben Lindstromb6434ae2000-12-05 01:15:09 +00009.Dd January 1, 1996
Ben Lindstromb22c2b82001-03-05 06:50:47 +000010.Dt SSH-KEYSCAN 1
Ben Lindstromb6434ae2000-12-05 01:15:09 +000011.Os
12.Sh NAME
13.Nm ssh-keyscan
14.Nd gather ssh public keys
15.Sh SYNOPSIS
16.Nm ssh-keyscan
Damien Miller495dca32003-04-01 21:42:14 +100017.Bk -words
Ben Lindstrom325e70c2001-08-06 22:41:30 +000018.Op Fl v46
19.Op Fl p Ar port
20.Op Fl T Ar timeout
21.Op Fl t Ar type
22.Op Fl f Ar file
23.Op Ar host | addrlist namelist
24.Op Ar ...
Damien Miller495dca32003-04-01 21:42:14 +100025.Ek
Ben Lindstromb6434ae2000-12-05 01:15:09 +000026.Sh DESCRIPTION
27.Nm
28is a utility for gathering the public ssh host keys of a number of
Damien Miller495dca32003-04-01 21:42:14 +100029hosts.
30It was designed to aid in building and verifying
Ben Lindstromb6434ae2000-12-05 01:15:09 +000031.Pa ssh_known_hosts
32files.
33.Nm
34provides a minimal interface suitable for use by shell and perl
35scripts.
36.Pp
37.Nm
38uses non-blocking socket I/O to contact as many hosts as possible in
Damien Miller495dca32003-04-01 21:42:14 +100039parallel, so it is very efficient.
40The keys from a domain of 1,000
Ben Lindstromb6434ae2000-12-05 01:15:09 +000041hosts can be collected in tens of seconds, even when some of those
Damien Miller495dca32003-04-01 21:42:14 +100042hosts are down or do not run ssh.
43For scanning, one does not need
Ben Lindstrom594e2032001-09-12 18:35:30 +000044login access to the machines that are being scanned, nor does the
45scanning process involve any encryption.
Ben Lindstrom0b5afb92001-08-06 22:01:29 +000046.Pp
47The options are as follows:
Ben Lindstromb6434ae2000-12-05 01:15:09 +000048.Bl -tag -width Ds
Ben Lindstrom325e70c2001-08-06 22:41:30 +000049.It Fl p Ar port
50Port to connect to on the remote host.
Ben Lindstrom8d066fb2001-09-12 17:06:13 +000051.It Fl T Ar timeout
Damien Miller495dca32003-04-01 21:42:14 +100052Set the timeout for connection attempts.
53If
Ben Lindstromb6434ae2000-12-05 01:15:09 +000054.Pa timeout
55seconds have elapsed since a connection was initiated to a host or since the
56last time anything was read from that host, then the connection is
Damien Miller495dca32003-04-01 21:42:14 +100057closed and the host in question considered unavailable.
58Default is 5 seconds.
Ben Lindstrom325e70c2001-08-06 22:41:30 +000059.It Fl t Ar type
Ben Lindstrom8d066fb2001-09-12 17:06:13 +000060Specifies the type of the key to fetch from the scanned hosts.
Ben Lindstrom325e70c2001-08-06 22:41:30 +000061The possible values are
62.Dq rsa1
63for protocol version 1 and
64.Dq rsa
65or
66.Dq dsa
67for protocol version 2.
68Multiple values may be specified by separating them with commas.
69The default is
70.Dq rsa1 .
71.It Fl f Ar filename
Ben Lindstrom24643222001-06-25 05:08:11 +000072Read hosts or
Ben Lindstromb6434ae2000-12-05 01:15:09 +000073.Pa addrlist namelist
74pairs from this file, one per line.
75If
76.Pa -
77is supplied instead of a filename,
78.Nm
Ben Lindstrom24643222001-06-25 05:08:11 +000079will read hosts or
Ben Lindstromb6434ae2000-12-05 01:15:09 +000080.Pa addrlist namelist
81pairs from the standard input.
Ben Lindstrom325e70c2001-08-06 22:41:30 +000082.It Fl v
83Verbose mode.
84Causes
85.Nm
86to print debugging messages about its progress.
87.It Fl 4
88Forces
89.Nm
90to use IPv4 addresses only.
91.It Fl 6
92Forces
93.Nm
94to use IPv6 addresses only.
Ben Lindstromd26dcf32001-01-06 15:18:16 +000095.El
Ben Lindstrom0b5afb92001-08-06 22:01:29 +000096.Sh SECURITY
Ben Lindstrom594e2032001-09-12 18:35:30 +000097If a ssh_known_hosts file is constructed using
Ben Lindstrom0b5afb92001-08-06 22:01:29 +000098.Nm
Ben Lindstrom594e2032001-09-12 18:35:30 +000099without verifying the keys, users will be vulnerable to
Ben Lindstrom0b5afb92001-08-06 22:01:29 +0000100.I man in the middle
101attacks.
Ben Lindstrom594e2032001-09-12 18:35:30 +0000102On the other hand, if the security model allows such a risk,
Ben Lindstrom0b5afb92001-08-06 22:01:29 +0000103.Nm
Ben Lindstrom594e2032001-09-12 18:35:30 +0000104can help in the detection of tampered keyfiles or man in the middle
105attacks which have begun after the ssh_known_hosts file was created.
Ben Lindstromb6434ae2000-12-05 01:15:09 +0000106.Sh FILES
Ben Lindstromb6434ae2000-12-05 01:15:09 +0000107.Pa Input format:
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000108.Bd -literal
Ben Lindstromb6434ae2000-12-05 01:15:09 +00001091.2.3.4,1.2.4.4 name.my.domain,name,n.my.domain,n,1.2.3.4,1.2.4.4
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000110.Ed
Ben Lindstromb6434ae2000-12-05 01:15:09 +0000111.Pp
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000112.Pa Output format for rsa1 keys:
113.Bd -literal
Ben Lindstromb6434ae2000-12-05 01:15:09 +0000114host-or-namelist bits exponent modulus
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000115.Ed
116.Pp
117.Pa Output format for rsa and dsa keys:
118.Bd -literal
119host-or-namelist keytype base64-encoded-key
120.Ed
121.Pp
122Where
123.Pa keytype
124is either
125.Dq ssh-rsa
126or
Damien Miller93506352003-05-14 13:46:33 +1000127.Dq ssh-dss .
Ben Lindstromb6434ae2000-12-05 01:15:09 +0000128.Pp
Damien Miller05eda432002-02-10 18:32:28 +1100129.Pa /etc/ssh/ssh_known_hosts
Damien Millerf1ce5052003-06-11 22:04:39 +1000130.Sh EXAMPLES
131Print the
132.Pa rsa1
133host key for machine
134.Pa hostname :
135.Bd -literal
136$ ssh-keyscan hostname
137.Ed
138.Pp
139Find all hosts from the file
140.Pa ssh_hosts
141which have new or different keys from those in the sorted file
142.Pa ssh_known_hosts :
143.Bd -literal
144$ ssh-keyscan -t rsa,dsa -f ssh_hosts | \e
145 sort -u - ssh_known_hosts | diff ssh_known_hosts -
146.Ed
147.Sh SEE ALSO
148.Xr ssh 1 ,
149.Xr sshd 8
150.Sh AUTHORS
151.An David Mazieres Aq dm@lcs.mit.edu
152wrote the initial version, and
153.An Wayne Davison Aq wayned@users.sourceforge.net
154added support for protocol version 2.
Ben Lindstromb6434ae2000-12-05 01:15:09 +0000155.Sh BUGS
156It generates "Connection closed by remote host" messages on the consoles
Ben Lindstrom325e70c2001-08-06 22:41:30 +0000157of all the machines it scans if the server is older than version 2.9.
Ben Lindstromb6434ae2000-12-05 01:15:09 +0000158This is because it opens a connection to the ssh port, reads the public
159key, and drops the connection as soon as it gets the key.