Annotation of src/usr.bin/ssh/ssh.1, Revision 1.103
1.1 deraadt 1: .\" -*- nroff -*-
2: .\"
3: .\" Author: Tatu Ylonen <ylo@cs.hut.fi>
4: .\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland
5: .\" All rights reserved
6: .\"
1.59 deraadt 7: .\" As far as I am concerned, the code I have written for this software
8: .\" can be used freely for any purpose. Any derived versions of this
9: .\" software must be clearly marked as such, and if the derived work is
10: .\" incompatible with the protocol description in the RFC file, it must be
11: .\" called by a name other than "ssh" or "Secure Shell".
12: .\"
1.93 deraadt 13: .\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved.
14: .\" Copyright (c) 1999 Aaron Campbell. All rights reserved.
15: .\" Copyright (c) 1999 Theo de Raadt. All rights reserved.
1.59 deraadt 16: .\"
17: .\" Redistribution and use in source and binary forms, with or without
18: .\" modification, are permitted provided that the following conditions
19: .\" are met:
20: .\" 1. Redistributions of source code must retain the above copyright
21: .\" notice, this list of conditions and the following disclaimer.
22: .\" 2. Redistributions in binary form must reproduce the above copyright
23: .\" notice, this list of conditions and the following disclaimer in the
24: .\" documentation and/or other materials provided with the distribution.
1.1 deraadt 25: .\"
1.59 deraadt 26: .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR
27: .\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
28: .\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
29: .\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT,
30: .\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
31: .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
32: .\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
33: .\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
34: .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
35: .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
1.1 deraadt 36: .\"
1.103 ! markus 37: .\" $OpenBSD: ssh.1,v 1.102 2001/04/10 09:13:22 itojun Exp $
1.2 deraadt 38: .Dd September 25, 1999
39: .Dt SSH 1
40: .Os
41: .Sh NAME
42: .Nm ssh
1.96 deraadt 43: .Nd OpenSSH SSH client (remote login program)
1.2 deraadt 44: .Sh SYNOPSIS
45: .Nm ssh
46: .Op Fl l Ar login_name
1.5 deraadt 47: .Op Ar hostname | user@hostname
1.2 deraadt 48: .Op Ar command
49: .Pp
50: .Nm ssh
1.86 jakob 51: .Op Fl afgknqstvxACNPTX1246
1.51 markus 52: .Op Fl c Ar cipher_spec
1.2 deraadt 53: .Op Fl e Ar escape_char
54: .Op Fl i Ar identity_file
55: .Op Fl l Ar login_name
1.91 markus 56: .Op Fl m Ar mac_spec
1.2 deraadt 57: .Op Fl o Ar option
58: .Op Fl p Ar port
1.12 aaron 59: .Oo Fl L Xo
60: .Sm off
1.33 markus 61: .Ar port :
1.12 aaron 62: .Ar host :
63: .Ar hostport
64: .Sm on
65: .Xc
66: .Oc
67: .Oo Fl R Xo
68: .Sm off
1.33 markus 69: .Ar port :
1.12 aaron 70: .Ar host :
71: .Ar hostport
72: .Sm on
73: .Xc
74: .Oc
1.5 deraadt 75: .Op Ar hostname | user@hostname
1.2 deraadt 76: .Op Ar command
1.44 aaron 77: .Sh DESCRIPTION
1.2 deraadt 78: .Nm
1.96 deraadt 79: (SSH client) is a program for logging into a remote machine and for
1.40 aaron 80: executing commands on a remote machine.
81: It is intended to replace
1.1 deraadt 82: rlogin and rsh, and provide secure encrypted communications between
1.40 aaron 83: two untrusted hosts over an insecure network.
84: X11 connections and
1.1 deraadt 85: arbitrary TCP/IP ports can also be forwarded over the secure channel.
1.2 deraadt 86: .Pp
87: .Nm
1.44 aaron 88: connects and logs into the specified
1.2 deraadt 89: .Ar hostname .
1.1 deraadt 90: The user must prove
1.49 markus 91: his/her identity to the remote machine using one of several methods
92: depending on the protocol version used:
93: .Pp
94: .Ss SSH protocol version 1
1.2 deraadt 95: .Pp
1.1 deraadt 96: First, if the machine the user logs in from is listed in
1.2 deraadt 97: .Pa /etc/hosts.equiv
1.1 deraadt 98: or
1.2 deraadt 99: .Pa /etc/shosts.equiv
1.1 deraadt 100: on the remote machine, and the user names are
101: the same on both sides, the user is immediately permitted to log in.
1.44 aaron 102: Second, if
1.2 deraadt 103: .Pa \&.rhosts
1.1 deraadt 104: or
1.2 deraadt 105: .Pa \&.shosts
1.1 deraadt 106: exists in the user's home directory on the
107: remote machine and contains a line containing the name of the client
108: machine and the name of the user on that machine, the user is
1.40 aaron 109: permitted to log in.
110: This form of authentication alone is normally not
1.1 deraadt 111: allowed by the server because it is not secure.
1.2 deraadt 112: .Pp
1.1 deraadt 113: The second (and primary) authentication method is the
1.2 deraadt 114: .Pa rhosts
1.1 deraadt 115: or
1.2 deraadt 116: .Pa hosts.equiv
1.40 aaron 117: method combined with RSA-based host authentication.
118: It means that if the login would be permitted by
1.49 markus 119: .Pa $HOME/.rhosts ,
120: .Pa $HOME/.shosts ,
1.2 deraadt 121: .Pa /etc/hosts.equiv ,
1.1 deraadt 122: or
1.2 deraadt 123: .Pa /etc/shosts.equiv ,
1.11 deraadt 124: and if additionally the server can verify the client's
1.44 aaron 125: host key (see
1.2 deraadt 126: .Pa /etc/ssh_known_hosts
1.23 markus 127: and
128: .Pa $HOME/.ssh/known_hosts
1.1 deraadt 129: in the
1.2 deraadt 130: .Sx FILES
1.40 aaron 131: section), only then login is permitted.
132: This authentication method closes security holes due to IP
133: spoofing, DNS spoofing and routing spoofing.
134: [Note to the administrator:
1.2 deraadt 135: .Pa /etc/hosts.equiv ,
1.49 markus 136: .Pa $HOME/.rhosts ,
1.1 deraadt 137: and the rlogin/rsh protocol in general, are inherently insecure and should be
138: disabled if security is desired.]
1.2 deraadt 139: .Pp
1.44 aaron 140: As a third authentication method,
1.2 deraadt 141: .Nm
1.1 deraadt 142: supports RSA based authentication.
143: The scheme is based on public-key cryptography: there are cryptosystems
144: where encryption and decryption are done using separate keys, and it
145: is not possible to derive the decryption key from the encryption key.
1.40 aaron 146: RSA is one such system.
1.44 aaron 147: The idea is that each user creates a public/private
1.40 aaron 148: key pair for authentication purposes.
149: The server knows the public key, and only the user knows the private key.
1.44 aaron 150: The file
1.2 deraadt 151: .Pa $HOME/.ssh/authorized_keys
1.1 deraadt 152: lists the public keys that are permitted for logging
1.40 aaron 153: in.
154: When the user logs in, the
1.2 deraadt 155: .Nm
1.1 deraadt 156: program tells the server which key pair it would like to use for
1.40 aaron 157: authentication.
158: The server checks if this key is permitted, and if
1.1 deraadt 159: so, sends the user (actually the
1.2 deraadt 160: .Nm
1.1 deraadt 161: program running on behalf of the user) a challenge, a random number,
1.40 aaron 162: encrypted by the user's public key.
163: The challenge can only be
164: decrypted using the proper private key.
165: The user's client then decrypts the
1.1 deraadt 166: challenge using the private key, proving that he/she knows the private
167: key but without disclosing it to the server.
1.2 deraadt 168: .Pp
169: .Nm
1.40 aaron 170: implements the RSA authentication protocol automatically.
171: The user creates his/her RSA key pair by running
1.2 deraadt 172: .Xr ssh-keygen 1 .
1.44 aaron 173: This stores the private key in
1.49 markus 174: .Pa $HOME/.ssh/identity
1.1 deraadt 175: and the public key in
1.49 markus 176: .Pa $HOME/.ssh/identity.pub
1.40 aaron 177: in the user's home directory.
178: The user should then copy the
1.2 deraadt 179: .Pa identity.pub
1.44 aaron 180: to
1.49 markus 181: .Pa $HOME/.ssh/authorized_keys
1.44 aaron 182: in his/her home directory on the remote machine (the
1.2 deraadt 183: .Pa authorized_keys
1.44 aaron 184: file corresponds to the conventional
1.49 markus 185: .Pa $HOME/.rhosts
1.1 deraadt 186: file, and has one key
1.40 aaron 187: per line, though the lines can be very long).
188: After this, the user can log in without giving the password.
189: RSA authentication is much
1.1 deraadt 190: more secure than rhosts authentication.
1.2 deraadt 191: .Pp
1.1 deraadt 192: The most convenient way to use RSA authentication may be with an
1.40 aaron 193: authentication agent.
194: See
1.2 deraadt 195: .Xr ssh-agent 1
1.1 deraadt 196: for more information.
1.2 deraadt 197: .Pp
1.44 aaron 198: If other authentication methods fail,
1.2 deraadt 199: .Nm
1.40 aaron 200: prompts the user for a password.
201: The password is sent to the remote
1.1 deraadt 202: host for checking; however, since all communications are encrypted,
203: the password cannot be seen by someone listening on the network.
1.2 deraadt 204: .Pp
1.49 markus 205: .Ss SSH protocol version 2
206: .Pp
207: When a user connects using the protocol version 2
208: different authentication methods are available:
209: At first, the client attempts to authenticate using the public key method.
210: If this method fails password authentication is tried.
211: .Pp
212: The public key method is similar to RSA authentication described
1.68 markus 213: in the previous section except that the DSA or RSA algorithm is used
214: instead.
1.102 itojun 215: The client uses his private key,
1.49 markus 216: .Pa $HOME/.ssh/id_dsa
1.102 itojun 217: or
218: .Pa $HOME/.ssh/id_rsa ,
1.49 markus 219: to sign the session identifier and sends the result to the server.
220: The server checks whether the matching public key is listed in
221: .Pa $HOME/.ssh/authorized_keys2
222: and grants access if both the key is found and the signature is correct.
223: The session identifier is derived from a shared Diffie-Hellman value
224: and is only known to the client and the server.
225: .Pp
226: If public key authentication fails or is not available a password
227: can be sent encrypted to the remote host for proving the user's identity.
228: This protocol 2 implementation does not yet support Kerberos or
229: S/Key authentication.
230: .Pp
231: Protocol 2 provides additional mechanisms for confidentiality
1.51 markus 232: (the traffic is encrypted using 3DES, Blowfish, CAST128 or Arcfour)
1.94 deraadt 233: and integrity (hmac-md5, hmac-sha1).
1.49 markus 234: Note that protocol 1 lacks a strong mechanism for ensuring the
235: integrity of the connection.
236: .Pp
237: .Ss Login session and remote execution
238: .Pp
1.1 deraadt 239: When the user's identity has been accepted by the server, the server
240: either executes the given command, or logs into the machine and gives
1.40 aaron 241: the user a normal shell on the remote machine.
242: All communication with
1.1 deraadt 243: the remote command or shell will be automatically encrypted.
1.2 deraadt 244: .Pp
1.1 deraadt 245: If a pseudo-terminal has been allocated (normal login session), the
1.2 deraadt 246: user can disconnect with
247: .Ic ~. ,
248: and suspend
249: .Nm
250: with
251: .Ic ~^Z .
252: All forwarded connections can be listed with
1.44 aaron 253: .Ic ~#
1.2 deraadt 254: and if
1.1 deraadt 255: the session blocks waiting for forwarded X11 or TCP/IP
1.2 deraadt 256: connections to terminate, it can be backgrounded with
257: .Ic ~&
258: (this should not be used while the user shell is active, as it can cause the
1.40 aaron 259: shell to hang).
260: All available escapes can be listed with
1.2 deraadt 261: .Ic ~? .
262: .Pp
263: A single tilde character can be sent as
264: .Ic ~~
265: (or by following the tilde by a character other than those described above).
1.1 deraadt 266: The escape character must always follow a newline to be interpreted as
1.40 aaron 267: special.
268: The escape character can be changed in configuration files
269: or on the command line.
1.2 deraadt 270: .Pp
1.1 deraadt 271: If no pseudo tty has been allocated, the
272: session is transparent and can be used to reliably transfer binary
1.40 aaron 273: data.
274: On most systems, setting the escape character to
1.2 deraadt 275: .Dq none
276: will also make the session transparent even if a tty is used.
277: .Pp
1.71 djm 278: The session terminates when the command or shell on the remote
1.92 markus 279: machine exits and all X11 and TCP/IP connections have been closed.
1.1 deraadt 280: The exit status of the remote program is returned as the exit status
281: of
1.2 deraadt 282: .Nm ssh .
283: .Pp
1.49 markus 284: .Ss X11 and TCP forwarding
285: .Pp
1.1 deraadt 286: If the user is using X11 (the
1.2 deraadt 287: .Ev DISPLAY
1.1 deraadt 288: environment variable is set), the connection to the X11 display is
289: automatically forwarded to the remote side in such a way that any X11
290: programs started from the shell (or command) will go through the
291: encrypted channel, and the connection to the real X server will be made
1.40 aaron 292: from the local machine.
293: The user should not manually set
1.2 deraadt 294: .Ev DISPLAY .
1.1 deraadt 295: Forwarding of X11 connections can be
296: configured on the command line or in configuration files.
1.2 deraadt 297: .Pp
298: The
1.44 aaron 299: .Ev DISPLAY
1.2 deraadt 300: value set by
301: .Nm
1.1 deraadt 302: will point to the server machine, but with a display number greater
1.40 aaron 303: than zero.
304: This is normal, and happens because
1.2 deraadt 305: .Nm
306: creates a
307: .Dq proxy
308: X server on the server machine for forwarding the
1.1 deraadt 309: connections over the encrypted channel.
1.2 deraadt 310: .Pp
311: .Nm
1.1 deraadt 312: will also automatically set up Xauthority data on the server machine.
313: For this purpose, it will generate a random authorization cookie,
314: store it in Xauthority on the server, and verify that any forwarded
315: connections carry this cookie and replace it by the real cookie when
1.40 aaron 316: the connection is opened.
317: The real authentication cookie is never
1.1 deraadt 318: sent to the server machine (and no cookies are sent in the plain).
1.2 deraadt 319: .Pp
1.1 deraadt 320: If the user is using an authentication agent, the connection to the agent
321: is automatically forwarded to the remote side unless disabled on
322: command line or in a configuration file.
1.2 deraadt 323: .Pp
1.1 deraadt 324: Forwarding of arbitrary TCP/IP connections over the secure channel can
1.40 aaron 325: be specified either on command line or in a configuration file.
326: One possible application of TCP/IP forwarding is a secure connection to an
1.92 markus 327: electronic purse; another is going through firewalls.
1.2 deraadt 328: .Pp
1.49 markus 329: .Ss Server authentication
330: .Pp
1.2 deraadt 331: .Nm
1.49 markus 332: automatically maintains and checks a database containing
1.40 aaron 333: identifications for all hosts it has ever been used with.
1.49 markus 334: RSA host keys are stored in
335: .Pa $HOME/.ssh/known_hosts
336: and
1.68 markus 337: host keys used in the protocol version 2 are stored in
1.49 markus 338: .Pa $HOME/.ssh/known_hosts2
1.40 aaron 339: in the user's home directory.
1.49 markus 340: Additionally, the files
1.2 deraadt 341: .Pa /etc/ssh_known_hosts
1.49 markus 342: and
343: .Pa /etc/ssh_known_hosts2
344: are automatically checked for known hosts.
1.40 aaron 345: Any new hosts are automatically added to the user's file.
346: If a host's identification
1.1 deraadt 347: ever changes,
1.2 deraadt 348: .Nm
1.1 deraadt 349: warns about this and disables password authentication to prevent a
1.40 aaron 350: trojan horse from getting the user's password.
351: Another purpose of
1.1 deraadt 352: this mechanism is to prevent man-in-the-middle attacks which could
1.40 aaron 353: otherwise be used to circumvent the encryption.
354: The
1.2 deraadt 355: .Cm StrictHostKeyChecking
1.1 deraadt 356: option (see below) can be used to prevent logins to machines whose
357: host key is not known or has changed.
1.65 aaron 358: .Pp
359: The options are as follows:
1.2 deraadt 360: .Bl -tag -width Ds
1.4 dugsong 361: .It Fl a
1.42 aaron 362: Disables forwarding of the authentication agent connection.
1.54 markus 363: .It Fl A
364: Enables forwarding of the authentication agent connection.
365: This can also be specified on a per-host basis in a configuration file.
1.6 deraadt 366: .It Fl c Ar blowfish|3des
1.44 aaron 367: Selects the cipher to use for encrypting the session.
1.2 deraadt 368: .Ar 3des
1.40 aaron 369: is used by default.
1.44 aaron 370: It is believed to be secure.
1.5 deraadt 371: .Ar 3des
372: (triple-des) is an encrypt-decrypt-encrypt triple with three different keys.
373: It is presumably more secure than the
1.2 deraadt 374: .Ar des
1.64 markus 375: cipher which is no longer fully supported in
1.51 markus 376: .Nm ssh .
1.5 deraadt 377: .Ar blowfish
378: is a fast block cipher, it appears very secure and is much faster than
1.40 aaron 379: .Ar 3des .
1.90 markus 380: .It Fl c Ar cipher_spec
1.51 markus 381: Additionally, for protocol version 2 a comma-separated list of ciphers can
1.61 aaron 382: be specified in order of preference.
1.90 markus 383: See
384: .Cm Ciphers
385: for more information.
1.2 deraadt 386: .It Fl e Ar ch|^ch|none
387: Sets the escape character for sessions with a pty (default:
388: .Ql ~ ) .
1.40 aaron 389: The escape character is only recognized at the beginning of a line.
390: The escape character followed by a dot
1.2 deraadt 391: .Pq Ql \&.
392: closes the connection, followed
1.1 deraadt 393: by control-Z suspends the connection, and followed by itself sends the
1.40 aaron 394: escape character once.
395: Setting the character to
1.2 deraadt 396: .Dq none
397: disables any escapes and makes the session fully transparent.
398: .It Fl f
399: Requests
400: .Nm
1.40 aaron 401: to go to background just before command execution.
402: This is useful if
1.2 deraadt 403: .Nm
404: is going to ask for passwords or passphrases, but the user
1.40 aaron 405: wants it in the background.
1.44 aaron 406: This implies
1.2 deraadt 407: .Fl n .
1.1 deraadt 408: The recommended way to start X11 programs at a remote site is with
1.2 deraadt 409: something like
410: .Ic ssh -f host xterm .
1.34 markus 411: .It Fl g
412: Allows remote hosts to connect to local forwarded ports.
1.2 deraadt 413: .It Fl i Ar identity_file
1.44 aaron 414: Selects the file from which the identity (private key) for
1.68 markus 415: RSA or DSA authentication is read.
1.44 aaron 416: Default is
1.49 markus 417: .Pa $HOME/.ssh/identity
1.40 aaron 418: in the user's home directory.
419: Identity files may also be specified on
420: a per-host basis in the configuration file.
421: It is possible to have multiple
1.2 deraadt 422: .Fl i
423: options (and multiple identities specified in
1.1 deraadt 424: configuration files).
1.2 deraadt 425: .It Fl k
1.42 aaron 426: Disables forwarding of Kerberos tickets and AFS tokens.
427: This may also be specified on a per-host basis in the configuration file.
1.2 deraadt 428: .It Fl l Ar login_name
1.40 aaron 429: Specifies the user to log in as on the remote machine.
430: This also may be specified on a per-host basis in the configuration file.
1.91 markus 431: .It Fl m Ar mac_spec
432: Additionally, for protocol version 2 a comma-separated list of MAC
433: (message authentication code) algorithms can
434: be specified in order of preference.
435: See the
436: .Cm MACs
437: keyword for more information.
1.2 deraadt 438: .It Fl n
439: Redirects stdin from
440: .Pa /dev/null
441: (actually, prevents reading from stdin).
1.1 deraadt 442: This must be used when
1.2 deraadt 443: .Nm
1.40 aaron 444: is run in the background.
445: A common trick is to use this to run X11 programs on a remote machine.
446: For example,
1.2 deraadt 447: .Ic ssh -n shadows.cs.hut.fi emacs &
448: will start an emacs on shadows.cs.hut.fi, and the X11
1.1 deraadt 449: connection will be automatically forwarded over an encrypted channel.
450: The
1.2 deraadt 451: .Nm
1.1 deraadt 452: program will be put in the background.
453: (This does not work if
1.2 deraadt 454: .Nm
455: needs to ask for a password or passphrase; see also the
456: .Fl f
457: option.)
1.53 markus 458: .It Fl N
459: Do not execute a remote command.
1.70 markus 460: This is useful if you just want to forward ports
1.53 markus 461: (protocol version 2 only).
1.2 deraadt 462: .It Fl o Ar option
1.1 deraadt 463: Can be used to give options in the format used in the config file.
464: This is useful for specifying options for which there is no separate
1.40 aaron 465: command-line flag.
466: The option has the same format as a line in the configuration file.
1.2 deraadt 467: .It Fl p Ar port
1.40 aaron 468: Port to connect to on the remote host.
469: This can be specified on a
1.1 deraadt 470: per-host basis in the configuration file.
1.16 markus 471: .It Fl P
472: Use a non-privileged port for outgoing connections.
473: This can be used if your firewall does
474: not permit connections from privileged ports.
1.30 provos 475: Note that this option turns off
1.16 markus 476: .Cm RhostsAuthentication
477: and
1.72 markus 478: .Cm RhostsRSAAuthentication
479: for older servers.
1.2 deraadt 480: .It Fl q
1.40 aaron 481: Quiet mode.
482: Causes all warning and diagnostic messages to be suppressed.
483: Only fatal errors are displayed.
1.80 djm 484: .It Fl s
485: May be used to request invocation of a subsystem on the remote system. Subsystems are a feature of the SSH2 protocol which facilitate the use
486: of SSH as a secure transport for other application (eg. sftp). The
487: subsystem is specified as the remote command.
1.2 deraadt 488: .It Fl t
1.40 aaron 489: Force pseudo-tty allocation.
1.43 brad 490: This can be used to execute arbitrary
1.40 aaron 491: screen-based programs on a remote machine, which can be very useful,
492: e.g., when implementing menu services.
1.73 markus 493: Multiple
494: .Fl t
495: options force tty allocation, even if
496: .Nm
497: has no local tty.
1.53 markus 498: .It Fl T
1.69 markus 499: Disable pseudo-tty allocation.
1.2 deraadt 500: .It Fl v
1.40 aaron 501: Verbose mode.
502: Causes
1.2 deraadt 503: .Nm
1.40 aaron 504: to print debugging messages about its progress.
505: This is helpful in
1.1 deraadt 506: debugging connection, authentication, and configuration problems.
1.73 markus 507: Multiple
508: .Fl v
509: options increases the verbosity.
1.61 aaron 510: Maximum is 3.
1.2 deraadt 511: .It Fl x
1.40 aaron 512: Disables X11 forwarding.
1.2 deraadt 513: .It Fl X
1.1 deraadt 514: Enables X11 forwarding.
1.54 markus 515: This can also be specified on a per-host basis in a configuration file.
1.2 deraadt 516: .It Fl C
1.1 deraadt 517: Requests compression of all data (including stdin, stdout, stderr, and
1.40 aaron 518: data for forwarded X11 and TCP/IP connections).
519: The compression algorithm is the same used by
1.34 markus 520: .Xr gzip 1 ,
521: and the
1.2 deraadt 522: .Dq level
523: can be controlled by the
524: .Cm CompressionLevel
1.40 aaron 525: option (see below).
526: Compression is desirable on modem lines and other
1.1 deraadt 527: slow connections, but will only slow down things on fast networks.
528: The default value can be set on a host-by-host basis in the
529: configuration files; see the
1.2 deraadt 530: .Cm Compress
1.1 deraadt 531: option below.
1.2 deraadt 532: .It Fl L Ar port:host:hostport
1.1 deraadt 533: Specifies that the given port on the local (client) host is to be
1.40 aaron 534: forwarded to the given host and port on the remote side.
535: This works by allocating a socket to listen to
1.2 deraadt 536: .Ar port
1.1 deraadt 537: on the local side, and whenever a connection is made to this port, the
538: connection is forwarded over the secure channel, and a connection is
539: made to
1.32 markus 540: .Ar host
541: port
542: .Ar hostport
1.40 aaron 543: from the remote machine.
544: Port forwardings can also be specified in the configuration file.
545: Only root can forward privileged ports.
1.32 markus 546: IPv6 addresses can be specified with an alternative syntax:
547: .Ar port/host/hostport
1.2 deraadt 548: .It Fl R Ar port:host:hostport
1.1 deraadt 549: Specifies that the given port on the remote (server) host is to be
1.40 aaron 550: forwarded to the given host and port on the local side.
551: This works by allocating a socket to listen to
1.2 deraadt 552: .Ar port
1.1 deraadt 553: on the remote side, and whenever a connection is made to this port, the
554: connection is forwarded over the secure channel, and a connection is
555: made to
1.32 markus 556: .Ar host
557: port
558: .Ar hostport
1.40 aaron 559: from the local machine.
560: Port forwardings can also be specified in the configuration file.
561: Privileged ports can be forwarded only when
1.1 deraadt 562: logging in as root on the remote machine.
1.85 jakob 563: .It Fl 1
564: Forces
565: .Nm
566: to try protocol version 1 only.
1.46 markus 567: .It Fl 2
568: Forces
569: .Nm
1.50 markus 570: to try protocol version 2 only.
1.32 markus 571: .It Fl 4
572: Forces
573: .Nm
574: to use IPv4 addresses only.
575: .It Fl 6
576: Forces
577: .Nm
578: to use IPv6 addresses only.
1.2 deraadt 579: .El
580: .Sh CONFIGURATION FILES
581: .Nm
1.1 deraadt 582: obtains configuration data from the following sources (in this order):
583: command line options, user's configuration file
1.2 deraadt 584: .Pq Pa $HOME/.ssh/config ,
585: and system-wide configuration file
586: .Pq Pa /etc/ssh_config .
587: For each parameter, the first obtained value
1.40 aaron 588: will be used.
589: The configuration files contain sections bracketed by
590: .Dq Host
591: specifications, and that section is only applied for hosts that
592: match one of the patterns given in the specification.
593: The matched host name is the one given on the command line.
1.2 deraadt 594: .Pp
1.1 deraadt 595: Since the first obtained value for each parameter is used, more
596: host-specific declarations should be given near the beginning of the
597: file, and general defaults at the end.
1.2 deraadt 598: .Pp
1.1 deraadt 599: The configuration file has the following format:
1.2 deraadt 600: .Pp
601: Empty lines and lines starting with
602: .Ql #
603: are comments.
604: .Pp
605: Otherwise a line is of the format
606: .Dq keyword arguments .
607: The possible
1.1 deraadt 608: keywords and their meanings are as follows (note that the
609: configuration files are case-sensitive):
1.2 deraadt 610: .Bl -tag -width Ds
611: .It Cm Host
1.1 deraadt 612: Restricts the following declarations (up to the next
1.2 deraadt 613: .Cm Host
1.1 deraadt 614: keyword) to be only for those hosts that match one of the patterns
1.2 deraadt 615: given after the keyword.
616: .Ql \&*
617: and
618: .Ql ?
619: can be used as wildcards in the
1.40 aaron 620: patterns.
621: A single
1.2 deraadt 622: .Ql \&*
623: as a pattern can be used to provide global
1.40 aaron 624: defaults for all hosts.
625: The host is the
1.2 deraadt 626: .Ar hostname
1.1 deraadt 627: argument given on the command line (i.e., the name is not converted to
628: a canonicalized host name before matching).
1.2 deraadt 629: .It Cm AFSTokenPassing
1.42 aaron 630: Specifies whether to pass AFS tokens to remote host.
631: The argument to this keyword must be
1.2 deraadt 632: .Dq yes
633: or
634: .Dq no .
635: .It Cm BatchMode
636: If set to
637: .Dq yes ,
1.40 aaron 638: passphrase/password querying will be disabled.
639: This option is useful in scripts and other batch jobs where you have no
640: user to supply the password.
641: The argument must be
1.2 deraadt 642: .Dq yes
643: or
644: .Dq no .
1.100 stevesk 645: The default is
646: .Dq no .
1.34 markus 647: .It Cm CheckHostIP
648: If this flag is set to
649: .Dq yes ,
1.100 stevesk 650: ssh will additionally check the host IP address in the
1.34 markus 651: .Pa known_hosts
1.42 aaron 652: file.
653: This allows ssh to detect if a host key changed due to DNS spoofing.
1.34 markus 654: If the option is set to
655: .Dq no ,
656: the check will not be executed.
1.100 stevesk 657: The default is
658: .Dq yes .
1.2 deraadt 659: .It Cm Cipher
1.62 markus 660: Specifies the cipher to use for encrypting the session
1.64 markus 661: in protocol version 1.
1.40 aaron 662: Currently,
1.64 markus 663: .Dq blowfish
1.1 deraadt 664: and
1.10 provos 665: .Dq 3des
1.40 aaron 666: are supported.
667: The default is
1.2 deraadt 668: .Dq 3des .
1.45 markus 669: .It Cm Ciphers
670: Specifies the ciphers allowed for protocol version 2
671: in order of preference.
672: Multiple ciphers must be comma-separated.
673: The default is
1.88 provos 674: .Pp
675: .Bd -literal
1.94 deraadt 676: ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour,
1.88 provos 677: aes192-cbc,aes256-cbc,rijndael128-cbc,rijndael192-cbc,
678: rijndael256-cbc,rijndael-cbc@lysator.liu.se''
679: .Ed
1.2 deraadt 680: .It Cm Compression
1.40 aaron 681: Specifies whether to use compression.
682: The argument must be
1.2 deraadt 683: .Dq yes
684: or
685: .Dq no .
1.100 stevesk 686: The default is
687: .Dq no .
1.2 deraadt 688: .It Cm CompressionLevel
1.100 stevesk 689: Specifies the compression level to use if compression is enabled.
1.40 aaron 690: The argument must be an integer from 1 (fast) to 9 (slow, best).
691: The default level is 6, which is good for most applications.
692: The meaning of the values is the same as in
1.34 markus 693: .Xr gzip 1 .
1.2 deraadt 694: .It Cm ConnectionAttempts
1.1 deraadt 695: Specifies the number of tries (one per second) to make before falling
1.40 aaron 696: back to rsh or exiting.
697: The argument must be an integer.
698: This may be useful in scripts if the connection sometimes fails.
1.100 stevesk 699: The default is 4.
1.68 markus 700: .It Cm PubkeyAuthentication
701: Specifies whether to try public key authentication.
1.50 markus 702: The argument to this keyword must be
703: .Dq yes
704: or
705: .Dq no .
1.100 stevesk 706: The default is
707: .Dq yes .
1.50 markus 708: Note that this option applies to protocol version 2 only.
1.2 deraadt 709: .It Cm EscapeChar
710: Sets the escape character (default:
711: .Ql ~ ) .
712: The escape character can also
1.40 aaron 713: be set on the command line.
714: The argument should be a single character,
1.2 deraadt 715: .Ql ^
716: followed by a letter, or
717: .Dq none
718: to disable the escape
1.1 deraadt 719: character entirely (making the connection transparent for binary
720: data).
1.44 aaron 721: .It Cm FallBackToRsh
1.1 deraadt 722: Specifies that if connecting via
1.2 deraadt 723: .Nm
1.1 deraadt 724: fails due to a connection refused error (there is no
1.2 deraadt 725: .Xr sshd 8
1.44 aaron 726: listening on the remote host),
1.2 deraadt 727: .Xr rsh 1
1.1 deraadt 728: should automatically be used instead (after a suitable warning about
1.40 aaron 729: the session being unencrypted).
730: The argument must be
1.2 deraadt 731: .Dq yes
732: or
733: .Dq no .
1.100 stevesk 734: The default is
735: .Dq no .
1.2 deraadt 736: .It Cm ForwardAgent
1.1 deraadt 737: Specifies whether the connection to the authentication agent (if any)
1.40 aaron 738: will be forwarded to the remote machine.
739: The argument must be
1.2 deraadt 740: .Dq yes
741: or
1.54 markus 742: .Dq no .
743: The default is
1.2 deraadt 744: .Dq no .
745: .It Cm ForwardX11
1.1 deraadt 746: Specifies whether X11 connections will be automatically redirected
1.44 aaron 747: over the secure channel and
1.2 deraadt 748: .Ev DISPLAY
1.40 aaron 749: set.
1.44 aaron 750: The argument must be
1.2 deraadt 751: .Dq yes
752: or
1.38 markus 753: .Dq no .
754: The default is
1.3 deraadt 755: .Dq no .
756: .It Cm GatewayPorts
757: Specifies whether remote hosts are allowed to connect to local
758: forwarded ports.
759: The argument must be
760: .Dq yes
761: or
762: .Dq no .
763: The default is
1.2 deraadt 764: .Dq no .
765: .It Cm GlobalKnownHostsFile
1.95 stevesk 766: Specifies a file to use for the protocol version 1 global
767: host key database instead of
1.2 deraadt 768: .Pa /etc/ssh_known_hosts .
1.95 stevesk 769: .It Cm GlobalKnownHostsFile2
770: Specifies a file to use for the protocol version 2 global
771: host key database instead of
772: .Pa /etc/ssh_known_hosts2 .
1.74 markus 773: .It Cm HostKeyAlias
774: Specifies an alias that should be used instead of the
775: real host name when looking up or saving the host key
1.82 stevesk 776: in the known_hosts files.
777: This option is useful for tunneling ssh connections
1.74 markus 778: or if you have multiple servers running on a single host.
1.103 ! markus 779: .It Cm HostKeyAlgorithms
! 780: Specfies the protocol version 2 host key algorithms
! 781: that the client wants to use in order of preference.
! 782: The default for this option is:
! 783: .Dq ssh-rsa,ssh-dss
1.2 deraadt 784: .It Cm HostName
1.40 aaron 785: Specifies the real host name to log into.
786: This can be used to specify nicknames or abbreviations for hosts.
787: Default is the name given on the command line.
788: Numeric IP addresses are also permitted (both on the command line and in
1.2 deraadt 789: .Cm HostName
1.1 deraadt 790: specifications).
1.2 deraadt 791: .It Cm IdentityFile
1.1 deraadt 792: Specifies the file from which the user's RSA authentication identity
1.2 deraadt 793: is read (default
1.49 markus 794: .Pa $HOME/.ssh/identity
1.2 deraadt 795: in the user's home directory).
1.1 deraadt 796: Additionally, any identities represented by the authentication agent
1.40 aaron 797: will be used for authentication.
798: The file name may use the tilde
799: syntax to refer to a user's home directory.
800: It is possible to have
1.1 deraadt 801: multiple identity files specified in configuration files; all these
802: identities will be tried in sequence.
1.2 deraadt 803: .It Cm KeepAlive
1.1 deraadt 804: Specifies whether the system should send keepalive messages to the
1.40 aaron 805: other side.
806: If they are sent, death of the connection or crash of one
807: of the machines will be properly noticed.
808: However, this means that
1.1 deraadt 809: connections will die if the route is down temporarily, and some people
1.41 aaron 810: find it annoying.
1.2 deraadt 811: .Pp
812: The default is
813: .Dq yes
814: (to send keepalives), and the client will notice
1.40 aaron 815: if the network goes down or the remote host dies.
816: This is important in scripts, and many users want it too.
1.2 deraadt 817: .Pp
818: To disable keepalives, the value should be set to
819: .Dq no
820: in both the server and the client configuration files.
821: .It Cm KerberosAuthentication
1.42 aaron 822: Specifies whether Kerberos authentication will be used.
823: The argument to this keyword must be
1.4 dugsong 824: .Dq yes
825: or
826: .Dq no .
1.2 deraadt 827: .It Cm KerberosTgtPassing
1.42 aaron 828: Specifies whether a Kerberos TGT will be forwarded to the server.
829: This will only work if the Kerberos server is actually an AFS kaserver.
830: The argument to this keyword must be
1.4 dugsong 831: .Dq yes
832: or
833: .Dq no .
1.2 deraadt 834: .It Cm LocalForward
1.1 deraadt 835: Specifies that a TCP/IP port on the local machine be forwarded over
1.40 aaron 836: the secure channel to given host:port from the remote machine.
837: The first argument must be a port number, and the second must be
838: host:port.
839: Multiple forwardings may be specified, and additional
840: forwardings can be given on the command line.
841: Only the superuser can forward privileged ports.
1.24 markus 842: .It Cm LogLevel
843: Gives the verbosity level that is used when logging messages from
844: .Nm ssh .
845: The possible values are:
1.77 markus 846: QUIET, FATAL, ERROR, INFO, VERBOSE and DEBUG.
847: The default is INFO.
1.91 markus 848: .It Cm MACs
849: Specifies the MAC (message authentication code) algorithms
850: in order of preference.
851: The MAC algorithm is used in protocol version 2
852: for data integrity protection.
853: Multiple algorithms must be comma-separated.
854: The default is
855: .Pp
856: .Bd -literal
1.94 deraadt 857: ``hmac-md5,hmac-sha1,hmac-ripemd160,hmac-ripemd160@openssh.com,
1.91 markus 858: hmac-sha1-96,hmac-md5-96''
859: .Ed
1.14 dugsong 860: .It Cm NumberOfPasswordPrompts
1.42 aaron 861: Specifies the number of password prompts before giving up.
862: The argument to this keyword must be an integer.
863: Default is 3.
1.34 markus 864: .It Cm PasswordAuthentication
1.40 aaron 865: Specifies whether to use password authentication.
866: The argument to this keyword must be
1.34 markus 867: .Dq yes
868: or
869: .Dq no .
1.100 stevesk 870: The default is
871: .Dq yes .
1.50 markus 872: Note that this option applies to both protocol version 1 and 2.
1.2 deraadt 873: .It Cm Port
1.40 aaron 874: Specifies the port number to connect on the remote host.
875: Default is 22.
1.99 djm 876: .It Cm PreferredAuthentications
877: Specifies the order in which the client should try protocol 2
878: authentication methods. This allows a client to prefer one method (e.g.
879: .Cm keyboard-interactive )
880: over another method (e.g.
881: .Cm password )
882: The default for this option is:
883: .Dq publickey, password, keyboard-interactive
1.45 markus 884: .It Cm Protocol
885: Specifies the protocol versions
886: .Nm
887: should support in order of preference.
888: The possible values are
889: .Dq 1
890: and
891: .Dq 2 .
892: Multiple versions must be comma-separated.
893: The default is
1.101 markus 894: .Dq 2,1 .
1.49 markus 895: This means that
896: .Nm
1.101 markus 897: tries version 2 and falls back to version 1
898: if version 2 is not available.
1.2 deraadt 899: .It Cm ProxyCommand
1.40 aaron 900: Specifies the command to use to connect to the server.
901: The command
902: string extends to the end of the line, and is executed with
903: .Pa /bin/sh .
904: In the command string,
905: .Ql %h
906: will be substituted by the host name to
907: connect and
908: .Ql %p
909: by the port.
910: The command can be basically anything,
911: and should read from its standard input and write to its standard output.
912: It should eventually connect an
1.2 deraadt 913: .Xr sshd 8
1.1 deraadt 914: server running on some machine, or execute
1.2 deraadt 915: .Ic sshd -i
1.40 aaron 916: somewhere.
917: Host key management will be done using the
1.1 deraadt 918: HostName of the host being connected (defaulting to the name typed by
919: the user).
1.29 markus 920: Note that
921: .Cm CheckHostIP
922: is not available for connects with a proxy command.
1.2 deraadt 923: .Pp
924: .It Cm RemoteForward
1.1 deraadt 925: Specifies that a TCP/IP port on the remote machine be forwarded over
1.40 aaron 926: the secure channel to given host:port from the local machine.
927: The first argument must be a port number, and the second must be
928: host:port.
929: Multiple forwardings may be specified, and additional
930: forwardings can be given on the command line.
931: Only the superuser can forward privileged ports.
1.2 deraadt 932: .It Cm RhostsAuthentication
1.40 aaron 933: Specifies whether to try rhosts based authentication.
934: Note that this
1.1 deraadt 935: declaration only affects the client side and has no effect whatsoever
1.40 aaron 936: on security.
937: Disabling rhosts authentication may reduce
1.1 deraadt 938: authentication time on slow connections when rhosts authentication is
1.40 aaron 939: not used.
940: Most servers do not permit RhostsAuthentication because it
941: is not secure (see RhostsRSAAuthentication).
942: The argument to this keyword must be
1.2 deraadt 943: .Dq yes
944: or
945: .Dq no .
1.100 stevesk 946: The default is
947: .Dq yes .
1.2 deraadt 948: .It Cm RhostsRSAAuthentication
1.1 deraadt 949: Specifies whether to try rhosts based authentication with RSA host
1.40 aaron 950: authentication.
951: The argument must be
1.2 deraadt 952: .Dq yes
953: or
954: .Dq no .
1.100 stevesk 955: The default is
956: .Dq yes .
1.2 deraadt 957: .It Cm RSAAuthentication
1.40 aaron 958: Specifies whether to try RSA authentication.
959: The argument to this keyword must be
1.2 deraadt 960: .Dq yes
961: or
962: .Dq no .
1.1 deraadt 963: RSA authentication will only be
964: attempted if the identity file exists, or an authentication agent is
965: running.
1.100 stevesk 966: The default is
967: .Dq yes .
1.50 markus 968: Note that this option applies to protocol version 1 only.
1.81 markus 969: .It Cm ChallengeResponseAuthentication
970: Specifies whether to use challenge response authentication.
971: Currently there is only support for
1.27 markus 972: .Xr skey 1
1.40 aaron 973: authentication.
974: The argument to this keyword must be
1.27 markus 975: .Dq yes
976: or
977: .Dq no .
978: The default is
979: .Dq no .
1.2 deraadt 980: .It Cm StrictHostKeyChecking
981: If this flag is set to
1.44 aaron 982: .Dq yes ,
1.2 deraadt 983: .Nm
1.79 stevesk 984: will never automatically add host keys to the
1.2 deraadt 985: .Pa $HOME/.ssh/known_hosts
1.48 markus 986: and
987: .Pa $HOME/.ssh/known_hosts2
1.79 stevesk 988: files, and refuses to connect to hosts whose host key has changed.
1.40 aaron 989: This provides maximum protection against trojan horse attacks.
990: However, it can be somewhat annoying if you don't have good
1.2 deraadt 991: .Pa /etc/ssh_known_hosts
1.48 markus 992: and
993: .Pa /etc/ssh_known_hosts2
1.1 deraadt 994: files installed and frequently
1.79 stevesk 995: connect to new hosts.
996: This option forces the user to manually
997: add all new hosts.
998: If this flag is set to
999: .Dq no ,
1000: .Nm
1001: will automatically add new host keys to the
1002: user known hosts files.
1003: If this flag is set to
1004: .Dq ask ,
1005: new host keys
1006: will be added to the user known host files only after the user
1007: has confirmed that is what they really want to do, and
1008: .Nm
1009: will refuse to connect to hosts whose host key has changed.
1.40 aaron 1010: The host keys of
1.79 stevesk 1011: known hosts will be verified automatically in all cases.
1.40 aaron 1012: The argument must be
1.79 stevesk 1013: .Dq yes ,
1014: .Dq no
1.2 deraadt 1015: or
1.79 stevesk 1016: .Dq ask .
1017: The default is
1018: .Dq ask .
1.16 markus 1019: .It Cm UsePrivilegedPort
1020: Specifies whether to use a privileged port for outgoing connections.
1021: The argument must be
1022: .Dq yes
1023: or
1024: .Dq no .
1025: The default is
1.98 markus 1026: .Dq no .
1.16 markus 1027: Note that setting this option to
1028: .Dq no
1.30 provos 1029: turns off
1.16 markus 1030: .Cm RhostsAuthentication
1031: and
1.72 markus 1032: .Cm RhostsRSAAuthentication
1033: for older servers.
1.34 markus 1034: .It Cm User
1.40 aaron 1035: Specifies the user to log in as.
1036: This can be useful if you have a different user name on different machines.
1037: This saves the trouble of
1.34 markus 1038: having to remember to give the user name on the command line.
1039: .It Cm UserKnownHostsFile
1.95 stevesk 1040: Specifies a file to use for the protocol version 1 user
1041: host key database instead of
1.34 markus 1042: .Pa $HOME/.ssh/known_hosts .
1.95 stevesk 1043: .It Cm UserKnownHostsFile2
1044: Specifies a file to use for the protocol version 2 user
1045: host key database instead of
1046: .Pa $HOME/.ssh/known_hosts2 .
1.2 deraadt 1047: .It Cm UseRsh
1.40 aaron 1048: Specifies that rlogin/rsh should be used for this host.
1049: It is possible that the host does not at all support the
1.2 deraadt 1050: .Nm
1.40 aaron 1051: protocol.
1052: This causes
1.2 deraadt 1053: .Nm
1.40 aaron 1054: to immediately execute
1.2 deraadt 1055: .Xr rsh 1 .
1.1 deraadt 1056: All other options (except
1.2 deraadt 1057: .Cm HostName )
1.40 aaron 1058: are ignored if this has been specified.
1059: The argument must be
1.2 deraadt 1060: .Dq yes
1061: or
1062: .Dq no .
1.55 markus 1063: .It Cm XAuthLocation
1064: Specifies the location of the
1065: .Xr xauth 1
1066: program.
1067: The default is
1068: .Pa /usr/X11R6/bin/xauth .
1.58 itojun 1069: .El
1.2 deraadt 1070: .Sh ENVIRONMENT
1071: .Nm
1.1 deraadt 1072: will normally set the following environment variables:
1.2 deraadt 1073: .Bl -tag -width Ds
1074: .It Ev DISPLAY
1075: The
1076: .Ev DISPLAY
1.40 aaron 1077: variable indicates the location of the X11 server.
1.44 aaron 1078: It is automatically set by
1.2 deraadt 1079: .Nm
1080: to point to a value of the form
1081: .Dq hostname:n
1082: where hostname indicates
1.40 aaron 1083: the host where the shell runs, and n is an integer >= 1.
1084: .Nm
1085: uses this special value to forward X11 connections over the secure
1086: channel.
1087: The user should normally not set DISPLAY explicitly, as that
1.1 deraadt 1088: will render the X11 connection insecure (and will require the user to
1089: manually copy any required authorization cookies).
1.2 deraadt 1090: .It Ev HOME
1.1 deraadt 1091: Set to the path of the user's home directory.
1.2 deraadt 1092: .It Ev LOGNAME
1093: Synonym for
1.12 aaron 1094: .Ev USER ;
1095: set for compatibility with systems that use this variable.
1.2 deraadt 1096: .It Ev MAIL
1.1 deraadt 1097: Set to point the user's mailbox.
1.40 aaron 1098: .It Ev PATH
1.2 deraadt 1099: Set to the default
1100: .Ev PATH ,
1101: as specified when compiling
1.12 aaron 1102: .Nm ssh .
1.18 markus 1103: .It Ev SSH_AUTH_SOCK
1.17 markus 1104: indicates the path of a unix-domain socket used to communicate with the
1105: agent.
1.2 deraadt 1106: .It Ev SSH_CLIENT
1.40 aaron 1107: Identifies the client end of the connection.
1108: The variable contains
1.1 deraadt 1109: three space-separated values: client ip-address, client port number,
1110: and server port number.
1.73 markus 1111: .It Ev SSH_ORIGINAL_COMMAND
1112: The variable contains the original command line if a forced command
1113: is executed.
1114: It can be used to extract the original arguments.
1.2 deraadt 1115: .It Ev SSH_TTY
1.1 deraadt 1116: This is set to the name of the tty (path to the device) associated
1.40 aaron 1117: with the current shell or command.
1118: If the current session has no tty,
1.1 deraadt 1119: this variable is not set.
1.2 deraadt 1120: .It Ev TZ
1.1 deraadt 1121: The timezone variable is set to indicate the present timezone if it
1.56 deraadt 1122: was set when the daemon was started (i.e., the daemon passes the value
1.1 deraadt 1123: on to new connections).
1.2 deraadt 1124: .It Ev USER
1.1 deraadt 1125: Set to the name of the user logging in.
1.2 deraadt 1126: .El
1127: .Pp
1.44 aaron 1128: Additionally,
1.2 deraadt 1129: .Nm
1.44 aaron 1130: reads
1131: .Pa $HOME/.ssh/environment ,
1.2 deraadt 1132: and adds lines of the format
1133: .Dq VARNAME=value
1.12 aaron 1134: to the environment.
1.2 deraadt 1135: .Sh FILES
1.36 markus 1136: .Bl -tag -width Ds
1.95 stevesk 1137: .It Pa $HOME/.ssh/known_hosts, $HOME/.ssh/known_hosts2
1.1 deraadt 1138: Records host keys for all hosts the user has logged into (that are not
1.2 deraadt 1139: in
1.95 stevesk 1140: .Pa /etc/ssh_known_hosts
1141: for protocol version 1 or
1142: .Pa /etc/ssh_known_hosts2
1143: for protocol version 2).
1.2 deraadt 1144: See
1145: .Xr sshd 8 .
1.102 itojun 1146: .It Pa $HOME/.ssh/identity, $HOME/.ssh/id_dsa, $HOME/.ssh/id_rsa
1147: Contains the authentication identity of the user.
1148: They are for protocol 1 RSA, protocol 2 DSA, and protocol 2 RSA, respectively.
1.48 markus 1149: These files
1150: contain sensitive data and should be readable by the user but not
1.15 markus 1151: accessible by others (read/write/execute).
1152: Note that
1153: .Nm
1.48 markus 1154: ignores a private key file if it is accessible by others.
1.15 markus 1155: It is possible to specify a passphrase when
1.1 deraadt 1156: generating the key; the passphrase will be used to encrypt the
1.8 deraadt 1157: sensitive part of this file using 3DES.
1.102 itojun 1158: .It Pa $HOME/.ssh/identity.pub, $HOME/.ssh/id_dsa.pub, $HOME/.ssh/id_rsa.pub
1.1 deraadt 1159: Contains the public key for authentication (public part of the
1.40 aaron 1160: identity file in human-readable form).
1.48 markus 1161: The contents of the
1162: .Pa $HOME/.ssh/identity.pub
1163: file should be added to
1.2 deraadt 1164: .Pa $HOME/.ssh/authorized_keys
1165: on all machines
1.102 itojun 1166: where you wish to log in using protocol version 1 RSA authentication.
1.48 markus 1167: The contents of the
1168: .Pa $HOME/.ssh/id_dsa.pub
1.102 itojun 1169: and
1170: .Pa $HOME/.ssh/id_rsa.pub
1.48 markus 1171: file should be added to
1172: .Pa $HOME/.ssh/authorized_keys2
1173: on all machines
1.102 itojun 1174: where you wish to log in using protocol version 2 DSA/RSA authentication.
1.48 markus 1175: These files are not
1.40 aaron 1176: sensitive and can (but need not) be readable by anyone.
1.48 markus 1177: These files are
1.84 markus 1178: never used automatically and are not necessary; they are only provided for
1.1 deraadt 1179: the convenience of the user.
1.2 deraadt 1180: .It Pa $HOME/.ssh/config
1.40 aaron 1181: This is the per-user configuration file.
1182: The format of this file is described above.
1183: This file is used by the
1.2 deraadt 1184: .Nm
1.40 aaron 1185: client.
1186: This file does not usually contain any sensitive information,
1.1 deraadt 1187: but the recommended permissions are read/write for the user, and not
1188: accessible by others.
1.2 deraadt 1189: .It Pa $HOME/.ssh/authorized_keys
1.40 aaron 1190: Lists the RSA keys that can be used for logging in as this user.
1191: The format of this file is described in the
1.2 deraadt 1192: .Xr sshd 8
1.40 aaron 1193: manual page.
1194: In the simplest form the format is the same as the .pub
1.1 deraadt 1195: identity files (that is, each line contains the number of bits in
1196: modulus, public exponent, modulus, and comment fields, separated by
1.40 aaron 1197: spaces).
1198: This file is not highly sensitive, but the recommended
1.1 deraadt 1199: permissions are read/write for the user, and not accessible by others.
1.48 markus 1200: .It Pa $HOME/.ssh/authorized_keys2
1.68 markus 1201: Lists the public keys (DSA/RSA) that can be used for logging in as this user.
1.48 markus 1202: This file is not highly sensitive, but the recommended
1203: permissions are read/write for the user, and not accessible by others.
1204: .It Pa /etc/ssh_known_hosts, /etc/ssh_known_hosts2
1.40 aaron 1205: Systemwide list of known host keys.
1.48 markus 1206: .Pa /etc/ssh_known_hosts
1207: contains RSA and
1208: .Pa /etc/ssh_known_hosts2
1.68 markus 1209: contains DSA or RSA keys for protocol version 2.
1.48 markus 1210: These files should be prepared by the
1.1 deraadt 1211: system administrator to contain the public host keys of all machines in the
1.40 aaron 1212: organization.
1213: This file should be world-readable.
1214: This file contains
1.1 deraadt 1215: public keys, one per line, in the following format (fields separated
1216: by spaces): system name, number of bits in modulus, public exponent,
1.40 aaron 1217: modulus, and optional comment field.
1218: When different names are used
1.1 deraadt 1219: for the same machine, all such names should be listed, separated by
1.40 aaron 1220: commas.
1221: The format is described on the
1.2 deraadt 1222: .Xr sshd 8
1.1 deraadt 1223: manual page.
1.2 deraadt 1224: .Pp
1.1 deraadt 1225: The canonical system name (as returned by name servers) is used by
1.2 deraadt 1226: .Xr sshd 8
1.1 deraadt 1227: to verify the client host when logging in; other names are needed because
1.2 deraadt 1228: .Nm
1.1 deraadt 1229: does not convert the user-supplied name to a canonical name before
1230: checking the key, because someone with access to the name servers
1231: would then be able to fool host authentication.
1.2 deraadt 1232: .It Pa /etc/ssh_config
1.40 aaron 1233: Systemwide configuration file.
1234: This file provides defaults for those
1.1 deraadt 1235: values that are not specified in the user's configuration file, and
1.40 aaron 1236: for those users who do not have a configuration file.
1237: This file must be world-readable.
1.2 deraadt 1238: .It Pa $HOME/.rhosts
1239: This file is used in
1240: .Pa \&.rhosts
1241: authentication to list the
1.40 aaron 1242: host/user pairs that are permitted to log in.
1243: (Note that this file is
1.1 deraadt 1244: also used by rlogin and rsh, which makes using this file insecure.)
1245: Each line of the file contains a host name (in the canonical form
1246: returned by name servers), and then a user name on that host,
1.40 aaron 1247: separated by a space.
1.92 markus 1248: On some machines this file may need to be
1.1 deraadt 1249: world-readable if the user's home directory is on a NFS partition,
1250: because
1.2 deraadt 1251: .Xr sshd 8
1.40 aaron 1252: reads it as root.
1253: Additionally, this file must be owned by the user,
1254: and must not have write permissions for anyone else.
1255: The recommended
1.1 deraadt 1256: permission for most machines is read/write for the user, and not
1257: accessible by others.
1.2 deraadt 1258: .Pp
1.1 deraadt 1259: Note that by default
1.2 deraadt 1260: .Xr sshd 8
1.1 deraadt 1261: will be installed so that it requires successful RSA host
1.40 aaron 1262: authentication before permitting \s+2.\s0rhosts authentication.
1263: If your server machine does not have the client's host key in
1.2 deraadt 1264: .Pa /etc/ssh_known_hosts ,
1265: you can store it in
1266: .Pa $HOME/.ssh/known_hosts .
1267: The easiest way to do this is to
1.1 deraadt 1268: connect back to the client from the server machine using ssh; this
1.48 markus 1269: will automatically add the host key to
1.2 deraadt 1270: .Pa $HOME/.ssh/known_hosts .
1271: .It Pa $HOME/.shosts
1272: This file is used exactly the same way as
1273: .Pa \&.rhosts .
1274: The purpose for
1.1 deraadt 1275: having this file is to be able to use rhosts authentication with
1.2 deraadt 1276: .Nm
1277: without permitting login with
1278: .Xr rlogin 1
1279: or
1280: .Xr rsh 1 .
1281: .It Pa /etc/hosts.equiv
1282: This file is used during
1.40 aaron 1283: .Pa \&.rhosts authentication.
1284: It contains
1.1 deraadt 1285: canonical hosts names, one per line (the full format is described on
1286: the
1.2 deraadt 1287: .Xr sshd 8
1.40 aaron 1288: manual page).
1289: If the client host is found in this file, login is
1.1 deraadt 1290: automatically permitted provided client and server user names are the
1.40 aaron 1291: same.
1292: Additionally, successful RSA host authentication is normally
1293: required.
1294: This file should only be writable by root.
1.2 deraadt 1295: .It Pa /etc/shosts.equiv
1.44 aaron 1296: This file is processed exactly as
1.2 deraadt 1297: .Pa /etc/hosts.equiv .
1.1 deraadt 1298: This file may be useful to permit logins using
1.2 deraadt 1299: .Nm
1.1 deraadt 1300: but not using rsh/rlogin.
1.2 deraadt 1301: .It Pa /etc/sshrc
1.1 deraadt 1302: Commands in this file are executed by
1.2 deraadt 1303: .Nm
1.1 deraadt 1304: when the user logs in just before the user's shell (or command) is started.
1305: See the
1.2 deraadt 1306: .Xr sshd 8
1.1 deraadt 1307: manual page for more information.
1.2 deraadt 1308: .It Pa $HOME/.ssh/rc
1.1 deraadt 1309: Commands in this file are executed by
1.2 deraadt 1310: .Nm
1.1 deraadt 1311: when the user logs in just before the user's shell (or command) is
1312: started.
1.44 aaron 1313: See the
1.2 deraadt 1314: .Xr sshd 8
1.1 deraadt 1315: manual page for more information.
1.31 markus 1316: .It Pa $HOME/.ssh/environment
1317: Contains additional definitions for environment variables, see section
1318: .Sx ENVIRONMENT
1319: above.
1.58 itojun 1320: .El
1.67 aaron 1321: .Sh AUTHORS
1.78 markus 1322: OpenSSH is a derivative of the original and free
1323: ssh 1.2.12 release by Tatu Ylonen.
1324: Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos,
1325: Theo de Raadt and Dug Song
1326: removed many bugs, re-added newer features and
1327: created OpenSSH.
1328: Markus Friedl contributed the support for SSH
1329: protocol versions 1.5 and 2.0.
1.2 deraadt 1330: .Sh SEE ALSO
1331: .Xr rlogin 1 ,
1332: .Xr rsh 1 ,
1333: .Xr scp 1 ,
1.83 djm 1334: .Xr sftp 1 ,
1.2 deraadt 1335: .Xr ssh-add 1 ,
1336: .Xr ssh-agent 1 ,
1337: .Xr ssh-keygen 1 ,
1338: .Xr telnet 1 ,
1.87 itojun 1339: .Xr sshd 8
![[BACK]](/icons/back.gif){kind=icon}
Return to ssh.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / ssh