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/ssh/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. 1009Take note that X11 forwarding can represent a security hazard. 1010.Pp 1011The 1012.Ev DISPLAY 1013value set by 1014.Nm 1015will point to the server machine, but with a display number greater than zero. 1016This is normal, and happens because 1017.Nm 1018creates a 1019.Dq proxy 1020X server on the server machine for forwarding the 1021connections over the encrypted channel. 1022.Pp 1023.Nm 1024will also automatically set up Xauthority data on the server machine. 1025For this purpose, it will generate a random authorization cookie, 1026store it in Xauthority on the server, and verify that any forwarded 1027connections carry this cookie and replace it by the real cookie when 1028the connection is opened. 1029The real authentication cookie is never 1030sent to the server machine (and no cookies are sent in the plain). 1031.Pp 1032If the 1033.Cm ForwardAgent 1034variable is set to 1035.Dq yes 1036(or see the description of the 1037.Fl A 1038and 1039.Fl a 1040options above) and 1041the user is using an authentication agent, the connection to the agent 1042is automatically forwarded to the remote side. 1043.Sh VERIFYING HOST KEYS 1044When connecting to a server for the first time, 1045a fingerprint of the server's public key is presented to the user 1046(unless the option 1047.Cm StrictHostKeyChecking 1048has been disabled). 1049Fingerprints can be determined using 1050.Xr ssh-keygen 1 : 1051.Pp 1052.Dl $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key 1053.Pp 1054If the fingerprint is already known, it can be matched 1055and the key can be accepted or rejected. 1056Because of the difficulty of comparing host keys 1057just by looking at hex strings, 1058there is also support to compare host keys visually, 1059using 1060.Em random art . 1061By setting the 1062.Cm VisualHostKey 1063option to 1064.Dq yes , 1065a small ASCII graphic gets displayed on every login to a server, no matter 1066if the session itself is interactive or not. 1067By learning the pattern a known server produces, a user can easily 1068find out that the host key has changed when a completely different pattern 1069is displayed. 1070Because these patterns are not unambiguous however, a pattern that looks 1071similar to the pattern remembered only gives a good probability that the 1072host key is the same, not guaranteed proof. 1073.Pp 1074To get a listing of the fingerprints along with their random art for 1075all known hosts, the following command line can be used: 1076.Pp 1077.Dl $ ssh-keygen -lv -f ~/.ssh/known_hosts 1078.Pp 1079If the fingerprint is unknown, 1080an alternative method of verification is available: 1081SSH fingerprints verified by DNS. 1082An additional resource record (RR), 1083SSHFP, 1084is added to a zonefile 1085and the connecting client is able to match the fingerprint 1086with that of the key presented. 1087.Pp 1088In this example, we are connecting a client to a server, 1089.Dq host.example.com . 1090The SSHFP resource records should first be added to the zonefile for 1091host.example.com: 1092.Bd -literal -offset indent 1093$ ssh-keygen -r host.example.com. 1094.Ed 1095.Pp 1096The output lines will have to be added to the zonefile. 1097To check that the zone is answering fingerprint queries: 1098.Pp 1099.Dl $ dig -t SSHFP host.example.com 1100.Pp 1101Finally the client connects: 1102.Bd -literal -offset indent 1103$ ssh -o "VerifyHostKeyDNS ask" host.example.com 1104[...] 1105Matching host key fingerprint found in DNS. 1106Are you sure you want to continue connecting (yes/no)? 1107.Ed 1108.Pp 1109See the 1110.Cm VerifyHostKeyDNS 1111option in 1112.Xr ssh_config 5 1113for more information. 1114.Sh SSH-BASED VIRTUAL PRIVATE NETWORKS 1115.Nm 1116contains support for Virtual Private Network (VPN) tunnelling 1117using the 1118.Xr tun 4 1119network pseudo-device, 1120allowing two networks to be joined securely. 1121The 1122.Xr sshd_config 5 1123configuration option 1124.Cm PermitTunnel 1125controls whether the server supports this, 1126and at what level (layer 2 or 3 traffic). 1127.Pp 1128The following example would connect client network 10.0.50.0/24 1129with remote network 10.0.99.0/24 using a point-to-point connection 1130from 10.1.1.1 to 10.1.1.2, 1131provided that the SSH server running on the gateway to the remote network, 1132at 192.168.1.15, allows it. 1133.Pp 1134On the client: 1135.Bd -literal -offset indent 1136# ssh -f -w 0:1 192.168.1.15 true 1137# ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252 1138# route add 10.0.99.0/24 10.1.1.2 1139.Ed 1140.Pp 1141On the server: 1142.Bd -literal -offset indent 1143# ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252 1144# route add 10.0.50.0/24 10.1.1.1 1145.Ed 1146.Pp 1147Client access may be more finely tuned via the 1148.Pa /root/.ssh/authorized_keys 1149file (see below) and the 1150.Cm PermitRootLogin 1151server option. 1152The following entry would permit connections on 1153.Xr tun 4 1154device 1 from user 1155.Dq jane 1156and on tun device 2 from user 1157.Dq john , 1158if 1159.Cm PermitRootLogin 1160is set to 1161.Dq forced-commands-only : 1162.Bd -literal -offset 2n 1163tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane 1164tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john 1165.Ed 1166.Pp 1167Since an SSH-based setup entails a fair amount of overhead, 1168it may be more suited to temporary setups, 1169such as for wireless VPNs. 1170More permanent VPNs are better provided by tools such as 1171.Xr ipsecctl 8 1172and 1173.Xr isakmpd 8 . 1174.Sh ENVIRONMENT 1175.Nm 1176will normally set the following environment variables: 1177.Bl -tag -width "SSH_ORIGINAL_COMMAND" 1178.It Ev DISPLAY 1179The 1180.Ev DISPLAY 1181variable indicates the location of the X11 server. 1182It is automatically set by 1183.Nm 1184to point to a value of the form 1185.Dq hostname:n , 1186where 1187.Dq hostname 1188indicates the host where the shell runs, and 1189.Sq n 1190is an integer \*(Ge 1. 1191.Nm 1192uses this special value to forward X11 connections over the secure 1193channel. 1194The user should normally not set 1195.Ev DISPLAY 1196explicitly, as that 1197will render the X11 connection insecure (and will require the user to 1198manually copy any required authorization cookies). 1199.It Ev HOME 1200Set to the path of the user's home directory. 1201.It Ev LOGNAME 1202Synonym for 1203.Ev USER ; 1204set for compatibility with systems that use this variable. 1205.It Ev MAIL 1206Set to the path of the user's mailbox. 1207.It Ev PATH 1208Set to the default 1209.Ev PATH , 1210as specified when compiling 1211.Nm . 1212.It Ev SSH_ASKPASS 1213If 1214.Nm 1215needs a passphrase, it will read the passphrase from the current 1216terminal if it was run from a terminal. 1217If 1218.Nm 1219does not have a terminal associated with it but 1220.Ev DISPLAY 1221and 1222.Ev SSH_ASKPASS 1223are set, it will execute the program specified by 1224.Ev SSH_ASKPASS 1225and open an X11 window to read the passphrase. 1226This is particularly useful when calling 1227.Nm 1228from a 1229.Pa .xsession 1230or related script. 1231(Note that on some machines it 1232may be necessary to redirect the input from 1233.Pa /dev/null 1234to make this work.) 1235.It Ev SSH_AUTH_SOCK 1236Identifies the path of a 1237.Ux Ns -domain 1238socket used to communicate with the agent. 1239.It Ev SSH_CONNECTION 1240Identifies the client and server ends of the connection. 1241The variable contains 1242four space-separated values: client IP address, client port number, 1243server IP address, and server port number. 1244.It Ev SSH_ORIGINAL_COMMAND 1245This variable contains the original command line if a forced command 1246is executed. 1247It can be used to extract the original arguments. 1248.It Ev SSH_TTY 1249This is set to the name of the tty (path to the device) associated 1250with the current shell or command. 1251If the current session has no tty, 1252this variable is not set. 1253.It Ev TZ 1254This variable is set to indicate the present time zone if it 1255was set when the daemon was started (i.e. the daemon passes the value 1256on to new connections). 1257.It Ev USER 1258Set to the name of the user logging in. 1259.El 1260.Pp 1261Additionally, 1262.Nm 1263reads 1264.Pa ~/.ssh/environment , 1265and adds lines of the format 1266.Dq VARNAME=value 1267to the environment if the file exists and users are allowed to 1268change their environment. 1269For more information, see the 1270.Cm PermitUserEnvironment 1271option in 1272.Xr sshd_config 5 . 1273.Sh FILES 1274.Bl -tag -width Ds -compact 1275.It Pa ~/.rhosts 1276This file is used for host-based authentication (see above). 1277On some machines this file may need to be 1278world-readable if the user's home directory is on an NFS partition, 1279because 1280.Xr sshd 8 1281reads it as root. 1282Additionally, this file must be owned by the user, 1283and must not have write permissions for anyone else. 1284The recommended 1285permission for most machines is read/write for the user, and not 1286accessible by others. 1287.Pp 1288.It Pa ~/.shosts 1289This file is used in exactly the same way as 1290.Pa .rhosts , 1291but allows host-based authentication without permitting login with 1292rlogin/rsh. 1293.Pp 1294.It Pa ~/.ssh/ 1295This directory is the default location for all user-specific configuration 1296and authentication information. 1297There is no general requirement to keep the entire contents of this directory 1298secret, but the recommended permissions are read/write/execute for the user, 1299and not accessible by others. 1300.Pp 1301.It Pa ~/.ssh/authorized_keys 1302Lists the public keys (DSA/ECDSA/RSA) that can be used for logging in as 1303this user. 1304The format of this file is described in the 1305.Xr sshd 8 1306manual page. 1307This file is not highly sensitive, but the recommended 1308permissions are read/write for the user, and not accessible by others. 1309.Pp 1310.It Pa ~/.ssh/config 1311This is the per-user configuration file. 1312The file format and configuration options are described in 1313.Xr ssh_config 5 . 1314Because of the potential for abuse, this file must have strict permissions: 1315read/write for the user, and not accessible by others. 1316.Pp 1317.It Pa ~/.ssh/environment 1318Contains additional definitions for environment variables; see 1319.Sx ENVIRONMENT , 1320above. 1321.Pp 1322.It Pa ~/.ssh/identity 1323.It Pa ~/.ssh/id_dsa 1324.It Pa ~/.ssh/id_ecdsa 1325.It Pa ~/.ssh/id_rsa 1326Contains the private key for authentication. 1327These files 1328contain sensitive data and should be readable by the user but not 1329accessible by others (read/write/execute). 1330.Nm 1331will simply ignore a private key file if it is accessible by others. 1332It is possible to specify a passphrase when 1333generating the key which will be used to encrypt the 1334sensitive part of this file using 3DES. 1335.Pp 1336.It Pa ~/.ssh/identity.pub 1337.It Pa ~/.ssh/id_dsa.pub 1338.It Pa ~/.ssh/id_ecdsa.pub 1339.It Pa ~/.ssh/id_rsa.pub 1340Contains the public key for authentication. 1341These files are not 1342sensitive and can (but need not) be readable by anyone. 1343.Pp 1344.It Pa ~/.ssh/known_hosts 1345Contains a list of host keys for all hosts the user has logged into 1346that are not already in the systemwide list of known host keys. 1347See 1348.Xr sshd 8 1349for further details of the format of this file. 1350.Pp 1351.It Pa ~/.ssh/rc 1352Commands in this file are executed by 1353.Nm 1354when the user logs in, just before the user's shell (or command) is 1355started. 1356See the 1357.Xr sshd 8 1358manual page for more information. 1359.Pp 1360.It Pa /etc/hosts.equiv 1361This file is for host-based authentication (see above). 1362It should only be writable by root. 1363.Pp 1364.It Pa /etc/ssh/shosts.equiv 1365This file is used in exactly the same way as 1366.Pa hosts.equiv , 1367but allows host-based authentication without permitting login with 1368rlogin/rsh. 1369.Pp 1370.It Pa /etc/ssh/ssh_config 1371Systemwide configuration file. 1372The file format and configuration options are described in 1373.Xr ssh_config 5 . 1374.Pp 1375.It Pa /etc/ssh/ssh_host_key 1376.It Pa /etc/ssh/ssh_host_dsa_key 1377.It Pa /etc/ssh/ssh_host_ecdsa_key 1378.It Pa /etc/ssh/ssh_host_rsa_key 1379These files contain the private parts of the host keys 1380and are used for host-based authentication. 1381If protocol version 1 is used, 1382.Nm 1383must be setuid root, since the host key is readable only by root. 1384For protocol version 2, 1385.Nm 1386uses 1387.Xr ssh-keysign 8 1388to access the host keys, 1389eliminating the requirement that 1390.Nm 1391be setuid root when host-based authentication is used. 1392By default 1393.Nm 1394is not setuid root. 1395.Pp 1396.It Pa /etc/ssh/ssh_known_hosts 1397Systemwide list of known host keys. 1398This file should be prepared by the 1399system administrator to contain the public host keys of all machines in the 1400organization. 1401It should be world-readable. 1402See 1403.Xr sshd 8 1404for further details of the format of this file. 1405.Pp 1406.It Pa /etc/ssh/sshrc 1407Commands in this file are executed by 1408.Nm 1409when the user logs in, just before the user's shell (or command) is started. 1410See the 1411.Xr sshd 8 1412manual page for more information. 1413.El 1414.Sh EXIT STATUS 1415.Nm 1416exits with the exit status of the remote command or with 255 1417if an error occurred. 1418.Sh SEE ALSO 1419.Xr scp 1 , 1420.Xr sftp 1 , 1421.Xr ssh-add 1 , 1422.Xr ssh-agent 1 , 1423.Xr ssh-keygen 1 , 1424.Xr ssh-keyscan 1 , 1425.Xr tun 4 , 1426.Xr hosts.equiv 5 , 1427.Xr ssh_config 5 , 1428.Xr ssh-keysign 8 , 1429.Xr sshd 8 1430.Rs 1431.%R RFC 4250 1432.%T "The Secure Shell (SSH) Protocol Assigned Numbers" 1433.%D 2006 1434.Re 1435.Rs 1436.%R RFC 4251 1437.%T "The Secure Shell (SSH) Protocol Architecture" 1438.%D 2006 1439.Re 1440.Rs 1441.%R RFC 4252 1442.%T "The Secure Shell (SSH) Authentication Protocol" 1443.%D 2006 1444.Re 1445.Rs 1446.%R RFC 4253 1447.%T "The Secure Shell (SSH) Transport Layer Protocol" 1448.%D 2006 1449.Re 1450.Rs 1451.%R RFC 4254 1452.%T "The Secure Shell (SSH) Connection Protocol" 1453.%D 2006 1454.Re 1455.Rs 1456.%R RFC 4255 1457.%T "Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints" 1458.%D 2006 1459.Re 1460.Rs 1461.%R RFC 4256 1462.%T "Generic Message Exchange Authentication for the Secure Shell Protocol (SSH)" 1463.%D 2006 1464.Re 1465.Rs 1466.%R RFC 4335 1467.%T "The Secure Shell (SSH) Session Channel Break Extension" 1468.%D 2006 1469.Re 1470.Rs 1471.%R RFC 4344 1472.%T "The Secure Shell (SSH) Transport Layer Encryption Modes" 1473.%D 2006 1474.Re 1475.Rs 1476.%R RFC 4345 1477.%T "Improved Arcfour Modes for the Secure Shell (SSH) Transport Layer Protocol" 1478.%D 2006 1479.Re 1480.Rs 1481.%R RFC 4419 1482.%T "Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol" 1483.%D 2006 1484.Re 1485.Rs 1486.%R RFC 4716 1487.%T "The Secure Shell (SSH) Public Key File Format" 1488.%D 2006 1489.Re 1490.Rs 1491.%R RFC 5656 1492.%T "Elliptic Curve Algorithm Integration in the Secure Shell Transport Layer" 1493.%D 2009 1494.Re 1495.Rs 1496.%T "Hash Visualization: a New Technique to improve Real-World Security" 1497.%A A. Perrig 1498.%A D. Song 1499.%D 1999 1500.%O "International Workshop on Cryptographic Techniques and E-Commerce (CrypTEC '99)" 1501.Re 1502.Sh AUTHORS 1503OpenSSH is a derivative of the original and free 1504ssh 1.2.12 release by Tatu Ylonen. 1505Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 1506Theo de Raadt and Dug Song 1507removed many bugs, re-added newer features and 1508created OpenSSH. 1509Markus Friedl contributed the support for SSH 1510protocol versions 1.5 and 2.0. 1511