1.\" -*- nroff -*- 2.\" 3.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 4.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 5.\" All rights reserved 6.\" 7.\" As far as I am concerned, the code I have written for this software 8.\" can be used freely for any purpose. Any derived versions of this 9.\" software must be clearly marked as such, and if the derived work is 10.\" incompatible with the protocol description in the RFC file, it must be 11.\" called by a name other than "ssh" or "Secure Shell". 12.\" 13.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. 14.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. 15.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. 16.\" 17.\" Redistribution and use in source and binary forms, with or without 18.\" modification, are permitted provided that the following conditions 19.\" are met: 20.\" 1. Redistributions of source code must retain the above copyright 21.\" notice, this list of conditions and the following disclaimer. 22.\" 2. Redistributions in binary form must reproduce the above copyright 23.\" notice, this list of conditions and the following disclaimer in the 24.\" documentation and/or other materials provided with the distribution. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR 27.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES 28.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. 29.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, 30.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 31.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, 32.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY 33.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT 34.\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF 35.\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 36.\" 37.\" $OpenBSD: ssh.1,v 1.209 2005/07/06 09:33:05 dtucker Exp $ 38.\" $FreeBSD$ 39.Dd September 25, 1999 40.Dt SSH 1 41.Os 42.Sh NAME 43.Nm ssh 44.Nd OpenSSH SSH client (remote login program) 45.Sh SYNOPSIS 46.Nm ssh 47.Op Fl 1246AaCfgkMNnqsTtVvXxY 48.Op Fl b Ar bind_address 49.Op Fl c Ar cipher_spec 50.Bk -words 51.Op Fl D Ar port 52.Op Fl e Ar escape_char 53.Op Fl F Ar configfile 54.Op Fl i Ar identity_file 55.Oo Fl L Xo 56.Sm off 57.Ar port : 58.Ar host : 59.Ar hostport 60.Sm on 61.Xc 62.Oc 63.Ek 64.Op Fl l Ar login_name 65.Op Fl m Ar mac_spec 66.Op Fl o Ar option 67.Bk -words 68.Op Fl p Ar port 69.Ek 70.Oo Fl R Xo 71.Sm off 72.Ar port : 73.Ar host : 74.Ar hostport 75.Sm on 76.Xc 77.Oc 78.Op Fl S Ar ctl 79.Oo Ar user Ns @ Oc Ns Ar hostname 80.Op Ar command 81.Sh DESCRIPTION 82.Nm 83(SSH client) is a program for logging into a remote machine and for 84executing commands on a remote machine. 85It is intended to replace rlogin and rsh, 86and provide secure encrypted communications between 87two untrusted hosts over an insecure network. 88X11 connections and arbitrary TCP/IP ports 89can also be forwarded over the secure channel. 90.Pp 91.Nm 92connects and logs into the specified 93.Ar hostname 94(with optional 95.Ar user 96name). 97The user must prove 98his/her identity to the remote machine using one of several methods 99depending on the protocol version used. 100.Pp 101If 102.Ar command 103is specified, 104.Ar command 105is executed on the remote host instead of a login shell. 106.Ss SSH protocol version 1 107First, if the machine the user logs in from is listed in 108.Pa /etc/hosts.equiv 109or 110.Pa /etc/ssh/shosts.equiv 111on the remote machine, and the user names are 112the same on both sides, the user is immediately permitted to log in. 113Second, if 114.Pa .rhosts 115or 116.Pa .shosts 117exists in the user's home directory on the 118remote machine and contains a line containing the name of the client 119machine and the name of the user on that machine, the user is 120permitted to log in. 121This form of authentication alone is normally not 122allowed by the server because it is not secure. 123.Pp 124The second authentication method is the 125.Em rhosts 126or 127.Em hosts.equiv 128method combined with RSA-based host authentication. 129If the machine the user logs in from is listed in 130.Pa /etc/hosts.equiv 131or 132.Pa /etc/shosts.equiv 133on the remote machine, and the user names are 134the same on both sides, or if the files 135.Pa ~/.rhosts 136or 137.Pa ~/.shosts 138exist in the user's home directory on the 139remote machine and contain a line containing the name of the client 140machine and the name of the user on that machine, the user is 141considered for log in. 142Additionally, if the server can verify the client's 143host key (see 144.Pa /etc/ssh/ssh_known_hosts 145and 146.Pa ~/.ssh/known_hosts 147in the 148.Sx FILES 149section), only then is login permitted. 150This authentication method closes security holes due to IP 151spoofing, DNS spoofing and routing spoofing. 152[Note to the administrator: 153.Pa /etc/hosts.equiv , 154.Pa ~/.rhosts , 155and the rlogin/rsh protocol in general, are inherently insecure and should be 156disabled if security is desired.] 157.Pp 158As a third authentication method, 159.Nm 160supports RSA based authentication. 161The scheme is based on public-key cryptography: there are cryptosystems 162where encryption and decryption are done using separate keys, and it 163is not possible to derive the decryption key from the encryption key. 164RSA is one such system. 165The idea is that each user creates a public/private 166key pair for authentication purposes. 167The server knows the public key, and only the user knows the private key. 168.Pp 169The file 170.Pa ~/.ssh/authorized_keys 171lists the public keys that are permitted for logging in. 172When the user logs in, the 173.Nm 174program tells the server which key pair it would like to use for 175authentication. 176The server checks if this key is permitted, and if so, 177sends the user (actually the 178.Nm 179program running on behalf of the user) a challenge, a random number, 180encrypted by the user's public key. 181The challenge can only be decrypted using the proper private key. 182The user's client then decrypts the challenge using the private key, 183proving that he/she knows the private key 184but without disclosing it to the server. 185.Pp 186.Nm 187implements the RSA authentication protocol automatically. 188The user creates his/her RSA key pair by running 189.Xr ssh-keygen 1 . 190This stores the private key in 191.Pa ~/.ssh/identity 192and stores the public key in 193.Pa ~/.ssh/identity.pub 194in the user's home directory. 195The user should then copy the 196.Pa identity.pub 197to 198.Pa ~/.ssh/authorized_keys 199in his/her home directory on the remote machine (the 200.Pa authorized_keys 201file corresponds to the conventional 202.Pa ~/.rhosts 203file, and has one key 204per line, though the lines can be very long). 205After this, the user can log in without giving the password. 206RSA authentication is much more secure than 207.Em rhosts 208authentication. 209.Pp 210The most convenient way to use RSA authentication may be with an 211authentication agent. 212See 213.Xr ssh-agent 1 214for more information. 215.Pp 216If other authentication methods fail, 217.Nm 218prompts the user for a password. 219The password is sent to the remote 220host for checking; however, since all communications are encrypted, 221the password cannot be seen by someone listening on the network. 222.Ss SSH protocol version 2 223When a user connects using protocol version 2, 224similar authentication methods are available. 225Using the default values for 226.Cm PreferredAuthentications , 227the client will try to authenticate first using the hostbased method; 228if this method fails, public key authentication is attempted, 229and finally if this method fails, keyboard-interactive and 230password authentication are tried. 231.Pp 232The public key method is similar to RSA authentication described 233in the previous section and allows the RSA or DSA algorithm to be used: 234The client uses his private key, 235.Pa ~/.ssh/id_dsa 236or 237.Pa ~/.ssh/id_rsa , 238to sign the session identifier and sends the result to the server. 239The server checks whether the matching public key is listed in 240.Pa ~/.ssh/authorized_keys 241and grants access if both the key is found and the signature is correct. 242The session identifier is derived from a shared Diffie-Hellman value 243and is only known to the client and the server. 244.Pp 245If public key authentication fails or is not available, a password 246can be sent encrypted to the remote host to prove the user's identity. 247.Pp 248Additionally, 249.Nm 250supports hostbased or challenge response authentication. 251.Pp 252Protocol 2 provides additional mechanisms for confidentiality 253(the traffic is encrypted using AES, 3DES, Blowfish, CAST128 or Arcfour) 254and integrity (hmac-md5, hmac-sha1, hmac-ripemd160). 255Note that protocol 1 lacks a strong mechanism for ensuring the 256integrity of the connection. 257.Ss Login session and remote execution 258When the user's identity has been accepted by the server, the server 259either executes the given command, or logs into the machine and gives 260the user a normal shell on the remote machine. 261All communication with 262the remote command or shell will be automatically encrypted. 263.Pp 264If a pseudo-terminal has been allocated (normal login session), the 265user may use the escape characters noted below. 266.Pp 267If no pseudo-tty has been allocated, 268the session is transparent and can be used to reliably transfer binary data. 269On most systems, setting the escape character to 270.Dq none 271will also make the session transparent even if a tty is used. 272.Pp 273The session terminates when the command or shell on the remote 274machine exits and all X11 and TCP/IP connections have been closed. 275The exit status of the remote program is returned as the exit status of 276.Nm ssh . 277.Ss Escape Characters 278When a pseudo-terminal has been requested, 279.Nm 280supports a number of functions through the use of an escape character. 281.Pp 282A single tilde character can be sent as 283.Ic ~~ 284or by following the tilde by a character other than those described below. 285The escape character must always follow a newline to be interpreted as 286special. 287The escape character can be changed in configuration files using the 288.Cm EscapeChar 289configuration directive or on the command line by the 290.Fl e 291option. 292.Pp 293The supported escapes (assuming the default 294.Ql ~ ) 295are: 296.Bl -tag -width Ds 297.It Cm ~. 298Disconnect. 299.It Cm ~^Z 300Background 301.Nm ssh . 302.It Cm ~# 303List forwarded connections. 304.It Cm ~& 305Background 306.Nm 307at logout when waiting for forwarded connection / X11 sessions to terminate. 308.It Cm ~? 309Display a list of escape characters. 310.It Cm ~B 311Send a BREAK to the remote system 312(only useful for SSH protocol version 2 and if the peer supports it). 313.It Cm ~C 314Open command line. 315Currently this allows the addition of port forwardings using the 316.Fl L 317and 318.Fl R 319options (see below). 320It also allows the cancellation of existing remote port-forwardings 321using 322.Fl KR Ar hostport . 323Basic help is available, using the 324.Fl h 325option. 326.It Cm ~R 327Request rekeying of the connection 328(only useful for SSH protocol version 2 and if the peer supports it). 329.El 330.Ss X11 and TCP forwarding 331If the 332.Cm ForwardX11 333variable is set to 334.Dq yes 335(or see the description of the 336.Fl X 337and 338.Fl x 339options described later) 340and the user is using X11 (the 341.Ev DISPLAY 342environment variable is set), the connection to the X11 display is 343automatically forwarded to the remote side in such a way that any X11 344programs started from the shell (or command) will go through the 345encrypted channel, and the connection to the real X server will be made 346from the local machine. 347The user should not manually set 348.Ev DISPLAY . 349Forwarding of X11 connections can be 350configured on the command line or in configuration files. 351.Pp 352The 353.Ev DISPLAY 354value set by 355.Nm 356will point to the server machine, but with a display number greater than zero. 357This is normal, and happens because 358.Nm 359creates a 360.Dq proxy 361X server on the server machine for forwarding the 362connections over the encrypted channel. 363.Pp 364.Nm 365will also automatically set up Xauthority data on the server machine. 366For this purpose, it will generate a random authorization cookie, 367store it in Xauthority on the server, and verify that any forwarded 368connections carry this cookie and replace it by the real cookie when 369the connection is opened. 370The real authentication cookie is never 371sent to the server machine (and no cookies are sent in the plain). 372.Pp 373If the 374.Cm ForwardAgent 375variable is set to 376.Dq yes 377(or see the description of the 378.Fl A 379and 380.Fl a 381options described later) and 382the user is using an authentication agent, the connection to the agent 383is automatically forwarded to the remote side. 384.Pp 385Forwarding of arbitrary TCP/IP connections over the secure channel can 386be specified either on the command line or in a configuration file. 387One possible application of TCP/IP forwarding is a secure connection to an 388electronic purse; another is going through firewalls. 389.Ss Server authentication 390.Nm 391automatically maintains and checks a database containing 392identifications for all hosts it has ever been used with. 393Host keys are stored in 394.Pa ~/.ssh/known_hosts 395in the user's home directory. 396Additionally, the file 397.Pa /etc/ssh/ssh_known_hosts 398is automatically checked for known hosts. 399Any new hosts are automatically added to the user's file. 400If a host's identification ever changes, 401.Nm 402warns about this and disables password authentication to prevent a 403trojan horse from getting the user's password. 404Another purpose of this mechanism is to prevent man-in-the-middle attacks 405which could otherwise be used to circumvent the encryption. 406The 407.Cm StrictHostKeyChecking 408option can be used to prevent logins to machines whose 409host key is not known or has changed. 410.Pp 411.Nm 412can be configured to verify host identification using fingerprint resource 413records (SSHFP) published in DNS. 414The 415.Cm VerifyHostKeyDNS 416option can be used to control how DNS lookups are performed. 417SSHFP resource records can be generated using 418.Xr ssh-keygen 1 . 419.Pp 420The options are as follows: 421.Bl -tag -width Ds 422.It Fl 1 423Forces 424.Nm 425to try protocol version 1 only. 426.It Fl 2 427Forces 428.Nm 429to try protocol version 2 only. 430.It Fl 4 431Forces 432.Nm 433to use IPv4 addresses only. 434.It Fl 6 435Forces 436.Nm 437to use IPv6 addresses only. 438.It Fl A 439Enables forwarding of the authentication agent connection. 440This can also be specified on a per-host basis in a configuration file. 441.Pp 442Agent forwarding should be enabled with caution. 443Users with the ability to bypass file permissions on the remote host 444(for the agent's Unix-domain socket) 445can access the local agent through the forwarded connection. 446An attacker cannot obtain key material from the agent, 447however they can perform operations on the keys that enable them to 448authenticate using the identities loaded into the agent. 449.It Fl a 450Disables forwarding of the authentication agent connection. 451.It Fl b Ar bind_address 452Use 453.Ar bind_address 454on the local machine as the source address 455of the connection. 456Only useful on systems with more than one address. 457.It Fl C 458Requests compression of all data (including stdin, stdout, stderr, and 459data for forwarded X11 and TCP/IP connections). 460The compression algorithm is the same used by 461.Xr gzip 1 , 462and the 463.Dq level 464can be controlled by the 465.Cm CompressionLevel 466option for protocol version 1. 467Compression is desirable on modem lines and other 468slow connections, but will only slow down things on fast networks. 469The default value can be set on a host-by-host basis in the 470configuration files; see the 471.Cm Compression 472option. 473.It Fl c Ar cipher_spec 474Selects the cipher specification for encrypting the session. 475.Pp 476Protocol version 1 allows specification of a single cipher. 477The suported values are 478.Dq 3des , 479.Dq blowfish 480and 481.Dq des . 482.Ar 3des 483(triple-des) is an encrypt-decrypt-encrypt triple with three different keys. 484It is believed to be secure. 485.Ar blowfish 486is a fast block cipher; it appears very secure and is much faster than 487.Ar 3des . 488.Ar des 489is only supported in the 490.Nm 491client for interoperability with legacy protocol 1 implementations 492that do not support the 493.Ar 3des 494cipher. 495Its use is strongly discouraged due to cryptographic weaknesses. 496The default is 497.Dq 3des . 498.Pp 499For protocol version 2 500.Ar cipher_spec 501is a comma-separated list of ciphers 502listed in order of preference. 503The supported ciphers are 504.Dq 3des-cbc , 505.Dq aes128-cbc , 506.Dq aes192-cbc , 507.Dq aes256-cbc , 508.Dq aes128-ctr , 509.Dq aes192-ctr , 510.Dq aes256-ctr , 511.Dq arcfour128 , 512.Dq arcfour256 , 513.Dq arcfour , 514.Dq blowfish-cbc , 515and 516.Dq cast128-cbc . 517The default is 518.Bd -literal 519 ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour128, 520 arcfour256,arcfour,aes192-cbc,aes256-cbc,aes128-ctr, 521 aes192-ctr,aes256-ctr'' 522.Ed 523.It Fl D Ar port 524Specifies a local 525.Dq dynamic 526application-level port forwarding. 527This works by allocating a socket to listen to 528.Ar port 529on the local side, and whenever a connection is made to this port, the 530connection is forwarded over the secure channel, and the application 531protocol is then used to determine where to connect to from the 532remote machine. 533Currently the SOCKS4 and SOCKS5 protocols are supported, and 534.Nm 535will act as a SOCKS server. 536Only root can forward privileged ports. 537Dynamic port forwardings can also be specified in the configuration file. 538.It Fl e Ar ch | ^ch | none 539Sets the escape character for sessions with a pty (default: 540.Ql ~ ) . 541The escape character is only recognized at the beginning of a line. 542The escape character followed by a dot 543.Pq Ql \&. 544closes the connection; 545followed by control-Z suspends the connection; 546and followed by itself sends the escape character once. 547Setting the character to 548.Dq none 549disables any escapes and makes the session fully transparent. 550.It Fl F Ar configfile 551Specifies an alternative per-user configuration file. 552If a configuration file is given on the command line, 553the system-wide configuration file 554.Pq Pa /etc/ssh/ssh_config 555will be ignored. 556The default for the per-user configuration file is 557.Pa ~/.ssh/config . 558.It Fl f 559Requests 560.Nm 561to go to background just before command execution. 562This is useful if 563.Nm 564is going to ask for passwords or passphrases, but the user 565wants it in the background. 566This implies 567.Fl n . 568The recommended way to start X11 programs at a remote site is with 569something like 570.Ic ssh -f host xterm . 571.It Fl g 572Allows remote hosts to connect to local forwarded ports. 573.It Fl I Ar smartcard_device 574Specifies which smartcard device to use. 575The argument is the device 576.Nm 577should use to communicate with a smartcard used for storing the user's 578private RSA key. 579.It Fl i Ar identity_file 580Selects a file from which the identity (private key) for 581RSA or DSA authentication is read. 582The default is 583.Pa ~/.ssh/identity 584for protocol version 1, and 585.Pa ~/.ssh/id_rsa 586and 587.Pa ~/.ssh/id_dsa 588for protocol version 2. 589Identity files may also be specified on 590a per-host basis in the configuration file. 591It is possible to have multiple 592.Fl i 593options (and multiple identities specified in 594configuration files). 595.It Fl k 596Disables forwarding (delegation) of GSSAPI credentials to the server. 597.It Fl L Xo 598.Sm off 599.Ar port : host : hostport 600.Sm on 601.Xc 602Specifies that the given port on the local (client) host is to be 603forwarded to the given host and port on the remote side. 604This works by allocating a socket to listen to 605.Ar port 606on the local side, and whenever a connection is made to this port, the 607connection is forwarded over the secure channel, and a connection is 608made to 609.Ar host 610port 611.Ar hostport 612from the remote machine. 613Port forwardings can also be specified in the configuration file. 614Only root can forward privileged ports. 615IPv6 addresses can be specified with an alternative syntax: 616.Sm off 617.Xo 618.Ar port No / Ar host No / 619.Ar hostport . 620.Xc 621.Sm on 622.It Fl l Ar login_name 623Specifies the user to log in as on the remote machine. 624This also may be specified on a per-host basis in the configuration file. 625.It Fl M 626Places the 627.Nm 628client into 629.Dq master 630mode for connection sharing. 631Refer to the description of 632.Cm ControlMaster 633in 634.Xr ssh_config 5 635for details. 636.It Fl m Ar mac_spec 637Additionally, for protocol version 2 a comma-separated list of MAC 638(message authentication code) algorithms can 639be specified in order of preference. 640See the 641.Cm MACs 642keyword for more information. 643.It Fl N 644Do not execute a remote command. 645This is useful for just forwarding ports 646(protocol version 2 only). 647.It Fl n 648Redirects stdin from 649.Pa /dev/null 650(actually, prevents reading from stdin). 651This must be used when 652.Nm 653is run in the background. 654A common trick is to use this to run X11 programs on a remote machine. 655For example, 656.Ic ssh -n shadows.cs.hut.fi emacs & 657will start an emacs on shadows.cs.hut.fi, and the X11 658connection will be automatically forwarded over an encrypted channel. 659The 660.Nm 661program will be put in the background. 662(This does not work if 663.Nm 664needs to ask for a password or passphrase; see also the 665.Fl f 666option.) 667.It Fl o Ar option 668Can be used to give options in the format used in the configuration file. 669This is useful for specifying options for which there is no separate 670command-line flag. 671For full details of the options listed below, and their possible values, see 672.Xr ssh_config 5 . 673.Pp 674.Bl -tag -width Ds -offset indent -compact 675.It AddressFamily 676.It BatchMode 677.It BindAddress 678.It ChallengeResponseAuthentication 679.It CheckHostIP 680.It Cipher 681.It Ciphers 682.It ClearAllForwardings 683.It Compression 684.It CompressionLevel 685.It ConnectionAttempts 686.It ConnectTimeout 687.It ControlMaster 688.It ControlPath 689.It DynamicForward 690.It EscapeChar 691.It ForwardAgent 692.It ForwardX11 693.It ForwardX11Trusted 694.It GatewayPorts 695.It GlobalKnownHostsFile 696.It GSSAPIAuthentication 697.It GSSAPIDelegateCredentials 698.It Host 699.It HostbasedAuthentication 700.It HostKeyAlgorithms 701.It HostKeyAlias 702.It HostName 703.It IdentityFile 704.It IdentitiesOnly 705.It LocalForward 706.It LogLevel 707.It MACs 708.It NoHostAuthenticationForLocalhost 709.It NumberOfPasswordPrompts 710.It PasswordAuthentication 711.It Port 712.It PreferredAuthentications 713.It Protocol 714.It ProxyCommand 715.It PubkeyAuthentication 716.It RemoteForward 717.It RhostsRSAAuthentication 718.It RSAAuthentication 719.It SendEnv 720.It ServerAliveInterval 721.It ServerAliveCountMax 722.It SmartcardDevice 723.It StrictHostKeyChecking 724.It TCPKeepAlive 725.It UsePrivilegedPort 726.It User 727.It UserKnownHostsFile 728.It VerifyHostKeyDNS 729.It XAuthLocation 730.El 731.It Fl p Ar port 732Port to connect to on the remote host. 733This can be specified on a 734per-host basis in the configuration file. 735.It Fl q 736Quiet mode. 737Causes all warning and diagnostic messages to be suppressed. 738.It Fl R Xo 739.Sm off 740.Ar port : host : hostport 741.Sm on 742.Xc 743Specifies that the given port on the remote (server) host is to be 744forwarded to the given host and port on the local side. 745This works by allocating a socket to listen to 746.Ar port 747on the remote side, and whenever a connection is made to this port, the 748connection is forwarded over the secure channel, and a connection is 749made to 750.Ar host 751port 752.Ar hostport 753from the local machine. 754Port forwardings can also be specified in the configuration file. 755Privileged ports can be forwarded only when 756logging in as root on the remote machine. 757IPv6 addresses can be specified with an alternative syntax: 758.Sm off 759.Xo 760.Ar port No / Ar host No / 761.Ar hostport . 762.Xc 763.Sm on 764.It Fl S Ar ctl 765Specifies the location of a control socket for connection sharing. 766Refer to the description of 767.Cm ControlPath 768and 769.Cm ControlMaster 770in 771.Xr ssh_config 5 772for details. 773.It Fl s 774May be used to request invocation of a subsystem on the remote system. 775Subsystems are a feature of the SSH2 protocol which facilitate the use 776of SSH as a secure transport for other applications (eg.\& 777.Xr sftp 1 ) . 778The subsystem is specified as the remote command. 779.It Fl T 780Disable pseudo-tty allocation. 781.It Fl t 782Force pseudo-tty allocation. 783This can be used to execute arbitrary 784screen-based programs on a remote machine, which can be very useful, 785e.g., when implementing menu services. 786Multiple 787.Fl t 788options force tty allocation, even if 789.Nm 790has no local tty. 791.It Fl V 792Display the version number and exit. 793.It Fl v 794Verbose mode. 795Causes 796.Nm 797to print debugging messages about its progress. 798This is helpful in 799debugging connection, authentication, and configuration problems. 800Multiple 801.Fl v 802options increase the verbosity. 803The maximum is 3. 804.It Fl X 805Enables X11 forwarding. 806This can also be specified on a per-host basis in a configuration file. 807.Pp 808X11 forwarding should be enabled with caution. 809Users with the ability to bypass file permissions on the remote host 810(for the user's X authorization database) 811can access the local X11 display through the forwarded connection. 812An attacker may then be able to perform activities such as keystroke monitoring. 813.It Fl x 814Disables X11 forwarding. 815.It Fl Y 816Enables trusted X11 forwarding. 817.El 818.Sh CONFIGURATION FILES 819.Nm 820may additionally obtain configuration data from 821a per-user configuration file and a system-wide configuration file. 822The file format and configuration options are described in 823.Xr ssh_config 5 . 824.Sh ENVIRONMENT 825.Nm 826will normally set the following environment variables: 827.Bl -tag -width LOGNAME 828.It Ev DISPLAY 829The 830.Ev DISPLAY 831variable indicates the location of the X11 server. 832It is automatically set by 833.Nm 834to point to a value of the form 835.Dq hostname:n 836where hostname indicates 837the host where the shell runs, and n is an integer \*(Ge 1. 838.Nm 839uses this special value to forward X11 connections over the secure 840channel. 841The user should normally not set 842.Ev DISPLAY 843explicitly, as that 844will render the X11 connection insecure (and will require the user to 845manually copy any required authorization cookies). 846.It Ev HOME 847Set to the path of the user's home directory. 848.It Ev LOGNAME 849Synonym for 850.Ev USER ; 851set for compatibility with systems that use this variable. 852.It Ev MAIL 853Set to the path of the user's mailbox. 854.It Ev PATH 855Set to the default 856.Ev PATH , 857as specified when compiling 858.Nm ssh . 859.It Ev SSH_ASKPASS 860If 861.Nm 862needs a passphrase, it will read the passphrase from the current 863terminal if it was run from a terminal. 864If 865.Nm 866does not have a terminal associated with it but 867.Ev DISPLAY 868and 869.Ev SSH_ASKPASS 870are set, it will execute the program specified by 871.Ev SSH_ASKPASS 872and open an X11 window to read the passphrase. 873This is particularly useful when calling 874.Nm 875from a 876.Pa .Xsession 877or related script. 878(Note that on some machines it 879may be necessary to redirect the input from 880.Pa /dev/null 881to make this work.) 882.It Ev SSH_AUTH_SOCK 883Identifies the path of a unix-domain socket used to communicate with the 884agent. 885.It Ev SSH_CONNECTION 886Identifies the client and server ends of the connection. 887The variable contains 888four space-separated values: client ip-address, client port number, 889server ip-address and server port number. 890.It Ev SSH_ORIGINAL_COMMAND 891The variable contains the original command line if a forced command 892is executed. 893It can be used to extract the original arguments. 894.It Ev SSH_TTY 895This is set to the name of the tty (path to the device) associated 896with the current shell or command. 897If the current session has no tty, 898this variable is not set. 899.It Ev TZ 900The timezone variable is set to indicate the present timezone if it 901was set when the daemon was started (i.e., the daemon passes the value 902on to new connections). 903.It Ev USER 904Set to the name of the user logging in. 905.El 906.Pp 907Additionally, 908.Nm 909reads 910.Pa ~/.ssh/environment , 911and adds lines of the format 912.Dq VARNAME=value 913to the environment if the file exists and if users are allowed to 914change their environment. 915For more information, see the 916.Cm PermitUserEnvironment 917option in 918.Xr sshd_config 5 . 919.Sh FILES 920.Bl -tag -width Ds 921.It Pa ~/.ssh/known_hosts 922Records host keys for all hosts the user has logged into that are not 923in 924.Pa /etc/ssh/ssh_known_hosts . 925See 926.Xr sshd 8 . 927.It Pa ~/.ssh/identity, ~/.ssh/id_dsa, ~/.ssh/id_rsa 928Contains the authentication identity of the user. 929They are for protocol 1 RSA, protocol 2 DSA, and protocol 2 RSA, respectively. 930These files 931contain sensitive data and should be readable by the user but not 932accessible by others (read/write/execute). 933Note that 934.Nm 935ignores a private key file if it is accessible by others. 936It is possible to specify a passphrase when 937generating the key; the passphrase will be used to encrypt the 938sensitive part of this file using 3DES. 939.It Pa ~/.ssh/identity.pub, ~/.ssh/id_dsa.pub, ~/.ssh/id_rsa.pub 940Contains the public key for authentication (public part of the 941identity file in human-readable form). 942The contents of the 943.Pa ~/.ssh/identity.pub 944file should be added to the file 945.Pa ~/.ssh/authorized_keys 946on all machines 947where the user wishes to log in using protocol version 1 RSA authentication. 948The contents of the 949.Pa ~/.ssh/id_dsa.pub 950and 951.Pa ~/.ssh/id_rsa.pub 952file should be added to 953.Pa ~/.ssh/authorized_keys 954on all machines 955where the user wishes to log in using protocol version 2 DSA/RSA authentication. 956These files are not 957sensitive and can (but need not) be readable by anyone. 958These files are 959never used automatically and are not necessary; they are only provided for 960the convenience of the user. 961.It Pa ~/.ssh/config 962This is the per-user configuration file. 963The file format and configuration options are described in 964.Xr ssh_config 5 . 965Because of the potential for abuse, this file must have strict permissions: 966read/write for the user, and not accessible by others. 967.It Pa ~/.ssh/authorized_keys 968Lists the public keys (RSA/DSA) that can be used for logging in as this user. 969The format of this file is described in the 970.Xr sshd 8 971manual page. 972In the simplest form the format is the same as the 973.Pa .pub 974identity files. 975This file is not highly sensitive, but the recommended 976permissions are read/write for the user, and not accessible by others. 977.It Pa /etc/ssh/ssh_known_hosts 978Systemwide list of known host keys. 979This file should be prepared by the 980system administrator to contain the public host keys of all machines in the 981organization. 982This file should be world-readable. 983This file contains 984public keys, one per line, in the following format (fields separated 985by spaces): system name, public key and optional comment field. 986When different names are used 987for the same machine, all such names should be listed, separated by 988commas. 989The format is described in the 990.Xr sshd 8 991manual page. 992.Pp 993The canonical system name (as returned by name servers) is used by 994.Xr sshd 8 995to verify the client host when logging in; other names are needed because 996.Nm 997does not convert the user-supplied name to a canonical name before 998checking the key, because someone with access to the name servers 999would then be able to fool host authentication. 1000.It Pa /etc/ssh/ssh_config 1001Systemwide configuration file. 1002The file format and configuration options are described in 1003.Xr ssh_config 5 . 1004.It Pa /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key 1005These three files contain the private parts of the host keys 1006and are used for 1007.Cm RhostsRSAAuthentication 1008and 1009.Cm HostbasedAuthentication . 1010If the protocol version 1 1011.Cm RhostsRSAAuthentication 1012method is used, 1013.Nm 1014must be setuid root, since the host key is readable only by root. 1015For protocol version 2, 1016.Nm 1017uses 1018.Xr ssh-keysign 8 1019to access the host keys for 1020.Cm HostbasedAuthentication . 1021This eliminates the requirement that 1022.Nm 1023be setuid root when that authentication method is used. 1024By default 1025.Nm 1026is not setuid root. 1027.It Pa ~/.rhosts 1028This file is used in 1029.Em rhosts 1030authentication to list the 1031host/user pairs that are permitted to log in. 1032(Note that this file is 1033also used by rlogin and rsh, which makes using this file insecure.) 1034Each line of the file contains a host name (in the canonical form 1035returned by name servers), and then a user name on that host, 1036separated by a space. 1037On some machines this file may need to be 1038world-readable if the user's home directory is on a NFS partition, 1039because 1040.Xr sshd 8 1041reads it as root. 1042Additionally, this file must be owned by the user, 1043and must not have write permissions for anyone else. 1044The recommended 1045permission for most machines is read/write for the user, and not 1046accessible by others. 1047.Pp 1048Note that by default 1049.Xr sshd 8 1050will be installed so that it requires successful RSA host 1051authentication before permitting 1052.Em rhosts 1053authentication. 1054If the server machine does not have the client's host key in 1055.Pa /etc/ssh/ssh_known_hosts , 1056it can be stored in 1057.Pa ~/.ssh/known_hosts . 1058The easiest way to do this is to 1059connect back to the client from the server machine using ssh; this 1060will automatically add the host key to 1061.Pa ~/.ssh/known_hosts . 1062.It Pa ~/.shosts 1063This file is used exactly the same way as 1064.Pa .rhosts . 1065The purpose for 1066having this file is to be able to use rhosts authentication with 1067.Nm 1068without permitting login with 1069.Xr rlogin 1070or 1071.Xr rsh 1 . 1072.It Pa /etc/hosts.equiv 1073This file is used during 1074.Em rhosts 1075authentication. 1076It contains 1077canonical hosts names, one per line (the full format is described in the 1078.Xr sshd 8 1079manual page). 1080If the client host is found in this file, login is 1081automatically permitted provided client and server user names are the 1082same. 1083Additionally, successful RSA host authentication is normally 1084required. 1085This file should only be writable by root. 1086.It Pa /etc/ssh/shosts.equiv 1087This file is processed exactly as 1088.Pa /etc/hosts.equiv . 1089This file may be useful to permit logins using 1090.Nm 1091but not using rsh/rlogin. 1092.It Pa /etc/ssh/sshrc 1093Commands in this file are executed by 1094.Nm 1095when the user logs in just before the user's shell (or command) is started. 1096See the 1097.Xr sshd 8 1098manual page for more information. 1099.It Pa ~/.ssh/rc 1100Commands in this file are executed by 1101.Nm 1102when the user logs in just before the user's shell (or command) is 1103started. 1104See the 1105.Xr sshd 8 1106manual page for more information. 1107.It Pa ~/.ssh/environment 1108Contains additional definitions for environment variables, see section 1109.Sx ENVIRONMENT 1110above. 1111.El 1112.Sh DIAGNOSTICS 1113.Nm 1114exits with the exit status of the remote command or with 255 1115if an error occurred. 1116.Sh SEE ALSO 1117.Xr gzip 1 , 1118.Xr rsh 1 , 1119.Xr scp 1 , 1120.Xr sftp 1 , 1121.Xr ssh-add 1 , 1122.Xr ssh-agent 1 , 1123.Xr ssh-keygen 1 , 1124.Xr telnet 1 , 1125.Xr hosts.equiv 5 , 1126.Xr ssh_config 5 , 1127.Xr ssh-keysign 8 , 1128.Xr sshd 8 1129.Rs 1130.%A T. Ylonen 1131.%A T. Kivinen 1132.%A M. Saarinen 1133.%A T. Rinne 1134.%A S. Lehtinen 1135.%T "SSH Protocol Architecture" 1136.%N draft-ietf-secsh-architecture-12.txt 1137.%D January 2002 1138.%O work in progress material 1139.Re 1140.Sh AUTHORS 1141OpenSSH is a derivative of the original and free 1142ssh 1.2.12 release by Tatu Ylonen. 1143Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, 1144Theo de Raadt and Dug Song 1145removed many bugs, re-added newer features and 1146created OpenSSH. 1147Markus Friedl contributed the support for SSH 1148protocol versions 1.5 and 2.0. 1149