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