1 '\" te
   2 .\" Copyright (c) 2004, Sun Microsystems, Inc. All Rights Reserved.
   3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   6 .TH SSH-KEYSCAN 1 "Jul 24, 2004"
   7 .SH NAME
   8 ssh-keyscan \- gather public ssh host keys of a number of hosts
   9 .SH SYNOPSIS
  10 .LP
  11 .nf
  12 \fBssh-keyscan\fR [\fB-v46\fR] [\fB-p\fR \fIport\fR] [\fB-T\fR \fItimeout\fR] [\fB-t\fR \fItype\fR]
  13      [\fB-f\fR \fIfile\fR] [\fB-\fR] [\fIhost\fR... | \fIaddrlist\fR \fInamelist\fR] [...]
  14 .fi
  15 
  16 .SH DESCRIPTION
  17 .LP
  18 \fBssh-keyscan\fR is a utility for gathering the public ssh host keys of a
  19 number of hosts. It was designed to aid in building and verifying
  20 \fBssh_known_hosts\fR files. \fBssh-keyscan\fR provides a minimal interface
  21 suitable for use by shell and perl scripts. The output of \fBssh-keyscan\fR is
  22 directed to standard output.
  23 .sp
  24 .LP
  25 \fBssh-keyscan\fR uses non-blocking socket I/O to contact as many hosts as
  26 possible in parallel, so it is very efficient. The keys from a domain of 1,000
  27 hosts can be collected in tens of seconds, even when some of those hosts are
  28 down or do not run ssh. For scanning, one does not need login access to the
  29 machines that are being scanned, nor does the scanning process involve any
  30 encryption.
  31 .SS "File Format"
  32 .LP
  33 Input format:
  34 .sp
  35 .in +2
  36 .nf
  37 1.2.3.4,1.2.4.4
  38 \fIname.my.domain,name,n.my.domain,n,\fR1.2.3.4,1.2.4.4
  39 .fi
  40 .in -2
  41 .sp
  42 
  43 .sp
  44 .LP
  45 Output format for \fBrsa1\fR keys:
  46 .sp
  47 .in +2
  48 .nf
  49 \fIhost-or-namelist bits exponent modulus\fR
  50 .fi
  51 .in -2
  52 .sp
  53 
  54 .sp
  55 .LP
  56 Output format for \fBrsa\fR and \fBdsa\fR keys, where \fIkeytype\fR is either
  57 \fBssh-rsa\fR or `\fBssh-dsa\fR:
  58 .sp
  59 .in +2
  60 .nf
  61 \fIhost-or-namelist keytype base64-encoded-key\fR
  62 .fi
  63 .in -2
  64 .sp
  65 
  66 .SH OPTIONS
  67 .LP
  68 The following options are supported:
  69 .sp
  70 .ne 2
  71 .na
  72 \fB\fB-f\fR \fIfilename\fR\fR
  73 .ad
  74 .RS 28n
  75 Read hosts or addrlist namelist pairs from this file, one per line. If you
  76 specity - instead of a filename, \fBssh-keyscan\fR reads hosts or addrlist
  77 namelist pairs from the standard input.
  78 .RE
  79 
  80 .sp
  81 .ne 2
  82 .na
  83 \fB\fB-p\fR \fIport\fR\fR
  84 .ad
  85 .RS 28n
  86 Port to connect to on the remote host.
  87 .RE
  88 
  89 .sp
  90 .ne 2
  91 .na
  92 \fB\fB-T\fR \fItimeout\fR\fR
  93 .ad
  94 .RS 28n
  95 Set the timeout for connection attempts. If \fItimeout\fR seconds have elapsed
  96 since a connection was initiated to a host or since the last time anything was
  97 read from that host, the connection is closed and the host in question is
  98 considered unavailable. The default is for \fItimeout\fR is 5 seconds.
  99 .RE
 100 
 101 .sp
 102 .ne 2
 103 .na
 104 \fB\fB-t\fR \fItype\fR\fR
 105 .ad
 106 .RS 28n
 107 Specify the type of the key to fetch from the scanned hosts. The possible
 108 values for \fItype\fR are \fBrsa1\fR for protocol version 1 and \fBrsa\fR or
 109 \fBdsa\fR for protocol version 2. Specify multiple values by separating them
 110 with commas. The default is \fBrsa1\fR.
 111 .RE
 112 
 113 .sp
 114 .ne 2
 115 .na
 116 \fB\fB-v\fR\fR
 117 .ad
 118 .RS 28n
 119 Specify verbose mode. Print debugging messages about progress.
 120 .RE
 121 
 122 .sp
 123 .ne 2
 124 .na
 125 \fB\fB-4\fR\fR
 126 .ad
 127 .RS 28n
 128 Force to use IPv4 addresses only.
 129 .RE
 130 
 131 .sp
 132 .ne 2
 133 .na
 134 \fB\fB-6\fR\fR
 135 .ad
 136 .RS 28n
 137 Forces to use IPv6 addresses only.
 138 .RE
 139 
 140 .SH SECURITY
 141 .LP
 142 If a \fBssh_known_hosts\fR file is constructed using \fBssh-keyscan\fR without
 143 verifying the keys, users are vulnerable to man-in-the-middle attacks. If the
 144 security model allows such a risk, \fBssh-keyscan\fR can help in the detection
 145 of tampered keyfiles or man-in-the-middle attacks which have begun after the
 146 \fBssh_known_hosts\fR file was created.
 147 .SH EXAMPLES
 148 .LP
 149 \fBExample 1 \fRPrinting the \fBrsa1\fR Host Key
 150 .sp
 151 .LP
 152 The following example prints the \fBrsa1\fR host key for machine
 153 \fBhostname\fR:
 154 
 155 .sp
 156 .in +2
 157 .nf
 158 $ ssh-keyscan hostname
 159 .fi
 160 .in -2
 161 .sp
 162 
 163 .LP
 164 \fBExample 2 \fRFinding All Hosts
 165 .sp
 166 .LP
 167 The following commands finds all hosts from the file \fBssh_hosts\fR which have
 168 new or different keys from those in the sorted file \fBssh_known_hosts\fR:
 169 
 170 .sp
 171 .in +2
 172 .nf
 173 $ ssh-keyscan -t rsa,dsa -f ssh_hosts | \e
 174      sort -u - ssh_known_hosts | diff ssh_known_hosts -
 175 .fi
 176 .in -2
 177 .sp
 178 
 179 .SH FILES
 180 .ne 2
 181 .na
 182 \fB\fB/etc/ssh_known_hosts\fR \fR
 183 .ad
 184 .RS 25n
 185 
 186 .RE
 187 
 188 .SH EXIT STATUS
 189 .LP
 190 The following exit values are returned:
 191 .sp
 192 .ne 2
 193 .na
 194 \fB\fB0\fR \fR
 195 .ad
 196 .RS 6n
 197 No usage errors. \fBssh-keyscan\fR might or might not have succeeded or failed
 198 to scan one, more or all of the given hosts.
 199 .RE
 200 
 201 .sp
 202 .ne 2
 203 .na
 204 \fB\fB1\fR\fR
 205 .ad
 206 .RS 6n
 207 Usage error.
 208 .RE
 209 
 210 .SH ATTRIBUTES
 211 .LP
 212 See \fBattributes\fR(5) for descriptions of the following attributes:
 213 .sp
 214 
 215 .sp
 216 .TS
 217 box;
 218 c | c
 219 l | l .
 220 ATTRIBUTE TYPE  ATTRIBUTE VALUE
 221 _
 222 Interface Stability     Evolving
 223 .TE
 224 
 225 .SH SEE ALSO
 226 .LP
 227 \fBssh\fR(1), \fBsshd\fR(1M), \fBattributes\fR(5)
 228 .SH AUTHORS
 229 .LP
 230 David Mazieres wrote the initial version, and Wayne Davison added suppport for
 231 protocol version 2.
 232 .SH BUGS
 233 .LP
 234 \fBssh\(emkeyscan\fR generates
 235 .sp
 236 .in +2
 237 .nf
 238 Connection closed by remote host
 239 .fi
 240 .in -2
 241 .sp
 242 
 243 .sp
 244 .LP
 245 messages on the consoles of all machines it scans if the server is older than
 246 version 2.9. This is because \fBssh-keyscan\fR opens a connection to the
 247 \fBssh\fR port, reads the public key, and drops the connection as soon as it
 248 gets the key.