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/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