1.\" -*- nroff -*- 2.\" 3.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 4.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 5.\" All rights reserved 6.\" 7.\" As far as I am concerned, the code I have written for this software 8.\" can be used freely for any purpose. Any derived versions of this 9.\" software must be clearly marked as such, and if the derived work is 10.\" incompatible with the protocol description in the RFC file, it must be 11.\" called by a name other than "ssh" or "Secure Shell". 12.\" 13.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. 14.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. 15.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. 16.\" 17.\" Redistribution and use in source and binary forms, with or without 18.\" modification, are permitted provided that the following conditions 19.\" are met: 20.\" 1. Redistributions of source code must retain the above copyright 21.\" notice, this list of conditions and the following disclaimer. 22.\" 2. Redistributions in binary form must reproduce the above copyright 23.\" notice, this list of conditions and the following disclaimer in the 24.\" documentation and/or other materials provided with the distribution. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 27.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 28.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 29.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 30.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 31.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 32.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 33.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 34.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 35.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 36.\" 37.\" $OpenBSD: ssh.1,v 1.287 2009/10/28 16:38:18 reyk Exp $ 38.Dd $Mdocdate: October 28 2009 $ 39.Dt SSH 1 40.Os 41.Sh NAME 42.Nm ssh 43.Nd OpenSSH SSH client (remote login program) 44.Sh SYNOPSIS 45.Nm ssh 46.Op Fl 1246AaCfgKkMNnqsTtVvXxYy 47.Op Fl b Ar bind_address 48.Op Fl c Ar cipher_spec 49.Oo Fl D\ \& 50.Sm off 51.Oo Ar bind_address : Oc 52.Ar port 53.Sm on 54.Oc 55.Op Fl e Ar escape_char 56.Op Fl F Ar configfile 57.Bk -words 58.Op Fl i Ar identity_file 59.Ek 60.Oo Fl L\ \& 61.Sm off 62.Oo Ar bind_address : Oc 63.Ar port : host : hostport 64.Sm on 65.Oc 66.Bk -words 67.Op Fl l Ar login_name 68.Ek 69.Op Fl m Ar mac_spec 70.Op Fl O Ar ctl_cmd 71.Op Fl o Ar option 72.Op Fl p Ar port 73.Oo Fl R\ \& 74.Sm off 75.Oo Ar bind_address : Oc 76.Ar port : host : hostport 77.Sm on 78.Oc 79.Op Fl S Ar ctl_path 80.Bk -words 81.Oo Fl w Ar local_tun Ns 82.Op : Ns Ar remote_tun Oc 83.Oo Ar user Ns @ Oc Ns Ar hostname 84.Op Ar command 85.Ek 86.Sh DESCRIPTION 87.Nm 88(SSH client) is a program for logging into a remote machine and for 89executing commands on a remote machine. 90It is intended to replace rlogin and rsh, 91and provide secure encrypted communications between 92two untrusted hosts over an insecure network. 93X11 connections and arbitrary TCP ports 94can also be forwarded over the secure channel. 95.Pp 96.Nm 97connects and logs into the specified 98.Ar hostname 99(with optional 100.Ar user 101name). 102The user must prove 103his/her identity to the remote machine using one of several methods 104depending on the protocol version used (see below). 105.Pp 106If 107.Ar command 108is specified, 109it is executed on the remote host instead of a login shell. 110.Pp 111The options are as follows: 112.Bl -tag -width Ds 113.It Fl 1 114Forces 115.Nm 116to try protocol version 1 only. 117.It Fl 2 118Forces 119.Nm 120to try protocol version 2 only. 121.It Fl 4 122Forces 123.Nm 124to use IPv4 addresses only. 125.It Fl 6 126Forces 127.Nm 128to use IPv6 addresses only. 129.It Fl A 130Enables forwarding of the authentication agent connection. 131This can also be specified on a per-host basis in a configuration file. 132.Pp 133Agent forwarding should be enabled with caution. 134Users with the ability to bypass file permissions on the remote host 135(for the agent's 136.Ux Ns -domain 137socket) can access the local agent through the forwarded connection. 138An attacker cannot obtain key material from the agent, 139however they can perform operations on the keys that enable them to 140authenticate using the identities loaded into the agent. 141.It Fl a 142Disables forwarding of the authentication agent connection. 143.It Fl b Ar bind_address 144Use 145.Ar bind_address 146on the local machine as the source address 147of the connection. 148Only useful on systems with more than one address. 149.It Fl C 150Requests compression of all data (including stdin, stdout, stderr, and 151data for forwarded X11 and TCP connections). 152The compression algorithm is the same used by 153.Xr gzip 1 , 154and the 155.Dq level 156can be controlled by the 157.Cm CompressionLevel 158option for protocol version 1. 159Compression is desirable on modem lines and other 160slow connections, but will only slow down things on fast networks. 161The default value can be set on a host-by-host basis in the 162configuration files; see the 163.Cm Compression 164option. 165.It Fl c Ar cipher_spec 166Selects the cipher specification for encrypting the session. 167.Pp 168Protocol version 1 allows specification of a single cipher. 169The supported values are 170.Dq 3des , 171.Dq blowfish , 172and 173.Dq des . 174.Ar 3des 175(triple-des) is an encrypt-decrypt-encrypt triple with three different keys. 176It is believed to be secure. 177.Ar blowfish 178is a fast block cipher; it appears very secure and is much faster than 179.Ar 3des . 180.Ar des 181is only supported in the 182.Nm 183client for interoperability with legacy protocol 1 implementations 184that do not support the 185.Ar 3des 186cipher. 187Its use is strongly discouraged due to cryptographic weaknesses. 188The default is 189.Dq 3des . 190.Pp 191For protocol version 2, 192.Ar cipher_spec 193is a comma-separated list of ciphers 194listed in order of preference. 195See the 196.Cm Ciphers 197keyword for more information. 198.It Fl D Xo 199.Sm off 200.Oo Ar bind_address : Oc 201.Ar port 202.Sm on 203.Xc 204Specifies a local 205.Dq dynamic 206application-level port forwarding. 207This works by allocating a socket to listen to 208.Ar port 209on the local side, optionally bound to the specified 210.Ar bind_address . 211Whenever a connection is made to this port, the 212connection is forwarded over the secure channel, and the application 213protocol is then used to determine where to connect to from the 214remote machine. 215Currently the SOCKS4 and SOCKS5 protocols are supported, and 216.Nm 217will act as a SOCKS server. 218Only root can forward privileged ports. 219Dynamic port forwardings can also be specified in the configuration file. 220.Pp 221IPv6 addresses can be specified with an alternative syntax: 222.Sm off 223.Xo 224.Op Ar bind_address No / 225.Ar port 226.Xc 227.Sm on 228or by enclosing the address in square brackets. 229Only the superuser can forward privileged ports. 230By default, the local port is bound in accordance with the 231.Cm GatewayPorts 232setting. 233However, an explicit 234.Ar bind_address 235may be used to bind the connection to a specific address. 236The 237.Ar bind_address 238of 239.Dq localhost 240indicates that the listening port be bound for local use only, while an 241empty address or 242.Sq * 243indicates that the port should be available from all interfaces. 244.It Fl e Ar escape_char 245Sets the escape character for sessions with a pty (default: 246.Ql ~ ) . 247The escape character is only recognized at the beginning of a line. 248The escape character followed by a dot 249.Pq Ql \&. 250closes the connection; 251followed by control-Z suspends the connection; 252and followed by itself sends the escape character once. 253Setting the character to 254.Dq none 255disables any escapes and makes the session fully transparent. 256.It Fl F Ar configfile 257Specifies an alternative per-user configuration file. 258If a configuration file is given on the command line, 259the system-wide configuration file 260.Pq Pa /etc/ssh/ssh_config 261will be ignored. 262The default for the per-user configuration file is 263.Pa ~/.ssh/config . 264.It Fl f 265Requests 266.Nm 267to go to background just before command execution. 268This is useful if 269.Nm 270is going to ask for passwords or passphrases, but the user 271wants it in the background. 272This implies 273.Fl n . 274The recommended way to start X11 programs at a remote site is with 275something like 276.Ic ssh -f host xterm . 277.Pp 278If the 279.Cm ExitOnForwardFailure 280configuration option is set to 281.Dq yes , 282then a client started with 283.Fl f 284will wait for all remote port forwards to be successfully established 285before placing itself in the background. 286.It Fl g 287Allows remote hosts to connect to local forwarded ports. 288.It Fl I Ar smartcard_device 289Specify the device 290.Nm 291should use to communicate with a smartcard used for storing the user's 292private RSA key. 293This option is only available if support for smartcard devices 294is compiled in (default is no support). 295.It Fl i Ar identity_file 296Selects a file from which the identity (private key) for 297RSA or DSA authentication is read. 298The default is 299.Pa ~/.ssh/identity 300for protocol version 1, and 301.Pa ~/.ssh/id_rsa 302and 303.Pa ~/.ssh/id_dsa 304for protocol version 2. 305Identity files may also be specified on 306a per-host basis in the configuration file. 307It is possible to have multiple 308.Fl i 309options (and multiple identities specified in 310configuration files). 311.It Fl K 312Enables GSSAPI-based authentication and forwarding (delegation) of GSSAPI 313credentials to the server. 314.It Fl k 315Disables forwarding (delegation) of GSSAPI credentials to the server. 316.It Fl L Xo 317.Sm off 318.Oo Ar bind_address : Oc 319.Ar port : host : hostport 320.Sm on 321.Xc 322Specifies that the given port on the local (client) host is to be 323forwarded to the given host and port on the remote side. 324This works by allocating a socket to listen to 325.Ar port 326on the local side, optionally bound to the specified 327.Ar bind_address . 328Whenever a connection is made to this port, the 329connection is forwarded over the secure channel, and a connection is 330made to 331.Ar host 332port 333.Ar hostport 334from the remote machine. 335Port forwardings can also be specified in the configuration file. 336IPv6 addresses can be specified with an alternative syntax: 337.Sm off 338.Xo 339.Op Ar bind_address No / 340.Ar port No / Ar host No / 341.Ar hostport 342.Xc 343.Sm on 344or by enclosing the address in square brackets. 345Only the superuser can forward privileged ports. 346By default, the local port is bound in accordance with the 347.Cm GatewayPorts 348setting. 349However, an explicit 350.Ar bind_address 351may be used to bind the connection to a specific address. 352The 353.Ar bind_address 354of 355.Dq localhost 356indicates that the listening port be bound for local use only, while an 357empty address or 358.Sq * 359indicates that the port should be available from all interfaces. 360.It Fl l Ar login_name 361Specifies the user to log in as on the remote machine. 362This also may be specified on a per-host basis in the configuration file. 363.It Fl M 364Places the 365.Nm 366client into 367.Dq master 368mode for connection sharing. 369Multiple 370.Fl M 371options places 372.Nm 373into 374.Dq master 375mode with confirmation required before slave connections are accepted. 376Refer to the description of 377.Cm ControlMaster 378in 379.Xr ssh_config 5 380for details. 381.It Fl m Ar mac_spec 382Additionally, for protocol version 2 a comma-separated list of MAC 383(message authentication code) algorithms can 384be specified in order of preference. 385See the 386.Cm MACs 387keyword for more information. 388.It Fl N 389Do not execute a remote command. 390This is useful for just forwarding ports 391(protocol version 2 only). 392.It Fl n 393Redirects stdin from 394.Pa /dev/null 395(actually, prevents reading from stdin). 396This must be used when 397.Nm 398is run in the background. 399A common trick is to use this to run X11 programs on a remote machine. 400For example, 401.Ic ssh -n shadows.cs.hut.fi emacs & 402will start an emacs on shadows.cs.hut.fi, and the X11 403connection will be automatically forwarded over an encrypted channel. 404The 405.Nm 406program will be put in the background. 407(This does not work if 408.Nm 409needs to ask for a password or passphrase; see also the 410.Fl f 411option.) 412.It Fl O Ar ctl_cmd 413Control an active connection multiplexing master process. 414When the 415.Fl O 416option is specified, the 417.Ar ctl_cmd 418argument is interpreted and passed to the master process. 419Valid commands are: 420.Dq check 421(check that the master process is running) and 422.Dq exit 423(request the master to exit). 424.It Fl o Ar option 425Can be used to give options in the format used in the configuration file. 426This is useful for specifying options for which there is no separate 427command-line flag. 428For full details of the options listed below, and their possible values, see 429.Xr ssh_config 5 . 430.Pp 431.Bl -tag -width Ds -offset indent -compact 432.It AddressFamily 433.It BatchMode 434.It BindAddress 435.It ChallengeResponseAuthentication 436.It CheckHostIP 437.It Cipher 438.It Ciphers 439.It ClearAllForwardings 440.It Compression 441.It CompressionLevel 442.It ConnectionAttempts 443.It ConnectTimeout 444.It ControlMaster 445.It ControlPath 446.It DynamicForward 447.It EscapeChar 448.It ExitOnForwardFailure 449.It ForwardAgent 450.It ForwardX11 451.It ForwardX11Trusted 452.It GatewayPorts 453.It GlobalKnownHostsFile 454.It GSSAPIAuthentication 455.It GSSAPIDelegateCredentials 456.It HashKnownHosts 457.It Host 458.It HostbasedAuthentication 459.It HostKeyAlgorithms 460.It HostKeyAlias 461.It HostName 462.It IdentityFile 463.It IdentitiesOnly 464.It KbdInteractiveDevices 465.It LocalCommand 466.It LocalForward 467.It LogLevel 468.It MACs 469.It NoHostAuthenticationForLocalhost 470.It NumberOfPasswordPrompts 471.It PasswordAuthentication 472.It PermitLocalCommand 473.It Port 474.It PreferredAuthentications 475.It Protocol 476.It ProxyCommand 477.It PubkeyAuthentication 478.It RDomain 479.It RekeyLimit 480.It RemoteForward 481.It RhostsRSAAuthentication 482.It RSAAuthentication 483.It SendEnv 484.It ServerAliveInterval 485.It ServerAliveCountMax 486.It SmartcardDevice 487.It StrictHostKeyChecking 488.It TCPKeepAlive 489.It Tunnel 490.It TunnelDevice 491.It UsePrivilegedPort 492.It User 493.It UserKnownHostsFile 494.It VerifyHostKeyDNS 495.It VisualHostKey 496.It XAuthLocation 497.El 498.It Fl p Ar port 499Port to connect to on the remote host. 500This can be specified on a 501per-host basis in the configuration file. 502.It Fl q 503Quiet mode. 504Causes most warning and diagnostic messages to be suppressed. 505.It Fl R Xo 506.Sm off 507.Oo Ar bind_address : Oc 508.Ar port : host : hostport 509.Sm on 510.Xc 511Specifies that the given port on the remote (server) host is to be 512forwarded to the given host and port on the local side. 513This works by allocating a socket to listen to 514.Ar port 515on the remote side, and whenever a connection is made to this port, the 516connection is forwarded over the secure channel, and a connection is 517made to 518.Ar host 519port 520.Ar hostport 521from the local machine. 522.Pp 523Port forwardings can also be specified in the configuration file. 524Privileged ports can be forwarded only when 525logging in as root on the remote machine. 526IPv6 addresses can be specified by enclosing the address in square braces or 527using an alternative syntax: 528.Sm off 529.Xo 530.Op Ar bind_address No / 531.Ar host No / Ar port No / 532.Ar hostport 533.Xc . 534.Sm on 535.Pp 536By default, the listening socket on the server will be bound to the loopback 537interface only. 538This may be overridden by specifying a 539.Ar bind_address . 540An empty 541.Ar bind_address , 542or the address 543.Ql * , 544indicates that the remote socket should listen on all interfaces. 545Specifying a remote 546.Ar bind_address 547will only succeed if the server's 548.Cm GatewayPorts 549option is enabled (see 550.Xr sshd_config 5 ) . 551.Pp 552If the 553.Ar port 554argument is 555.Ql 0 , 556the listen port will be dynamically allocated on the server and reported 557to the client at run time. 558.It Fl S Ar ctl_path 559Specifies the location of a control socket for connection sharing. 560Refer to the description of 561.Cm ControlPath 562and 563.Cm ControlMaster 564in 565.Xr ssh_config 5 566for details. 567.It Fl s 568May be used to request invocation of a subsystem on the remote system. 569Subsystems are a feature of the SSH2 protocol which facilitate the use 570of SSH as a secure transport for other applications (eg.\& 571.Xr sftp 1 ) . 572The subsystem is specified as the remote command. 573.It Fl T 574Disable pseudo-tty allocation. 575.It Fl t 576Force pseudo-tty allocation. 577This can be used to execute arbitrary 578screen-based programs on a remote machine, which can be very useful, 579e.g. when implementing menu services. 580Multiple 581.Fl t 582options force tty allocation, even if 583.Nm 584has no local tty. 585.It Fl V 586Display the version number and exit. 587.It Fl v 588Verbose mode. 589Causes 590.Nm 591to print debugging messages about its progress. 592This is helpful in 593debugging connection, authentication, and configuration problems. 594Multiple 595.Fl v 596options increase the verbosity. 597The maximum is 3. 598.It Fl w Xo 599.Ar local_tun Ns Op : Ns Ar remote_tun 600.Xc 601Requests 602tunnel 603device forwarding with the specified 604.Xr tun 4 605devices between the client 606.Pq Ar local_tun 607and the server 608.Pq Ar remote_tun . 609.Pp 610The devices may be specified by numerical ID or the keyword 611.Dq any , 612which uses the next available tunnel device. 613If 614.Ar remote_tun 615is not specified, it defaults to 616.Dq any . 617See also the 618.Cm Tunnel 619and 620.Cm TunnelDevice 621directives in 622.Xr ssh_config 5 . 623If the 624.Cm Tunnel 625directive is unset, it is set to the default tunnel mode, which is 626.Dq point-to-point . 627.It Fl X 628Enables X11 forwarding. 629This can also be specified on a per-host basis in a configuration file. 630.Pp 631X11 forwarding should be enabled with caution. 632Users with the ability to bypass file permissions on the remote host 633(for the user's X authorization database) 634can access the local X11 display through the forwarded connection. 635An attacker may then be able to perform activities such as keystroke monitoring. 636.Pp 637For this reason, X11 forwarding is subjected to X11 SECURITY extension 638restrictions by default. 639Please refer to the 640.Nm 641.Fl Y 642option and the 643.Cm ForwardX11Trusted 644directive in 645.Xr ssh_config 5 646for more information. 647.It Fl x 648Disables X11 forwarding. 649.It Fl Y 650Enables trusted X11 forwarding. 651Trusted X11 forwardings are not subjected to the X11 SECURITY extension 652controls. 653.It Fl y 654Send log information using the 655.Xr syslog 3 656system module. 657By default this information is sent to stderr. 658.El 659.Pp 660.Nm 661may additionally obtain configuration data from 662a per-user configuration file and a system-wide configuration file. 663The file format and configuration options are described in 664.Xr ssh_config 5 . 665.Pp 666.Nm 667exits with the exit status of the remote command or with 255 668if an error occurred. 669.Sh AUTHENTICATION 670The OpenSSH SSH client supports SSH protocols 1 and 2. 671The default is to use protocol 2 only, 672though this can be changed via the 673.Cm Protocol 674option in 675.Xr ssh_config 5 676or the 677.Fl 1 678and 679.Fl 2 680options (see above). 681Both protocols support similar authentication methods, 682but protocol 2 is the default since 683it provides additional mechanisms for confidentiality 684(the traffic is encrypted using AES, 3DES, Blowfish, CAST128, or Arcfour) 685and integrity (hmac-md5, hmac-sha1, umac-64, hmac-ripemd160). 686Protocol 1 lacks a strong mechanism for ensuring the 687integrity of the connection. 688.Pp 689The methods available for authentication are: 690GSSAPI-based authentication, 691host-based authentication, 692public key authentication, 693challenge-response authentication, 694and password authentication. 695Authentication methods are tried in the order specified above, 696though protocol 2 has a configuration option to change the default order: 697.Cm PreferredAuthentications . 698.Pp 699Host-based authentication works as follows: 700If the machine the user logs in from is listed in 701.Pa /etc/hosts.equiv 702or 703.Pa /etc/shosts.equiv 704on the remote machine, and the user names are 705the same on both sides, or if the files 706.Pa ~/.rhosts 707or 708.Pa ~/.shosts 709exist in the user's home directory on the 710remote machine and contain a line containing the name of the client 711machine and the name of the user on that machine, the user is 712considered for login. 713Additionally, the server 714.Em must 715be able to verify the client's 716host key (see the description of 717.Pa /etc/ssh/ssh_known_hosts 718and 719.Pa ~/.ssh/known_hosts , 720below) 721for login to be permitted. 722This authentication method closes security holes due to IP 723spoofing, DNS spoofing, and routing spoofing. 724[Note to the administrator: 725.Pa /etc/hosts.equiv , 726.Pa ~/.rhosts , 727and the rlogin/rsh protocol in general, are inherently insecure and should be 728disabled if security is desired.] 729.Pp 730Public key authentication works as follows: 731The scheme is based on public-key cryptography, 732using cryptosystems 733where encryption and decryption are done using separate keys, 734and it is unfeasible to derive the decryption key from the encryption key. 735The idea is that each user creates a public/private 736key pair for authentication purposes. 737The server knows the public key, and only the user knows the private key. 738.Nm 739implements public key authentication protocol automatically, 740using either the RSA or DSA algorithms. 741Protocol 1 is restricted to using only RSA keys, 742but protocol 2 may use either. 743The 744.Sx HISTORY 745section of 746.Xr ssl 8 747contains a brief discussion of the two algorithms. 748.Pp 749The file 750.Pa ~/.ssh/authorized_keys 751lists the public keys that are permitted for logging in. 752When the user logs in, the 753.Nm 754program tells the server which key pair it would like to use for 755authentication. 756The client proves that it has access to the private key 757and the server checks that the corresponding public key 758is authorized to accept the account. 759.Pp 760The user creates his/her key pair by running 761.Xr ssh-keygen 1 . 762This stores the private key in 763.Pa ~/.ssh/identity 764(protocol 1), 765.Pa ~/.ssh/id_dsa 766(protocol 2 DSA), 767or 768.Pa ~/.ssh/id_rsa 769(protocol 2 RSA) 770and stores the public key in 771.Pa ~/.ssh/identity.pub 772(protocol 1), 773.Pa ~/.ssh/id_dsa.pub 774(protocol 2 DSA), 775or 776.Pa ~/.ssh/id_rsa.pub 777(protocol 2 RSA) 778in the user's home directory. 779The user should then copy the public key 780to 781.Pa ~/.ssh/authorized_keys 782in his/her home directory on the remote machine. 783The 784.Pa authorized_keys 785file corresponds to the conventional 786.Pa ~/.rhosts 787file, and has one key 788per line, though the lines can be very long. 789After this, the user can log in without giving the password. 790.Pp 791The most convenient way to use public key authentication may be with an 792authentication agent. 793See 794.Xr ssh-agent 1 795for more information. 796.Pp 797Challenge-response authentication works as follows: 798The server sends an arbitrary 799.Qq challenge 800text, and prompts for a response. 801Protocol 2 allows multiple challenges and responses; 802protocol 1 is restricted to just one challenge/response. 803Examples of challenge-response authentication include 804BSD Authentication (see 805.Xr login.conf 5 ) 806and PAM (some non-OpenBSD systems). 807.Pp 808Finally, if other authentication methods fail, 809.Nm 810prompts the user for a password. 811The password is sent to the remote 812host for checking; however, since all communications are encrypted, 813the password cannot be seen by someone listening on the network. 814.Pp 815.Nm 816automatically maintains and checks a database containing 817identification for all hosts it has ever been used with. 818Host keys are stored in 819.Pa ~/.ssh/known_hosts 820in the user's home directory. 821Additionally, the file 822.Pa /etc/ssh/ssh_known_hosts 823is automatically checked for known hosts. 824Any new hosts are automatically added to the user's file. 825If a host's identification ever changes, 826.Nm 827warns about this and disables password authentication to prevent 828server spoofing or man-in-the-middle attacks, 829which could otherwise be used to circumvent the encryption. 830The 831.Cm StrictHostKeyChecking 832option can be used to control logins to machines whose 833host key is not known or has changed. 834.Pp 835When the user's identity has been accepted by the server, the server 836either executes the given command, or logs into the machine and gives 837the user a normal shell on the remote machine. 838All communication with 839the remote command or shell will be automatically encrypted. 840.Pp 841If a pseudo-terminal has been allocated (normal login session), the 842user may use the escape characters noted below. 843.Pp 844If no pseudo-tty has been allocated, 845the session is transparent and can be used to reliably transfer binary data. 846On most systems, setting the escape character to 847.Dq none 848will also make the session transparent even if a tty is used. 849.Pp 850The session terminates when the command or shell on the remote 851machine exits and all X11 and TCP connections have been closed. 852.Sh ESCAPE CHARACTERS 853When a pseudo-terminal has been requested, 854.Nm 855supports a number of functions through the use of an escape character. 856.Pp 857A single tilde character can be sent as 858.Ic ~~ 859or by following the tilde by a character other than those described below. 860The escape character must always follow a newline to be interpreted as 861special. 862The escape character can be changed in configuration files using the 863.Cm EscapeChar 864configuration directive or on the command line by the 865.Fl e 866option. 867.Pp 868The supported escapes (assuming the default 869.Ql ~ ) 870are: 871.Bl -tag -width Ds 872.It Cm ~. 873Disconnect. 874.It Cm ~^Z 875Background 876.Nm . 877.It Cm ~# 878List forwarded connections. 879.It Cm ~& 880Background 881.Nm 882at logout when waiting for forwarded connection / X11 sessions to terminate. 883.It Cm ~? 884Display a list of escape characters. 885.It Cm ~B 886Send a BREAK to the remote system 887(only useful for SSH protocol version 2 and if the peer supports it). 888.It Cm ~C 889Open command line. 890Currently this allows the addition of port forwardings using the 891.Fl L , 892.Fl R 893and 894.Fl D 895options (see above). 896It also allows the cancellation of existing remote port-forwardings 897using 898.Sm off 899.Fl KR Oo Ar bind_address : Oc Ar port . 900.Sm on 901.Ic !\& Ns Ar command 902allows the user to execute a local command if the 903.Ic PermitLocalCommand 904option is enabled in 905.Xr ssh_config 5 . 906Basic help is available, using the 907.Fl h 908option. 909.It Cm ~R 910Request rekeying of the connection 911(only useful for SSH protocol version 2 and if the peer supports it). 912.El 913.Sh TCP FORWARDING 914Forwarding of arbitrary TCP connections over the secure channel can 915be specified either on the command line or in a configuration file. 916One possible application of TCP forwarding is a secure connection to a 917mail server; another is going through firewalls. 918.Pp 919In the example below, we look at encrypting communication between 920an IRC client and server, even though the IRC server does not directly 921support encrypted communications. 922This works as follows: 923the user connects to the remote host using 924.Nm , 925specifying a port to be used to forward connections 926to the remote server. 927After that it is possible to start the service which is to be encrypted 928on the client machine, 929connecting to the same local port, 930and 931.Nm 932will encrypt and forward the connection. 933.Pp 934The following example tunnels an IRC session from client machine 935.Dq 127.0.0.1 936(localhost) 937to remote server 938.Dq server.example.com : 939.Bd -literal -offset 4n 940$ ssh -f -L 1234:localhost:6667 server.example.com sleep 10 941$ irc -c '#users' -p 1234 pinky 127.0.0.1 942.Ed 943.Pp 944This tunnels a connection to IRC server 945.Dq server.example.com , 946joining channel 947.Dq #users , 948nickname 949.Dq pinky , 950using port 1234. 951It doesn't matter which port is used, 952as long as it's greater than 1023 953(remember, only root can open sockets on privileged ports) 954and doesn't conflict with any ports already in use. 955The connection is forwarded to port 6667 on the remote server, 956since that's the standard port for IRC services. 957.Pp 958The 959.Fl f 960option backgrounds 961.Nm 962and the remote command 963.Dq sleep 10 964is specified to allow an amount of time 965(10 seconds, in the example) 966to start the service which is to be tunnelled. 967If no connections are made within the time specified, 968.Nm 969will exit. 970.Sh X11 FORWARDING 971If the 972.Cm ForwardX11 973variable is set to 974.Dq yes 975(or see the description of the 976.Fl X , 977.Fl x , 978and 979.Fl Y 980options above) 981and the user is using X11 (the 982.Ev DISPLAY 983environment variable is set), the connection to the X11 display is 984automatically forwarded to the remote side in such a way that any X11 985programs started from the shell (or command) will go through the 986encrypted channel, and the connection to the real X server will be made 987from the local machine. 988The user should not manually set 989.Ev DISPLAY . 990Forwarding of X11 connections can be 991configured on the command line or in configuration files. 992.Pp 993The 994.Ev DISPLAY 995value set by 996.Nm 997will point to the server machine, but with a display number greater than zero. 998This is normal, and happens because 999.Nm 1000creates a 1001.Dq proxy 1002X server on the server machine for forwarding the 1003connections over the encrypted channel. 1004.Pp 1005.Nm 1006will also automatically set up Xauthority data on the server machine. 1007For this purpose, it will generate a random authorization cookie, 1008store it in Xauthority on the server, and verify that any forwarded 1009connections carry this cookie and replace it by the real cookie when 1010the connection is opened. 1011The real authentication cookie is never 1012sent to the server machine (and no cookies are sent in the plain). 1013.Pp 1014If the 1015.Cm ForwardAgent 1016variable is set to 1017.Dq yes 1018(or see the description of the 1019.Fl A 1020and 1021.Fl a 1022options above) and 1023the user is using an authentication agent, the connection to the agent 1024is automatically forwarded to the remote side. 1025.Sh VERIFYING HOST KEYS 1026When connecting to a server for the first time, 1027a fingerprint of the server's public key is presented to the user 1028(unless the option 1029.Cm StrictHostKeyChecking 1030has been disabled). 1031Fingerprints can be determined using 1032.Xr ssh-keygen 1 : 1033.Pp 1034.Dl $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key 1035.Pp 1036If the fingerprint is already known, it can be matched 1037and the key can be accepted or rejected. 1038Because of the difficulty of comparing host keys 1039just by looking at hex strings, 1040there is also support to compare host keys visually, 1041using 1042.Em random art . 1043By setting the 1044.Cm VisualHostKey 1045option to 1046.Dq yes , 1047a small ASCII graphic gets displayed on every login to a server, no matter 1048if the session itself is interactive or not. 1049By learning the pattern a known server produces, a user can easily 1050find out that the host key has changed when a completely different pattern 1051is displayed. 1052Because these patterns are not unambiguous however, a pattern that looks 1053similar to the pattern remembered only gives a good probability that the 1054host key is the same, not guaranteed proof. 1055.Pp 1056To get a listing of the fingerprints along with their random art for 1057all known hosts, the following command line can be used: 1058.Pp 1059.Dl $ ssh-keygen -lv -f ~/.ssh/known_hosts 1060.Pp 1061If the fingerprint is unknown, 1062an alternative method of verification is available: 1063SSH fingerprints verified by DNS. 1064An additional resource record (RR), 1065SSHFP, 1066is added to a zonefile 1067and the connecting client is able to match the fingerprint 1068with that of the key presented. 1069.Pp 1070In this example, we are connecting a client to a server, 1071.Dq host.example.com . 1072The SSHFP resource records should first be added to the zonefile for 1073host.example.com: 1074.Bd -literal -offset indent 1075$ ssh-keygen -r host.example.com. 1076.Ed 1077.Pp 1078The output lines will have to be added to the zonefile. 1079To check that the zone is answering fingerprint queries: 1080.Pp 1081.Dl $ dig -t SSHFP host.example.com 1082.Pp 1083Finally the client connects: 1084.Bd -literal -offset indent 1085$ ssh -o "VerifyHostKeyDNS ask" host.example.com 1086[...] 1087Matching host key fingerprint found in DNS. 1088Are you sure you want to continue connecting (yes/no)? 1089.Ed 1090.Pp 1091See the 1092.Cm VerifyHostKeyDNS 1093option in 1094.Xr ssh_config 5 1095for more information. 1096.Sh SSH-BASED VIRTUAL PRIVATE NETWORKS 1097.Nm 1098contains support for Virtual Private Network (VPN) tunnelling 1099using the 1100.Xr tun 4 1101network pseudo-device, 1102allowing two networks to be joined securely. 1103The 1104.Xr sshd_config 5 1105configuration option 1106.Cm PermitTunnel 1107controls whether the server supports this, 1108and at what level (layer 2 or 3 traffic). 1109.Pp 1110The following example would connect client network 10.0.50.0/24 1111with remote network 10.0.99.0/24 using a point-to-point connection 1112from 10.1.1.1 to 10.1.1.2, 1113provided that the SSH server running on the gateway to the remote network, 1114at 192.168.1.15, allows it. 1115.Pp 1116On the client: 1117.Bd -literal -offset indent 1118# ssh -f -w 0:1 192.168.1.15 true 1119# ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252 1120# route add 10.0.99.0/24 10.1.1.2 1121.Ed 1122.Pp 1123On the server: 1124.Bd -literal -offset indent 1125# ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252 1126# route add 10.0.50.0/24 10.1.1.1 1127.Ed 1128.Pp 1129Client access may be more finely tuned via the 1130.Pa /root/.ssh/authorized_keys 1131file (see below) and the 1132.Cm PermitRootLogin 1133server option. 1134The following entry would permit connections on 1135.Xr tun 4 1136device 1 from user 1137.Dq jane 1138and on tun device 2 from user 1139.Dq john , 1140if 1141.Cm PermitRootLogin 1142is set to 1143.Dq forced-commands-only : 1144.Bd -literal -offset 2n 1145tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane 1146tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john 1147.Ed 1148.Pp 1149Since an SSH-based setup entails a fair amount of overhead, 1150it may be more suited to temporary setups, 1151such as for wireless VPNs. 1152More permanent VPNs are better provided by tools such as 1153.Xr ipsecctl 8 1154and 1155.Xr isakmpd 8 . 1156.Sh ENVIRONMENT 1157.Nm 1158will normally set the following environment variables: 1159.Bl -tag -width "SSH_ORIGINAL_COMMAND" 1160.It Ev DISPLAY 1161The 1162.Ev DISPLAY 1163variable indicates the location of the X11 server. 1164It is automatically set by 1165.Nm 1166to point to a value of the form 1167.Dq hostname:n , 1168where 1169.Dq hostname 1170indicates the host where the shell runs, and 1171.Sq n 1172is an integer \*(Ge 1. 1173.Nm 1174uses this special value to forward X11 connections over the secure 1175channel. 1176The user should normally not set 1177.Ev DISPLAY 1178explicitly, as that 1179will render the X11 connection insecure (and will require the user to 1180manually copy any required authorization cookies). 1181.It Ev HOME 1182Set to the path of the user's home directory. 1183.It Ev LOGNAME 1184Synonym for 1185.Ev USER ; 1186set for compatibility with systems that use this variable. 1187.It Ev MAIL 1188Set to the path of the user's mailbox. 1189.It Ev PATH 1190Set to the default 1191.Ev PATH , 1192as specified when compiling 1193.Nm . 1194.It Ev SSH_ASKPASS 1195If 1196.Nm 1197needs a passphrase, it will read the passphrase from the current 1198terminal if it was run from a terminal. 1199If 1200.Nm 1201does not have a terminal associated with it but 1202.Ev DISPLAY 1203and 1204.Ev SSH_ASKPASS 1205are set, it will execute the program specified by 1206.Ev SSH_ASKPASS 1207and open an X11 window to read the passphrase. 1208This is particularly useful when calling 1209.Nm 1210from a 1211.Pa .xsession 1212or related script. 1213(Note that on some machines it 1214may be necessary to redirect the input from 1215.Pa /dev/null 1216to make this work.) 1217.It Ev SSH_AUTH_SOCK 1218Identifies the path of a 1219.Ux Ns -domain 1220socket used to communicate with the agent. 1221.It Ev SSH_CONNECTION 1222Identifies the client and server ends of the connection. 1223The variable contains 1224four space-separated values: client IP address, client port number, 1225server IP address, and server port number. 1226.It Ev SSH_ORIGINAL_COMMAND 1227This variable contains the original command line if a forced command 1228is executed. 1229It can be used to extract the original arguments. 1230.It Ev SSH_TTY 1231This is set to the name of the tty (path to the device) associated 1232with the current shell or command. 1233If the current session has no tty, 1234this variable is not set. 1235.It Ev TZ 1236This variable is set to indicate the present time zone if it 1237was set when the daemon was started (i.e. the daemon passes the value 1238on to new connections). 1239.It Ev USER 1240Set to the name of the user logging in. 1241.El 1242.Pp 1243Additionally, 1244.Nm 1245reads 1246.Pa ~/.ssh/environment , 1247and adds lines of the format 1248.Dq VARNAME=value 1249to the environment if the file exists and users are allowed to 1250change their environment. 1251For more information, see the 1252.Cm PermitUserEnvironment 1253option in 1254.Xr sshd_config 5 . 1255.Sh FILES 1256.Bl -tag -width Ds -compact 1257.It ~/.rhosts 1258This file is used for host-based authentication (see above). 1259On some machines this file may need to be 1260world-readable if the user's home directory is on an NFS partition, 1261because 1262.Xr sshd 8 1263reads it as root. 1264Additionally, this file must be owned by the user, 1265and must not have write permissions for anyone else. 1266The recommended 1267permission for most machines is read/write for the user, and not 1268accessible by others. 1269.Pp 1270.It ~/.shosts 1271This file is used in exactly the same way as 1272.Pa .rhosts , 1273but allows host-based authentication without permitting login with 1274rlogin/rsh. 1275.Pp 1276.It ~/.ssh/ 1277This directory is the default location for all user-specific configuration 1278and authentication information. 1279There is no general requirement to keep the entire contents of this directory 1280secret, but the recommended permissions are read/write/execute for the user, 1281and not accessible by others. 1282.Pp 1283.It ~/.ssh/authorized_keys 1284Lists the public keys (RSA/DSA) that can be used for logging in as this user. 1285The format of this file is described in the 1286.Xr sshd 8 1287manual page. 1288This file is not highly sensitive, but the recommended 1289permissions are read/write for the user, and not accessible by others. 1290.Pp 1291.It ~/.ssh/config 1292This is the per-user configuration file. 1293The file format and configuration options are described in 1294.Xr ssh_config 5 . 1295Because of the potential for abuse, this file must have strict permissions: 1296read/write for the user, and not accessible by others. 1297.Pp 1298.It ~/.ssh/environment 1299Contains additional definitions for environment variables; see 1300.Sx ENVIRONMENT , 1301above. 1302.Pp 1303.It ~/.ssh/identity 1304.It ~/.ssh/id_dsa 1305.It ~/.ssh/id_rsa 1306Contains the private key for authentication. 1307These files 1308contain sensitive data and should be readable by the user but not 1309accessible by others (read/write/execute). 1310.Nm 1311will simply ignore a private key file if it is accessible by others. 1312It is possible to specify a passphrase when 1313generating the key which will be used to encrypt the 1314sensitive part of this file using 3DES. 1315.Pp 1316.It ~/.ssh/identity.pub 1317.It ~/.ssh/id_dsa.pub 1318.It ~/.ssh/id_rsa.pub 1319Contains the public key for authentication. 1320These files are not 1321sensitive and can (but need not) be readable by anyone. 1322.Pp 1323.It ~/.ssh/known_hosts 1324Contains a list of host keys for all hosts the user has logged into 1325that are not already in the systemwide list of known host keys. 1326See 1327.Xr sshd 8 1328for further details of the format of this file. 1329.Pp 1330.It ~/.ssh/rc 1331Commands in this file are executed by 1332.Nm 1333when the user logs in, just before the user's shell (or command) is 1334started. 1335See the 1336.Xr sshd 8 1337manual page for more information. 1338.Pp 1339.It /etc/hosts.equiv 1340This file is for host-based authentication (see above). 1341It should only be writable by root. 1342.Pp 1343.It /etc/shosts.equiv 1344This file is used in exactly the same way as 1345.Pa hosts.equiv , 1346but allows host-based authentication without permitting login with 1347rlogin/rsh. 1348.Pp 1349.It Pa /etc/ssh/ssh_config 1350Systemwide configuration file. 1351The file format and configuration options are described in 1352.Xr ssh_config 5 . 1353.Pp 1354.It /etc/ssh/ssh_host_key 1355.It /etc/ssh/ssh_host_dsa_key 1356.It /etc/ssh/ssh_host_rsa_key 1357These three files contain the private parts of the host keys 1358and are used for host-based authentication. 1359If protocol version 1 is used, 1360.Nm 1361must be setuid root, since the host key is readable only by root. 1362For protocol version 2, 1363.Nm 1364uses 1365.Xr ssh-keysign 8 1366to access the host keys, 1367eliminating the requirement that 1368.Nm 1369be setuid root when host-based authentication is used. 1370By default 1371.Nm 1372is not setuid root. 1373.Pp 1374.It /etc/ssh/ssh_known_hosts 1375Systemwide list of known host keys. 1376This file should be prepared by the 1377system administrator to contain the public host keys of all machines in the 1378organization. 1379It should be world-readable. 1380See 1381.Xr sshd 8 1382for further details of the format of this file. 1383.Pp 1384.It /etc/ssh/sshrc 1385Commands in this file are executed by 1386.Nm 1387when the user logs in, just before the user's shell (or command) is started. 1388See the 1389.Xr sshd 8 1390manual page for more information. 1391.El 1392.Sh SEE ALSO 1393.Xr scp 1 , 1394.Xr sftp 1 , 1395.Xr ssh-add 1 , 1396.Xr ssh-agent 1 , 1397.Xr ssh-keygen 1 , 1398.Xr ssh-keyscan 1 , 1399.Xr tun 4 , 1400.Xr hosts.equiv 5 , 1401.Xr ssh_config 5 , 1402.Xr ssh-keysign 8 , 1403.Xr sshd 8 1404.Rs 1405.%R RFC 4250 1406.%T "The Secure Shell (SSH) Protocol Assigned Numbers" 1407.%D 2006 1408.Re 1409.Rs 1410.%R RFC 4251 1411.%T "The Secure Shell (SSH) Protocol Architecture" 1412.%D 2006 1413.Re 1414.Rs 1415.%R RFC 4252 1416.%T "The Secure Shell (SSH) Authentication Protocol" 1417.%D 2006 1418.Re 1419.Rs 1420.%R RFC 4253 1421.%T "The Secure Shell (SSH) Transport Layer Protocol" 1422.%D 2006 1423.Re 1424.Rs 1425.%R RFC 4254 1426.%T "The Secure Shell (SSH) Connection Protocol" 1427.%D 2006 1428.Re 1429.Rs 1430.%R RFC 4255 1431.%T "Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints" 1432.%D 2006 1433.Re 1434.Rs 1435.%R RFC 4256 1436.%T "Generic Message Exchange Authentication for the Secure Shell Protocol (SSH)" 1437.%D 2006 1438.Re 1439.Rs 1440.%R RFC 4335 1441.%T "The Secure Shell (SSH) Session Channel Break Extension" 1442.%D 2006 1443.Re 1444.Rs 1445.%R RFC 4344 1446.%T "The Secure Shell (SSH) Transport Layer Encryption Modes" 1447.%D 2006 1448.Re 1449.Rs 1450.%R RFC 4345 1451.%T "Improved Arcfour Modes for the Secure Shell (SSH) Transport Layer Protocol" 1452.%D 2006 1453.Re 1454.Rs 1455.%R RFC 4419 1456.%T "Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol" 1457.%D 2006 1458.Re 1459.Rs 1460.%R RFC 4716 1461.%T "The Secure Shell (SSH) Public Key File Format" 1462.%D 2006 1463.Re 1464.Rs 1465.%T "Hash Visualization: a New Technique to improve Real-World Security" 1466.%A A. Perrig 1467.%A D. Song 1468.%D 1999 1469.%O "International Workshop on Cryptographic Techniques and E-Commerce (CrypTEC '99)" 1470.Re 1471.Sh AUTHORS 1472OpenSSH is a derivative of the original and free 1473ssh 1.2.12 release by Tatu Ylonen. 1474Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 1475Theo de Raadt and Dug Song 1476removed many bugs, re-added newer features and 1477created OpenSSH. 1478Markus Friedl contributed the support for SSH 1479protocol versions 1.5 and 2.0. 1480