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