ssh.0 revision 189006
1180740SdesSSH(1) OpenBSD Reference Manual SSH(1) 2180740Sdes 3180740SdesNAME 4180740Sdes ssh - OpenSSH SSH client (remote login program) 5180740Sdes 6180740SdesSYNOPSIS 7189006Sdes ssh [-1246AaCfgKkMNnqsTtVvXxYy] [-b bind_address] [-c cipher_spec] 8180740Sdes [-D [bind_address:]port] [-e escape_char] [-F configfile] 9180740Sdes [-i identity_file] [-L [bind_address:]port:host:hostport] 10180740Sdes [-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option] [-p port] 11180740Sdes [-R [bind_address:]port:host:hostport] [-S ctl_path] 12180740Sdes [-w local_tun[:remote_tun]] [user@]hostname [command] 13180740Sdes 14180740SdesDESCRIPTION 15180740Sdes ssh (SSH client) is a program for logging into a remote machine and for 16180740Sdes executing commands on a remote machine. It is intended to replace rlogin 17180740Sdes and rsh, and provide secure encrypted communications between two untrust- 18180740Sdes ed hosts over an insecure network. X11 connections and arbitrary TCP 19180740Sdes ports can also be forwarded over the secure channel. 20180740Sdes 21180740Sdes ssh connects and logs into the specified hostname (with optional user 22180740Sdes name). The user must prove his/her identity to the remote machine using 23180740Sdes one of several methods depending on the protocol version used (see be- 24180740Sdes low). 25180740Sdes 26180740Sdes If command is specified, it is executed on the remote host instead of a 27180740Sdes login shell. 28180740Sdes 29180740Sdes The options are as follows: 30180740Sdes 31180740Sdes -1 Forces ssh to try protocol version 1 only. 32180740Sdes 33180740Sdes -2 Forces ssh to try protocol version 2 only. 34180740Sdes 35180740Sdes -4 Forces ssh to use IPv4 addresses only. 36180740Sdes 37180740Sdes -6 Forces ssh to use IPv6 addresses only. 38180740Sdes 39180740Sdes -A Enables forwarding of the authentication agent connection. This 40180740Sdes can also be specified on a per-host basis in a configuration 41180740Sdes file. 42180740Sdes 43180740Sdes Agent forwarding should be enabled with caution. Users with the 44180740Sdes ability to bypass file permissions on the remote host (for the 45180740Sdes agent's Unix-domain socket) can access the local agent through 46180740Sdes the forwarded connection. An attacker cannot obtain key material 47180740Sdes from the agent, however they can perform operations on the keys 48180740Sdes that enable them to authenticate using the identities loaded into 49180740Sdes the agent. 50180740Sdes 51180740Sdes -a Disables forwarding of the authentication agent connection. 52180740Sdes 53180740Sdes -b bind_address 54180740Sdes Use bind_address on the local machine as the source address of 55180740Sdes the connection. Only useful on systems with more than one ad- 56180740Sdes dress. 57180740Sdes 58180740Sdes -C Requests compression of all data (including stdin, stdout, 59180740Sdes stderr, and data for forwarded X11 and TCP connections). The 60180740Sdes compression algorithm is the same used by gzip(1), and the 61180740Sdes ``level'' can be controlled by the CompressionLevel option for 62180740Sdes protocol version 1. Compression is desirable on modem lines and 63180740Sdes other slow connections, but will only slow down things on fast 64180740Sdes networks. The default value can be set on a host-by-host basis 65180740Sdes in the configuration files; see the Compression option. 66180740Sdes 67180740Sdes -c cipher_spec 68180740Sdes Selects the cipher specification for encrypting the session. 69180740Sdes 70180740Sdes Protocol version 1 allows specification of a single cipher. The 71180740Sdes supported values are ``3des'', ``blowfish'', and ``des''. 3des 72180740Sdes (triple-des) is an encrypt-decrypt-encrypt triple with three dif- 73180740Sdes ferent keys. It is believed to be secure. blowfish is a fast 74180740Sdes block cipher; it appears very secure and is much faster than 75180740Sdes 3des. des is only supported in the ssh client for interoperabil- 76180740Sdes ity with legacy protocol 1 implementations that do not support 77180740Sdes the 3des cipher. Its use is strongly discouraged due to crypto- 78180740Sdes graphic weaknesses. The default is ``3des''. 79180740Sdes 80180740Sdes For protocol version 2, cipher_spec is a comma-separated list of 81180740Sdes ciphers listed in order of preference. The supported ciphers 82180740Sdes are: 3des-cbc, aes128-cbc, aes192-cbc, aes256-cbc, aes128-ctr, 83180740Sdes aes192-ctr, aes256-ctr, arcfour128, arcfour256, arcfour, blow- 84180740Sdes fish-cbc, and cast128-cbc. The default is: 85180740Sdes 86180740Sdes aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour128, 87180740Sdes arcfour256,arcfour,aes192-cbc,aes256-cbc,aes128-ctr, 88180740Sdes aes192-ctr,aes256-ctr 89180740Sdes 90180740Sdes -D [bind_address:]port 91180740Sdes Specifies a local ``dynamic'' application-level port forwarding. 92180740Sdes This works by allocating a socket to listen to port on the local 93180740Sdes side, optionally bound to the specified bind_address. Whenever a 94180740Sdes connection is made to this port, the connection is forwarded over 95180740Sdes the secure channel, and the application protocol is then used to 96180740Sdes determine where to connect to from the remote machine. Currently 97180740Sdes the SOCKS4 and SOCKS5 protocols are supported, and ssh will act 98180740Sdes as a SOCKS server. Only root can forward privileged ports. Dy- 99180740Sdes namic port forwardings can also be specified in the configuration 100180740Sdes file. 101180740Sdes 102180740Sdes IPv6 addresses can be specified with an alternative syntax: 103180740Sdes [bind_address/]port or by enclosing the address in square brack- 104180740Sdes ets. Only the superuser can forward privileged ports. By de- 105180740Sdes fault, the local port is bound in accordance with the 106180740Sdes GatewayPorts setting. However, an explicit bind_address may be 107180740Sdes used to bind the connection to a specific address. The 108180740Sdes bind_address of ``localhost'' indicates that the listening port 109180740Sdes be bound for local use only, while an empty address or `*' indi- 110180740Sdes cates that the port should be available from all interfaces. 111180740Sdes 112180740Sdes -e escape_char 113180740Sdes Sets the escape character for sessions with a pty (default: `~'). 114180740Sdes The escape character is only recognized at the beginning of a 115180740Sdes line. The escape character followed by a dot (`.') closes the 116180740Sdes connection; followed by control-Z suspends the connection; and 117180740Sdes followed by itself sends the escape character once. Setting the 118180740Sdes character to ``none'' disables any escapes and makes the session 119180740Sdes fully transparent. 120180740Sdes 121180740Sdes -F configfile 122180740Sdes Specifies an alternative per-user configuration file. If a con- 123180740Sdes figuration file is given on the command line, the system-wide 124180740Sdes configuration file (/etc/ssh/ssh_config) will be ignored. The 125180740Sdes default for the per-user configuration file is ~/.ssh/config. 126180740Sdes 127180740Sdes -f Requests ssh to go to background just before command execution. 128180740Sdes This is useful if ssh is going to ask for passwords or passphras- 129180740Sdes es, but the user wants it in the background. This implies -n. 130180740Sdes The recommended way to start X11 programs at a remote site is 131180740Sdes with something like ssh -f host xterm. 132180740Sdes 133180750Sdes If the ExitOnForwardFailure configuration option is set to 134180750Sdes ``yes'', then a client started with -f will wait for all remote 135180750Sdes port forwards to be successfully established before placing it- 136180750Sdes self in the background. 137180750Sdes 138180740Sdes -g Allows remote hosts to connect to local forwarded ports. 139180740Sdes 140180740Sdes -I smartcard_device 141180740Sdes Specify the device ssh should use to communicate with a smartcard 142180740Sdes used for storing the user's private RSA key. This option is only 143180740Sdes available if support for smartcard devices is compiled in (de- 144180740Sdes fault is no support). 145180740Sdes 146180740Sdes -i identity_file 147180740Sdes Selects a file from which the identity (private key) for RSA or 148180740Sdes DSA authentication is read. The default is ~/.ssh/identity for 149180740Sdes protocol version 1, and ~/.ssh/id_rsa and ~/.ssh/id_dsa for pro- 150180740Sdes tocol version 2. Identity files may also be specified on a per- 151180740Sdes host basis in the configuration file. It is possible to have 152180740Sdes multiple -i options (and multiple identities specified in config- 153180740Sdes uration files). 154180740Sdes 155180744Sdes -K Enables GSSAPI-based authentication and forwarding (delegation) 156180744Sdes of GSSAPI credentials to the server. 157180744Sdes 158180740Sdes -k Disables forwarding (delegation) of GSSAPI credentials to the 159180740Sdes server. 160180740Sdes 161180740Sdes -L [bind_address:]port:host:hostport 162180740Sdes Specifies that the given port on the local (client) host is to be 163180740Sdes forwarded to the given host and port on the remote side. This 164180740Sdes works by allocating a socket to listen to port on the local side, 165180740Sdes optionally bound to the specified bind_address. Whenever a con- 166180740Sdes nection is made to this port, the connection is forwarded over 167180740Sdes the secure channel, and a connection is made to host port 168180740Sdes hostport from the remote machine. Port forwardings can also be 169180740Sdes specified in the configuration file. IPv6 addresses can be spec- 170180740Sdes ified with an alternative syntax: [bind_address/]port/host/host- 171180740Sdes port or by enclosing the address in square brackets. Only the 172180740Sdes superuser can forward privileged ports. By default, the local 173180740Sdes port is bound in accordance with the GatewayPorts setting. How- 174180740Sdes ever, an explicit bind_address may be used to bind the connection 175180740Sdes to a specific address. The bind_address of ``localhost'' indi- 176180740Sdes cates that the listening port be bound for local use only, while 177180740Sdes an empty address or `*' indicates that the port should be avail- 178180740Sdes able from all interfaces. 179180740Sdes 180180740Sdes -l login_name 181180740Sdes Specifies the user to log in as on the remote machine. This also 182180740Sdes may be specified on a per-host basis in the configuration file. 183180740Sdes 184180740Sdes -M Places the ssh client into ``master'' mode for connection shar- 185180740Sdes ing. Multiple -M options places ssh into ``master'' mode with 186180740Sdes confirmation required before slave connections are accepted. Re- 187180740Sdes fer to the description of ControlMaster in ssh_config(5) for de- 188180740Sdes tails. 189180740Sdes 190180740Sdes -m mac_spec 191180740Sdes Additionally, for protocol version 2 a comma-separated list of 192180740Sdes MAC (message authentication code) algorithms can be specified in 193180740Sdes order of preference. See the MACs keyword for more information. 194180740Sdes 195180740Sdes -N Do not execute a remote command. This is useful for just for- 196180740Sdes warding ports (protocol version 2 only). 197180740Sdes 198180740Sdes -n Redirects stdin from /dev/null (actually, prevents reading from 199180740Sdes stdin). This must be used when ssh is run in the background. A 200180740Sdes common trick is to use this to run X11 programs on a remote ma- 201180740Sdes chine. For example, ssh -n shadows.cs.hut.fi emacs & will start 202180740Sdes an emacs on shadows.cs.hut.fi, and the X11 connection will be au- 203180740Sdes tomatically forwarded over an encrypted channel. The ssh program 204180740Sdes will be put in the background. (This does not work if ssh needs 205180740Sdes to ask for a password or passphrase; see also the -f option.) 206180740Sdes 207180740Sdes -O ctl_cmd 208180740Sdes Control an active connection multiplexing master process. When 209180740Sdes the -O option is specified, the ctl_cmd argument is interpreted 210180740Sdes and passed to the master process. Valid commands are: ``check'' 211180740Sdes (check that the master process is running) and ``exit'' (request 212180740Sdes the master to exit). 213180740Sdes 214180740Sdes -o option 215180740Sdes Can be used to give options in the format used in the configura- 216180740Sdes tion file. This is useful for specifying options for which there 217180740Sdes is no separate command-line flag. For full details of the op- 218180740Sdes tions listed below, and their possible values, see ssh_config(5). 219180740Sdes 220180740Sdes AddressFamily 221180740Sdes BatchMode 222180740Sdes BindAddress 223180740Sdes ChallengeResponseAuthentication 224180740Sdes CheckHostIP 225180740Sdes Cipher 226180740Sdes Ciphers 227180740Sdes ClearAllForwardings 228180740Sdes Compression 229180740Sdes CompressionLevel 230180740Sdes ConnectionAttempts 231180740Sdes ConnectTimeout 232180740Sdes ControlMaster 233180740Sdes ControlPath 234180740Sdes DynamicForward 235180740Sdes EscapeChar 236180740Sdes ExitOnForwardFailure 237180740Sdes ForwardAgent 238180740Sdes ForwardX11 239180740Sdes ForwardX11Trusted 240180740Sdes GatewayPorts 241180740Sdes GlobalKnownHostsFile 242180740Sdes GSSAPIAuthentication 243180740Sdes GSSAPIDelegateCredentials 244180740Sdes HashKnownHosts 245180740Sdes Host 246180740Sdes HostbasedAuthentication 247180740Sdes HostKeyAlgorithms 248180740Sdes HostKeyAlias 249180740Sdes HostName 250180740Sdes IdentityFile 251180740Sdes IdentitiesOnly 252180740Sdes KbdInteractiveDevices 253180740Sdes LocalCommand 254180740Sdes LocalForward 255180740Sdes LogLevel 256180740Sdes MACs 257180740Sdes NoHostAuthenticationForLocalhost 258180740Sdes NumberOfPasswordPrompts 259180740Sdes PasswordAuthentication 260180740Sdes PermitLocalCommand 261180740Sdes Port 262180740Sdes PreferredAuthentications 263180740Sdes Protocol 264180740Sdes ProxyCommand 265180740Sdes PubkeyAuthentication 266180740Sdes RekeyLimit 267180740Sdes RemoteForward 268180740Sdes RhostsRSAAuthentication 269180740Sdes RSAAuthentication 270180740Sdes SendEnv 271180740Sdes ServerAliveInterval 272180740Sdes ServerAliveCountMax 273180740Sdes SmartcardDevice 274180740Sdes StrictHostKeyChecking 275180740Sdes TCPKeepAlive 276180740Sdes Tunnel 277180740Sdes TunnelDevice 278180740Sdes UsePrivilegedPort 279180740Sdes User 280180740Sdes UserKnownHostsFile 281180740Sdes VerifyHostKeyDNS 282180750Sdes VisualHostKey 283180740Sdes XAuthLocation 284180740Sdes 285180740Sdes -p port 286180740Sdes Port to connect to on the remote host. This can be specified on 287180740Sdes a per-host basis in the configuration file. 288180740Sdes 289180746Sdes -q Quiet mode. Causes most warning and diagnostic messages to be 290180740Sdes suppressed. 291180740Sdes 292180740Sdes -R [bind_address:]port:host:hostport 293180740Sdes Specifies that the given port on the remote (server) host is to 294180740Sdes be forwarded to the given host and port on the local side. This 295180740Sdes works by allocating a socket to listen to port on the remote 296180740Sdes side, and whenever a connection is made to this port, the connec- 297180740Sdes tion is forwarded over the secure channel, and a connection is 298180740Sdes made to host port hostport from the local machine. 299180740Sdes 300180740Sdes Port forwardings can also be specified in the configuration file. 301180740Sdes Privileged ports can be forwarded only when logging in as root on 302180740Sdes the remote machine. IPv6 addresses can be specified by enclosing 303180740Sdes the address in square braces or using an alternative syntax: 304180740Sdes [bind_address/]host/port/hostport. 305180740Sdes 306180740Sdes By default, the listening socket on the server will be bound to 307189006Sdes the loopback interface only. This may be overridden by specify- 308189006Sdes ing a bind_address. An empty bind_address, or the address `*', 309189006Sdes indicates that the remote socket should listen on all interfaces. 310180740Sdes Specifying a remote bind_address will only succeed if the serv- 311180740Sdes er's GatewayPorts option is enabled (see sshd_config(5)). 312180740Sdes 313189006Sdes If the port argument is `0', the listen port will be dynamically 314189006Sdes allocated on the server and reported to the client at run time. 315189006Sdes 316180740Sdes -S ctl_path 317180740Sdes Specifies the location of a control socket for connection shar- 318180740Sdes ing. Refer to the description of ControlPath and ControlMaster 319180740Sdes in ssh_config(5) for details. 320180740Sdes 321180740Sdes -s May be used to request invocation of a subsystem on the remote 322180740Sdes system. Subsystems are a feature of the SSH2 protocol which fa- 323180740Sdes cilitate the use of SSH as a secure transport for other applica- 324180740Sdes tions (eg. sftp(1)). The subsystem is specified as the remote 325180740Sdes command. 326180740Sdes 327180740Sdes -T Disable pseudo-tty allocation. 328180740Sdes 329180740Sdes -t Force pseudo-tty allocation. This can be used to execute arbi- 330180740Sdes trary screen-based programs on a remote machine, which can be 331180740Sdes very useful, e.g. when implementing menu services. Multiple -t 332180740Sdes options force tty allocation, even if ssh has no local tty. 333180740Sdes 334180740Sdes -V Display the version number and exit. 335180740Sdes 336180740Sdes -v Verbose mode. Causes ssh to print debugging messages about its 337180740Sdes progress. This is helpful in debugging connection, authentica- 338180740Sdes tion, and configuration problems. Multiple -v options increase 339180740Sdes the verbosity. The maximum is 3. 340180740Sdes 341180740Sdes -w local_tun[:remote_tun] 342180740Sdes Requests tunnel device forwarding with the specified tun(4) de- 343180740Sdes vices between the client (local_tun) and the server (remote_tun). 344180740Sdes 345180740Sdes The devices may be specified by numerical ID or the keyword 346180740Sdes ``any'', which uses the next available tunnel device. If 347180740Sdes remote_tun is not specified, it defaults to ``any''. See also 348180740Sdes the Tunnel and TunnelDevice directives in ssh_config(5). If the 349180740Sdes Tunnel directive is unset, it is set to the default tunnel mode, 350180740Sdes which is ``point-to-point''. 351180740Sdes 352180740Sdes -X Enables X11 forwarding. This can also be specified on a per-host 353180740Sdes basis in a configuration file. 354180740Sdes 355180740Sdes X11 forwarding should be enabled with caution. Users with the 356180740Sdes ability to bypass file permissions on the remote host (for the 357180740Sdes user's X authorization database) can access the local X11 display 358180740Sdes through the forwarded connection. An attacker may then be able 359180740Sdes to perform activities such as keystroke monitoring. 360180740Sdes 361180740Sdes For this reason, X11 forwarding is subjected to X11 SECURITY ex- 362180740Sdes tension restrictions by default. Please refer to the ssh -Y op- 363180740Sdes tion and the ForwardX11Trusted directive in ssh_config(5) for 364180740Sdes more information. 365180740Sdes 366180740Sdes -x Disables X11 forwarding. 367180740Sdes 368180740Sdes -Y Enables trusted X11 forwarding. Trusted X11 forwardings are not 369180740Sdes subjected to the X11 SECURITY extension controls. 370180740Sdes 371189006Sdes -y Send log information using the syslog(3) system module. By de- 372189006Sdes fault this information is sent to stderr. 373189006Sdes 374180740Sdes ssh may additionally obtain configuration data from a per-user configura- 375180740Sdes tion file and a system-wide configuration file. The file format and con- 376180740Sdes figuration options are described in ssh_config(5). 377180740Sdes 378180740Sdes ssh exits with the exit status of the remote command or with 255 if an 379180740Sdes error occurred. 380180740Sdes 381180740SdesAUTHENTICATION 382180740Sdes The OpenSSH SSH client supports SSH protocols 1 and 2. Protocol 2 is the 383180740Sdes default, with ssh falling back to protocol 1 if it detects protocol 2 is 384180740Sdes unsupported. These settings may be altered using the Protocol option in 385180740Sdes ssh_config(5), or enforced using the -1 and -2 options (see above). Both 386180740Sdes protocols support similar authentication methods, but protocol 2 is pre- 387180740Sdes ferred since it provides additional mechanisms for confidentiality (the 388180740Sdes traffic is encrypted using AES, 3DES, Blowfish, CAST128, or Arcfour) and 389180744Sdes integrity (hmac-md5, hmac-sha1, umac-64, hmac-ripemd160). Protocol 1 390180744Sdes lacks a strong mechanism for ensuring the integrity of the connection. 391180740Sdes 392180740Sdes The methods available for authentication are: GSSAPI-based authentica- 393180740Sdes tion, host-based authentication, public key authentication, challenge-re- 394180740Sdes sponse authentication, and password authentication. Authentication meth- 395180740Sdes ods are tried in the order specified above, though protocol 2 has a con- 396180740Sdes figuration option to change the default order: PreferredAuthentications. 397180740Sdes 398180740Sdes Host-based authentication works as follows: If the machine the user logs 399180740Sdes in from is listed in /etc/hosts.equiv or /etc/shosts.equiv on the remote 400180740Sdes machine, and the user names are the same on both sides, or if the files 401180740Sdes ~/.rhosts or ~/.shosts exist in the user's home directory on the remote 402180740Sdes machine and contain a line containing the name of the client machine and 403180740Sdes the name of the user on that machine, the user is considered for login. 404180740Sdes Additionally, the server must be able to verify the client's host key 405180740Sdes (see the description of /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts, 406180740Sdes below) for login to be permitted. This authentication method closes se- 407180740Sdes curity holes due to IP spoofing, DNS spoofing, and routing spoofing. 408180740Sdes [Note to the administrator: /etc/hosts.equiv, ~/.rhosts, and the 409180740Sdes rlogin/rsh protocol in general, are inherently insecure and should be 410180740Sdes disabled if security is desired.] 411180740Sdes 412180740Sdes Public key authentication works as follows: The scheme is based on pub- 413180740Sdes lic-key cryptography, using cryptosystems where encryption and decryption 414180740Sdes are done using separate keys, and it is unfeasible to derive the decryp- 415180740Sdes tion key from the encryption key. The idea is that each user creates a 416180740Sdes public/private key pair for authentication purposes. The server knows 417180740Sdes the public key, and only the user knows the private key. ssh implements 418180740Sdes public key authentication protocol automatically, using either the RSA or 419180740Sdes DSA algorithms. Protocol 1 is restricted to using only RSA keys, but 420180740Sdes protocol 2 may use either. The HISTORY section of ssl(8) contains a 421180740Sdes brief discussion of the two algorithms. 422180740Sdes 423180740Sdes The file ~/.ssh/authorized_keys lists the public keys that are permitted 424180740Sdes for logging in. When the user logs in, the ssh program tells the server 425180740Sdes which key pair it would like to use for authentication. The client 426180740Sdes proves that it has access to the private key and the server checks that 427180740Sdes the corresponding public key is authorized to accept the account. 428180740Sdes 429180740Sdes The user creates his/her key pair by running ssh-keygen(1). This stores 430180740Sdes the private key in ~/.ssh/identity (protocol 1), ~/.ssh/id_dsa (protocol 431180740Sdes 2 DSA), or ~/.ssh/id_rsa (protocol 2 RSA) and stores the public key in 432180740Sdes ~/.ssh/identity.pub (protocol 1), ~/.ssh/id_dsa.pub (protocol 2 DSA), or 433180740Sdes ~/.ssh/id_rsa.pub (protocol 2 RSA) in the user's home directory. The us- 434180740Sdes er should then copy the public key to ~/.ssh/authorized_keys in his/her 435180740Sdes home directory on the remote machine. The authorized_keys file corre- 436180740Sdes sponds to the conventional ~/.rhosts file, and has one key per line, 437180740Sdes though the lines can be very long. After this, the user can log in with- 438180740Sdes out giving the password. 439180740Sdes 440180740Sdes The most convenient way to use public key authentication may be with an 441180740Sdes authentication agent. See ssh-agent(1) for more information. 442180740Sdes 443180740Sdes Challenge-response authentication works as follows: The server sends an 444180740Sdes arbitrary "challenge" text, and prompts for a response. Protocol 2 al- 445180740Sdes lows multiple challenges and responses; protocol 1 is restricted to just 446180740Sdes one challenge/response. Examples of challenge-response authentication 447180740Sdes include BSD Authentication (see login.conf(5)) and PAM (some non-OpenBSD 448180740Sdes systems). 449180740Sdes 450180740Sdes Finally, if other authentication methods fail, ssh prompts the user for a 451180740Sdes password. The password is sent to the remote host for checking; however, 452180740Sdes since all communications are encrypted, the password cannot be seen by 453180740Sdes someone listening on the network. 454180740Sdes 455180740Sdes ssh automatically maintains and checks a database containing identifica- 456180740Sdes tion for all hosts it has ever been used with. Host keys are stored in 457180740Sdes ~/.ssh/known_hosts in the user's home directory. Additionally, the file 458180740Sdes /etc/ssh/ssh_known_hosts is automatically checked for known hosts. Any 459180740Sdes new hosts are automatically added to the user's file. If a host's iden- 460180740Sdes tification ever changes, ssh warns about this and disables password au- 461180740Sdes thentication to prevent server spoofing or man-in-the-middle attacks, 462180740Sdes which could otherwise be used to circumvent the encryption. The 463180740Sdes StrictHostKeyChecking option can be used to control logins to machines 464180740Sdes whose host key is not known or has changed. 465180740Sdes 466180740Sdes When the user's identity has been accepted by the server, the server ei- 467180740Sdes ther executes the given command, or logs into the machine and gives the 468180740Sdes user a normal shell on the remote machine. All communication with the 469180740Sdes remote command or shell will be automatically encrypted. 470180740Sdes 471180740Sdes If a pseudo-terminal has been allocated (normal login session), the user 472180740Sdes may use the escape characters noted below. 473180740Sdes 474180740Sdes If no pseudo-tty has been allocated, the session is transparent and can 475180740Sdes be used to reliably transfer binary data. On most systems, setting the 476180740Sdes escape character to ``none'' will also make the session transparent even 477180740Sdes if a tty is used. 478180740Sdes 479180740Sdes The session terminates when the command or shell on the remote machine 480180740Sdes exits and all X11 and TCP connections have been closed. 481180740Sdes 482180740SdesESCAPE CHARACTERS 483180740Sdes When a pseudo-terminal has been requested, ssh supports a number of func- 484180740Sdes tions through the use of an escape character. 485180740Sdes 486180740Sdes A single tilde character can be sent as ~~ or by following the tilde by a 487180740Sdes character other than those described below. The escape character must 488180740Sdes always follow a newline to be interpreted as special. The escape charac- 489180740Sdes ter can be changed in configuration files using the EscapeChar configura- 490180740Sdes tion directive or on the command line by the -e option. 491180740Sdes 492180740Sdes The supported escapes (assuming the default `~') are: 493180740Sdes 494180740Sdes ~. Disconnect. 495180740Sdes 496180740Sdes ~^Z Background ssh. 497180740Sdes 498180740Sdes ~# List forwarded connections. 499180740Sdes 500180740Sdes ~& Background ssh at logout when waiting for forwarded connection / 501180740Sdes X11 sessions to terminate. 502180740Sdes 503180740Sdes ~? Display a list of escape characters. 504180740Sdes 505180740Sdes ~B Send a BREAK to the remote system (only useful for SSH protocol 506180740Sdes version 2 and if the peer supports it). 507180740Sdes 508180740Sdes ~C Open command line. Currently this allows the addition of port 509189006Sdes forwardings using the -L, -R and -D options (see above). It also 510189006Sdes allows the cancellation of existing remote port-forwardings using 511180740Sdes -KR[bind_address:]port. !command allows the user to execute a 512180740Sdes local command if the PermitLocalCommand option is enabled in 513180740Sdes ssh_config(5). Basic help is available, using the -h option. 514180740Sdes 515180740Sdes ~R Request rekeying of the connection (only useful for SSH protocol 516180740Sdes version 2 and if the peer supports it). 517180740Sdes 518180740SdesTCP FORWARDING 519180740Sdes Forwarding of arbitrary TCP connections over the secure channel can be 520180740Sdes specified either on the command line or in a configuration file. One 521180740Sdes possible application of TCP forwarding is a secure connection to a mail 522180740Sdes server; another is going through firewalls. 523180740Sdes 524180740Sdes In the example below, we look at encrypting communication between an IRC 525180740Sdes client and server, even though the IRC server does not directly support 526180740Sdes encrypted communications. This works as follows: the user connects to 527180740Sdes the remote host using ssh, specifying a port to be used to forward con- 528180740Sdes nections to the remote server. After that it is possible to start the 529180740Sdes service which is to be encrypted on the client machine, connecting to the 530180740Sdes same local port, and ssh will encrypt and forward the connection. 531180740Sdes 532180740Sdes The following example tunnels an IRC session from client machine 533180740Sdes ``127.0.0.1'' (localhost) to remote server ``server.example.com'': 534180740Sdes 535180740Sdes $ ssh -f -L 1234:localhost:6667 server.example.com sleep 10 536180740Sdes $ irc -c '#users' -p 1234 pinky 127.0.0.1 537180740Sdes 538180740Sdes This tunnels a connection to IRC server ``server.example.com'', joining 539180740Sdes channel ``#users'', nickname ``pinky'', using port 1234. It doesn't mat- 540180740Sdes ter which port is used, as long as it's greater than 1023 (remember, only 541180740Sdes root can open sockets on privileged ports) and doesn't conflict with any 542180740Sdes ports already in use. The connection is forwarded to port 6667 on the 543180740Sdes remote server, since that's the standard port for IRC services. 544180740Sdes 545180740Sdes The -f option backgrounds ssh and the remote command ``sleep 10'' is 546180740Sdes specified to allow an amount of time (10 seconds, in the example) to 547180740Sdes start the service which is to be tunnelled. If no connections are made 548180740Sdes within the time specified, ssh will exit. 549180740Sdes 550180740SdesX11 FORWARDING 551180740Sdes If the ForwardX11 variable is set to ``yes'' (or see the description of 552180740Sdes the -X, -x, and -Y options above) and the user is using X11 (the DISPLAY 553180740Sdes environment variable is set), the connection to the X11 display is auto- 554180740Sdes matically forwarded to the remote side in such a way that any X11 pro- 555180740Sdes grams started from the shell (or command) will go through the encrypted 556180740Sdes channel, and the connection to the real X server will be made from the 557180740Sdes local machine. The user should not manually set DISPLAY. Forwarding of 558180740Sdes X11 connections can be configured on the command line or in configuration 559180740Sdes files. 560180740Sdes 561180740Sdes The DISPLAY value set by ssh will point to the server machine, but with a 562180740Sdes display number greater than zero. This is normal, and happens because 563180740Sdes ssh creates a ``proxy'' X server on the server machine for forwarding the 564180740Sdes connections over the encrypted channel. 565180740Sdes 566180740Sdes ssh will also automatically set up Xauthority data on the server machine. 567180740Sdes For this purpose, it will generate a random authorization cookie, store 568180740Sdes it in Xauthority on the server, and verify that any forwarded connections 569180740Sdes carry this cookie and replace it by the real cookie when the connection 570180740Sdes is opened. The real authentication cookie is never sent to the server 571180740Sdes machine (and no cookies are sent in the plain). 572180740Sdes 573180740Sdes If the ForwardAgent variable is set to ``yes'' (or see the description of 574180740Sdes the -A and -a options above) and the user is using an authentication 575180740Sdes agent, the connection to the agent is automatically forwarded to the re- 576180740Sdes mote side. 577180740Sdes 578180740SdesVERIFYING HOST KEYS 579180740Sdes When connecting to a server for the first time, a fingerprint of the 580180740Sdes server's public key is presented to the user (unless the option 581180740Sdes StrictHostKeyChecking has been disabled). Fingerprints can be determined 582180740Sdes using ssh-keygen(1): 583180740Sdes 584180740Sdes $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key 585180740Sdes 586180750Sdes If the fingerprint is already known, it can be matched and the key can be 587180750Sdes accepted or rejected. Because of the difficulty of comparing host keys 588180750Sdes just by looking at hex strings, there is also support to compare host 589180750Sdes keys visually, using random art. By setting the VisualHostKey option to 590180750Sdes ``yes'', a small ASCII graphic gets displayed on every login to a server, 591180750Sdes no matter if the session itself is interactive or not. By learning the 592180750Sdes pattern a known server produces, a user can easily find out that the host 593180750Sdes key has changed when a completely different pattern is displayed. Be- 594180750Sdes cause these patterns are not unambiguous however, a pattern that looks 595180750Sdes similar to the pattern remembered only gives a good probability that the 596180750Sdes host key is the same, not guaranteed proof. 597180740Sdes 598180750Sdes To get a listing of the fingerprints along with their random art for all 599180750Sdes known hosts, the following command line can be used: 600180750Sdes 601180750Sdes $ ssh-keygen -lv -f ~/.ssh/known_hosts 602180750Sdes 603180750Sdes If the fingerprint is unknown, an alternative method of verification is 604180750Sdes available: SSH fingerprints verified by DNS. An additional resource 605180750Sdes record (RR), SSHFP, is added to a zonefile and the connecting client is 606180750Sdes able to match the fingerprint with that of the key presented. 607180750Sdes 608180740Sdes In this example, we are connecting a client to a server, 609180740Sdes ``host.example.com''. The SSHFP resource records should first be added 610180740Sdes to the zonefile for host.example.com: 611180740Sdes 612180740Sdes $ ssh-keygen -r host.example.com. 613180740Sdes 614180740Sdes The output lines will have to be added to the zonefile. To check that 615180740Sdes the zone is answering fingerprint queries: 616180740Sdes 617180740Sdes $ dig -t SSHFP host.example.com 618180740Sdes 619180740Sdes Finally the client connects: 620180740Sdes 621180740Sdes $ ssh -o "VerifyHostKeyDNS ask" host.example.com 622180740Sdes [...] 623180740Sdes Matching host key fingerprint found in DNS. 624180740Sdes Are you sure you want to continue connecting (yes/no)? 625180740Sdes 626180740Sdes See the VerifyHostKeyDNS option in ssh_config(5) for more information. 627180740Sdes 628180740SdesSSH-BASED VIRTUAL PRIVATE NETWORKS 629180740Sdes ssh contains support for Virtual Private Network (VPN) tunnelling using 630180740Sdes the tun(4) network pseudo-device, allowing two networks to be joined se- 631180740Sdes curely. The sshd_config(5) configuration option PermitTunnel controls 632180740Sdes whether the server supports this, and at what level (layer 2 or 3 traf- 633180740Sdes fic). 634180740Sdes 635180740Sdes The following example would connect client network 10.0.50.0/24 with re- 636180740Sdes mote network 10.0.99.0/24 using a point-to-point connection from 10.1.1.1 637180740Sdes to 10.1.1.2, provided that the SSH server running on the gateway to the 638180740Sdes remote network, at 192.168.1.15, allows it. 639180740Sdes 640180740Sdes On the client: 641180740Sdes 642180740Sdes # ssh -f -w 0:1 192.168.1.15 true 643180740Sdes # ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252 644180740Sdes # route add 10.0.99.0/24 10.1.1.2 645180740Sdes 646180740Sdes On the server: 647180740Sdes 648180740Sdes # ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252 649180740Sdes # route add 10.0.50.0/24 10.1.1.1 650180740Sdes 651180740Sdes Client access may be more finely tuned via the /root/.ssh/authorized_keys 652180740Sdes file (see below) and the PermitRootLogin server option. The following 653180740Sdes entry would permit connections on tun(4) device 1 from user ``jane'' and 654180740Sdes on tun device 2 from user ``john'', if PermitRootLogin is set to 655180740Sdes ``forced-commands-only'': 656180740Sdes 657180740Sdes tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane 658180740Sdes tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john 659180740Sdes 660180740Sdes Since an SSH-based setup entails a fair amount of overhead, it may be 661180740Sdes more suited to temporary setups, such as for wireless VPNs. More perma- 662180740Sdes nent VPNs are better provided by tools such as ipsecctl(8) and 663180740Sdes isakmpd(8). 664180740Sdes 665180740SdesENVIRONMENT 666180740Sdes ssh will normally set the following environment variables: 667180740Sdes 668180740Sdes DISPLAY The DISPLAY variable indicates the location of the 669180740Sdes X11 server. It is automatically set by ssh to 670180740Sdes point to a value of the form ``hostname:n'', where 671180740Sdes ``hostname'' indicates the host where the shell 672180740Sdes runs, and `n' is an integer >= 1. ssh uses this 673180740Sdes special value to forward X11 connections over the 674180740Sdes secure channel. The user should normally not set 675180740Sdes DISPLAY explicitly, as that will render the X11 676180740Sdes connection insecure (and will require the user to 677180740Sdes manually copy any required authorization cookies). 678180740Sdes 679180740Sdes HOME Set to the path of the user's home directory. 680180740Sdes 681180740Sdes LOGNAME Synonym for USER; set for compatibility with sys- 682180740Sdes tems that use this variable. 683180740Sdes 684180740Sdes MAIL Set to the path of the user's mailbox. 685180740Sdes 686180740Sdes PATH Set to the default PATH, as specified when compil- 687180740Sdes ing ssh. 688180740Sdes 689180740Sdes SSH_ASKPASS If ssh needs a passphrase, it will read the 690180740Sdes passphrase from the current terminal if it was run 691180740Sdes from a terminal. If ssh does not have a terminal 692180740Sdes associated with it but DISPLAY and SSH_ASKPASS are 693180740Sdes set, it will execute the program specified by 694180740Sdes SSH_ASKPASS and open an X11 window to read the 695180740Sdes passphrase. This is particularly useful when call- 696180740Sdes ing ssh from a .xsession or related script. (Note 697180740Sdes that on some machines it may be necessary to redi- 698180740Sdes rect the input from /dev/null to make this work.) 699180740Sdes 700180740Sdes SSH_AUTH_SOCK Identifies the path of a UNIX-domain socket used to 701180740Sdes communicate with the agent. 702180740Sdes 703180740Sdes SSH_CONNECTION Identifies the client and server ends of the con- 704180740Sdes nection. The variable contains four space-separat- 705180740Sdes ed values: client IP address, client port number, 706180740Sdes server IP address, and server port number. 707180740Sdes 708180740Sdes SSH_ORIGINAL_COMMAND This variable contains the original command line if 709180740Sdes a forced command is executed. It can be used to 710180740Sdes extract the original arguments. 711180740Sdes 712180740Sdes SSH_TTY This is set to the name of the tty (path to the de- 713180740Sdes vice) associated with the current shell or command. 714180740Sdes If the current session has no tty, this variable is 715180740Sdes not set. 716180740Sdes 717180740Sdes TZ This variable is set to indicate the present time 718180740Sdes zone if it was set when the daemon was started 719180740Sdes (i.e. the daemon passes the value on to new connec- 720180740Sdes tions). 721180740Sdes 722180740Sdes USER Set to the name of the user logging in. 723180740Sdes 724180740Sdes Additionally, ssh reads ~/.ssh/environment, and adds lines of the format 725180740Sdes ``VARNAME=value'' to the environment if the file exists and users are al- 726180740Sdes lowed to change their environment. For more information, see the 727180740Sdes PermitUserEnvironment option in sshd_config(5). 728180740Sdes 729180740SdesFILES 730180740Sdes ~/.rhosts 731180740Sdes This file is used for host-based authentication (see above). On 732180740Sdes some machines this file may need to be world-readable if the us- 733180740Sdes er's home directory is on an NFS partition, because sshd(8) reads 734180740Sdes it as root. Additionally, this file must be owned by the user, 735180740Sdes and must not have write permissions for anyone else. The recom- 736180740Sdes mended permission for most machines is read/write for the user, 737180740Sdes and not accessible by others. 738180740Sdes 739180740Sdes ~/.shosts 740180740Sdes This file is used in exactly the same way as .rhosts, but allows 741180740Sdes host-based authentication without permitting login with 742180740Sdes rlogin/rsh. 743180740Sdes 744180746Sdes ~/.ssh/ 745180746Sdes This directory is the default location for all user-specific con- 746180746Sdes figuration and authentication information. There is no general 747180746Sdes requirement to keep the entire contents of this directory secret, 748180746Sdes but the recommended permissions are read/write/execute for the 749180746Sdes user, and not accessible by others. 750180746Sdes 751180740Sdes ~/.ssh/authorized_keys 752180740Sdes Lists the public keys (RSA/DSA) that can be used for logging in 753180740Sdes as this user. The format of this file is described in the 754180740Sdes sshd(8) manual page. This file is not highly sensitive, but the 755180740Sdes recommended permissions are read/write for the user, and not ac- 756180740Sdes cessible by others. 757180740Sdes 758180740Sdes ~/.ssh/config 759180740Sdes This is the per-user configuration file. The file format and 760180740Sdes configuration options are described in ssh_config(5). Because of 761180740Sdes the potential for abuse, this file must have strict permissions: 762180740Sdes read/write for the user, and not accessible by others. 763180740Sdes 764180740Sdes ~/.ssh/environment 765180740Sdes Contains additional definitions for environment variables; see 766180740Sdes ENVIRONMENT, above. 767180740Sdes 768180740Sdes ~/.ssh/identity 769180740Sdes ~/.ssh/id_dsa 770180740Sdes ~/.ssh/id_rsa 771180740Sdes Contains the private key for authentication. These files contain 772180740Sdes sensitive data and should be readable by the user but not acces- 773180740Sdes sible by others (read/write/execute). ssh will simply ignore a 774180740Sdes private key file if it is accessible by others. It is possible 775180740Sdes to specify a passphrase when generating the key which will be 776180740Sdes used to encrypt the sensitive part of this file using 3DES. 777180740Sdes 778180740Sdes ~/.ssh/identity.pub 779180740Sdes ~/.ssh/id_dsa.pub 780180740Sdes ~/.ssh/id_rsa.pub 781180740Sdes Contains the public key for authentication. These files are not 782180740Sdes sensitive and can (but need not) be readable by anyone. 783180740Sdes 784180740Sdes ~/.ssh/known_hosts 785180740Sdes Contains a list of host keys for all hosts the user has logged 786180740Sdes into that are not already in the systemwide list of known host 787180740Sdes keys. See sshd(8) for further details of the format of this 788180740Sdes file. 789180740Sdes 790180740Sdes ~/.ssh/rc 791180740Sdes Commands in this file are executed by ssh when the user logs in, 792180740Sdes just before the user's shell (or command) is started. See the 793180740Sdes sshd(8) manual page for more information. 794180740Sdes 795180740Sdes /etc/hosts.equiv 796180740Sdes This file is for host-based authentication (see above). It 797180740Sdes should only be writable by root. 798180740Sdes 799180740Sdes /etc/shosts.equiv 800180740Sdes This file is used in exactly the same way as hosts.equiv, but al- 801180740Sdes lows host-based authentication without permitting login with 802180740Sdes rlogin/rsh. 803180740Sdes 804180740Sdes /etc/ssh/ssh_config 805180740Sdes Systemwide configuration file. The file format and configuration 806180740Sdes options are described in ssh_config(5). 807180740Sdes 808180740Sdes /etc/ssh/ssh_host_key 809180740Sdes /etc/ssh/ssh_host_dsa_key 810180740Sdes /etc/ssh/ssh_host_rsa_key 811180740Sdes These three files contain the private parts of the host keys and 812180740Sdes are used for host-based authentication. If protocol version 1 is 813180740Sdes used, ssh must be setuid root, since the host key is readable on- 814180740Sdes ly by root. For protocol version 2, ssh uses ssh-keysign(8) to 815180740Sdes access the host keys, eliminating the requirement that ssh be se- 816180740Sdes tuid root when host-based authentication is used. By default ssh 817180740Sdes is not setuid root. 818180740Sdes 819180740Sdes /etc/ssh/ssh_known_hosts 820180740Sdes Systemwide list of known host keys. This file should be prepared 821180740Sdes by the system administrator to contain the public host keys of 822180740Sdes all machines in the organization. It should be world-readable. 823180740Sdes See sshd(8) for further details of the format of this file. 824180740Sdes 825180740Sdes /etc/ssh/sshrc 826180740Sdes Commands in this file are executed by ssh when the user logs in, 827180740Sdes just before the user's shell (or command) is started. See the 828180740Sdes sshd(8) manual page for more information. 829180740Sdes 830180740SdesSEE ALSO 831180740Sdes scp(1), sftp(1), ssh-add(1), ssh-agent(1), ssh-keygen(1), ssh-keyscan(1), 832180740Sdes tun(4), hosts.equiv(5), ssh_config(5), ssh-keysign(8), sshd(8) 833180740Sdes 834180740Sdes The Secure Shell (SSH) Protocol Assigned Numbers, RFC 4250, 2006. 835180740Sdes 836180740Sdes The Secure Shell (SSH) Protocol Architecture, RFC 4251, 2006. 837180740Sdes 838180740Sdes The Secure Shell (SSH) Authentication Protocol, RFC 4252, 2006. 839180740Sdes 840180740Sdes The Secure Shell (SSH) Transport Layer Protocol, RFC 4253, 2006. 841180740Sdes 842180740Sdes The Secure Shell (SSH) Connection Protocol, RFC 4254, 2006. 843180740Sdes 844180740Sdes Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints, RFC 845180740Sdes 4255, 2006. 846180740Sdes 847180740Sdes Generic Message Exchange Authentication for the Secure Shell Protocol 848180740Sdes (SSH), RFC 4256, 2006. 849180740Sdes 850180740Sdes The Secure Shell (SSH) Session Channel Break Extension, RFC 4335, 2006. 851180740Sdes 852180740Sdes The Secure Shell (SSH) Transport Layer Encryption Modes, RFC 4344, 2006. 853180740Sdes 854180740Sdes Improved Arcfour Modes for the Secure Shell (SSH) Transport Layer 855180740Sdes Protocol, RFC 4345, 2006. 856180740Sdes 857180740Sdes Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer 858180740Sdes Protocol, RFC 4419, 2006. 859180740Sdes 860180740Sdes The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006. 861180740Sdes 862180750Sdes A. Perrig and D. Song, Hash Visualization: a New Technique to improve 863180750Sdes Real-World Security, 1999, International Workshop on Cryptographic 864180750Sdes Techniques and E-Commerce (CrypTEC '99). 865180750Sdes 866180740SdesAUTHORS 867180740Sdes OpenSSH is a derivative of the original and free ssh 1.2.12 release by 868180740Sdes Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo 869180740Sdes de Raadt and Dug Song removed many bugs, re-added newer features and 870180740Sdes created OpenSSH. Markus Friedl contributed the support for SSH protocol 871180740Sdes versions 1.5 and 2.0. 872180740Sdes 873189006SdesOpenBSD 4.5 February 12, 2009 14 874