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