contrib/make-ssh-known-hosts.1

   1 .\" -*- nroff -*-
   2 .\" ----------------------------------------------------------------------
   3 .\" make-ssh-known-hosts.1 -- Make ssh-known-hosts file
   4 .\" Copyright (c) 1995 Tero Kivinen
   5 .\" All Rights Reserved.
   6 .\"
   7 .\" Make-ssh-known-hosts is distributed in the hope that it will be
   8 .\" useful, but WITHOUT ANY WARRANTY.  No author or distributor accepts
   9 .\" responsibility to anyone for the consequences of using it or for
  10 .\" whether it serves any particular purpose or works at all, unless he
  11 .\" says so in writing.  Refer to the General Public License for full
  12 .\" details.
  13 .\"
  14 .\" Everyone is granted permission to copy, modify and redistribute
  15 .\" make-ssh-known-hosts, but only under the conditions described in
  16 .\" the General Public License.  A copy of this license is supposed to
  17 .\" have been given to you along with make-ssh-known-hosts so you can
  18 .\" know your rights and responsibilities.  It should be in a file named
  19 .\" COPYING.  Among other things, the copyright notice and this notice
  20 .\" must be preserved on all copies.
  21 .\" ----------------------------------------------------------------------
  22 .\"       Program: make-ssh-known-hosts.1
  23 .\"       $Source$
  24 .\"       Author : $Author$
  25 .\"
  26 .\"       (C) Tero Kivinen 1995 <Tero.Kivinen@hut.fi>
  27 .\"
  28 .\"       Creation          : 03:51 Jun 28 1995 kivinen
  29 .\"       Last Modification : 03:44 Jun 28 1995 kivinen
  30 .\"       Last check in     : $Date$
  31 .\"       Revision number   : $Revision$
  32 .\"       State             : $State$
  33 .\"       Version           : 1.1
  34 .\"
  35 .\"       Description       : Manual page for make-ssh-known-hosts.pl
  36 .\"
  37 .\"       $Log$
  38 .\"       Revision 1.1  2000/03/15 01:13:03  damien
  39 .\"        - Created contrib/ subdirectory. Included helpers from Phil Hands'
  40 .\"          Debian package, README file and chroot patch from Ricardo Cerqueira
  41 .\"          <rmcc@clix.pt>
  42 .\"        - Moved gnome-ssh-askpass.c to contrib directory and reomved config
  43 .\"          option.
  44 .\"        - Slight cleanup to doc files
  45 .\"
  46 .\"       Revision 1.4  1998/07/08 00:40:14  kivinen
  47 .\"             Changed to do similar commercial #ifdef processing than other
  48 .\"             files.
  49 .\"
  50 .\"       Revision 1.3  1998/06/11 00:07:21  kivinen
  51 .\"             Fixed comment characters.
  52 .\"
  53 .\" Revision 1.2  1997/04/27  21:48:28  kivinen
  54 .\"     Added F-SECURE stuff.
  55 .\"
  56 .\"       Revision 1.1.1.1  1996/02/18 21:38:13  ylo
  57 .\"             Imported ssh-1.2.13.
  58 .\"
  59 .\" Revision 1.5  1995/10/02  01:23:23  ylo
  60 .\"     Make substitutions by configure.
  61 .\"
  62 .\" Revision 1.4  1995/08/31  09:21:35  ylo
  63 .\"     Minor cleanup.
  64 .\"
  65 .\" Revision 1.3  1995/08/29  22:37:10  ylo
  66 .\"     Minor cleanup.
  67 .\"
  68 .\" Revision 1.2  1995/07/15  13:26:11  ylo
  69 .\"     Changes from kivinen.
  70 .\"
  71 .\" Revision 1.1.1.1  1995/07/12  22:41:05  ylo
  72 .\" Imported ssh-1.0.0.
  73 .\"
  74 .\"
  75 .\"
  76 .\" If you have any useful modifications or extensions please send them to
  77 .\" Tero.Kivinen@hut.fi
  78 .\"
  79 .\"
  80 .\"
  81 .\"
  82 .\"
  83 .\" #ifndef F_SECURE_COMMERCIAL
  84 .TH MAKE-SSH-KNOWN-HOSTS 1 "November 8, 1995" "SSH TOOLS" "SSH TOOLS"
  85 .\" #endif F_SECURE_COMMERCIAL
  86 .SH NAME
  87 make-ssh-known-hosts \- make ssh_known_hosts file from DNS data
  88 .SH SYNOPSIS
  89 .na
  90 .TP
  91 .B make-ssh-known-hosts
  92 .RB "[\|" "\-\-initialdns "\c
  93 .I initial_dns\c
  94 \|]
  95 .br
  96 .RB "[\|" "\-\-server "\c
  97 .I domain_name_server\c
  98 \|]
  99 .br
 100 .RB "[\|" "\-\-subdomains "\c
 101 .I comma_separated_list_of_subdomains\c
 102 \|]
 103 .br
 104 .RB "[\|" "\-\-debug "\c
 105 .I debug_level\c
 106 \|]
 107 .br
 108 .RB "[\|" "\-\-timeout "\c
 109 .I ssh_exec_timeout\c
 110 \|]
 111 .br
 112 .RB "[\|" "\-\-pingtimeout "\c
 113 .I ping_timeout\c
 114 \|]
 115 .br
 116 .RB "[\|" "\-\-passwordtimeout "\c
 117 .I timeout_when_asking_password\c
 118 \|]
 119 .br
 120 .RB "[\|" "\-\-notrustdaemon" "\|]"
 121 .br
 122 .RB "[\|" "\-\-norecursive" "\|]"
 123 .br
 124 .RB "[\|" "\-\-domainnamesplit" "\|]"
 125 .br
 126 .RB "[\|" "\-\-silent" "\|]"
 127 .br
 128 .RB "[\|" "\-\-keyscan" "\|]"
 129 .br
 130 .RB "[\|" "\-\-nslookup "\c
 131 .I path_to_nslookup_program\c
 132 \|]
 133 .br
 134 .RB "[\|" "\-\-ssh "\c
 135 .I path_to_ssh_program\c
 136 \|]
 137 .br
 138 .IR "domain_name " "[\|" "take_regexp " "[\|" "remove_regexp"\|]\|]"
 139
 140 .SH DESCRIPTION
 141 .LP
 142 .B make-ssh-known-hosts
 143 is a perl5 script that helps create the
 144 .I /etc/ssh_known_hosts
 145 file, which is used by
 146 .B ssh
 147 to contain the host keys of all publicly known hosts.
 148 .B Ssh
 149 does not normally permit login using rhosts or /etc/hosts.equiv
 150 authentication unless the server knows the client's host key.  In
 151 addition, the host keys are used to prevent man-in-the-middle attacks.
 152 .LP
 153 In addition to
 154 .IR /etc/ssh_known_hosts ",
 155 .B ssh
 156 also uses the
 157 .I $HOME/.ssh/known_hosts
 158 file.  This file, however, is intended to contain only those hosts
 159 that the particular user needs but are not in the global file.  It is
 160 intended that the
 161 .I /etc/ssh_known_hosts
 162 file be maintained by the system administration, and periodically
 163 updated to contain the host keys for any new hosts.
 164 .LP
 165 The
 166 .B make-ssh-known-hosts
 167 program finds all the hosts in a domain by making a DNS query to the
 168 master domain name server of the domain. The master domain name server
 169 is located by searching for the SOA record of the domain from the initial
 170 domain name server (which can be specified with the
 171 .B \-\-initialdns
 172 option). The master domain name server can also be given directly with
 173 the
 174 .B \-\-server
 175 option.
 176 .LP
 177 After getting the hostname list
 178 .B make-ssh-known-hosts
 179 tries to get the public key from every host in the domain. It first
 180 tries to connect ssh port to check check if the host is alive, and if
 181 so, it tries to run the command
 182 .B cat /etc/ssh_host_key.pub
 183 on the remote machine using
 184 .BR ssh ".
 185 If the command succeeds, it knows the remote machine has
 186 .B ssh
 187 installed properly, and it then extracts the public key from the
 188 output, and prints the
 189 .B /etc/ssh_known_hosts
 190 entry for it to
 191 .BR STDOUT ". Because
 192 .B make-ssh-known-hosts
 193 is usually run before
 194 remote machines have /etc/ssh_known_hosts file you may have to use
 195 RSA-authentication to allow access to hosts.
 196 .LP
 197 If the command fails for some reason, it checks if the
 198 .B ssh
 199 client still got the public key from the remote host in the initial dialog,
 200 and if so, it will print a proper entry, and if
 201 .B \-\-notrustdaemon
 202 option is given comment it out.
 203 .LP
 204 .I Domain_name
 205 is the domain name for which the file is to be generated. By default
 206 .B make-ssh-known-hosts
 207 extracts also all subdomains of domain. Many sites will want to
 208 include several domains in their
 209 .I /etc/ssh_known_hosts
 210 file.  The entries for each domain should be extracted separately by
 211 running
 212 .B make-ssh-known-hosts
 213 once for each domain.  The results should then be combined to create
 214 the final file.
 215 .LP
 216 .I Take_regexp
 217 is a perl regular expression that matches the hosts to be taken from the
 218 domain. The data matched contains all the DNS records in the form "\|\c
 219 .B fieldname=value\c
 220 \|". The fields are separated with newline, and the perl match is made in
 221 multiline mode and it is case insensetive. The multiline mode means
 222 that you can use a regexp like "\|\c
 223 .B ^wks=.*telnet.*$\c
 224 \|" to match all hosts that have WKS (well known services) field that
 225 contains value "telnet".
 226 .LP
 227 .I Remove_regexp
 228 is similar but those hosts that match the regexp are not added (it can
 229 be used for example to filter out PCs and Macs using the hinfo field: "\|\c
 230 .B ^hinfo=.*(mac|pc)\c
 231 \|").
 232
 233 .SH OPTIONS
 234 .TP
 235 .BI "\-\-initialdns " "initial_dns"\c
 236 .TP
 237 .BI "\-i " "initial_dns"\c
 238 \&Set the initial domain name server used to query the SOA record of the
 239 domain.
 240
 241 .TP
 242 .BI "\-\-server " "domain_name_server"\c
 243 .TP
 244 .BI "\-se " "domain_name_server"\c
 245 \&Set the master domain name server of the domain. This host is used
 246 to query the DNS list of the domain.
 247
 248 .TP
 249 .BI "\-\-subdomains " "subdomainlist"\c
 250 .TP
 251 .BI "\-su " "subdomainlist"\c
 252 \&Comma separated list of subdomains that are added to hostnames. For
 253 example, if subdomainlist is "\|\c
 254 .I ,foo, foo.bar, foo.bar.zappa, foo.bar.zappa.hut.fi\c
 255 \|" then when host foobar is added to
 256 .B /etc/ssh_known_hosts
 257 file it has aliases "\|\c
 258 .I foobar, foobar.foo, foobar.foo.bar, foobar.foo.bar.zappa, foobar.foo.bar.zappa.hut.fi\c
 259 \|". The default action is to take all subparts of the host but the
 260 second last on a host by host basis.  (The last element is usually the
 261 country code, and something like
 262 .I foobar.foo.bar.zappa.hut
 263 would not make sense.)
 264
 265 .TP
 266 .BI "\-\-debug " "debug_level"\c
 267 .TP
 268 .BI "\-de " "debug_level"\c
 269 \&Set the debug level. Default is 5, bigger values give more output.
 270 Using a big value (like 999) will print lots of debugging output.
 271
 272 .TP
 273 .BI "\-\-timeout " "ssh_exec_timeout"\c
 274 .TP
 275 .BI "\-ti " "ssh_exec_timeout"\c
 276 \&Timeout when executing
 277 .B ssh
 278 command.  The default is 60 seconds.
 279
 280 .TP
 281 .BI "\-\-pingtimeout " "ping_timeout"\c
 282 .TP
 283 .BI "\-pi " "ping_timeout"\c
 284 \&Timeout when trying to ping the ssh port.  The default is 3 seconds.
 285
 286 .TP
 287 .BI "\-\-passwordtimeout " "timeout_when_asking_password"\c
 288 .TP
 289 .BI "\-pa " "timeout_when_asking_password"\c
 290 \&Timeout when asking password for ssh command. Default is that no
 291 passwords are queried. Use value 0 to have no timeout for password queries.
 292
 293 .TP
 294 .BI "\-\-notrustdaemon"\c
 295 .TP
 296 .BI "\-notr"\c
 297 \&If the
 298 .B ssh
 299 command fails, use the public key stored in the local known hosts file
 300 and trust it is the correct key for the host. If this option is not
 301 given such entries are commented out in the generated
 302 .B /etc/ssh_known_hosts
 303 file.
 304
 305 .TP
 306 .BI "\-\-norecursive"\c
 307 .TP
 308 .BI "\-nor"\c
 309 \&Tell
 310 .B make-ssh-known-hosts
 311 that it should only extract keys for the given domain, and not to be
 312 recursive.
 313
 314 .TP
 315 .BI "\-\-domainnamesplit"\c
 316 .TP
 317 .BI "\-do"\c
 318 \&Split the domainname to get the list of subdomains. Use this option
 319 if you don't want hostname to splitted to pieces automatically.
 320 Default splitting is done host by host basis. If the domain is
 321 zappa.hut.fi, and the host name is foo.bar then default action adds
 322 entries "\|\c
 323 .I foo, foo.bar, foo.bar.zappa, foo.bar.zappa.hut.fi\c
 324 \|" and this options adds entries "\|\c
 325 .I foo.bar, foo.bar.zappa, foo.bar.zappa.hut.fi\c
 326 \|").
 327
 328 .TP
 329 .BI "\-\-silent"\c
 330 .TP
 331 .BI "\-si"\c
 332 \&Be silent.
 333
 334 .TP
 335 .BI "\-\-keyscan"\c
 336 .TP
 337 .BI "\-k"\c
 338 \&Output list of all hosts in format "ipaddr1,ipaddr2,...ipaddrn
 339 hostname.domain.co,hostname,ipaddr1,ipaddr2,all_other_hostname_entries".
 340 The output of this can be feeded to ssh-keyscan to fetch keys.
 341
 342 .TP
 343 .BI "\-\-nslookup " "path_to_nslookup_program"\c
 344 .TP
 345 .BI "\-n " "path_to_nslookup_program"\c
 346 \&Path to the
 347 .B nslookup
 348 program.
 349
 350 .TP
 351 .BI "\-\-ssh " "path_to_ssh_program"\c
 352 .TP
 353 .BI "\-ss " "path_to_ssh_program"\c
 354 \&Path to the
 355 .B ssh
 356 program, including all options.
 357
 358 .SH EXAMPLES
 359 .LP
 360 The following command:
 361 .IP
 362 .B example# make-ssh-known-hosts cs.hut.fi > \c
 363 .B /etc/ssh_known_hosts
 364 .LP
 365 finds all public keys of the hosts in
 366 .B cs.hut.fi
 367 domain and put them to
 368 .B /etc/ssh_known_hosts
 369 file splitting domain names on a per host basis.
 370 .LP
 371 The command
 372 .IP
 373 .B example% make-ssh-known-hosts hut.fi '^wks=.*ssh' > \c
 374 .B hut-hosts
 375 .LP
 376 finds all hosts in
 377 .B hut.fi
 378 domain, and its subdomains having own name server (cs.hut.fi,
 379 tf.hut.fi, tky.hut.fi) that have ssh service and puts their public key
 380 to hut-hosts file. This would require that the domain name server of
 381 hut.fi would define all hosts running ssh to have entry ssh in their
 382 WKS record. Because nobody yet adds ssh to WKS, it would be better to
 383 use command
 384 .IP
 385 .B example% make-ssh-known-hosts hut.fi '^wks=.*telnet' > \c
 386 .B hut-hosts
 387 .LP
 388 that would take those host having telnet service. This uses default
 389 subdomain list.
 390
 391 .LP
 392 The command:
 393 .IP
 394 .B example% make-ssh-known-hosts hut.fi 'dipoli.hut.fi' '^hinfo=.*(mac|pc)' > \c
 395 .B dipoli-hosts
 396 .LP
 397 finds all hosts in hut.fi domain that are in dipoli.hut.fi subdomain
 398 (note dipoli.hut.fi does not have own name server so its entries are
 399 in hut.fi-server) and that are not Mac or PC.
 400
 401 .SH FILES
 402 .ta 3i
 403 /etc/ssh_known_hosts    Global host public key list
 404
 405 .SH "SEE ALSO"
 406 .BR ssh (1),
 407 .BR sshd (8),
 408 .BR ssh-keygen (1),
 409 .BR ping (8),
 410 .BR nslookup (8),
 411 .BR perl (1),
 412 .BR perlre (1)
 413
 414 .SH AUTHOR
 415 Tero Kivinen <kivinen@hut.fi>
 416
 417 .SH COPYING
 418 .LP
 419 Permission is granted to make and distribute verbatim copies of
 420 this manual provided the copyright notice and this permission notice
 421 are preserved on all copies.
 422 .LP
 423 Permission is granted to copy and distribute modified versions of this
 424 manual under the conditions for verbatim copying, provided that the
 425 entire resulting derived work is distributed under the terms of a
 426 permission notice identical to this one.
 427 .LP
 428 Permission is granted to copy and distribute translations of this
 429 manual into another language, under the above conditions for modified
 430 versions, except that this permission notice may be included in
 431 translations approved by the the author instead of in the original
 432 English.