ssh.0 revision 214979
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] 8204861Sdes [-D [bind_address:]port] [-e escape_char] [-F configfile] [-I pkcs11] 9180740Sdes [-i identity_file] [-L [bind_address:]port:host:hostport] 10180740Sdes [-l login_name] [-m mac_spec] [-O ctl_cmd] [-o option] [-p port] 11204861Sdes [-R [bind_address:]port:host:hostport] [-S ctl_path] [-W host:port] 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 17214979Sdes and rsh, and provide secure encrypted communications between two 18214979Sdes untrusted hosts over an insecure network. X11 connections and arbitrary 19214979Sdes TCP 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 23214979Sdes one of several methods depending on the protocol version used (see 24214979Sdes below). 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 45204861Sdes 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 55214979Sdes the connection. Only useful on systems with more than one 56214979Sdes address. 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 72214979Sdes (triple-des) is an encrypt-decrypt-encrypt triple with three 73214979Sdes different keys. It is believed to be secure. blowfish is a fast 74180740Sdes block cipher; it appears very secure and is much faster than 75214979Sdes 3des. des is only supported in the ssh client for 76214979Sdes interoperability with legacy protocol 1 implementations that do 77214979Sdes not support the 3des cipher. Its use is strongly discouraged due 78214979Sdes to cryptographic weaknesses. The default is ``3des''. 79180740Sdes 80180740Sdes For protocol version 2, cipher_spec is a comma-separated list of 81197670Sdes ciphers listed in order of preference. See the Ciphers keyword 82214979Sdes in ssh_config(5) for more information. 83180740Sdes 84180740Sdes -D [bind_address:]port 85180740Sdes Specifies a local ``dynamic'' application-level port forwarding. 86180740Sdes This works by allocating a socket to listen to port on the local 87180740Sdes side, optionally bound to the specified bind_address. Whenever a 88180740Sdes connection is made to this port, the connection is forwarded over 89180740Sdes the secure channel, and the application protocol is then used to 90180740Sdes determine where to connect to from the remote machine. Currently 91180740Sdes the SOCKS4 and SOCKS5 protocols are supported, and ssh will act 92214979Sdes as a SOCKS server. Only root can forward privileged ports. 93214979Sdes Dynamic port forwardings can also be specified in the 94214979Sdes configuration file. 95180740Sdes 96214979Sdes IPv6 addresses can be specified by enclosing the address in 97214979Sdes square brackets. Only the superuser can forward privileged 98214979Sdes ports. By default, the local port is bound in accordance with 99214979Sdes the GatewayPorts setting. However, an explicit bind_address may 100214979Sdes be used to bind the connection to a specific address. The 101180740Sdes bind_address of ``localhost'' indicates that the listening port 102214979Sdes be bound for local use only, while an empty address or `*' 103214979Sdes indicates that the port should be available from all interfaces. 104180740Sdes 105180740Sdes -e escape_char 106180740Sdes Sets the escape character for sessions with a pty (default: `~'). 107180740Sdes The escape character is only recognized at the beginning of a 108180740Sdes line. The escape character followed by a dot (`.') closes the 109180740Sdes connection; followed by control-Z suspends the connection; and 110180740Sdes followed by itself sends the escape character once. Setting the 111180740Sdes character to ``none'' disables any escapes and makes the session 112180740Sdes fully transparent. 113180740Sdes 114180740Sdes -F configfile 115214979Sdes Specifies an alternative per-user configuration file. If a 116214979Sdes configuration file is given on the command line, the system-wide 117180740Sdes configuration file (/etc/ssh/ssh_config) will be ignored. The 118180740Sdes default for the per-user configuration file is ~/.ssh/config. 119180740Sdes 120180740Sdes -f Requests ssh to go to background just before command execution. 121214979Sdes This is useful if ssh is going to ask for passwords or 122214979Sdes passphrases, but the user wants it in the background. This 123214979Sdes implies -n. The recommended way to start X11 programs at a 124214979Sdes remote site is with something like ssh -f host xterm. 125180740Sdes 126180750Sdes If the ExitOnForwardFailure configuration option is set to 127180750Sdes ``yes'', then a client started with -f will wait for all remote 128214979Sdes port forwards to be successfully established before placing 129214979Sdes itself in the background. 130180750Sdes 131180740Sdes -g Allows remote hosts to connect to local forwarded ports. 132180740Sdes 133204861Sdes -I pkcs11 134204861Sdes Specify the PKCS#11 shared library ssh should use to communicate 135204861Sdes with a PKCS#11 token providing the user's private RSA key. 136180740Sdes 137180740Sdes -i identity_file 138180740Sdes Selects a file from which the identity (private key) for RSA or 139180740Sdes DSA authentication is read. The default is ~/.ssh/identity for 140214979Sdes protocol version 1, and ~/.ssh/id_rsa and ~/.ssh/id_dsa for 141214979Sdes protocol version 2. Identity files may also be specified on a 142214979Sdes per-host basis in the configuration file. It is possible to have 143214979Sdes multiple -i options (and multiple identities specified in 144214979Sdes configuration files). ssh will also try to load certificate 145214979Sdes information from the filename obtained by appending -cert.pub to 146214979Sdes identity filenames. 147180740Sdes 148180744Sdes -K Enables GSSAPI-based authentication and forwarding (delegation) 149180744Sdes of GSSAPI credentials to the server. 150180744Sdes 151180740Sdes -k Disables forwarding (delegation) of GSSAPI credentials to the 152180740Sdes server. 153180740Sdes 154180740Sdes -L [bind_address:]port:host:hostport 155180740Sdes Specifies that the given port on the local (client) host is to be 156180740Sdes forwarded to the given host and port on the remote side. This 157180740Sdes works by allocating a socket to listen to port on the local side, 158214979Sdes optionally bound to the specified bind_address. Whenever a 159214979Sdes connection is made to this port, the connection is forwarded over 160180740Sdes the secure channel, and a connection is made to host port 161180740Sdes hostport from the remote machine. Port forwardings can also be 162214979Sdes specified in the configuration file. IPv6 addresses can be 163214979Sdes specified by enclosing the address in square brackets. Only the 164180740Sdes superuser can forward privileged ports. By default, the local 165214979Sdes port is bound in accordance with the GatewayPorts setting. 166214979Sdes However, an explicit bind_address may be used to bind the 167214979Sdes connection to a specific address. The bind_address of 168214979Sdes ``localhost'' indicates that the listening port be bound for 169214979Sdes local use only, while an empty address or `*' indicates that the 170214979Sdes port should be available from all interfaces. 171180740Sdes 172180740Sdes -l login_name 173180740Sdes Specifies the user to log in as on the remote machine. This also 174180740Sdes may be specified on a per-host basis in the configuration file. 175180740Sdes 176214979Sdes -M Places the ssh client into ``master'' mode for connection 177214979Sdes sharing. Multiple -M options places ssh into ``master'' mode 178214979Sdes with confirmation required before slave connections are accepted. 179214979Sdes Refer to the description of ControlMaster in ssh_config(5) for 180214979Sdes details. 181180740Sdes 182180740Sdes -m mac_spec 183180740Sdes Additionally, for protocol version 2 a comma-separated list of 184180740Sdes MAC (message authentication code) algorithms can be specified in 185180740Sdes order of preference. See the MACs keyword for more information. 186180740Sdes 187214979Sdes -N Do not execute a remote command. This is useful for just 188214979Sdes forwarding ports (protocol version 2 only). 189180740Sdes 190180740Sdes -n Redirects stdin from /dev/null (actually, prevents reading from 191180740Sdes stdin). This must be used when ssh is run in the background. A 192214979Sdes common trick is to use this to run X11 programs on a remote 193214979Sdes machine. For example, ssh -n shadows.cs.hut.fi emacs & will 194214979Sdes start an emacs on shadows.cs.hut.fi, and the X11 connection will 195214979Sdes be automatically forwarded over an encrypted channel. The ssh 196214979Sdes program will be put in the background. (This does not work if 197214979Sdes ssh needs to ask for a password or passphrase; see also the -f 198214979Sdes option.) 199180740Sdes 200180740Sdes -O ctl_cmd 201180740Sdes Control an active connection multiplexing master process. When 202180740Sdes the -O option is specified, the ctl_cmd argument is interpreted 203180740Sdes and passed to the master process. Valid commands are: ``check'' 204214979Sdes (check that the master process is running), ``forward'' (request 205214979Sdes forwardings without command execution) and ``exit'' (request the 206214979Sdes master to exit). 207180740Sdes 208180740Sdes -o option 209214979Sdes Can be used to give options in the format used in the 210214979Sdes configuration file. This is useful for specifying options for 211214979Sdes which there is no separate command-line flag. For full details 212214979Sdes of the options listed below, and their possible values, see 213214979Sdes ssh_config(5). 214180740Sdes 215180740Sdes AddressFamily 216180740Sdes BatchMode 217180740Sdes BindAddress 218180740Sdes ChallengeResponseAuthentication 219180740Sdes CheckHostIP 220180740Sdes Cipher 221180740Sdes Ciphers 222180740Sdes ClearAllForwardings 223180740Sdes Compression 224180740Sdes CompressionLevel 225180740Sdes ConnectionAttempts 226180740Sdes ConnectTimeout 227180740Sdes ControlMaster 228180740Sdes ControlPath 229180740Sdes DynamicForward 230180740Sdes EscapeChar 231180740Sdes ExitOnForwardFailure 232180740Sdes ForwardAgent 233180740Sdes ForwardX11 234180740Sdes ForwardX11Trusted 235180740Sdes GatewayPorts 236180740Sdes GlobalKnownHostsFile 237180740Sdes GSSAPIAuthentication 238180740Sdes GSSAPIDelegateCredentials 239180740Sdes HashKnownHosts 240180740Sdes Host 241180740Sdes HostbasedAuthentication 242180740Sdes HostKeyAlgorithms 243180740Sdes HostKeyAlias 244180740Sdes HostName 245180740Sdes IdentityFile 246180740Sdes IdentitiesOnly 247180740Sdes KbdInteractiveDevices 248180740Sdes LocalCommand 249180740Sdes LocalForward 250180740Sdes LogLevel 251180740Sdes MACs 252180740Sdes NoHostAuthenticationForLocalhost 253180740Sdes NumberOfPasswordPrompts 254180740Sdes PasswordAuthentication 255180740Sdes PermitLocalCommand 256204861Sdes PKCS11Provider 257180740Sdes Port 258180740Sdes PreferredAuthentications 259180740Sdes Protocol 260180740Sdes ProxyCommand 261180740Sdes PubkeyAuthentication 262180740Sdes RekeyLimit 263180740Sdes RemoteForward 264180740Sdes RhostsRSAAuthentication 265180740Sdes RSAAuthentication 266180740Sdes SendEnv 267180740Sdes ServerAliveInterval 268180740Sdes ServerAliveCountMax 269180740Sdes StrictHostKeyChecking 270180740Sdes TCPKeepAlive 271180740Sdes Tunnel 272180740Sdes TunnelDevice 273180740Sdes UsePrivilegedPort 274180740Sdes User 275180740Sdes UserKnownHostsFile 276180740Sdes VerifyHostKeyDNS 277180750Sdes VisualHostKey 278180740Sdes XAuthLocation 279180740Sdes 280180740Sdes -p port 281180740Sdes Port to connect to on the remote host. This can be specified on 282180740Sdes a per-host basis in the configuration file. 283180740Sdes 284180746Sdes -q Quiet mode. Causes most warning and diagnostic messages to be 285180740Sdes suppressed. 286180740Sdes 287180740Sdes -R [bind_address:]port:host:hostport 288180740Sdes Specifies that the given port on the remote (server) host is to 289180740Sdes be forwarded to the given host and port on the local side. This 290180740Sdes works by allocating a socket to listen to port on the remote 291214979Sdes side, and whenever a connection is made to this port, the 292214979Sdes connection is forwarded over the secure channel, and a connection 293214979Sdes is made to host port hostport from the local machine. 294180740Sdes 295180740Sdes Port forwardings can also be specified in the configuration file. 296180740Sdes Privileged ports can be forwarded only when logging in as root on 297180740Sdes the remote machine. IPv6 addresses can be specified by enclosing 298214979Sdes the address in square braces. 299180740Sdes 300180740Sdes By default, the listening socket on the server will be bound to 301214979Sdes the loopback interface only. This may be overridden by 302214979Sdes specifying a bind_address. An empty bind_address, or the address 303214979Sdes `*', indicates that the remote socket should listen on all 304214979Sdes interfaces. Specifying a remote bind_address will only succeed 305214979Sdes if the server's GatewayPorts option is enabled (see 306214979Sdes sshd_config(5)). 307180740Sdes 308189006Sdes If the port argument is `0', the listen port will be dynamically 309189006Sdes allocated on the server and reported to the client at run time. 310214979Sdes When used together with -O forward the allocated port will be 311214979Sdes printed to the standard output. 312189006Sdes 313180740Sdes -S ctl_path 314214979Sdes Specifies the location of a control socket for connection 315214979Sdes sharing, or the string ``none'' to disable connection sharing. 316214979Sdes Refer to the description of ControlPath and ControlMaster in 317214979Sdes ssh_config(5) for details. 318180740Sdes 319180740Sdes -s May be used to request invocation of a subsystem on the remote 320214979Sdes system. Subsystems are a feature of the SSH2 protocol which 321214979Sdes facilitate the use of SSH as a secure transport for other 322214979Sdes applications (eg. sftp(1)). The subsystem is specified as the 323214979Sdes remote command. 324180740Sdes 325180740Sdes -T Disable pseudo-tty allocation. 326180740Sdes 327214979Sdes -t Force pseudo-tty allocation. This can be used to execute 328214979Sdes arbitrary screen-based programs on a remote machine, which can be 329180740Sdes very useful, e.g. when implementing menu services. Multiple -t 330180740Sdes options force tty allocation, even if ssh has no local tty. 331180740Sdes 332180740Sdes -V Display the version number and exit. 333180740Sdes 334180740Sdes -v Verbose mode. Causes ssh to print debugging messages about its 335214979Sdes progress. This is helpful in debugging connection, 336214979Sdes authentication, and configuration problems. Multiple -v options 337214979Sdes increase the verbosity. The maximum is 3. 338180740Sdes 339204861Sdes -W host:port 340214979Sdes Requests that standard input and output on the client be 341214979Sdes forwarded to host on port over the secure channel. Implies -N, 342214979Sdes -T, ExitOnForwardFailure and ClearAllForwardings and works with 343214979Sdes Protocol version 2 only. 344204861Sdes 345180740Sdes -w local_tun[:remote_tun] 346214979Sdes Requests tunnel device forwarding with the specified tun(4) 347214979Sdes devices between the client (local_tun) and the server 348214979Sdes (remote_tun). 349180740Sdes 350180740Sdes The devices may be specified by numerical ID or the keyword 351180740Sdes ``any'', which uses the next available tunnel device. If 352180740Sdes remote_tun is not specified, it defaults to ``any''. See also 353180740Sdes the Tunnel and TunnelDevice directives in ssh_config(5). If the 354180740Sdes Tunnel directive is unset, it is set to the default tunnel mode, 355180740Sdes which is ``point-to-point''. 356180740Sdes 357180740Sdes -X Enables X11 forwarding. This can also be specified on a per-host 358180740Sdes basis in a configuration file. 359180740Sdes 360180740Sdes X11 forwarding should be enabled with caution. Users with the 361180740Sdes ability to bypass file permissions on the remote host (for the 362180740Sdes user's X authorization database) can access the local X11 display 363180740Sdes through the forwarded connection. An attacker may then be able 364180740Sdes to perform activities such as keystroke monitoring. 365180740Sdes 366214979Sdes For this reason, X11 forwarding is subjected to X11 SECURITY 367214979Sdes extension restrictions by default. Please refer to the ssh -Y 368214979Sdes option and the ForwardX11Trusted directive in ssh_config(5) for 369180740Sdes more information. 370180740Sdes 371180740Sdes -x Disables X11 forwarding. 372180740Sdes 373180740Sdes -Y Enables trusted X11 forwarding. Trusted X11 forwardings are not 374180740Sdes subjected to the X11 SECURITY extension controls. 375180740Sdes 376214979Sdes -y Send log information using the syslog(3) system module. By 377214979Sdes default this information is sent to stderr. 378189006Sdes 379214979Sdes ssh may additionally obtain configuration data from a per-user 380214979Sdes configuration file and a system-wide configuration file. The file format 381214979Sdes and configuration options are described in ssh_config(5). 382180740Sdes 383180740Sdes ssh exits with the exit status of the remote command or with 255 if an 384180740Sdes error occurred. 385180740Sdes 386180740SdesAUTHENTICATION 387204861Sdes The OpenSSH SSH client supports SSH protocols 1 and 2. The default is to 388204861Sdes use protocol 2 only, though this can be changed via the Protocol option 389204861Sdes in ssh_config(5) or the -1 and -2 options (see above). Both protocols 390204861Sdes support similar authentication methods, but protocol 2 is the default 391204861Sdes since it provides additional mechanisms for confidentiality (the traffic 392214979Sdes is encrypted using AES, 3DES, Blowfish, CAST128, or Arcfour) and 393214979Sdes integrity (hmac-md5, hmac-sha1, umac-64, hmac-ripemd160). Protocol 1 394214979Sdes lacks a strong mechanism for ensuring the integrity of the connection. 395180740Sdes 396214979Sdes The methods available for authentication are: GSSAPI-based 397214979Sdes authentication, host-based authentication, public key authentication, 398214979Sdes challenge-response authentication, and password authentication. 399214979Sdes Authentication methods are tried in the order specified above, though 400214979Sdes protocol 2 has a configuration option to change the default order: 401214979Sdes PreferredAuthentications. 402180740Sdes 403180740Sdes Host-based authentication works as follows: If the machine the user logs 404180740Sdes in from is listed in /etc/hosts.equiv or /etc/shosts.equiv on the remote 405180740Sdes machine, and the user names are the same on both sides, or if the files 406180740Sdes ~/.rhosts or ~/.shosts exist in the user's home directory on the remote 407180740Sdes machine and contain a line containing the name of the client machine and 408180740Sdes the name of the user on that machine, the user is considered for login. 409180740Sdes Additionally, the server must be able to verify the client's host key 410180740Sdes (see the description of /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts, 411214979Sdes below) for login to be permitted. This authentication method closes 412214979Sdes security holes due to IP spoofing, DNS spoofing, and routing spoofing. 413180740Sdes [Note to the administrator: /etc/hosts.equiv, ~/.rhosts, and the 414180740Sdes rlogin/rsh protocol in general, are inherently insecure and should be 415180740Sdes disabled if security is desired.] 416180740Sdes 417214979Sdes Public key authentication works as follows: The scheme is based on 418214979Sdes public-key cryptography, using cryptosystems where encryption and 419214979Sdes decryption are done using separate keys, and it is unfeasible to derive 420214979Sdes the decryption key from the encryption key. The idea is that each user 421214979Sdes creates a public/private key pair for authentication purposes. The 422214979Sdes server knows the public key, and only the user knows the private key. 423214979Sdes ssh implements public key authentication protocol automatically, using 424214979Sdes either the RSA or DSA algorithms. Protocol 1 is restricted to using only 425214979Sdes RSA keys, but protocol 2 may use either. The HISTORY section of ssl(8) 426214979Sdes contains a brief discussion of the two algorithms. 427180740Sdes 428180740Sdes The file ~/.ssh/authorized_keys lists the public keys that are permitted 429180740Sdes for logging in. When the user logs in, the ssh program tells the server 430180740Sdes which key pair it would like to use for authentication. The client 431180740Sdes proves that it has access to the private key and the server checks that 432180740Sdes the corresponding public key is authorized to accept the account. 433180740Sdes 434180740Sdes The user creates his/her key pair by running ssh-keygen(1). This stores 435180740Sdes the private key in ~/.ssh/identity (protocol 1), ~/.ssh/id_dsa (protocol 436180740Sdes 2 DSA), or ~/.ssh/id_rsa (protocol 2 RSA) and stores the public key in 437180740Sdes ~/.ssh/identity.pub (protocol 1), ~/.ssh/id_dsa.pub (protocol 2 DSA), or 438214979Sdes ~/.ssh/id_rsa.pub (protocol 2 RSA) in the user's home directory. The 439214979Sdes user should then copy the public key to ~/.ssh/authorized_keys in his/her 440214979Sdes home directory on the remote machine. The authorized_keys file 441214979Sdes corresponds to the conventional ~/.rhosts file, and has one key per line, 442214979Sdes though the lines can be very long. After this, the user can log in 443214979Sdes without giving the password. 444180740Sdes 445214979Sdes A variation on public key authentication is available in the form of 446214979Sdes certificate authentication: instead of a set of public/private keys, 447214979Sdes signed certificates are used. This has the advantage that a single 448214979Sdes trusted certification authority can be used in place of many 449214979Sdes public/private keys. See the CERTIFICATES section of ssh-keygen(1) for 450214979Sdes more information. 451180740Sdes 452204861Sdes The most convenient way to use public key or certificate authentication 453214979Sdes may be with an authentication agent. See ssh-agent(1) for more 454214979Sdes information. 455204861Sdes 456180740Sdes Challenge-response authentication works as follows: The server sends an 457214979Sdes arbitrary "challenge" text, and prompts for a response. Protocol 2 458214979Sdes allows multiple challenges and responses; protocol 1 is restricted to 459214979Sdes just one challenge/response. Examples of challenge-response 460214979Sdes authentication include BSD Authentication (see login.conf(5)) and PAM 461214979Sdes (some non-OpenBSD systems). 462180740Sdes 463180740Sdes Finally, if other authentication methods fail, ssh prompts the user for a 464180740Sdes password. The password is sent to the remote host for checking; however, 465180740Sdes since all communications are encrypted, the password cannot be seen by 466180740Sdes someone listening on the network. 467180740Sdes 468214979Sdes ssh automatically maintains and checks a database containing 469214979Sdes identification for all hosts it has ever been used with. Host keys are 470214979Sdes stored in ~/.ssh/known_hosts in the user's home directory. Additionally, 471214979Sdes the file /etc/ssh/ssh_known_hosts is automatically checked for known 472214979Sdes hosts. Any new hosts are automatically added to the user's file. If a 473214979Sdes host's identification ever changes, ssh warns about this and disables 474214979Sdes password authentication to prevent server spoofing or man-in-the-middle 475214979Sdes attacks, which could otherwise be used to circumvent the encryption. The 476180740Sdes StrictHostKeyChecking option can be used to control logins to machines 477180740Sdes whose host key is not known or has changed. 478180740Sdes 479214979Sdes When the user's identity has been accepted by the server, the server 480214979Sdes either executes the given command, or logs into the machine and gives the 481180740Sdes user a normal shell on the remote machine. All communication with the 482180740Sdes remote command or shell will be automatically encrypted. 483180740Sdes 484180740Sdes If a pseudo-terminal has been allocated (normal login session), the user 485180740Sdes may use the escape characters noted below. 486180740Sdes 487180740Sdes If no pseudo-tty has been allocated, the session is transparent and can 488180740Sdes be used to reliably transfer binary data. On most systems, setting the 489180740Sdes escape character to ``none'' will also make the session transparent even 490180740Sdes if a tty is used. 491180740Sdes 492180740Sdes The session terminates when the command or shell on the remote machine 493180740Sdes exits and all X11 and TCP connections have been closed. 494180740Sdes 495180740SdesESCAPE CHARACTERS 496214979Sdes When a pseudo-terminal has been requested, ssh supports a number of 497214979Sdes functions through the use of an escape character. 498180740Sdes 499180740Sdes A single tilde character can be sent as ~~ or by following the tilde by a 500180740Sdes character other than those described below. The escape character must 501214979Sdes always follow a newline to be interpreted as special. The escape 502214979Sdes character can be changed in configuration files using the EscapeChar 503214979Sdes configuration directive or on the command line by the -e option. 504180740Sdes 505180740Sdes The supported escapes (assuming the default `~') are: 506180740Sdes 507180740Sdes ~. Disconnect. 508180740Sdes 509180740Sdes ~^Z Background ssh. 510180740Sdes 511180740Sdes ~# List forwarded connections. 512180740Sdes 513180740Sdes ~& Background ssh at logout when waiting for forwarded connection / 514180740Sdes X11 sessions to terminate. 515180740Sdes 516180740Sdes ~? Display a list of escape characters. 517180740Sdes 518180740Sdes ~B Send a BREAK to the remote system (only useful for SSH protocol 519180740Sdes version 2 and if the peer supports it). 520180740Sdes 521180740Sdes ~C Open command line. Currently this allows the addition of port 522189006Sdes forwardings using the -L, -R and -D options (see above). It also 523189006Sdes allows the cancellation of existing remote port-forwardings using 524180740Sdes -KR[bind_address:]port. !command allows the user to execute a 525180740Sdes local command if the PermitLocalCommand option is enabled in 526180740Sdes ssh_config(5). Basic help is available, using the -h option. 527180740Sdes 528180740Sdes ~R Request rekeying of the connection (only useful for SSH protocol 529180740Sdes version 2 and if the peer supports it). 530180740Sdes 531180740SdesTCP FORWARDING 532180740Sdes Forwarding of arbitrary TCP connections over the secure channel can be 533180740Sdes specified either on the command line or in a configuration file. One 534180740Sdes possible application of TCP forwarding is a secure connection to a mail 535180740Sdes server; another is going through firewalls. 536180740Sdes 537180740Sdes In the example below, we look at encrypting communication between an IRC 538180740Sdes client and server, even though the IRC server does not directly support 539180740Sdes encrypted communications. This works as follows: the user connects to 540214979Sdes the remote host using ssh, specifying a port to be used to forward 541214979Sdes connections to the remote server. After that it is possible to start the 542180740Sdes service which is to be encrypted on the client machine, connecting to the 543180740Sdes same local port, and ssh will encrypt and forward the connection. 544180740Sdes 545180740Sdes The following example tunnels an IRC session from client machine 546180740Sdes ``127.0.0.1'' (localhost) to remote server ``server.example.com'': 547180740Sdes 548180740Sdes $ ssh -f -L 1234:localhost:6667 server.example.com sleep 10 549180740Sdes $ irc -c '#users' -p 1234 pinky 127.0.0.1 550180740Sdes 551180740Sdes This tunnels a connection to IRC server ``server.example.com'', joining 552214979Sdes channel ``#users'', nickname ``pinky'', using port 1234. It doesn't 553214979Sdes matter which port is used, as long as it's greater than 1023 (remember, 554214979Sdes only root can open sockets on privileged ports) and doesn't conflict with 555214979Sdes any ports already in use. The connection is forwarded to port 6667 on 556214979Sdes the remote server, since that's the standard port for IRC services. 557180740Sdes 558180740Sdes The -f option backgrounds ssh and the remote command ``sleep 10'' is 559180740Sdes specified to allow an amount of time (10 seconds, in the example) to 560180740Sdes start the service which is to be tunnelled. If no connections are made 561180740Sdes within the time specified, ssh will exit. 562180740Sdes 563180740SdesX11 FORWARDING 564180740Sdes If the ForwardX11 variable is set to ``yes'' (or see the description of 565180740Sdes the -X, -x, and -Y options above) and the user is using X11 (the DISPLAY 566214979Sdes environment variable is set), the connection to the X11 display is 567214979Sdes automatically forwarded to the remote side in such a way that any X11 568214979Sdes programs started from the shell (or command) will go through the 569214979Sdes encrypted channel, and the connection to the real X server will be made 570214979Sdes from the local machine. The user should not manually set DISPLAY. 571214979Sdes Forwarding of X11 connections can be configured on the command line or in 572214979Sdes configuration files. 573180740Sdes 574180740Sdes The DISPLAY value set by ssh will point to the server machine, but with a 575180740Sdes display number greater than zero. This is normal, and happens because 576180740Sdes ssh creates a ``proxy'' X server on the server machine for forwarding the 577180740Sdes connections over the encrypted channel. 578180740Sdes 579180740Sdes ssh will also automatically set up Xauthority data on the server machine. 580180740Sdes For this purpose, it will generate a random authorization cookie, store 581180740Sdes it in Xauthority on the server, and verify that any forwarded connections 582180740Sdes carry this cookie and replace it by the real cookie when the connection 583180740Sdes is opened. The real authentication cookie is never sent to the server 584180740Sdes machine (and no cookies are sent in the plain). 585180740Sdes 586180740Sdes If the ForwardAgent variable is set to ``yes'' (or see the description of 587180740Sdes the -A and -a options above) and the user is using an authentication 588214979Sdes agent, the connection to the agent is automatically forwarded to the 589214979Sdes remote side. 590180740Sdes 591180740SdesVERIFYING HOST KEYS 592180740Sdes When connecting to a server for the first time, a fingerprint of the 593180740Sdes server's public key is presented to the user (unless the option 594180740Sdes StrictHostKeyChecking has been disabled). Fingerprints can be determined 595180740Sdes using ssh-keygen(1): 596180740Sdes 597180740Sdes $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key 598180740Sdes 599180750Sdes If the fingerprint is already known, it can be matched and the key can be 600180750Sdes accepted or rejected. Because of the difficulty of comparing host keys 601180750Sdes just by looking at hex strings, there is also support to compare host 602180750Sdes keys visually, using random art. By setting the VisualHostKey option to 603180750Sdes ``yes'', a small ASCII graphic gets displayed on every login to a server, 604180750Sdes no matter if the session itself is interactive or not. By learning the 605180750Sdes pattern a known server produces, a user can easily find out that the host 606214979Sdes key has changed when a completely different pattern is displayed. 607214979Sdes Because these patterns are not unambiguous however, a pattern that looks 608180750Sdes similar to the pattern remembered only gives a good probability that the 609180750Sdes host key is the same, not guaranteed proof. 610180740Sdes 611180750Sdes To get a listing of the fingerprints along with their random art for all 612180750Sdes known hosts, the following command line can be used: 613180750Sdes 614180750Sdes $ ssh-keygen -lv -f ~/.ssh/known_hosts 615180750Sdes 616180750Sdes If the fingerprint is unknown, an alternative method of verification is 617180750Sdes available: SSH fingerprints verified by DNS. An additional resource 618180750Sdes record (RR), SSHFP, is added to a zonefile and the connecting client is 619180750Sdes able to match the fingerprint with that of the key presented. 620180750Sdes 621180740Sdes In this example, we are connecting a client to a server, 622180740Sdes ``host.example.com''. The SSHFP resource records should first be added 623180740Sdes to the zonefile for host.example.com: 624180740Sdes 625180740Sdes $ ssh-keygen -r host.example.com. 626180740Sdes 627180740Sdes The output lines will have to be added to the zonefile. To check that 628180740Sdes the zone is answering fingerprint queries: 629180740Sdes 630180740Sdes $ dig -t SSHFP host.example.com 631180740Sdes 632180740Sdes Finally the client connects: 633180740Sdes 634180740Sdes $ ssh -o "VerifyHostKeyDNS ask" host.example.com 635180740Sdes [...] 636180740Sdes Matching host key fingerprint found in DNS. 637180740Sdes Are you sure you want to continue connecting (yes/no)? 638180740Sdes 639180740Sdes See the VerifyHostKeyDNS option in ssh_config(5) for more information. 640180740Sdes 641180740SdesSSH-BASED VIRTUAL PRIVATE NETWORKS 642180740Sdes ssh contains support for Virtual Private Network (VPN) tunnelling using 643214979Sdes the tun(4) network pseudo-device, allowing two networks to be joined 644214979Sdes securely. The sshd_config(5) configuration option PermitTunnel controls 645214979Sdes whether the server supports this, and at what level (layer 2 or 3 646214979Sdes traffic). 647180740Sdes 648214979Sdes The following example would connect client network 10.0.50.0/24 with 649214979Sdes remote network 10.0.99.0/24 using a point-to-point connection from 650214979Sdes 10.1.1.1 to 10.1.1.2, provided that the SSH server running on the gateway 651214979Sdes to the remote network, at 192.168.1.15, allows it. 652180740Sdes 653180740Sdes On the client: 654180740Sdes 655180740Sdes # ssh -f -w 0:1 192.168.1.15 true 656180740Sdes # ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252 657180740Sdes # route add 10.0.99.0/24 10.1.1.2 658180740Sdes 659180740Sdes On the server: 660180740Sdes 661180740Sdes # ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252 662180740Sdes # route add 10.0.50.0/24 10.1.1.1 663180740Sdes 664180740Sdes Client access may be more finely tuned via the /root/.ssh/authorized_keys 665180740Sdes file (see below) and the PermitRootLogin server option. The following 666180740Sdes entry would permit connections on tun(4) device 1 from user ``jane'' and 667180740Sdes on tun device 2 from user ``john'', if PermitRootLogin is set to 668180740Sdes ``forced-commands-only'': 669180740Sdes 670180740Sdes tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane 671180740Sdes tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john 672180740Sdes 673180740Sdes Since an SSH-based setup entails a fair amount of overhead, it may be 674214979Sdes more suited to temporary setups, such as for wireless VPNs. More 675214979Sdes permanent VPNs are better provided by tools such as ipsecctl(8) and 676180740Sdes isakmpd(8). 677180740Sdes 678180740SdesENVIRONMENT 679180740Sdes ssh will normally set the following environment variables: 680180740Sdes 681180740Sdes DISPLAY The DISPLAY variable indicates the location of the 682180740Sdes X11 server. It is automatically set by ssh to 683180740Sdes point to a value of the form ``hostname:n'', where 684180740Sdes ``hostname'' indicates the host where the shell 685180740Sdes runs, and `n' is an integer >= 1. ssh uses this 686180740Sdes special value to forward X11 connections over the 687180740Sdes secure channel. The user should normally not set 688180740Sdes DISPLAY explicitly, as that will render the X11 689180740Sdes connection insecure (and will require the user to 690180740Sdes manually copy any required authorization cookies). 691180740Sdes 692180740Sdes HOME Set to the path of the user's home directory. 693180740Sdes 694214979Sdes LOGNAME Synonym for USER; set for compatibility with 695214979Sdes systems that use this variable. 696180740Sdes 697180740Sdes MAIL Set to the path of the user's mailbox. 698180740Sdes 699214979Sdes PATH Set to the default PATH, as specified when 700214979Sdes compiling ssh. 701180740Sdes 702180740Sdes SSH_ASKPASS If ssh needs a passphrase, it will read the 703180740Sdes passphrase from the current terminal if it was run 704180740Sdes from a terminal. If ssh does not have a terminal 705180740Sdes associated with it but DISPLAY and SSH_ASKPASS are 706180740Sdes set, it will execute the program specified by 707180740Sdes SSH_ASKPASS and open an X11 window to read the 708214979Sdes passphrase. This is particularly useful when 709214979Sdes calling ssh from a .xsession or related script. 710214979Sdes (Note that on some machines it may be necessary to 711214979Sdes redirect the input from /dev/null to make this 712214979Sdes work.) 713180740Sdes 714180740Sdes SSH_AUTH_SOCK Identifies the path of a UNIX-domain socket used to 715180740Sdes communicate with the agent. 716180740Sdes 717214979Sdes SSH_CONNECTION Identifies the client and server ends of the 718214979Sdes connection. The variable contains four space- 719214979Sdes separated values: client IP address, client port 720214979Sdes number, server IP address, and server port number. 721180740Sdes 722180740Sdes SSH_ORIGINAL_COMMAND This variable contains the original command line if 723180740Sdes a forced command is executed. It can be used to 724180740Sdes extract the original arguments. 725180740Sdes 726214979Sdes SSH_TTY This is set to the name of the tty (path to the 727214979Sdes device) associated with the current shell or 728214979Sdes command. If the current session has no tty, this 729214979Sdes variable is not set. 730180740Sdes 731180740Sdes TZ This variable is set to indicate the present time 732180740Sdes zone if it was set when the daemon was started 733214979Sdes (i.e. the daemon passes the value on to new 734214979Sdes connections). 735180740Sdes 736180740Sdes USER Set to the name of the user logging in. 737180740Sdes 738180740Sdes Additionally, ssh reads ~/.ssh/environment, and adds lines of the format 739214979Sdes ``VARNAME=value'' to the environment if the file exists and users are 740214979Sdes allowed to change their environment. For more information, see the 741180740Sdes PermitUserEnvironment option in sshd_config(5). 742180740Sdes 743180740SdesFILES 744180740Sdes ~/.rhosts 745180740Sdes This file is used for host-based authentication (see above). On 746214979Sdes some machines this file may need to be world-readable if the 747214979Sdes user's home directory is on an NFS partition, because sshd(8) 748214979Sdes reads it as root. Additionally, this file must be owned by the 749214979Sdes user, and must not have write permissions for anyone else. The 750214979Sdes recommended permission for most machines is read/write for the 751214979Sdes user, and not accessible by others. 752180740Sdes 753180740Sdes ~/.shosts 754180740Sdes This file is used in exactly the same way as .rhosts, but allows 755180740Sdes host-based authentication without permitting login with 756180740Sdes rlogin/rsh. 757180740Sdes 758180746Sdes ~/.ssh/ 759214979Sdes This directory is the default location for all user-specific 760214979Sdes configuration and authentication information. There is no 761214979Sdes general requirement to keep the entire contents of this directory 762214979Sdes secret, but the recommended permissions are read/write/execute 763214979Sdes for the user, and not accessible by others. 764180746Sdes 765180740Sdes ~/.ssh/authorized_keys 766180740Sdes Lists the public keys (RSA/DSA) that can be used for logging in 767180740Sdes as this user. The format of this file is described in the 768180740Sdes sshd(8) manual page. This file is not highly sensitive, but the 769214979Sdes recommended permissions are read/write for the user, and not 770214979Sdes accessible by others. 771180740Sdes 772180740Sdes ~/.ssh/config 773180740Sdes This is the per-user configuration file. The file format and 774180740Sdes configuration options are described in ssh_config(5). Because of 775180740Sdes the potential for abuse, this file must have strict permissions: 776180740Sdes read/write for the user, and not accessible by others. 777180740Sdes 778180740Sdes ~/.ssh/environment 779180740Sdes Contains additional definitions for environment variables; see 780180740Sdes ENVIRONMENT, above. 781180740Sdes 782180740Sdes ~/.ssh/identity 783180740Sdes ~/.ssh/id_dsa 784180740Sdes ~/.ssh/id_rsa 785180740Sdes Contains the private key for authentication. These files contain 786214979Sdes sensitive data and should be readable by the user but not 787214979Sdes accessible by others (read/write/execute). ssh will simply 788214979Sdes ignore a private key file if it is accessible by others. It is 789214979Sdes possible to specify a passphrase when generating the key which 790214979Sdes will be used to encrypt the sensitive part of this file using 791214979Sdes 3DES. 792180740Sdes 793180740Sdes ~/.ssh/identity.pub 794180740Sdes ~/.ssh/id_dsa.pub 795180740Sdes ~/.ssh/id_rsa.pub 796180740Sdes Contains the public key for authentication. These files are not 797180740Sdes sensitive and can (but need not) be readable by anyone. 798180740Sdes 799180740Sdes ~/.ssh/known_hosts 800180740Sdes Contains a list of host keys for all hosts the user has logged 801180740Sdes into that are not already in the systemwide list of known host 802180740Sdes keys. See sshd(8) for further details of the format of this 803180740Sdes file. 804180740Sdes 805180740Sdes ~/.ssh/rc 806180740Sdes Commands in this file are executed by ssh when the user logs in, 807180740Sdes just before the user's shell (or command) is started. See the 808180740Sdes sshd(8) manual page for more information. 809180740Sdes 810180740Sdes /etc/hosts.equiv 811180740Sdes This file is for host-based authentication (see above). It 812180740Sdes should only be writable by root. 813180740Sdes 814180740Sdes /etc/shosts.equiv 815214979Sdes This file is used in exactly the same way as hosts.equiv, but 816214979Sdes allows host-based authentication without permitting login with 817180740Sdes rlogin/rsh. 818180740Sdes 819180740Sdes /etc/ssh/ssh_config 820180740Sdes Systemwide configuration file. The file format and configuration 821180740Sdes options are described in ssh_config(5). 822180740Sdes 823180740Sdes /etc/ssh/ssh_host_key 824180740Sdes /etc/ssh/ssh_host_dsa_key 825180740Sdes /etc/ssh/ssh_host_rsa_key 826180740Sdes These three files contain the private parts of the host keys and 827180740Sdes are used for host-based authentication. If protocol version 1 is 828214979Sdes used, ssh must be setuid root, since the host key is readable 829214979Sdes only by root. For protocol version 2, ssh uses ssh-keysign(8) to 830214979Sdes access the host keys, eliminating the requirement that ssh be 831214979Sdes setuid root when host-based authentication is used. By default 832214979Sdes ssh is not setuid root. 833180740Sdes 834180740Sdes /etc/ssh/ssh_known_hosts 835180740Sdes Systemwide list of known host keys. This file should be prepared 836180740Sdes by the system administrator to contain the public host keys of 837180740Sdes all machines in the organization. It should be world-readable. 838180740Sdes See sshd(8) for further details of the format of this file. 839180740Sdes 840180740Sdes /etc/ssh/sshrc 841180740Sdes Commands in this file are executed by ssh when the user logs in, 842180740Sdes just before the user's shell (or command) is started. See the 843180740Sdes sshd(8) manual page for more information. 844180740Sdes 845180740SdesSEE ALSO 846180740Sdes scp(1), sftp(1), ssh-add(1), ssh-agent(1), ssh-keygen(1), ssh-keyscan(1), 847180740Sdes tun(4), hosts.equiv(5), ssh_config(5), ssh-keysign(8), sshd(8) 848180740Sdes 849180740Sdes The Secure Shell (SSH) Protocol Assigned Numbers, RFC 4250, 2006. 850180740Sdes 851180740Sdes The Secure Shell (SSH) Protocol Architecture, RFC 4251, 2006. 852180740Sdes 853180740Sdes The Secure Shell (SSH) Authentication Protocol, RFC 4252, 2006. 854180740Sdes 855180740Sdes The Secure Shell (SSH) Transport Layer Protocol, RFC 4253, 2006. 856180740Sdes 857180740Sdes The Secure Shell (SSH) Connection Protocol, RFC 4254, 2006. 858180740Sdes 859180740Sdes Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints, RFC 860180740Sdes 4255, 2006. 861180740Sdes 862180740Sdes Generic Message Exchange Authentication for the Secure Shell Protocol 863180740Sdes (SSH), RFC 4256, 2006. 864180740Sdes 865180740Sdes The Secure Shell (SSH) Session Channel Break Extension, RFC 4335, 2006. 866180740Sdes 867180740Sdes The Secure Shell (SSH) Transport Layer Encryption Modes, RFC 4344, 2006. 868180740Sdes 869180740Sdes Improved Arcfour Modes for the Secure Shell (SSH) Transport Layer 870180740Sdes Protocol, RFC 4345, 2006. 871180740Sdes 872180740Sdes Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer 873180740Sdes Protocol, RFC 4419, 2006. 874180740Sdes 875180740Sdes The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006. 876180740Sdes 877214979Sdes A. Perrig, D. Song, Hash Visualization: a New Technique to improve 878180750Sdes Real-World Security, 1999, International Workshop on Cryptographic 879180750Sdes Techniques and E-Commerce (CrypTEC '99). 880180750Sdes 881180740SdesAUTHORS 882180740Sdes OpenSSH is a derivative of the original and free ssh 1.2.12 release by 883180740Sdes Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo 884180740Sdes de Raadt and Dug Song removed many bugs, re-added newer features and 885180740Sdes created OpenSSH. Markus Friedl contributed the support for SSH protocol 886180740Sdes versions 1.5 and 2.0. 887180740Sdes 888214979SdesOpenBSD 4.8 August 4, 2010 OpenBSD 4.8 889