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