1SSH(1) General Commands Manual SSH(1) 2 3NAME 4 ssh M-bM-^@M-^S OpenSSH SSH client (remote login program) 5 6SYNOPSIS 7 ssh [-1246AaCfGgKkMNnqsTtVvXxYy] [-b bind_address] [-c cipher_spec] 8 [-D [bind_address:]port] [-E log_file] [-e escape_char] 9 [-F configfile] [-I pkcs11] [-i identity_file] 10 [-L [bind_address:]port:host:hostport] [-l login_name] [-m mac_spec] 11 [-O ctl_cmd] [-o option] [-p port] 12 [-Q cipher | cipher-auth | mac | kex | key | protocol-version] 13 [-R [bind_address:]port:host:hostport] [-S ctl_path] [-W host:port] 14 [-w local_tun[:remote_tun]] [user@]hostname [command] 15 16DESCRIPTION 17 ssh (SSH client) is a program for logging into a remote machine and for 18 executing commands on a remote machine. It is intended to replace rlogin 19 and rsh, and provide secure encrypted communications between two 20 untrusted hosts over an insecure network. X11 connections, arbitrary TCP 21 ports and UNIX-domain sockets can also be forwarded over the secure 22 channel. 23 24 ssh connects and logs into the specified hostname (with optional user 25 name). The user must prove his/her identity to the remote machine using 26 one of several methods depending on the protocol version used (see 27 below). 28 29 If command is specified, it is executed on the remote host instead of a 30 login shell. 31 32 The options are as follows: 33 34 -1 Forces ssh to try protocol version 1 only. 35 36 -2 Forces ssh to try protocol version 2 only. 37 38 -4 Forces ssh to use IPv4 addresses only. 39 40 -6 Forces ssh to use IPv6 addresses only. 41 42 -A Enables forwarding of the authentication agent connection. This 43 can also be specified on a per-host basis in a configuration 44 file. 45 46 Agent forwarding should be enabled with caution. Users with the 47 ability to bypass file permissions on the remote host (for the 48 agent's UNIX-domain socket) can access the local agent through 49 the forwarded connection. An attacker cannot obtain key material 50 from the agent, however they can perform operations on the keys 51 that enable them to authenticate using the identities loaded into 52 the agent. 53 54 -a Disables forwarding of the authentication agent connection. 55 56 -b bind_address 57 Use bind_address on the local machine as the source address of 58 the connection. Only useful on systems with more than one 59 address. 60 61 -C Requests compression of all data (including stdin, stdout, 62 stderr, and data for forwarded X11, TCP and UNIX-domain 63 connections). The compression algorithm is the same used by 64 gzip(1), and the M-bM-^@M-^\levelM-bM-^@M-^] can be controlled by the 65 CompressionLevel option for protocol version 1. Compression is 66 desirable on modem lines and other slow connections, but will 67 only slow down things on fast networks. The default value can be 68 set on a host-by-host basis in the configuration files; see the 69 Compression option. 70 71 -c cipher_spec 72 Selects the cipher specification for encrypting the session. 73 74 Protocol version 1 allows specification of a single cipher. The 75 supported values are M-bM-^@M-^\3desM-bM-^@M-^], M-bM-^@M-^\blowfishM-bM-^@M-^], and M-bM-^@M-^\desM-bM-^@M-^]. For protocol 76 version 2, cipher_spec is a comma-separated list of ciphers 77 listed in order of preference. See the Ciphers keyword in 78 ssh_config(5) for more information. 79 80 -D [bind_address:]port 81 Specifies a local M-bM-^@M-^\dynamicM-bM-^@M-^] application-level port forwarding. 82 This works by allocating a socket to listen to port on the local 83 side, optionally bound to the specified bind_address. Whenever a 84 connection is made to this port, the connection is forwarded over 85 the secure channel, and the application protocol is then used to 86 determine where to connect to from the remote machine. Currently 87 the SOCKS4 and SOCKS5 protocols are supported, and ssh will act 88 as a SOCKS server. Only root can forward privileged ports. 89 Dynamic port forwardings can also be specified in the 90 configuration file. 91 92 IPv6 addresses can be specified by enclosing the address in 93 square brackets. Only the superuser can forward privileged 94 ports. By default, the local port is bound in accordance with 95 the GatewayPorts setting. However, an explicit bind_address may 96 be used to bind the connection to a specific address. The 97 bind_address of M-bM-^@M-^\localhostM-bM-^@M-^] indicates that the listening port be 98 bound for local use only, while an empty address or M-bM-^@M-^X*M-bM-^@M-^Y indicates 99 that the port should be available from all interfaces. 100 101 -E log_file 102 Append debug logs to log_file instead of standard error. 103 104 -e escape_char 105 Sets the escape character for sessions with a pty (default: M-bM-^@M-^X~M-bM-^@M-^Y). 106 The escape character is only recognized at the beginning of a 107 line. The escape character followed by a dot (M-bM-^@M-^X.M-bM-^@M-^Y) closes the 108 connection; followed by control-Z suspends the connection; and 109 followed by itself sends the escape character once. Setting the 110 character to M-bM-^@M-^\noneM-bM-^@M-^] disables any escapes and makes the session 111 fully transparent. 112 113 -F configfile 114 Specifies an alternative per-user configuration file. If a 115 configuration file is given on the command line, the system-wide 116 configuration file (/etc/ssh/ssh_config) will be ignored. The 117 default for the per-user configuration file is ~/.ssh/config. 118 119 -f Requests ssh to go to background just before command execution. 120 This is useful if ssh is going to ask for passwords or 121 passphrases, but the user wants it in the background. This 122 implies -n. The recommended way to start X11 programs at a 123 remote site is with something like ssh -f host xterm. 124 125 If the ExitOnForwardFailure configuration option is set to M-bM-^@M-^\yesM-bM-^@M-^], 126 then a client started with -f will wait for all remote port 127 forwards to be successfully established before placing itself in 128 the background. 129 130 -G Causes ssh to print its configuration after evaluating Host and 131 Match blocks and exit. 132 133 -g Allows remote hosts to connect to local forwarded ports. If used 134 on a multiplexed connection, then this option must be specified 135 on the master process. 136 137 -I pkcs11 138 Specify the PKCS#11 shared library ssh should use to communicate 139 with a PKCS#11 token providing the user's private RSA key. 140 141 -i identity_file 142 Selects a file from which the identity (private key) for public 143 key authentication is read. The default is ~/.ssh/identity for 144 protocol version 1, and ~/.ssh/id_dsa, ~/.ssh/id_ecdsa, 145 ~/.ssh/id_ed25519 and ~/.ssh/id_rsa for protocol version 2. 146 Identity files may also be specified on a per-host basis in the 147 configuration file. It is possible to have multiple -i options 148 (and multiple identities specified in configuration files). ssh 149 will also try to load certificate information from the filename 150 obtained by appending -cert.pub to identity filenames. 151 152 -K Enables GSSAPI-based authentication and forwarding (delegation) 153 of GSSAPI credentials to the server. 154 155 -k Disables forwarding (delegation) of GSSAPI credentials to the 156 server. 157 158 -L [bind_address:]port:host:hostport 159 Specifies that the given port on the local (client) host is to be 160 forwarded to the given host and port on the remote side. This 161 works by allocating a socket to listen to port on the local side, 162 optionally bound to the specified bind_address. Whenever a 163 connection is made to this port, the connection is forwarded over 164 the secure channel, and a connection is made to host port 165 hostport from the remote machine. Port forwardings can also be 166 specified in the configuration file. IPv6 addresses can be 167 specified by enclosing the address in square brackets. Only the 168 superuser can forward privileged ports. By default, the local 169 port is bound in accordance with the GatewayPorts setting. 170 However, an explicit bind_address may be used to bind the 171 connection to a specific address. The bind_address of 172 M-bM-^@M-^\localhostM-bM-^@M-^] indicates that the listening port be bound for local 173 use only, while an empty address or M-bM-^@M-^X*M-bM-^@M-^Y indicates that the port 174 should be available from all interfaces. 175 176 -l login_name 177 Specifies the user to log in as on the remote machine. This also 178 may be specified on a per-host basis in the configuration file. 179 180 -M Places the ssh client into M-bM-^@M-^\masterM-bM-^@M-^] mode for connection sharing. 181 Multiple -M options places ssh into M-bM-^@M-^\masterM-bM-^@M-^] mode with 182 confirmation required before slave connections are accepted. 183 Refer to the description of ControlMaster in ssh_config(5) for 184 details. 185 186 -m mac_spec 187 Additionally, for protocol version 2 a comma-separated list of 188 MAC (message authentication code) algorithms can be specified in 189 order of preference. See the MACs keyword for more information. 190 191 -N Do not execute a remote command. This is useful for just 192 forwarding ports (protocol version 2 only). 193 194 -n Redirects stdin from /dev/null (actually, prevents reading from 195 stdin). This must be used when ssh is run in the background. A 196 common trick is to use this to run X11 programs on a remote 197 machine. For example, ssh -n shadows.cs.hut.fi emacs & will 198 start an emacs on shadows.cs.hut.fi, and the X11 connection will 199 be automatically forwarded over an encrypted channel. The ssh 200 program will be put in the background. (This does not work if 201 ssh needs to ask for a password or passphrase; see also the -f 202 option.) 203 204 -O ctl_cmd 205 Control an active connection multiplexing master process. When 206 the -O option is specified, the ctl_cmd argument is interpreted 207 and passed to the master process. Valid commands are: M-bM-^@M-^\checkM-bM-^@M-^] 208 (check that the master process is running), M-bM-^@M-^\forwardM-bM-^@M-^] (request 209 forwardings without command execution), M-bM-^@M-^\cancelM-bM-^@M-^] (cancel 210 forwardings), M-bM-^@M-^\exitM-bM-^@M-^] (request the master to exit), and M-bM-^@M-^\stopM-bM-^@M-^] 211 (request the master to stop accepting further multiplexing 212 requests). 213 214 -o option 215 Can be used to give options in the format used in the 216 configuration file. This is useful for specifying options for 217 which there is no separate command-line flag. For full details 218 of the options listed below, and their possible values, see 219 ssh_config(5). 220 221 AddressFamily 222 BatchMode 223 BindAddress 224 CanonicalDomains 225 CanonicalizeFallbackLocal 226 CanonicalizeHostname 227 CanonicalizeMaxDots 228 CanonicalizePermittedCNAMEs 229 ChallengeResponseAuthentication 230 CheckHostIP 231 Cipher 232 Ciphers 233 ClearAllForwardings 234 Compression 235 CompressionLevel 236 ConnectionAttempts 237 ConnectTimeout 238 ControlMaster 239 ControlPath 240 ControlPersist 241 DynamicForward 242 EscapeChar 243 ExitOnForwardFailure 244 FingerprintHash 245 ForwardAgent 246 ForwardX11 247 ForwardX11Timeout 248 ForwardX11Trusted 249 GatewayPorts 250 GlobalKnownHostsFile 251 GSSAPIAuthentication 252 GSSAPIDelegateCredentials 253 HashKnownHosts 254 Host 255 HostbasedAuthentication 256 HostbasedKeyTypes 257 HostKeyAlgorithms 258 HostKeyAlias 259 HostName 260 IdentityFile 261 IdentitiesOnly 262 IPQoS 263 KbdInteractiveAuthentication 264 KbdInteractiveDevices 265 KexAlgorithms 266 LocalCommand 267 LocalForward 268 LogLevel 269 MACs 270 Match 271 NoHostAuthenticationForLocalhost 272 NumberOfPasswordPrompts 273 PasswordAuthentication 274 PermitLocalCommand 275 PKCS11Provider 276 Port 277 PreferredAuthentications 278 Protocol 279 ProxyCommand 280 ProxyUseFdpass 281 PubkeyAuthentication 282 RekeyLimit 283 RemoteForward 284 RequestTTY 285 RhostsRSAAuthentication 286 RSAAuthentication 287 SendEnv 288 ServerAliveInterval 289 ServerAliveCountMax 290 StreamLocalBindMask 291 StreamLocalBindUnlink 292 StrictHostKeyChecking 293 TCPKeepAlive 294 Tunnel 295 TunnelDevice 296 UpdateHostKeys 297 UsePrivilegedPort 298 User 299 UserKnownHostsFile 300 VerifyHostKeyDNS 301 VisualHostKey 302 XAuthLocation 303 304 -p port 305 Port to connect to on the remote host. This can be specified on 306 a per-host basis in the configuration file. 307 308 -Q cipher | cipher-auth | mac | kex | key | protocol-version 309 Queries ssh for the algorithms supported for the specified 310 version 2. The available features are: cipher (supported 311 symmetric ciphers), cipher-auth (supported symmetric ciphers that 312 support authenticated encryption), mac (supported message 313 integrity codes), kex (key exchange algorithms), key (key types) 314 and protocol-version (supported SSH protocol versions). 315 316 -q Quiet mode. Causes most warning and diagnostic messages to be 317 suppressed. 318 319 -R [bind_address:]port:host:hostport 320 Specifies that the given port on the remote (server) host is to 321 be forwarded to the given host and port on the local side. This 322 works by allocating a socket to listen to port on the remote 323 side, and whenever a connection is made to this port, the 324 connection is forwarded over the secure channel, and a connection 325 is made to host port hostport from the local machine. 326 327 Port forwardings can also be specified in the configuration file. 328 Privileged ports can be forwarded only when logging in as root on 329 the remote machine. IPv6 addresses can be specified by enclosing 330 the address in square brackets. 331 332 By default, the listening socket on the server will be bound to 333 the loopback interface only. This may be overridden by 334 specifying a bind_address. An empty bind_address, or the address 335 M-bM-^@M-^X*M-bM-^@M-^Y, indicates that the remote socket should listen on all 336 interfaces. Specifying a remote bind_address will only succeed 337 if the server's GatewayPorts option is enabled (see 338 sshd_config(5)). 339 340 If the port argument is M-bM-^@M-^X0M-bM-^@M-^Y, the listen port will be dynamically 341 allocated on the server and reported to the client at run time. 342 When used together with -O forward the allocated port will be 343 printed to the standard output. 344 345 -S ctl_path 346 Specifies the location of a control socket for connection 347 sharing, or the string M-bM-^@M-^\noneM-bM-^@M-^] to disable connection sharing. 348 Refer to the description of ControlPath and ControlMaster in 349 ssh_config(5) for details. 350 351 -s May be used to request invocation of a subsystem on the remote 352 system. Subsystems are a feature of the SSH2 protocol which 353 facilitate the use of SSH as a secure transport for other 354 applications (eg. sftp(1)). The subsystem is specified as the 355 remote command. 356 357 -T Disable pseudo-tty allocation. 358 359 -t Force pseudo-tty allocation. This can be used to execute 360 arbitrary screen-based programs on a remote machine, which can be 361 very useful, e.g. when implementing menu services. Multiple -t 362 options force tty allocation, even if ssh has no local tty. 363 364 -V Display the version number and exit. 365 366 -v Verbose mode. Causes ssh to print debugging messages about its 367 progress. This is helpful in debugging connection, 368 authentication, and configuration problems. Multiple -v options 369 increase the verbosity. The maximum is 3. 370 371 -W host:port 372 Requests that standard input and output on the client be 373 forwarded to host on port over the secure channel. Implies -N, 374 -T, ExitOnForwardFailure and ClearAllForwardings. Works with 375 Protocol version 2 only. 376 377 -w local_tun[:remote_tun] 378 Requests tunnel device forwarding with the specified tun(4) 379 devices between the client (local_tun) and the server 380 (remote_tun). 381 382 The devices may be specified by numerical ID or the keyword 383 M-bM-^@M-^\anyM-bM-^@M-^], which uses the next available tunnel device. If 384 remote_tun is not specified, it defaults to M-bM-^@M-^\anyM-bM-^@M-^]. See also the 385 Tunnel and TunnelDevice directives in ssh_config(5). If the 386 Tunnel directive is unset, it is set to the default tunnel mode, 387 which is M-bM-^@M-^\point-to-pointM-bM-^@M-^]. 388 389 -X Enables X11 forwarding. This can also be specified on a per-host 390 basis in a configuration file. 391 392 X11 forwarding should be enabled with caution. Users with the 393 ability to bypass file permissions on the remote host (for the 394 user's X authorization database) can access the local X11 display 395 through the forwarded connection. An attacker may then be able 396 to perform activities such as keystroke monitoring. 397 398 For this reason, X11 forwarding is subjected to X11 SECURITY 399 extension restrictions by default. Please refer to the ssh -Y 400 option and the ForwardX11Trusted directive in ssh_config(5) for 401 more information. 402 403 -x Disables X11 forwarding. 404 405 -Y Enables trusted X11 forwarding. Trusted X11 forwardings are not 406 subjected to the X11 SECURITY extension controls. 407 408 -y Send log information using the syslog(3) system module. By 409 default this information is sent to stderr. 410 411 ssh may additionally obtain configuration data from a per-user 412 configuration file and a system-wide configuration file. The file format 413 and configuration options are described in ssh_config(5). 414 415AUTHENTICATION 416 The OpenSSH SSH client supports SSH protocols 1 and 2. The default is to 417 use protocol 2 only, though this can be changed via the Protocol option 418 in ssh_config(5) or the -1 and -2 options (see above). Both protocols 419 support similar authentication methods, but protocol 2 is the default 420 since it provides additional mechanisms for confidentiality (the traffic 421 is encrypted using AES, 3DES, Blowfish, CAST128, or Arcfour) and 422 integrity (hmac-md5, hmac-sha1, hmac-sha2-256, hmac-sha2-512, umac-64, 423 umac-128, hmac-ripemd160). Protocol 1 lacks a strong mechanism for 424 ensuring the integrity of the connection. 425 426 The methods available for authentication are: GSSAPI-based 427 authentication, host-based authentication, public key authentication, 428 challenge-response authentication, and password authentication. 429 Authentication methods are tried in the order specified above, though 430 protocol 2 has a configuration option to change the default order: 431 PreferredAuthentications. 432 433 Host-based authentication works as follows: If the machine the user logs 434 in from is listed in /etc/hosts.equiv or /etc/shosts.equiv on the remote 435 machine, and the user names are the same on both sides, or if the files 436 ~/.rhosts or ~/.shosts exist in the user's home directory on the remote 437 machine and contain a line containing the name of the client machine and 438 the name of the user on that machine, the user is considered for login. 439 Additionally, the server must be able to verify the client's host key 440 (see the description of /etc/ssh/ssh_known_hosts and ~/.ssh/known_hosts, 441 below) for login to be permitted. This authentication method closes 442 security holes due to IP spoofing, DNS spoofing, and routing spoofing. 443 [Note to the administrator: /etc/hosts.equiv, ~/.rhosts, and the 444 rlogin/rsh protocol in general, are inherently insecure and should be 445 disabled if security is desired.] 446 447 Public key authentication works as follows: The scheme is based on 448 public-key cryptography, using cryptosystems where encryption and 449 decryption are done using separate keys, and it is unfeasible to derive 450 the decryption key from the encryption key. The idea is that each user 451 creates a public/private key pair for authentication purposes. The 452 server knows the public key, and only the user knows the private key. 453 ssh implements public key authentication protocol automatically, using 454 one of the DSA, ECDSA, Ed25519 or RSA algorithms. Protocol 1 is 455 restricted to using only RSA keys, but protocol 2 may use any. The 456 HISTORY section of ssl(8) contains a brief discussion of the DSA and RSA 457 algorithms. 458 459 The file ~/.ssh/authorized_keys lists the public keys that are permitted 460 for logging in. When the user logs in, the ssh program tells the server 461 which key pair it would like to use for authentication. The client 462 proves that it has access to the private key and the server checks that 463 the corresponding public key is authorized to accept the account. 464 465 The user creates his/her key pair by running ssh-keygen(1). This stores 466 the private key in ~/.ssh/identity (protocol 1), ~/.ssh/id_dsa (protocol 467 2 DSA), ~/.ssh/id_ecdsa (protocol 2 ECDSA), ~/.ssh/id_ed25519 (protocol 2 468 Ed25519), or ~/.ssh/id_rsa (protocol 2 RSA) and stores the public key in 469 ~/.ssh/identity.pub (protocol 1), ~/.ssh/id_dsa.pub (protocol 2 DSA), 470 ~/.ssh/id_ecdsa.pub (protocol 2 ECDSA), ~/.ssh/id_ed25519.pub (protocol 2 471 Ed25519), or ~/.ssh/id_rsa.pub (protocol 2 RSA) in the user's home 472 directory. The user should then copy the public key to 473 ~/.ssh/authorized_keys in his/her home directory on the remote machine. 474 The authorized_keys file corresponds to the conventional ~/.rhosts file, 475 and has one key per line, though the lines can be very long. After this, 476 the user can log in without giving the password. 477 478 A variation on public key authentication is available in the form of 479 certificate authentication: instead of a set of public/private keys, 480 signed certificates are used. This has the advantage that a single 481 trusted certification authority can be used in place of many 482 public/private keys. See the CERTIFICATES section of ssh-keygen(1) for 483 more information. 484 485 The most convenient way to use public key or certificate authentication 486 may be with an authentication agent. See ssh-agent(1) for more 487 information. 488 489 Challenge-response authentication works as follows: The server sends an 490 arbitrary "challenge" text, and prompts for a response. Protocol 2 491 allows multiple challenges and responses; protocol 1 is restricted to 492 just one challenge/response. Examples of challenge-response 493 authentication include BSD Authentication (see login.conf(5)) and PAM 494 (some non-OpenBSD systems). 495 496 Finally, if other authentication methods fail, ssh prompts the user for a 497 password. The password is sent to the remote host for checking; however, 498 since all communications are encrypted, the password cannot be seen by 499 someone listening on the network. 500 501 ssh automatically maintains and checks a database containing 502 identification for all hosts it has ever been used with. Host keys are 503 stored in ~/.ssh/known_hosts in the user's home directory. Additionally, 504 the file /etc/ssh/ssh_known_hosts is automatically checked for known 505 hosts. Any new hosts are automatically added to the user's file. If a 506 host's identification ever changes, ssh warns about this and disables 507 password authentication to prevent server spoofing or man-in-the-middle 508 attacks, which could otherwise be used to circumvent the encryption. The 509 StrictHostKeyChecking option can be used to control logins to machines 510 whose host key is not known or has changed. 511 512 When the user's identity has been accepted by the server, the server 513 either executes the given command, or logs into the machine and gives the 514 user a normal shell on the remote machine. All communication with the 515 remote command or shell will be automatically encrypted. 516 517 If a pseudo-terminal has been allocated (normal login session), the user 518 may use the escape characters noted below. 519 520 If no pseudo-tty has been allocated, the session is transparent and can 521 be used to reliably transfer binary data. On most systems, setting the 522 escape character to M-bM-^@M-^\noneM-bM-^@M-^] will also make the session transparent even if 523 a tty is used. 524 525 The session terminates when the command or shell on the remote machine 526 exits and all X11 and TCP connections have been closed. 527 528ESCAPE CHARACTERS 529 When a pseudo-terminal has been requested, ssh supports a number of 530 functions through the use of an escape character. 531 532 A single tilde character can be sent as ~~ or by following the tilde by a 533 character other than those described below. The escape character must 534 always follow a newline to be interpreted as special. The escape 535 character can be changed in configuration files using the EscapeChar 536 configuration directive or on the command line by the -e option. 537 538 The supported escapes (assuming the default M-bM-^@M-^X~M-bM-^@M-^Y) are: 539 540 ~. Disconnect. 541 542 ~^Z Background ssh. 543 544 ~# List forwarded connections. 545 546 ~& Background ssh at logout when waiting for forwarded connection / 547 X11 sessions to terminate. 548 549 ~? Display a list of escape characters. 550 551 ~B Send a BREAK to the remote system (only useful for SSH protocol 552 version 2 and if the peer supports it). 553 554 ~C Open command line. Currently this allows the addition of port 555 forwardings using the -L, -R and -D options (see above). It also 556 allows the cancellation of existing port-forwardings with 557 -KL[bind_address:]port for local, -KR[bind_address:]port for 558 remote and -KD[bind_address:]port for dynamic port-forwardings. 559 !command allows the user to execute a local command if the 560 PermitLocalCommand option is enabled in ssh_config(5). Basic 561 help is available, using the -h option. 562 563 ~R Request rekeying of the connection (only useful for SSH protocol 564 version 2 and if the peer supports it). 565 566 ~V Decrease the verbosity (LogLevel) when errors are being written 567 to stderr. 568 569 ~v Increase the verbosity (LogLevel) when errors are being written 570 to stderr. 571 572TCP FORWARDING 573 Forwarding of arbitrary TCP connections over the secure channel can be 574 specified either on the command line or in a configuration file. One 575 possible application of TCP forwarding is a secure connection to a mail 576 server; another is going through firewalls. 577 578 In the example below, we look at encrypting communication between an IRC 579 client and server, even though the IRC server does not directly support 580 encrypted communications. This works as follows: the user connects to 581 the remote host using ssh, specifying a port to be used to forward 582 connections to the remote server. After that it is possible to start the 583 service which is to be encrypted on the client machine, connecting to the 584 same local port, and ssh will encrypt and forward the connection. 585 586 The following example tunnels an IRC session from client machine 587 M-bM-^@M-^\127.0.0.1M-bM-^@M-^] (localhost) to remote server M-bM-^@M-^\server.example.comM-bM-^@M-^]: 588 589 $ ssh -f -L 1234:localhost:6667 server.example.com sleep 10 590 $ irc -c '#users' -p 1234 pinky 127.0.0.1 591 592 This tunnels a connection to IRC server M-bM-^@M-^\server.example.comM-bM-^@M-^], joining 593 channel M-bM-^@M-^\#usersM-bM-^@M-^], nickname M-bM-^@M-^\pinkyM-bM-^@M-^], using port 1234. It doesn't matter 594 which port is used, as long as it's greater than 1023 (remember, only 595 root can open sockets on privileged ports) and doesn't conflict with any 596 ports already in use. The connection is forwarded to port 6667 on the 597 remote server, since that's the standard port for IRC services. 598 599 The -f option backgrounds ssh and the remote command M-bM-^@M-^\sleep 10M-bM-^@M-^] is 600 specified to allow an amount of time (10 seconds, in the example) to 601 start the service which is to be tunnelled. If no connections are made 602 within the time specified, ssh will exit. 603 604X11 FORWARDING 605 If the ForwardX11 variable is set to M-bM-^@M-^\yesM-bM-^@M-^] (or see the description of the 606 -X, -x, and -Y options above) and the user is using X11 (the DISPLAY 607 environment variable is set), the connection to the X11 display is 608 automatically forwarded to the remote side in such a way that any X11 609 programs started from the shell (or command) will go through the 610 encrypted channel, and the connection to the real X server will be made 611 from the local machine. The user should not manually set DISPLAY. 612 Forwarding of X11 connections can be configured on the command line or in 613 configuration files. 614 615 The DISPLAY value set by ssh will point to the server machine, but with a 616 display number greater than zero. This is normal, and happens because 617 ssh creates a M-bM-^@M-^\proxyM-bM-^@M-^] X server on the server machine for forwarding the 618 connections over the encrypted channel. 619 620 ssh will also automatically set up Xauthority data on the server machine. 621 For this purpose, it will generate a random authorization cookie, store 622 it in Xauthority on the server, and verify that any forwarded connections 623 carry this cookie and replace it by the real cookie when the connection 624 is opened. The real authentication cookie is never sent to the server 625 machine (and no cookies are sent in the plain). 626 627 If the ForwardAgent variable is set to M-bM-^@M-^\yesM-bM-^@M-^] (or see the description of 628 the -A and -a options above) and the user is using an authentication 629 agent, the connection to the agent is automatically forwarded to the 630 remote side. 631 632VERIFYING HOST KEYS 633 When connecting to a server for the first time, a fingerprint of the 634 server's public key is presented to the user (unless the option 635 StrictHostKeyChecking has been disabled). Fingerprints can be determined 636 using ssh-keygen(1): 637 638 $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key 639 640 If the fingerprint is already known, it can be matched and the key can be 641 accepted or rejected. Because of the difficulty of comparing host keys 642 just by looking at fingerprint strings, there is also support to compare 643 host keys visually, using random art. By setting the VisualHostKey 644 option to M-bM-^@M-^\yesM-bM-^@M-^], a small ASCII graphic gets displayed on every login to a 645 server, no matter if the session itself is interactive or not. By 646 learning the pattern a known server produces, a user can easily find out 647 that the host key has changed when a completely different pattern is 648 displayed. Because these patterns are not unambiguous however, a pattern 649 that looks similar to the pattern remembered only gives a good 650 probability that the host key is the same, not guaranteed proof. 651 652 To get a listing of the fingerprints along with their random art for all 653 known hosts, the following command line can be used: 654 655 $ ssh-keygen -lv -f ~/.ssh/known_hosts 656 657 If the fingerprint is unknown, an alternative method of verification is 658 available: SSH fingerprints verified by DNS. An additional resource 659 record (RR), SSHFP, is added to a zonefile and the connecting client is 660 able to match the fingerprint with that of the key presented. 661 662 In this example, we are connecting a client to a server, 663 M-bM-^@M-^\host.example.comM-bM-^@M-^]. The SSHFP resource records should first be added to 664 the zonefile for host.example.com: 665 666 $ ssh-keygen -r host.example.com. 667 668 The output lines will have to be added to the zonefile. To check that 669 the zone is answering fingerprint queries: 670 671 $ dig -t SSHFP host.example.com 672 673 Finally the client connects: 674 675 $ ssh -o "VerifyHostKeyDNS ask" host.example.com 676 [...] 677 Matching host key fingerprint found in DNS. 678 Are you sure you want to continue connecting (yes/no)? 679 680 See the VerifyHostKeyDNS option in ssh_config(5) for more information. 681 682SSH-BASED VIRTUAL PRIVATE NETWORKS 683 ssh contains support for Virtual Private Network (VPN) tunnelling using 684 the tun(4) network pseudo-device, allowing two networks to be joined 685 securely. The sshd_config(5) configuration option PermitTunnel controls 686 whether the server supports this, and at what level (layer 2 or 3 687 traffic). 688 689 The following example would connect client network 10.0.50.0/24 with 690 remote network 10.0.99.0/24 using a point-to-point connection from 691 10.1.1.1 to 10.1.1.2, provided that the SSH server running on the gateway 692 to the remote network, at 192.168.1.15, allows it. 693 694 On the client: 695 696 # ssh -f -w 0:1 192.168.1.15 true 697 # ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252 698 # route add 10.0.99.0/24 10.1.1.2 699 700 On the server: 701 702 # ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252 703 # route add 10.0.50.0/24 10.1.1.1 704 705 Client access may be more finely tuned via the /root/.ssh/authorized_keys 706 file (see below) and the PermitRootLogin server option. The following 707 entry would permit connections on tun(4) device 1 from user M-bM-^@M-^\janeM-bM-^@M-^] and on 708 tun device 2 from user M-bM-^@M-^\johnM-bM-^@M-^], if PermitRootLogin is set to 709 M-bM-^@M-^\forced-commands-onlyM-bM-^@M-^]: 710 711 tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane 712 tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john 713 714 Since an SSH-based setup entails a fair amount of overhead, it may be 715 more suited to temporary setups, such as for wireless VPNs. More 716 permanent VPNs are better provided by tools such as ipsecctl(8) and 717 isakmpd(8). 718 719ENVIRONMENT 720 ssh will normally set the following environment variables: 721 722 DISPLAY The DISPLAY variable indicates the location of the 723 X11 server. It is automatically set by ssh to 724 point to a value of the form M-bM-^@M-^\hostname:nM-bM-^@M-^], where 725 M-bM-^@M-^\hostnameM-bM-^@M-^] indicates the host where the shell runs, 726 and M-bM-^@M-^XnM-bM-^@M-^Y is an integer M-bM-^IM-% 1. ssh uses this special 727 value to forward X11 connections over the secure 728 channel. The user should normally not set DISPLAY 729 explicitly, as that will render the X11 connection 730 insecure (and will require the user to manually 731 copy any required authorization cookies). 732 733 HOME Set to the path of the user's home directory. 734 735 LOGNAME Synonym for USER; set for compatibility with 736 systems that use this variable. 737 738 MAIL Set to the path of the user's mailbox. 739 740 PATH Set to the default PATH, as specified when 741 compiling ssh. 742 743 SSH_ASKPASS If ssh needs a passphrase, it will read the 744 passphrase from the current terminal if it was run 745 from a terminal. If ssh does not have a terminal 746 associated with it but DISPLAY and SSH_ASKPASS are 747 set, it will execute the program specified by 748 SSH_ASKPASS and open an X11 window to read the 749 passphrase. This is particularly useful when 750 calling ssh from a .xsession or related script. 751 (Note that on some machines it may be necessary to 752 redirect the input from /dev/null to make this 753 work.) 754 755 SSH_AUTH_SOCK Identifies the path of a UNIX-domain socket used to 756 communicate with the agent. 757 758 SSH_CONNECTION Identifies the client and server ends of the 759 connection. The variable contains four space- 760 separated values: client IP address, client port 761 number, server IP address, and server port number. 762 763 SSH_ORIGINAL_COMMAND This variable contains the original command line if 764 a forced command is executed. It can be used to 765 extract the original arguments. 766 767 SSH_TTY This is set to the name of the tty (path to the 768 device) associated with the current shell or 769 command. If the current session has no tty, this 770 variable is not set. 771 772 TZ This variable is set to indicate the present time 773 zone if it was set when the daemon was started 774 (i.e. the daemon passes the value on to new 775 connections). 776 777 USER Set to the name of the user logging in. 778 779 Additionally, ssh reads ~/.ssh/environment, and adds lines of the format 780 M-bM-^@M-^\VARNAME=valueM-bM-^@M-^] to the environment if the file exists and users are 781 allowed to change their environment. For more information, see the 782 PermitUserEnvironment option in sshd_config(5). 783 784FILES 785 ~/.rhosts 786 This file is used for host-based authentication (see above). On 787 some machines this file may need to be world-readable if the 788 user's home directory is on an NFS partition, because sshd(8) 789 reads it as root. Additionally, this file must be owned by the 790 user, and must not have write permissions for anyone else. The 791 recommended permission for most machines is read/write for the 792 user, and not accessible by others. 793 794 ~/.shosts 795 This file is used in exactly the same way as .rhosts, but allows 796 host-based authentication without permitting login with 797 rlogin/rsh. 798 799 ~/.ssh/ 800 This directory is the default location for all user-specific 801 configuration and authentication information. There is no 802 general requirement to keep the entire contents of this directory 803 secret, but the recommended permissions are read/write/execute 804 for the user, and not accessible by others. 805 806 ~/.ssh/authorized_keys 807 Lists the public keys (DSA, ECDSA, Ed25519, RSA) that can be used 808 for logging in as this user. The format of this file is 809 described in the sshd(8) manual page. This file is not highly 810 sensitive, but the recommended permissions are read/write for the 811 user, and not accessible by others. 812 813 ~/.ssh/config 814 This is the per-user configuration file. The file format and 815 configuration options are described in ssh_config(5). Because of 816 the potential for abuse, this file must have strict permissions: 817 read/write for the user, and not writable by others. 818 819 ~/.ssh/environment 820 Contains additional definitions for environment variables; see 821 ENVIRONMENT, above. 822 823 ~/.ssh/identity 824 ~/.ssh/id_dsa 825 ~/.ssh/id_ecdsa 826 ~/.ssh/id_ed25519 827 ~/.ssh/id_rsa 828 Contains the private key for authentication. These files contain 829 sensitive data and should be readable by the user but not 830 accessible by others (read/write/execute). ssh will simply 831 ignore a private key file if it is accessible by others. It is 832 possible to specify a passphrase when generating the key which 833 will be used to encrypt the sensitive part of this file using 834 3DES. 835 836 ~/.ssh/identity.pub 837 ~/.ssh/id_dsa.pub 838 ~/.ssh/id_ecdsa.pub 839 ~/.ssh/id_ed25519.pub 840 ~/.ssh/id_rsa.pub 841 Contains the public key for authentication. These files are not 842 sensitive and can (but need not) be readable by anyone. 843 844 ~/.ssh/known_hosts 845 Contains a list of host keys for all hosts the user has logged 846 into that are not already in the systemwide list of known host 847 keys. See sshd(8) for further details of the format of this 848 file. 849 850 ~/.ssh/rc 851 Commands in this file are executed by ssh when the user logs in, 852 just before the user's shell (or command) is started. See the 853 sshd(8) manual page for more information. 854 855 /etc/hosts.equiv 856 This file is for host-based authentication (see above). It 857 should only be writable by root. 858 859 /etc/shosts.equiv 860 This file is used in exactly the same way as hosts.equiv, but 861 allows host-based authentication without permitting login with 862 rlogin/rsh. 863 864 /etc/ssh/ssh_config 865 Systemwide configuration file. The file format and configuration 866 options are described in ssh_config(5). 867 868 /etc/ssh/ssh_host_key 869 /etc/ssh/ssh_host_dsa_key 870 /etc/ssh/ssh_host_ecdsa_key 871 /etc/ssh/ssh_host_ed25519_key 872 /etc/ssh/ssh_host_rsa_key 873 These files contain the private parts of the host keys and are 874 used for host-based authentication. If protocol version 1 is 875 used, ssh must be setuid root, since the host key is readable 876 only by root. For protocol version 2, ssh uses ssh-keysign(8) to 877 access the host keys, eliminating the requirement that ssh be 878 setuid root when host-based authentication is used. By default 879 ssh is not setuid root. 880 881 /etc/ssh/ssh_known_hosts 882 Systemwide list of known host keys. This file should be prepared 883 by the system administrator to contain the public host keys of 884 all machines in the organization. It should be world-readable. 885 See sshd(8) for further details of the format of this file. 886 887 /etc/ssh/sshrc 888 Commands in this file are executed by ssh when the user logs in, 889 just before the user's shell (or command) is started. See the 890 sshd(8) manual page for more information. 891 892EXIT STATUS 893 ssh exits with the exit status of the remote command or with 255 if an 894 error occurred. 895 896SEE ALSO 897 scp(1), sftp(1), ssh-add(1), ssh-agent(1), ssh-keygen(1), ssh-keyscan(1), 898 tun(4), ssh_config(5), ssh-keysign(8), sshd(8) 899 900STANDARDS 901 S. Lehtinen and C. Lonvick, The Secure Shell (SSH) Protocol Assigned 902 Numbers, RFC 4250, January 2006. 903 904 T. Ylonen and C. Lonvick, The Secure Shell (SSH) Protocol Architecture, 905 RFC 4251, January 2006. 906 907 T. Ylonen and C. Lonvick, The Secure Shell (SSH) Authentication Protocol, 908 RFC 4252, January 2006. 909 910 T. Ylonen and C. Lonvick, The Secure Shell (SSH) Transport Layer 911 Protocol, RFC 4253, January 2006. 912 913 T. Ylonen and C. Lonvick, The Secure Shell (SSH) Connection Protocol, RFC 914 4254, January 2006. 915 916 J. Schlyter and W. Griffin, Using DNS to Securely Publish Secure Shell 917 (SSH) Key Fingerprints, RFC 4255, January 2006. 918 919 F. Cusack and M. Forssen, Generic Message Exchange Authentication for the 920 Secure Shell Protocol (SSH), RFC 4256, January 2006. 921 922 J. Galbraith and P. Remaker, The Secure Shell (SSH) Session Channel Break 923 Extension, RFC 4335, January 2006. 924 925 M. Bellare, T. Kohno, and C. Namprempre, The Secure Shell (SSH) Transport 926 Layer Encryption Modes, RFC 4344, January 2006. 927 928 B. Harris, Improved Arcfour Modes for the Secure Shell (SSH) Transport 929 Layer Protocol, RFC 4345, January 2006. 930 931 M. Friedl, N. Provos, and W. Simpson, Diffie-Hellman Group Exchange for 932 the Secure Shell (SSH) Transport Layer Protocol, RFC 4419, March 2006. 933 934 J. Galbraith and R. Thayer, The Secure Shell (SSH) Public Key File 935 Format, RFC 4716, November 2006. 936 937 D. Stebila and J. Green, Elliptic Curve Algorithm Integration in the 938 Secure Shell Transport Layer, RFC 5656, December 2009. 939 940 A. Perrig and D. Song, Hash Visualization: a New Technique to improve 941 Real-World Security, 1999, International Workshop on Cryptographic 942 Techniques and E-Commerce (CrypTEC '99). 943 944AUTHORS 945 OpenSSH is a derivative of the original and free ssh 1.2.12 release by 946 Tatu Ylonen. Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, Theo 947 de Raadt and Dug Song removed many bugs, re-added newer features and 948 created OpenSSH. Markus Friedl contributed the support for SSH protocol 949 versions 1.5 and 2.0. 950 951OpenBSD 5.7 March 3, 2015 OpenBSD 5.7 952