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