ssh.0 revision 239844
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 138218767Sdes Selects a file from which the identity (private key) for public 139218767Sdes key authentication is read. The default is ~/.ssh/identity for 140218767Sdes protocol version 1, and ~/.ssh/id_dsa, ~/.ssh/id_ecdsa and 141218767Sdes ~/.ssh/id_rsa for protocol version 2. Identity files may also be 142218767Sdes specified on a per-host basis in the configuration file. It is 143218767Sdes possible to have multiple -i options (and multiple identities 144218767Sdes specified in configuration files). ssh will also try to load 145218767Sdes certificate information from the filename obtained by appending 146218767Sdes -cert.pub to 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 205239844Sdes forwardings without command execution), ``cancel'' (cancel 206239844Sdes forwardings), ``exit'' (request the master to exit), and ``stop'' 207239844Sdes (request the master to stop accepting further multiplexing 208239844Sdes requests). 209180740Sdes 210180740Sdes -o option 211214979Sdes Can be used to give options in the format used in the 212214979Sdes configuration file. This is useful for specifying options for 213214979Sdes which there is no separate command-line flag. For full details 214214979Sdes of the options listed below, and their possible values, see 215214979Sdes ssh_config(5). 216180740Sdes 217180740Sdes AddressFamily 218180740Sdes BatchMode 219180740Sdes BindAddress 220180740Sdes ChallengeResponseAuthentication 221180740Sdes CheckHostIP 222180740Sdes Cipher 223180740Sdes Ciphers 224180740Sdes ClearAllForwardings 225180740Sdes Compression 226180740Sdes CompressionLevel 227180740Sdes ConnectionAttempts 228180740Sdes ConnectTimeout 229180740Sdes ControlMaster 230180740Sdes ControlPath 231239844Sdes ControlPersist 232180740Sdes DynamicForward 233180740Sdes EscapeChar 234180740Sdes ExitOnForwardFailure 235180740Sdes ForwardAgent 236180740Sdes ForwardX11 237239844Sdes ForwardX11Timeout 238180740Sdes ForwardX11Trusted 239180740Sdes GatewayPorts 240180740Sdes GlobalKnownHostsFile 241180740Sdes GSSAPIAuthentication 242180740Sdes GSSAPIDelegateCredentials 243180740Sdes HashKnownHosts 244180740Sdes Host 245180740Sdes HostbasedAuthentication 246180740Sdes HostKeyAlgorithms 247180740Sdes HostKeyAlias 248180740Sdes HostName 249180740Sdes IdentityFile 250180740Sdes IdentitiesOnly 251218767Sdes IPQoS 252239844Sdes KbdInteractiveAuthentication 253180740Sdes KbdInteractiveDevices 254218767Sdes KexAlgorithms 255180740Sdes LocalCommand 256180740Sdes LocalForward 257180740Sdes LogLevel 258180740Sdes MACs 259180740Sdes NoHostAuthenticationForLocalhost 260180740Sdes NumberOfPasswordPrompts 261180740Sdes PasswordAuthentication 262180740Sdes PermitLocalCommand 263204861Sdes PKCS11Provider 264180740Sdes Port 265180740Sdes PreferredAuthentications 266180740Sdes Protocol 267180740Sdes ProxyCommand 268180740Sdes PubkeyAuthentication 269180740Sdes RekeyLimit 270180740Sdes RemoteForward 271225825Sdes RequestTTY 272180740Sdes RhostsRSAAuthentication 273180740Sdes RSAAuthentication 274180740Sdes SendEnv 275180740Sdes ServerAliveInterval 276180740Sdes ServerAliveCountMax 277180740Sdes StrictHostKeyChecking 278180740Sdes TCPKeepAlive 279180740Sdes Tunnel 280180740Sdes TunnelDevice 281180740Sdes UsePrivilegedPort 282180740Sdes User 283180740Sdes UserKnownHostsFile 284180740Sdes VerifyHostKeyDNS 285180750Sdes VisualHostKey 286180740Sdes XAuthLocation 287180740Sdes 288180740Sdes -p port 289180740Sdes Port to connect to on the remote host. This can be specified on 290180740Sdes a per-host basis in the configuration file. 291180740Sdes 292180746Sdes -q Quiet mode. Causes most warning and diagnostic messages to be 293180740Sdes suppressed. 294180740Sdes 295180740Sdes -R [bind_address:]port:host:hostport 296180740Sdes Specifies that the given port on the remote (server) host is to 297180740Sdes be forwarded to the given host and port on the local side. This 298180740Sdes works by allocating a socket to listen to port on the remote 299214979Sdes side, and whenever a connection is made to this port, the 300214979Sdes connection is forwarded over the secure channel, and a connection 301214979Sdes is made to host port hostport from the local machine. 302180740Sdes 303180740Sdes Port forwardings can also be specified in the configuration file. 304180740Sdes Privileged ports can be forwarded only when logging in as root on 305180740Sdes the remote machine. IPv6 addresses can be specified by enclosing 306214979Sdes the address in square braces. 307180740Sdes 308180740Sdes By default, the listening socket on the server will be bound to 309214979Sdes the loopback interface only. This may be overridden by 310214979Sdes specifying a bind_address. An empty bind_address, or the address 311214979Sdes `*', indicates that the remote socket should listen on all 312214979Sdes interfaces. Specifying a remote bind_address will only succeed 313214979Sdes if the server's GatewayPorts option is enabled (see 314214979Sdes sshd_config(5)). 315180740Sdes 316189006Sdes If the port argument is `0', the listen port will be dynamically 317189006Sdes allocated on the server and reported to the client at run time. 318214979Sdes When used together with -O forward the allocated port will be 319214979Sdes printed to the standard output. 320189006Sdes 321180740Sdes -S ctl_path 322214979Sdes Specifies the location of a control socket for connection 323214979Sdes sharing, or the string ``none'' to disable connection sharing. 324214979Sdes Refer to the description of ControlPath and ControlMaster in 325214979Sdes ssh_config(5) for details. 326180740Sdes 327180740Sdes -s May be used to request invocation of a subsystem on the remote 328214979Sdes system. Subsystems are a feature of the SSH2 protocol which 329214979Sdes facilitate the use of SSH as a secure transport for other 330214979Sdes applications (eg. sftp(1)). The subsystem is specified as the 331214979Sdes remote command. 332180740Sdes 333180740Sdes -T Disable pseudo-tty allocation. 334180740Sdes 335214979Sdes -t Force pseudo-tty allocation. This can be used to execute 336214979Sdes arbitrary screen-based programs on a remote machine, which can be 337180740Sdes very useful, e.g. when implementing menu services. Multiple -t 338180740Sdes options force tty allocation, even if ssh has no local tty. 339180740Sdes 340180740Sdes -V Display the version number and exit. 341180740Sdes 342180740Sdes -v Verbose mode. Causes ssh to print debugging messages about its 343214979Sdes progress. This is helpful in debugging connection, 344214979Sdes authentication, and configuration problems. Multiple -v options 345214979Sdes increase the verbosity. The maximum is 3. 346180740Sdes 347204861Sdes -W host:port 348214979Sdes Requests that standard input and output on the client be 349214979Sdes forwarded to host on port over the secure channel. Implies -N, 350214979Sdes -T, ExitOnForwardFailure and ClearAllForwardings and works with 351214979Sdes Protocol version 2 only. 352204861Sdes 353180740Sdes -w local_tun[:remote_tun] 354214979Sdes Requests tunnel device forwarding with the specified tun(4) 355214979Sdes devices between the client (local_tun) and the server 356214979Sdes (remote_tun). 357180740Sdes 358180740Sdes The devices may be specified by numerical ID or the keyword 359180740Sdes ``any'', which uses the next available tunnel device. If 360180740Sdes remote_tun is not specified, it defaults to ``any''. See also 361180740Sdes the Tunnel and TunnelDevice directives in ssh_config(5). If the 362180740Sdes Tunnel directive is unset, it is set to the default tunnel mode, 363180740Sdes which is ``point-to-point''. 364180740Sdes 365180740Sdes -X Enables X11 forwarding. This can also be specified on a per-host 366180740Sdes basis in a configuration file. 367180740Sdes 368180740Sdes X11 forwarding should be enabled with caution. Users with the 369180740Sdes ability to bypass file permissions on the remote host (for the 370180740Sdes user's X authorization database) can access the local X11 display 371180740Sdes through the forwarded connection. An attacker may then be able 372180740Sdes to perform activities such as keystroke monitoring. 373180740Sdes 374214979Sdes For this reason, X11 forwarding is subjected to X11 SECURITY 375214979Sdes extension restrictions by default. Please refer to the ssh -Y 376214979Sdes option and the ForwardX11Trusted directive in ssh_config(5) for 377180740Sdes more information. 378180740Sdes 379180740Sdes -x Disables X11 forwarding. 380180740Sdes 381180740Sdes -Y Enables trusted X11 forwarding. Trusted X11 forwardings are not 382180740Sdes subjected to the X11 SECURITY extension controls. 383180740Sdes 384214979Sdes -y Send log information using the syslog(3) system module. By 385214979Sdes default this information is sent to stderr. 386189006Sdes 387214979Sdes ssh may additionally obtain configuration data from a per-user 388214979Sdes configuration file and a system-wide configuration file. The file format 389214979Sdes and configuration options are described in ssh_config(5). 390180740Sdes 391180740SdesAUTHENTICATION 392204861Sdes The OpenSSH SSH client supports SSH protocols 1 and 2. The default is to 393204861Sdes use protocol 2 only, though this can be changed via the Protocol option 394204861Sdes in ssh_config(5) or the -1 and -2 options (see above). Both protocols 395204861Sdes support similar authentication methods, but protocol 2 is the default 396204861Sdes since it provides additional mechanisms for confidentiality (the traffic 397214979Sdes is encrypted using AES, 3DES, Blowfish, CAST128, or Arcfour) and 398225825Sdes integrity (hmac-md5, hmac-sha1, hmac-sha2-256, hmac-sha2-512, umac-64, 399225825Sdes hmac-ripemd160). Protocol 1 lacks a strong mechanism for ensuring the 400225825Sdes integrity of the connection. 401180740Sdes 402214979Sdes The methods available for authentication are: GSSAPI-based 403214979Sdes authentication, host-based authentication, public key authentication, 404214979Sdes challenge-response authentication, and password authentication. 405214979Sdes Authentication methods are tried in the order specified above, though 406214979Sdes protocol 2 has a configuration option to change the default order: 407214979Sdes PreferredAuthentications. 408180740Sdes 409180740Sdes Host-based authentication works as follows: If the machine the user logs 410180740Sdes in from is listed in /etc/hosts.equiv or /etc/shosts.equiv on the remote 411180740Sdes machine, and the user names are the same on both sides, or if the files 412180740Sdes ~/.rhosts or ~/.shosts exist in the user's home directory on the remote 413180740Sdes machine and contain a line containing the name of the client machine and 414180740Sdes the name of the user on that machine, the user is considered for login. 415180740Sdes Additionally, the server must be able to verify the client's host key 416180740Sdes (see the description of /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts, 417214979Sdes below) for login to be permitted. This authentication method closes 418214979Sdes security holes due to IP spoofing, DNS spoofing, and routing spoofing. 419180740Sdes [Note to the administrator: /etc/hosts.equiv, ~/.rhosts, and the 420180740Sdes rlogin/rsh protocol in general, are inherently insecure and should be 421180740Sdes disabled if security is desired.] 422180740Sdes 423214979Sdes Public key authentication works as follows: The scheme is based on 424214979Sdes public-key cryptography, using cryptosystems where encryption and 425214979Sdes decryption are done using separate keys, and it is unfeasible to derive 426214979Sdes the decryption key from the encryption key. The idea is that each user 427214979Sdes creates a public/private key pair for authentication purposes. The 428214979Sdes server knows the public key, and only the user knows the private key. 429214979Sdes ssh implements public key authentication protocol automatically, using 430218767Sdes one of the DSA, ECDSA or RSA algorithms. Protocol 1 is restricted to 431218767Sdes using only RSA keys, but protocol 2 may use any. The HISTORY section of 432218767Sdes ssl(8) contains a brief discussion of the DSA and RSA algorithms. 433180740Sdes 434180740Sdes The file ~/.ssh/authorized_keys lists the public keys that are permitted 435180740Sdes for logging in. When the user logs in, the ssh program tells the server 436180740Sdes which key pair it would like to use for authentication. The client 437180740Sdes proves that it has access to the private key and the server checks that 438180740Sdes the corresponding public key is authorized to accept the account. 439180740Sdes 440180740Sdes The user creates his/her key pair by running ssh-keygen(1). This stores 441180740Sdes the private key in ~/.ssh/identity (protocol 1), ~/.ssh/id_dsa (protocol 442218767Sdes 2 DSA), ~/.ssh/id_ecdsa (protocol 2 ECDSA), or ~/.ssh/id_rsa (protocol 2 443218767Sdes RSA) and stores the public key in ~/.ssh/identity.pub (protocol 1), 444218767Sdes ~/.ssh/id_dsa.pub (protocol 2 DSA), ~/.ssh/id_ecdsa.pub (protocol 2 445218767Sdes ECDSA), or ~/.ssh/id_rsa.pub (protocol 2 RSA) in the user's home 446218767Sdes directory. The user should then copy the public key to 447218767Sdes ~/.ssh/authorized_keys in his/her home directory on the remote machine. 448218767Sdes The authorized_keys file corresponds to the conventional ~/.rhosts file, 449218767Sdes and has one key per line, though the lines can be very long. After this, 450218767Sdes the user can log in without giving the password. 451180740Sdes 452214979Sdes A variation on public key authentication is available in the form of 453214979Sdes certificate authentication: instead of a set of public/private keys, 454214979Sdes signed certificates are used. This has the advantage that a single 455214979Sdes trusted certification authority can be used in place of many 456214979Sdes public/private keys. See the CERTIFICATES section of ssh-keygen(1) for 457214979Sdes more information. 458180740Sdes 459204861Sdes The most convenient way to use public key or certificate authentication 460214979Sdes may be with an authentication agent. See ssh-agent(1) for more 461214979Sdes information. 462204861Sdes 463180740Sdes Challenge-response authentication works as follows: The server sends an 464214979Sdes arbitrary "challenge" text, and prompts for a response. Protocol 2 465214979Sdes allows multiple challenges and responses; protocol 1 is restricted to 466214979Sdes just one challenge/response. Examples of challenge-response 467214979Sdes authentication include BSD Authentication (see login.conf(5)) and PAM 468214979Sdes (some non-OpenBSD systems). 469180740Sdes 470180740Sdes Finally, if other authentication methods fail, ssh prompts the user for a 471180740Sdes password. The password is sent to the remote host for checking; however, 472180740Sdes since all communications are encrypted, the password cannot be seen by 473180740Sdes someone listening on the network. 474180740Sdes 475214979Sdes ssh automatically maintains and checks a database containing 476214979Sdes identification for all hosts it has ever been used with. Host keys are 477214979Sdes stored in ~/.ssh/known_hosts in the user's home directory. Additionally, 478214979Sdes the file /etc/ssh/ssh_known_hosts is automatically checked for known 479214979Sdes hosts. Any new hosts are automatically added to the user's file. If a 480214979Sdes host's identification ever changes, ssh warns about this and disables 481214979Sdes password authentication to prevent server spoofing or man-in-the-middle 482214979Sdes attacks, which could otherwise be used to circumvent the encryption. The 483180740Sdes StrictHostKeyChecking option can be used to control logins to machines 484180740Sdes whose host key is not known or has changed. 485180740Sdes 486214979Sdes When the user's identity has been accepted by the server, the server 487214979Sdes either executes the given command, or logs into the machine and gives the 488180740Sdes user a normal shell on the remote machine. All communication with the 489180740Sdes remote command or shell will be automatically encrypted. 490180740Sdes 491180740Sdes If a pseudo-terminal has been allocated (normal login session), the user 492180740Sdes may use the escape characters noted below. 493180740Sdes 494180740Sdes If no pseudo-tty has been allocated, the session is transparent and can 495180740Sdes be used to reliably transfer binary data. On most systems, setting the 496180740Sdes escape character to ``none'' will also make the session transparent even 497180740Sdes if a tty is used. 498180740Sdes 499180740Sdes The session terminates when the command or shell on the remote machine 500180740Sdes exits and all X11 and TCP connections have been closed. 501180740Sdes 502180740SdesESCAPE CHARACTERS 503214979Sdes When a pseudo-terminal has been requested, ssh supports a number of 504214979Sdes functions through the use of an escape character. 505180740Sdes 506180740Sdes A single tilde character can be sent as ~~ or by following the tilde by a 507180740Sdes character other than those described below. The escape character must 508214979Sdes always follow a newline to be interpreted as special. The escape 509214979Sdes character can be changed in configuration files using the EscapeChar 510214979Sdes configuration directive or on the command line by the -e option. 511180740Sdes 512180740Sdes The supported escapes (assuming the default `~') are: 513180740Sdes 514180740Sdes ~. Disconnect. 515180740Sdes 516180740Sdes ~^Z Background ssh. 517180740Sdes 518180740Sdes ~# List forwarded connections. 519180740Sdes 520180740Sdes ~& Background ssh at logout when waiting for forwarded connection / 521180740Sdes X11 sessions to terminate. 522180740Sdes 523180740Sdes ~? Display a list of escape characters. 524180740Sdes 525180740Sdes ~B Send a BREAK to the remote system (only useful for SSH protocol 526180740Sdes version 2 and if the peer supports it). 527180740Sdes 528180740Sdes ~C Open command line. Currently this allows the addition of port 529189006Sdes forwardings using the -L, -R and -D options (see above). It also 530239844Sdes allows the cancellation of existing port-forwardings with 531239844Sdes -KL[bind_address:]port for local, -KR[bind_address:]port for 532239844Sdes remote and -KD[bind_address:]port for dynamic port-forwardings. 533239844Sdes !command allows the user to execute a local command if the 534239844Sdes PermitLocalCommand option is enabled in ssh_config(5). Basic 535239844Sdes help is available, using the -h option. 536180740Sdes 537180740Sdes ~R Request rekeying of the connection (only useful for SSH protocol 538180740Sdes version 2 and if the peer supports it). 539180740Sdes 540180740SdesTCP FORWARDING 541180740Sdes Forwarding of arbitrary TCP connections over the secure channel can be 542180740Sdes specified either on the command line or in a configuration file. One 543180740Sdes possible application of TCP forwarding is a secure connection to a mail 544180740Sdes server; another is going through firewalls. 545180740Sdes 546180740Sdes In the example below, we look at encrypting communication between an IRC 547180740Sdes client and server, even though the IRC server does not directly support 548180740Sdes encrypted communications. This works as follows: the user connects to 549214979Sdes the remote host using ssh, specifying a port to be used to forward 550214979Sdes connections to the remote server. After that it is possible to start the 551180740Sdes service which is to be encrypted on the client machine, connecting to the 552180740Sdes same local port, and ssh will encrypt and forward the connection. 553180740Sdes 554180740Sdes The following example tunnels an IRC session from client machine 555180740Sdes ``127.0.0.1'' (localhost) to remote server ``server.example.com'': 556180740Sdes 557180740Sdes $ ssh -f -L 1234:localhost:6667 server.example.com sleep 10 558180740Sdes $ irc -c '#users' -p 1234 pinky 127.0.0.1 559180740Sdes 560180740Sdes This tunnels a connection to IRC server ``server.example.com'', joining 561214979Sdes channel ``#users'', nickname ``pinky'', using port 1234. It doesn't 562214979Sdes matter which port is used, as long as it's greater than 1023 (remember, 563214979Sdes only root can open sockets on privileged ports) and doesn't conflict with 564214979Sdes any ports already in use. The connection is forwarded to port 6667 on 565214979Sdes the remote server, since that's the standard port for IRC services. 566180740Sdes 567180740Sdes The -f option backgrounds ssh and the remote command ``sleep 10'' is 568180740Sdes specified to allow an amount of time (10 seconds, in the example) to 569180740Sdes start the service which is to be tunnelled. If no connections are made 570180740Sdes within the time specified, ssh will exit. 571180740Sdes 572180740SdesX11 FORWARDING 573180740Sdes If the ForwardX11 variable is set to ``yes'' (or see the description of 574180740Sdes the -X, -x, and -Y options above) and the user is using X11 (the DISPLAY 575214979Sdes environment variable is set), the connection to the X11 display is 576214979Sdes automatically forwarded to the remote side in such a way that any X11 577214979Sdes programs started from the shell (or command) will go through the 578214979Sdes encrypted channel, and the connection to the real X server will be made 579214979Sdes from the local machine. The user should not manually set DISPLAY. 580214979Sdes Forwarding of X11 connections can be configured on the command line or in 581214979Sdes configuration files. 582180740Sdes 583180740Sdes The DISPLAY value set by ssh will point to the server machine, but with a 584180740Sdes display number greater than zero. This is normal, and happens because 585180740Sdes ssh creates a ``proxy'' X server on the server machine for forwarding the 586180740Sdes connections over the encrypted channel. 587180740Sdes 588180740Sdes ssh will also automatically set up Xauthority data on the server machine. 589180740Sdes For this purpose, it will generate a random authorization cookie, store 590180740Sdes it in Xauthority on the server, and verify that any forwarded connections 591180740Sdes carry this cookie and replace it by the real cookie when the connection 592180740Sdes is opened. The real authentication cookie is never sent to the server 593180740Sdes machine (and no cookies are sent in the plain). 594180740Sdes 595180740Sdes If the ForwardAgent variable is set to ``yes'' (or see the description of 596180740Sdes the -A and -a options above) and the user is using an authentication 597214979Sdes agent, the connection to the agent is automatically forwarded to the 598214979Sdes remote side. 599180740Sdes 600180740SdesVERIFYING HOST KEYS 601180740Sdes When connecting to a server for the first time, a fingerprint of the 602180740Sdes server's public key is presented to the user (unless the option 603180740Sdes StrictHostKeyChecking has been disabled). Fingerprints can be determined 604180740Sdes using ssh-keygen(1): 605180740Sdes 606180740Sdes $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key 607180740Sdes 608180750Sdes If the fingerprint is already known, it can be matched and the key can be 609180750Sdes accepted or rejected. Because of the difficulty of comparing host keys 610180750Sdes just by looking at hex strings, there is also support to compare host 611180750Sdes keys visually, using random art. By setting the VisualHostKey option to 612180750Sdes ``yes'', a small ASCII graphic gets displayed on every login to a server, 613180750Sdes no matter if the session itself is interactive or not. By learning the 614180750Sdes pattern a known server produces, a user can easily find out that the host 615214979Sdes key has changed when a completely different pattern is displayed. 616214979Sdes Because these patterns are not unambiguous however, a pattern that looks 617180750Sdes similar to the pattern remembered only gives a good probability that the 618180750Sdes host key is the same, not guaranteed proof. 619180740Sdes 620180750Sdes To get a listing of the fingerprints along with their random art for all 621180750Sdes known hosts, the following command line can be used: 622180750Sdes 623180750Sdes $ ssh-keygen -lv -f ~/.ssh/known_hosts 624180750Sdes 625180750Sdes If the fingerprint is unknown, an alternative method of verification is 626180750Sdes available: SSH fingerprints verified by DNS. An additional resource 627180750Sdes record (RR), SSHFP, is added to a zonefile and the connecting client is 628180750Sdes able to match the fingerprint with that of the key presented. 629180750Sdes 630180740Sdes In this example, we are connecting a client to a server, 631180740Sdes ``host.example.com''. The SSHFP resource records should first be added 632180740Sdes to the zonefile for host.example.com: 633180740Sdes 634180740Sdes $ ssh-keygen -r host.example.com. 635180740Sdes 636180740Sdes The output lines will have to be added to the zonefile. To check that 637180740Sdes the zone is answering fingerprint queries: 638180740Sdes 639180740Sdes $ dig -t SSHFP host.example.com 640180740Sdes 641180740Sdes Finally the client connects: 642180740Sdes 643180740Sdes $ ssh -o "VerifyHostKeyDNS ask" host.example.com 644180740Sdes [...] 645180740Sdes Matching host key fingerprint found in DNS. 646180740Sdes Are you sure you want to continue connecting (yes/no)? 647180740Sdes 648180740Sdes See the VerifyHostKeyDNS option in ssh_config(5) for more information. 649180740Sdes 650180740SdesSSH-BASED VIRTUAL PRIVATE NETWORKS 651180740Sdes ssh contains support for Virtual Private Network (VPN) tunnelling using 652214979Sdes the tun(4) network pseudo-device, allowing two networks to be joined 653214979Sdes securely. The sshd_config(5) configuration option PermitTunnel controls 654214979Sdes whether the server supports this, and at what level (layer 2 or 3 655214979Sdes traffic). 656180740Sdes 657214979Sdes The following example would connect client network 10.0.50.0/24 with 658214979Sdes remote network 10.0.99.0/24 using a point-to-point connection from 659214979Sdes 10.1.1.1 to 10.1.1.2, provided that the SSH server running on the gateway 660214979Sdes to the remote network, at 192.168.1.15, allows it. 661180740Sdes 662180740Sdes On the client: 663180740Sdes 664180740Sdes # ssh -f -w 0:1 192.168.1.15 true 665180740Sdes # ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252 666180740Sdes # route add 10.0.99.0/24 10.1.1.2 667180740Sdes 668180740Sdes On the server: 669180740Sdes 670180740Sdes # ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252 671180740Sdes # route add 10.0.50.0/24 10.1.1.1 672180740Sdes 673180740Sdes Client access may be more finely tuned via the /root/.ssh/authorized_keys 674180740Sdes file (see below) and the PermitRootLogin server option. The following 675180740Sdes entry would permit connections on tun(4) device 1 from user ``jane'' and 676180740Sdes on tun device 2 from user ``john'', if PermitRootLogin is set to 677180740Sdes ``forced-commands-only'': 678180740Sdes 679180740Sdes tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane 680180740Sdes tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john 681180740Sdes 682180740Sdes Since an SSH-based setup entails a fair amount of overhead, it may be 683214979Sdes more suited to temporary setups, such as for wireless VPNs. More 684214979Sdes permanent VPNs are better provided by tools such as ipsecctl(8) and 685180740Sdes isakmpd(8). 686180740Sdes 687180740SdesENVIRONMENT 688180740Sdes ssh will normally set the following environment variables: 689180740Sdes 690180740Sdes DISPLAY The DISPLAY variable indicates the location of the 691180740Sdes X11 server. It is automatically set by ssh to 692180740Sdes point to a value of the form ``hostname:n'', where 693180740Sdes ``hostname'' indicates the host where the shell 694180740Sdes runs, and `n' is an integer >= 1. ssh uses this 695180740Sdes special value to forward X11 connections over the 696180740Sdes secure channel. The user should normally not set 697180740Sdes DISPLAY explicitly, as that will render the X11 698180740Sdes connection insecure (and will require the user to 699180740Sdes manually copy any required authorization cookies). 700180740Sdes 701180740Sdes HOME Set to the path of the user's home directory. 702180740Sdes 703214979Sdes LOGNAME Synonym for USER; set for compatibility with 704214979Sdes systems that use this variable. 705180740Sdes 706180740Sdes MAIL Set to the path of the user's mailbox. 707180740Sdes 708214979Sdes PATH Set to the default PATH, as specified when 709214979Sdes compiling ssh. 710180740Sdes 711180740Sdes SSH_ASKPASS If ssh needs a passphrase, it will read the 712180740Sdes passphrase from the current terminal if it was run 713180740Sdes from a terminal. If ssh does not have a terminal 714180740Sdes associated with it but DISPLAY and SSH_ASKPASS are 715180740Sdes set, it will execute the program specified by 716180740Sdes SSH_ASKPASS and open an X11 window to read the 717214979Sdes passphrase. This is particularly useful when 718214979Sdes calling ssh from a .xsession or related script. 719214979Sdes (Note that on some machines it may be necessary to 720214979Sdes redirect the input from /dev/null to make this 721214979Sdes work.) 722180740Sdes 723180740Sdes SSH_AUTH_SOCK Identifies the path of a UNIX-domain socket used to 724180740Sdes communicate with the agent. 725180740Sdes 726214979Sdes SSH_CONNECTION Identifies the client and server ends of the 727214979Sdes connection. The variable contains four space- 728214979Sdes separated values: client IP address, client port 729214979Sdes number, server IP address, and server port number. 730180740Sdes 731180740Sdes SSH_ORIGINAL_COMMAND This variable contains the original command line if 732180740Sdes a forced command is executed. It can be used to 733180740Sdes extract the original arguments. 734180740Sdes 735214979Sdes SSH_TTY This is set to the name of the tty (path to the 736214979Sdes device) associated with the current shell or 737214979Sdes command. If the current session has no tty, this 738214979Sdes variable is not set. 739180740Sdes 740180740Sdes TZ This variable is set to indicate the present time 741180740Sdes zone if it was set when the daemon was started 742214979Sdes (i.e. the daemon passes the value on to new 743214979Sdes connections). 744180740Sdes 745180740Sdes USER Set to the name of the user logging in. 746180740Sdes 747180740Sdes Additionally, ssh reads ~/.ssh/environment, and adds lines of the format 748214979Sdes ``VARNAME=value'' to the environment if the file exists and users are 749214979Sdes allowed to change their environment. For more information, see the 750180740Sdes PermitUserEnvironment option in sshd_config(5). 751180740Sdes 752180740SdesFILES 753180740Sdes ~/.rhosts 754180740Sdes This file is used for host-based authentication (see above). On 755214979Sdes some machines this file may need to be world-readable if the 756214979Sdes user's home directory is on an NFS partition, because sshd(8) 757214979Sdes reads it as root. Additionally, this file must be owned by the 758214979Sdes user, and must not have write permissions for anyone else. The 759214979Sdes recommended permission for most machines is read/write for the 760214979Sdes user, and not accessible by others. 761180740Sdes 762180740Sdes ~/.shosts 763180740Sdes This file is used in exactly the same way as .rhosts, but allows 764180740Sdes host-based authentication without permitting login with 765180740Sdes rlogin/rsh. 766180740Sdes 767180746Sdes ~/.ssh/ 768214979Sdes This directory is the default location for all user-specific 769214979Sdes configuration and authentication information. There is no 770214979Sdes general requirement to keep the entire contents of this directory 771214979Sdes secret, but the recommended permissions are read/write/execute 772214979Sdes for the user, and not accessible by others. 773180746Sdes 774180740Sdes ~/.ssh/authorized_keys 775218767Sdes Lists the public keys (DSA/ECDSA/RSA) that can be used for 776218767Sdes logging in as this user. The format of this file is described in 777218767Sdes the sshd(8) manual page. This file is not highly sensitive, but 778218767Sdes the recommended permissions are read/write for the user, and not 779214979Sdes accessible by others. 780180740Sdes 781180740Sdes ~/.ssh/config 782180740Sdes This is the per-user configuration file. The file format and 783180740Sdes configuration options are described in ssh_config(5). Because of 784180740Sdes the potential for abuse, this file must have strict permissions: 785180740Sdes read/write for the user, and not accessible by others. 786180740Sdes 787180740Sdes ~/.ssh/environment 788180740Sdes Contains additional definitions for environment variables; see 789180740Sdes ENVIRONMENT, above. 790180740Sdes 791180740Sdes ~/.ssh/identity 792180740Sdes ~/.ssh/id_dsa 793218767Sdes ~/.ssh/id_ecdsa 794180740Sdes ~/.ssh/id_rsa 795180740Sdes Contains the private key for authentication. These files contain 796214979Sdes sensitive data and should be readable by the user but not 797214979Sdes accessible by others (read/write/execute). ssh will simply 798214979Sdes ignore a private key file if it is accessible by others. It is 799214979Sdes possible to specify a passphrase when generating the key which 800214979Sdes will be used to encrypt the sensitive part of this file using 801214979Sdes 3DES. 802180740Sdes 803180740Sdes ~/.ssh/identity.pub 804180740Sdes ~/.ssh/id_dsa.pub 805218767Sdes ~/.ssh/id_ecdsa.pub 806180740Sdes ~/.ssh/id_rsa.pub 807180740Sdes Contains the public key for authentication. These files are not 808180740Sdes sensitive and can (but need not) be readable by anyone. 809180740Sdes 810180740Sdes ~/.ssh/known_hosts 811180740Sdes Contains a list of host keys for all hosts the user has logged 812180740Sdes into that are not already in the systemwide list of known host 813180740Sdes keys. See sshd(8) for further details of the format of this 814180740Sdes file. 815180740Sdes 816180740Sdes ~/.ssh/rc 817180740Sdes Commands in this file are executed by ssh when the user logs in, 818180740Sdes just before the user's shell (or command) is started. See the 819180740Sdes sshd(8) manual page for more information. 820180740Sdes 821180740Sdes /etc/hosts.equiv 822180740Sdes This file is for host-based authentication (see above). It 823180740Sdes should only be writable by root. 824180740Sdes 825180740Sdes /etc/shosts.equiv 826214979Sdes This file is used in exactly the same way as hosts.equiv, but 827214979Sdes allows host-based authentication without permitting login with 828180740Sdes rlogin/rsh. 829180740Sdes 830180740Sdes /etc/ssh/ssh_config 831180740Sdes Systemwide configuration file. The file format and configuration 832180740Sdes options are described in ssh_config(5). 833180740Sdes 834180740Sdes /etc/ssh/ssh_host_key 835180740Sdes /etc/ssh/ssh_host_dsa_key 836218767Sdes /etc/ssh/ssh_host_ecdsa_key 837180740Sdes /etc/ssh/ssh_host_rsa_key 838180740Sdes These three files contain the private parts of the host keys and 839180740Sdes are used for host-based authentication. If protocol version 1 is 840214979Sdes used, ssh must be setuid root, since the host key is readable 841214979Sdes only by root. For protocol version 2, ssh uses ssh-keysign(8) to 842214979Sdes access the host keys, eliminating the requirement that ssh be 843214979Sdes setuid root when host-based authentication is used. By default 844214979Sdes ssh is not setuid root. 845180740Sdes 846180740Sdes /etc/ssh/ssh_known_hosts 847180740Sdes Systemwide list of known host keys. This file should be prepared 848180740Sdes by the system administrator to contain the public host keys of 849180740Sdes all machines in the organization. It should be world-readable. 850180740Sdes See sshd(8) for further details of the format of this file. 851180740Sdes 852180740Sdes /etc/ssh/sshrc 853180740Sdes Commands in this file are executed by ssh when the user logs in, 854180740Sdes just before the user's shell (or command) is started. See the 855180740Sdes sshd(8) manual page for more information. 856180740Sdes 857218767SdesEXIT STATUS 858218767Sdes ssh exits with the exit status of the remote command or with 255 if an 859218767Sdes error occurred. 860218767Sdes 861180740SdesSEE ALSO 862180740Sdes scp(1), sftp(1), ssh-add(1), ssh-agent(1), ssh-keygen(1), ssh-keyscan(1), 863180740Sdes tun(4), hosts.equiv(5), ssh_config(5), ssh-keysign(8), sshd(8) 864180740Sdes 865180740Sdes The Secure Shell (SSH) Protocol Assigned Numbers, RFC 4250, 2006. 866180740Sdes 867180740Sdes The Secure Shell (SSH) Protocol Architecture, RFC 4251, 2006. 868180740Sdes 869180740Sdes The Secure Shell (SSH) Authentication Protocol, RFC 4252, 2006. 870180740Sdes 871180740Sdes The Secure Shell (SSH) Transport Layer Protocol, RFC 4253, 2006. 872180740Sdes 873180740Sdes The Secure Shell (SSH) Connection Protocol, RFC 4254, 2006. 874180740Sdes 875180740Sdes Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints, RFC 876180740Sdes 4255, 2006. 877180740Sdes 878180740Sdes Generic Message Exchange Authentication for the Secure Shell Protocol 879180740Sdes (SSH), RFC 4256, 2006. 880180740Sdes 881180740Sdes The Secure Shell (SSH) Session Channel Break Extension, RFC 4335, 2006. 882180740Sdes 883180740Sdes The Secure Shell (SSH) Transport Layer Encryption Modes, RFC 4344, 2006. 884180740Sdes 885180740Sdes Improved Arcfour Modes for the Secure Shell (SSH) Transport Layer 886180740Sdes Protocol, RFC 4345, 2006. 887180740Sdes 888180740Sdes Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer 889180740Sdes Protocol, RFC 4419, 2006. 890180740Sdes 891180740Sdes The Secure Shell (SSH) Public Key File Format, RFC 4716, 2006. 892180740Sdes 893218767Sdes Elliptic Curve Algorithm Integration in the Secure Shell Transport Layer, 894218767Sdes RFC 5656, 2009. 895218767Sdes 896218767Sdes A. Perrig and D. Song, Hash Visualization: a New Technique to improve 897180750Sdes Real-World Security, 1999, International Workshop on Cryptographic 898180750Sdes Techniques and E-Commerce (CrypTEC '99). 899180750Sdes 900180740SdesAUTHORS 901180740Sdes OpenSSH is a derivative of the original and free ssh 1.2.12 release by 902180740Sdes Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo 903180740Sdes de Raadt and Dug Song removed many bugs, re-added newer features and 904180740Sdes created OpenSSH. Markus Friedl contributed the support for SSH protocol 905180740Sdes versions 1.5 and 2.0. 906180740Sdes 907239844SdesOpenBSD 5.0 September 11, 2011 OpenBSD 5.0 908