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