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