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.283 2009/03/19 15:15:09 jmc Exp $ 38.Dd $Mdocdate: March 19 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 Unix-domain socket) 136can access the local agent through the forwarded connection. 137An attacker cannot obtain key material from the agent, 138however they can perform operations on the keys that enable them to 139authenticate using the identities loaded into the agent. 140.It Fl a 141Disables forwarding of the authentication agent connection. 142.It Fl b Ar bind_address 143Use 144.Ar bind_address 145on the local machine as the source address 146of the connection. 147Only useful on systems with more than one address. 148.It Fl C 149Requests compression of all data (including stdin, stdout, stderr, and 150data for forwarded X11 and TCP connections). 151The compression algorithm is the same used by 152.Xr gzip 1 , 153and the 154.Dq level 155can be controlled by the 156.Cm CompressionLevel 157option for protocol version 1. 158Compression is desirable on modem lines and other 159slow connections, but will only slow down things on fast networks. 160The default value can be set on a host-by-host basis in the 161configuration files; see the 162.Cm Compression 163option. 164.It Fl c Ar cipher_spec 165Selects the cipher specification for encrypting the session. 166.Pp 167Protocol version 1 allows specification of a single cipher. 168The supported values are 169.Dq 3des , 170.Dq blowfish , 171and 172.Dq des . 173.Ar 3des 174(triple-des) is an encrypt-decrypt-encrypt triple with three different keys. 175It is believed to be secure. 176.Ar blowfish 177is a fast block cipher; it appears very secure and is much faster than 178.Ar 3des . 179.Ar des 180is only supported in the 181.Nm 182client for interoperability with legacy protocol 1 implementations 183that do not support the 184.Ar 3des 185cipher. 186Its use is strongly discouraged due to cryptographic weaknesses. 187The default is 188.Dq 3des . 189.Pp 190For protocol version 2, 191.Ar cipher_spec 192is a comma-separated list of ciphers 193listed in order of preference. 194See the 195.Cm Ciphers 196keyword for more information. 197.It Fl D Xo 198.Sm off 199.Oo Ar bind_address : Oc 200.Ar port 201.Sm on 202.Xc 203Specifies a local 204.Dq dynamic 205application-level port forwarding. 206This works by allocating a socket to listen to 207.Ar port 208on the local side, optionally bound to the specified 209.Ar bind_address . 210Whenever a connection is made to this port, the 211connection is forwarded over the secure channel, and the application 212protocol is then used to determine where to connect to from the 213remote machine. 214Currently the SOCKS4 and SOCKS5 protocols are supported, and 215.Nm 216will act as a SOCKS server. 217Only root can forward privileged ports. 218Dynamic port forwardings can also be specified in the configuration file. 219.Pp 220IPv6 addresses can be specified with an alternative syntax: 221.Sm off 222.Xo 223.Op Ar bind_address No / 224.Ar port 225.Xc 226.Sm on 227or by enclosing the address in square brackets. 228Only the superuser can forward privileged ports. 229By default, the local port is bound in accordance with the 230.Cm GatewayPorts 231setting. 232However, an explicit 233.Ar bind_address 234may be used to bind the connection to a specific address. 235The 236.Ar bind_address 237of 238.Dq localhost 239indicates that the listening port be bound for local use only, while an 240empty address or 241.Sq * 242indicates that the port should be available from all interfaces. 243.It Fl e Ar escape_char 244Sets the escape character for sessions with a pty (default: 245.Ql ~ ) . 246The escape character is only recognized at the beginning of a line. 247The escape character followed by a dot 248.Pq Ql \&. 249closes the connection; 250followed by control-Z suspends the connection; 251and followed by itself sends the escape character once. 252Setting the character to 253.Dq none 254disables any escapes and makes the session fully transparent. 255.It Fl F Ar configfile 256Specifies an alternative per-user configuration file. 257If a configuration file is given on the command line, 258the system-wide configuration file 259.Pq Pa /etc/ssh/ssh_config 260will be ignored. 261The default for the per-user configuration file is 262.Pa ~/.ssh/config . 263.It Fl f 264Requests 265.Nm 266to go to background just before command execution. 267This is useful if 268.Nm 269is going to ask for passwords or passphrases, but the user 270wants it in the background. 271This implies 272.Fl n . 273The recommended way to start X11 programs at a remote site is with 274something like 275.Ic ssh -f host xterm . 276.Pp 277If the 278.Cm ExitOnForwardFailure 279configuration option is set to 280.Dq yes , 281then a client started with 282.Fl f 283will wait for all remote port forwards to be successfully established 284before placing itself in the background. 285.It Fl g 286Allows remote hosts to connect to local forwarded ports. 287.It Fl I Ar smartcard_device 288Specify the device 289.Nm 290should use to communicate with a smartcard used for storing the user's 291private RSA key. 292This option is only available if support for smartcard devices 293is compiled in (default is no support). 294.It Fl i Ar identity_file 295Selects a file from which the identity (private key) for 296RSA or DSA authentication is read. 297The default is 298.Pa ~/.ssh/identity 299for protocol version 1, and 300.Pa ~/.ssh/id_rsa 301and 302.Pa ~/.ssh/id_dsa 303for protocol version 2. 304Identity files may also be specified on 305a per-host basis in the configuration file. 306It is possible to have multiple 307.Fl i 308options (and multiple identities specified in 309configuration files). 310.It Fl K 311Enables GSSAPI-based authentication and forwarding (delegation) of GSSAPI 312credentials to the server. 313.It Fl k 314Disables forwarding (delegation) of GSSAPI credentials to the server. 315.It Fl L Xo 316.Sm off 317.Oo Ar bind_address : Oc 318.Ar port : host : hostport 319.Sm on 320.Xc 321Specifies that the given port on the local (client) host is to be 322forwarded to the given host and port on the remote side. 323This works by allocating a socket to listen to 324.Ar port 325on the local side, optionally bound to the specified 326.Ar bind_address . 327Whenever a connection is made to this port, the 328connection is forwarded over the secure channel, and a connection is 329made to 330.Ar host 331port 332.Ar hostport 333from the remote machine. 334Port forwardings can also be specified in the configuration file. 335IPv6 addresses can be specified with an alternative syntax: 336.Sm off 337.Xo 338.Op Ar bind_address No / 339.Ar port No / Ar host No / 340.Ar hostport 341.Xc 342.Sm on 343or by enclosing the address in square brackets. 344Only the superuser can forward privileged ports. 345By default, the local port is bound in accordance with the 346.Cm GatewayPorts 347setting. 348However, an explicit 349.Ar bind_address 350may be used to bind the connection to a specific address. 351The 352.Ar bind_address 353of 354.Dq localhost 355indicates that the listening port be bound for local use only, while an 356empty address or 357.Sq * 358indicates that the port should be available from all interfaces. 359.It Fl l Ar login_name 360Specifies the user to log in as on the remote machine. 361This also may be specified on a per-host basis in the configuration file. 362.It Fl M 363Places the 364.Nm 365client into 366.Dq master 367mode for connection sharing. 368Multiple 369.Fl M 370options places 371.Nm 372into 373.Dq master 374mode with confirmation required before slave connections are accepted. 375Refer to the description of 376.Cm ControlMaster 377in 378.Xr ssh_config 5 379for details. 380.It Fl m Ar mac_spec 381Additionally, for protocol version 2 a comma-separated list of MAC 382(message authentication code) algorithms can 383be specified in order of preference. 384See the 385.Cm MACs 386keyword for more information. 387.It Fl N 388Do not execute a remote command. 389This is useful for just forwarding ports 390(protocol version 2 only). 391.It Fl n 392Redirects stdin from 393.Pa /dev/null 394(actually, prevents reading from stdin). 395This must be used when 396.Nm 397is run in the background. 398A common trick is to use this to run X11 programs on a remote machine. 399For example, 400.Ic ssh -n shadows.cs.hut.fi emacs & 401will start an emacs on shadows.cs.hut.fi, and the X11 402connection will be automatically forwarded over an encrypted channel. 403The 404.Nm 405program will be put in the background. 406(This does not work if 407.Nm 408needs to ask for a password or passphrase; see also the 409.Fl f 410option.) 411.It Fl O Ar ctl_cmd 412Control an active connection multiplexing master process. 413When the 414.Fl O 415option is specified, the 416.Ar ctl_cmd 417argument is interpreted and passed to the master process. 418Valid commands are: 419.Dq check 420(check that the master process is running) and 421.Dq exit 422(request the master to exit). 423.It Fl o Ar option 424Can be used to give options in the format used in the configuration file. 425This is useful for specifying options for which there is no separate 426command-line flag. 427For full details of the options listed below, and their possible values, see 428.Xr ssh_config 5 . 429.Pp 430.Bl -tag -width Ds -offset indent -compact 431.It AddressFamily 432.It BatchMode 433.It BindAddress 434.It ChallengeResponseAuthentication 435.It CheckHostIP 436.It Cipher 437.It Ciphers 438.It ClearAllForwardings 439.It Compression 440.It CompressionLevel 441.It ConnectionAttempts 442.It ConnectTimeout 443.It ControlMaster 444.It ControlPath 445.It DynamicForward 446.It EscapeChar 447.It ExitOnForwardFailure 448.It ForwardAgent 449.It ForwardX11 450.It ForwardX11Trusted 451.It GatewayPorts 452.It GlobalKnownHostsFile 453.It GSSAPIAuthentication 454.It GSSAPIDelegateCredentials 455.It HashKnownHosts 456.It Host 457.It HostbasedAuthentication 458.It HostKeyAlgorithms 459.It HostKeyAlias 460.It HostName 461.It IdentityFile 462.It IdentitiesOnly 463.It KbdInteractiveDevices 464.It LocalCommand 465.It LocalForward 466.It LogLevel 467.It MACs 468.It NoHostAuthenticationForLocalhost 469.It NumberOfPasswordPrompts 470.It PasswordAuthentication 471.It PermitLocalCommand 472.It Port 473.It PreferredAuthentications 474.It Protocol 475.It ProxyCommand 476.It PubkeyAuthentication 477.It RekeyLimit 478.It RemoteForward 479.It RhostsRSAAuthentication 480.It RSAAuthentication 481.It SendEnv 482.It ServerAliveInterval 483.It ServerAliveCountMax 484.It SmartcardDevice 485.It StrictHostKeyChecking 486.It TCPKeepAlive 487.It Tunnel 488.It TunnelDevice 489.It UsePrivilegedPort 490.It User 491.It UserKnownHostsFile 492.It VerifyHostKeyDNS 493.It VisualHostKey 494.It XAuthLocation 495.El 496.It Fl p Ar port 497Port to connect to on the remote host. 498This can be specified on a 499per-host basis in the configuration file. 500.It Fl q 501Quiet mode. 502Causes most warning and diagnostic messages to be suppressed. 503.It Fl R Xo 504.Sm off 505.Oo Ar bind_address : Oc 506.Ar port : host : hostport 507.Sm on 508.Xc 509Specifies that the given port on the remote (server) host is to be 510forwarded to the given host and port on the local side. 511This works by allocating a socket to listen to 512.Ar port 513on the remote side, and whenever a connection is made to this port, the 514connection is forwarded over the secure channel, and a connection is 515made to 516.Ar host 517port 518.Ar hostport 519from the local machine. 520.Pp 521Port forwardings can also be specified in the configuration file. 522Privileged ports can be forwarded only when 523logging in as root on the remote machine. 524IPv6 addresses can be specified by enclosing the address in square braces or 525using an alternative syntax: 526.Sm off 527.Xo 528.Op Ar bind_address No / 529.Ar host No / Ar port No / 530.Ar hostport 531.Xc . 532.Sm on 533.Pp 534By default, the listening socket on the server will be bound to the loopback 535interface only. 536This may be overridden by specifying a 537.Ar bind_address . 538An empty 539.Ar bind_address , 540or the address 541.Ql * , 542indicates that the remote socket should listen on all interfaces. 543Specifying a remote 544.Ar bind_address 545will only succeed if the server's 546.Cm GatewayPorts 547option is enabled (see 548.Xr sshd_config 5 ) . 549.Pp 550If the 551.Ar port 552argument is 553.Ql 0 , 554the listen port will be dynamically allocated on the server and reported 555to the client at run time. 556.It Fl S Ar ctl_path 557Specifies the location of a control socket for connection sharing. 558Refer to the description of 559.Cm ControlPath 560and 561.Cm ControlMaster 562in 563.Xr ssh_config 5 564for details. 565.It Fl s 566May be used to request invocation of a subsystem on the remote system. 567Subsystems are a feature of the SSH2 protocol which facilitate the use 568of SSH as a secure transport for other applications (eg.\& 569.Xr sftp 1 ) . 570The subsystem is specified as the remote command. 571.It Fl T 572Disable pseudo-tty allocation. 573.It Fl t 574Force pseudo-tty allocation. 575This can be used to execute arbitrary 576screen-based programs on a remote machine, which can be very useful, 577e.g. when implementing menu services. 578Multiple 579.Fl t 580options force tty allocation, even if 581.Nm 582has no local tty. 583.It Fl V 584Display the version number and exit. 585.It Fl v 586Verbose mode. 587Causes 588.Nm 589to print debugging messages about its progress. 590This is helpful in 591debugging connection, authentication, and configuration problems. 592Multiple 593.Fl v 594options increase the verbosity. 595The maximum is 3. 596.It Fl w Xo 597.Ar local_tun Ns Op : Ns Ar remote_tun 598.Xc 599Requests 600tunnel 601device forwarding with the specified 602.Xr tun 4 603devices between the client 604.Pq Ar local_tun 605and the server 606.Pq Ar remote_tun . 607.Pp 608The devices may be specified by numerical ID or the keyword 609.Dq any , 610which uses the next available tunnel device. 611If 612.Ar remote_tun 613is not specified, it defaults to 614.Dq any . 615See also the 616.Cm Tunnel 617and 618.Cm TunnelDevice 619directives in 620.Xr ssh_config 5 . 621If the 622.Cm Tunnel 623directive is unset, it is set to the default tunnel mode, which is 624.Dq point-to-point . 625.It Fl X 626Enables X11 forwarding. 627This can also be specified on a per-host basis in a configuration file. 628.Pp 629X11 forwarding should be enabled with caution. 630Users with the ability to bypass file permissions on the remote host 631(for the user's X authorization database) 632can access the local X11 display through the forwarded connection. 633An attacker may then be able to perform activities such as keystroke monitoring. 634.Pp 635For this reason, X11 forwarding is subjected to X11 SECURITY extension 636restrictions by default. 637Please refer to the 638.Nm 639.Fl Y 640option and the 641.Cm ForwardX11Trusted 642directive in 643.Xr ssh_config 5 644for more information. 645.It Fl x 646Disables X11 forwarding. 647.It Fl Y 648Enables trusted X11 forwarding. 649Trusted X11 forwardings are not subjected to the X11 SECURITY extension 650controls. 651.It Fl y 652Send log information using the 653.Xr syslog 3 654system module. 655By default this information is sent to stderr. 656.El 657.Pp 658.Nm 659may additionally obtain configuration data from 660a per-user configuration file and a system-wide configuration file. 661The file format and configuration options are described in 662.Xr ssh_config 5 . 663.Pp 664.Nm 665exits with the exit status of the remote command or with 255 666if an error occurred. 667.Sh AUTHENTICATION 668The OpenSSH SSH client supports SSH protocols 1 and 2. 669Protocol 2 is the default, with 670.Nm 671falling back to protocol 1 if it detects protocol 2 is unsupported. 672These settings may be altered using the 673.Cm Protocol 674option in 675.Xr ssh_config 5 , 676or enforced using the 677.Fl 1 678and 679.Fl 2 680options (see above). 681Both protocols support similar authentication methods, 682but protocol 2 is preferred 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/ssh/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. 992Take note that X11 forwarding can represent a security hazard. 993.Pp 994The 995.Ev DISPLAY 996value set by 997.Nm 998will point to the server machine, but with a display number greater than zero. 999This is normal, and happens because 1000.Nm 1001creates a 1002.Dq proxy 1003X server on the server machine for forwarding the 1004connections over the encrypted channel. 1005.Pp 1006.Nm 1007will also automatically set up Xauthority data on the server machine. 1008For this purpose, it will generate a random authorization cookie, 1009store it in Xauthority on the server, and verify that any forwarded 1010connections carry this cookie and replace it by the real cookie when 1011the connection is opened. 1012The real authentication cookie is never 1013sent to the server machine (and no cookies are sent in the plain). 1014.Pp 1015If the 1016.Cm ForwardAgent 1017variable is set to 1018.Dq yes 1019(or see the description of the 1020.Fl A 1021and 1022.Fl a 1023options above) and 1024the user is using an authentication agent, the connection to the agent 1025is automatically forwarded to the remote side. 1026.Sh VERIFYING HOST KEYS 1027When connecting to a server for the first time, 1028a fingerprint of the server's public key is presented to the user 1029(unless the option 1030.Cm StrictHostKeyChecking 1031has been disabled). 1032Fingerprints can be determined using 1033.Xr ssh-keygen 1 : 1034.Pp 1035.Dl $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key 1036.Pp 1037If the fingerprint is already known, it can be matched 1038and the key can be accepted or rejected. 1039Because of the difficulty of comparing host keys 1040just by looking at hex strings, 1041there is also support to compare host keys visually, 1042using 1043.Em random art . 1044By setting the 1045.Cm VisualHostKey 1046option to 1047.Dq yes , 1048a small ASCII graphic gets displayed on every login to a server, no matter 1049if the session itself is interactive or not. 1050By learning the pattern a known server produces, a user can easily 1051find out that the host key has changed when a completely different pattern 1052is displayed. 1053Because these patterns are not unambiguous however, a pattern that looks 1054similar to the pattern remembered only gives a good probability that the 1055host key is the same, not guaranteed proof. 1056.Pp 1057To get a listing of the fingerprints along with their random art for 1058all known hosts, the following command line can be used: 1059.Pp 1060.Dl $ ssh-keygen -lv -f ~/.ssh/known_hosts 1061.Pp 1062If the fingerprint is unknown, 1063an alternative method of verification is available: 1064SSH fingerprints verified by DNS. 1065An additional resource record (RR), 1066SSHFP, 1067is added to a zonefile 1068and the connecting client is able to match the fingerprint 1069with that of the key presented. 1070.Pp 1071In this example, we are connecting a client to a server, 1072.Dq host.example.com . 1073The SSHFP resource records should first be added to the zonefile for 1074host.example.com: 1075.Bd -literal -offset indent 1076$ ssh-keygen -r host.example.com. 1077.Ed 1078.Pp 1079The output lines will have to be added to the zonefile. 1080To check that the zone is answering fingerprint queries: 1081.Pp 1082.Dl $ dig -t SSHFP host.example.com 1083.Pp 1084Finally the client connects: 1085.Bd -literal -offset indent 1086$ ssh -o "VerifyHostKeyDNS ask" host.example.com 1087[...] 1088Matching host key fingerprint found in DNS. 1089Are you sure you want to continue connecting (yes/no)? 1090.Ed 1091.Pp 1092See the 1093.Cm VerifyHostKeyDNS 1094option in 1095.Xr ssh_config 5 1096for more information. 1097.Sh SSH-BASED VIRTUAL PRIVATE NETWORKS 1098.Nm 1099contains support for Virtual Private Network (VPN) tunnelling 1100using the 1101.Xr tun 4 1102network pseudo-device, 1103allowing two networks to be joined securely. 1104The 1105.Xr sshd_config 5 1106configuration option 1107.Cm PermitTunnel 1108controls whether the server supports this, 1109and at what level (layer 2 or 3 traffic). 1110.Pp 1111The following example would connect client network 10.0.50.0/24 1112with remote network 10.0.99.0/24 using a point-to-point connection 1113from 10.1.1.1 to 10.1.1.2, 1114provided that the SSH server running on the gateway to the remote network, 1115at 192.168.1.15, allows it. 1116.Pp 1117On the client: 1118.Bd -literal -offset indent 1119# ssh -f -w 0:1 192.168.1.15 true 1120# ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252 1121# route add 10.0.99.0/24 10.1.1.2 1122.Ed 1123.Pp 1124On the server: 1125.Bd -literal -offset indent 1126# ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252 1127# route add 10.0.50.0/24 10.1.1.1 1128.Ed 1129.Pp 1130Client access may be more finely tuned via the 1131.Pa /root/.ssh/authorized_keys 1132file (see below) and the 1133.Cm PermitRootLogin 1134server option. 1135The following entry would permit connections on 1136.Xr tun 4 1137device 1 from user 1138.Dq jane 1139and on tun device 2 from user 1140.Dq john , 1141if 1142.Cm PermitRootLogin 1143is set to 1144.Dq forced-commands-only : 1145.Bd -literal -offset 2n 1146tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane 1147tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john 1148.Ed 1149.Pp 1150Since an SSH-based setup entails a fair amount of overhead, 1151it may be more suited to temporary setups, 1152such as for wireless VPNs. 1153More permanent VPNs are better provided by tools such as 1154.Xr ipsecctl 8 1155and 1156.Xr isakmpd 8 . 1157.Sh ENVIRONMENT 1158.Nm 1159will normally set the following environment variables: 1160.Bl -tag -width "SSH_ORIGINAL_COMMAND" 1161.It Ev DISPLAY 1162The 1163.Ev DISPLAY 1164variable indicates the location of the X11 server. 1165It is automatically set by 1166.Nm 1167to point to a value of the form 1168.Dq hostname:n , 1169where 1170.Dq hostname 1171indicates the host where the shell runs, and 1172.Sq n 1173is an integer \*(Ge 1. 1174.Nm 1175uses this special value to forward X11 connections over the secure 1176channel. 1177The user should normally not set 1178.Ev DISPLAY 1179explicitly, as that 1180will render the X11 connection insecure (and will require the user to 1181manually copy any required authorization cookies). 1182.It Ev HOME 1183Set to the path of the user's home directory. 1184.It Ev LOGNAME 1185Synonym for 1186.Ev USER ; 1187set for compatibility with systems that use this variable. 1188.It Ev MAIL 1189Set to the path of the user's mailbox. 1190.It Ev PATH 1191Set to the default 1192.Ev PATH , 1193as specified when compiling 1194.Nm . 1195.It Ev SSH_ASKPASS 1196If 1197.Nm 1198needs a passphrase, it will read the passphrase from the current 1199terminal if it was run from a terminal. 1200If 1201.Nm 1202does not have a terminal associated with it but 1203.Ev DISPLAY 1204and 1205.Ev SSH_ASKPASS 1206are set, it will execute the program specified by 1207.Ev SSH_ASKPASS 1208and open an X11 window to read the passphrase. 1209This is particularly useful when calling 1210.Nm 1211from a 1212.Pa .xsession 1213or related script. 1214(Note that on some machines it 1215may be necessary to redirect the input from 1216.Pa /dev/null 1217to make this work.) 1218.It Ev SSH_AUTH_SOCK 1219Identifies the path of a 1220.Ux Ns -domain 1221socket used to communicate with the agent. 1222.It Ev SSH_CONNECTION 1223Identifies the client and server ends of the connection. 1224The variable contains 1225four space-separated values: client IP address, client port number, 1226server IP address, and server port number. 1227.It Ev SSH_ORIGINAL_COMMAND 1228This variable contains the original command line if a forced command 1229is executed. 1230It can be used to extract the original arguments. 1231.It Ev SSH_TTY 1232This is set to the name of the tty (path to the device) associated 1233with the current shell or command. 1234If the current session has no tty, 1235this variable is not set. 1236.It Ev TZ 1237This variable is set to indicate the present time zone if it 1238was set when the daemon was started (i.e. the daemon passes the value 1239on to new connections). 1240.It Ev USER 1241Set to the name of the user logging in. 1242.El 1243.Pp 1244Additionally, 1245.Nm 1246reads 1247.Pa ~/.ssh/environment , 1248and adds lines of the format 1249.Dq VARNAME=value 1250to the environment if the file exists and users are allowed to 1251change their environment. 1252For more information, see the 1253.Cm PermitUserEnvironment 1254option in 1255.Xr sshd_config 5 . 1256.Sh FILES 1257.Bl -tag -width Ds -compact 1258.It ~/.rhosts 1259This file is used for host-based authentication (see above). 1260On some machines this file may need to be 1261world-readable if the user's home directory is on an NFS partition, 1262because 1263.Xr sshd 8 1264reads it as root. 1265Additionally, this file must be owned by the user, 1266and must not have write permissions for anyone else. 1267The recommended 1268permission for most machines is read/write for the user, and not 1269accessible by others. 1270.Pp 1271.It ~/.shosts 1272This file is used in exactly the same way as 1273.Pa .rhosts , 1274but allows host-based authentication without permitting login with 1275rlogin/rsh. 1276.Pp 1277.It ~/.ssh/ 1278This directory is the default location for all user-specific configuration 1279and authentication information. 1280There is no general requirement to keep the entire contents of this directory 1281secret, but the recommended permissions are read/write/execute for the user, 1282and not accessible by others. 1283.Pp 1284.It ~/.ssh/authorized_keys 1285Lists the public keys (RSA/DSA) that can be used for logging in as this user. 1286The format of this file is described in the 1287.Xr sshd 8 1288manual page. 1289This file is not highly sensitive, but the recommended 1290permissions are read/write for the user, and not accessible by others. 1291.Pp 1292.It ~/.ssh/config 1293This is the per-user configuration file. 1294The file format and configuration options are described in 1295.Xr ssh_config 5 . 1296Because of the potential for abuse, this file must have strict permissions: 1297read/write for the user, and not accessible by others. 1298.Pp 1299.It ~/.ssh/environment 1300Contains additional definitions for environment variables; see 1301.Sx ENVIRONMENT , 1302above. 1303.Pp 1304.It ~/.ssh/identity 1305.It ~/.ssh/id_dsa 1306.It ~/.ssh/id_rsa 1307Contains the private key for authentication. 1308These files 1309contain sensitive data and should be readable by the user but not 1310accessible by others (read/write/execute). 1311.Nm 1312will simply ignore a private key file if it is accessible by others. 1313It is possible to specify a passphrase when 1314generating the key which will be used to encrypt the 1315sensitive part of this file using 3DES. 1316.Pp 1317.It ~/.ssh/identity.pub 1318.It ~/.ssh/id_dsa.pub 1319.It ~/.ssh/id_rsa.pub 1320Contains the public key for authentication. 1321These files are not 1322sensitive and can (but need not) be readable by anyone. 1323.Pp 1324.It ~/.ssh/known_hosts 1325Contains a list of host keys for all hosts the user has logged into 1326that are not already in the systemwide list of known host keys. 1327See 1328.Xr sshd 8 1329for further details of the format of this file. 1330.Pp 1331.It ~/.ssh/rc 1332Commands in this file are executed by 1333.Nm 1334when the user logs in, just before the user's shell (or command) is 1335started. 1336See the 1337.Xr sshd 8 1338manual page for more information. 1339.Pp 1340.It /etc/hosts.equiv 1341This file is for host-based authentication (see above). 1342It should only be writable by root. 1343.Pp 1344.It /etc/ssh/shosts.equiv 1345This file is used in exactly the same way as 1346.Pa hosts.equiv , 1347but allows host-based authentication without permitting login with 1348rlogin/rsh. 1349.Pp 1350.It Pa /etc/ssh/ssh_config 1351Systemwide configuration file. 1352The file format and configuration options are described in 1353.Xr ssh_config 5 . 1354.Pp 1355.It /etc/ssh/ssh_host_key 1356.It /etc/ssh/ssh_host_dsa_key 1357.It /etc/ssh/ssh_host_rsa_key 1358These three files contain the private parts of the host keys 1359and are used for host-based authentication. 1360If protocol version 1 is used, 1361.Nm 1362must be setuid root, since the host key is readable only by root. 1363For protocol version 2, 1364.Nm 1365uses 1366.Xr ssh-keysign 8 1367to access the host keys, 1368eliminating the requirement that 1369.Nm 1370be setuid root when host-based authentication is used. 1371By default 1372.Nm 1373is not setuid root. 1374.Pp 1375.It /etc/ssh/ssh_known_hosts 1376Systemwide list of known host keys. 1377This file should be prepared by the 1378system administrator to contain the public host keys of all machines in the 1379organization. 1380It should be world-readable. 1381See 1382.Xr sshd 8 1383for further details of the format of this file. 1384.Pp 1385.It /etc/ssh/sshrc 1386Commands in this file are executed by 1387.Nm 1388when the user logs in, just before the user's shell (or command) is started. 1389See the 1390.Xr sshd 8 1391manual page for more information. 1392.El 1393.Sh SEE ALSO 1394.Xr scp 1 , 1395.Xr sftp 1 , 1396.Xr ssh-add 1 , 1397.Xr ssh-agent 1 , 1398.Xr ssh-keygen 1 , 1399.Xr ssh-keyscan 1 , 1400.Xr tun 4 , 1401.Xr hosts.equiv 5 , 1402.Xr ssh_config 5 , 1403.Xr ssh-keysign 8 , 1404.Xr sshd 8 1405.Rs 1406.%R RFC 4250 1407.%T "The Secure Shell (SSH) Protocol Assigned Numbers" 1408.%D 2006 1409.Re 1410.Rs 1411.%R RFC 4251 1412.%T "The Secure Shell (SSH) Protocol Architecture" 1413.%D 2006 1414.Re 1415.Rs 1416.%R RFC 4252 1417.%T "The Secure Shell (SSH) Authentication Protocol" 1418.%D 2006 1419.Re 1420.Rs 1421.%R RFC 4253 1422.%T "The Secure Shell (SSH) Transport Layer Protocol" 1423.%D 2006 1424.Re 1425.Rs 1426.%R RFC 4254 1427.%T "The Secure Shell (SSH) Connection Protocol" 1428.%D 2006 1429.Re 1430.Rs 1431.%R RFC 4255 1432.%T "Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints" 1433.%D 2006 1434.Re 1435.Rs 1436.%R RFC 4256 1437.%T "Generic Message Exchange Authentication for the Secure Shell Protocol (SSH)" 1438.%D 2006 1439.Re 1440.Rs 1441.%R RFC 4335 1442.%T "The Secure Shell (SSH) Session Channel Break Extension" 1443.%D 2006 1444.Re 1445.Rs 1446.%R RFC 4344 1447.%T "The Secure Shell (SSH) Transport Layer Encryption Modes" 1448.%D 2006 1449.Re 1450.Rs 1451.%R RFC 4345 1452.%T "Improved Arcfour Modes for the Secure Shell (SSH) Transport Layer Protocol" 1453.%D 2006 1454.Re 1455.Rs 1456.%R RFC 4419 1457.%T "Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol" 1458.%D 2006 1459.Re 1460.Rs 1461.%R RFC 4716 1462.%T "The Secure Shell (SSH) Public Key File Format" 1463.%D 2006 1464.Re 1465.Rs 1466.%T "Hash Visualization: a New Technique to improve Real-World Security" 1467.%A A. Perrig 1468.%A D. Song 1469.%D 1999 1470.%O "International Workshop on Cryptographic Techniques and E-Commerce (CrypTEC '99)" 1471.Re 1472.Sh AUTHORS 1473OpenSSH is a derivative of the original and free 1474ssh 1.2.12 release by Tatu Ylonen. 1475Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 1476Theo de Raadt and Dug Song 1477removed many bugs, re-added newer features and 1478created OpenSSH. 1479Markus Friedl contributed the support for SSH 1480protocol versions 1.5 and 2.0. 1481