1.\" -*- nroff -*- 2.\" 3.\" ssh.1.in 4.\" 5.\" Author: Tatu Ylonen <ylo@cs.hut.fi> 6.\" 7.\" Copyright (c) 1995 Tatu Ylonen <ylo@cs.hut.fi>, Espoo, Finland 8.\" All rights reserved 9.\" 10.\" Created: Sat Apr 22 21:55:14 1995 ylo 11.\" 12.\" $Id: ssh.1,v 1.37 2000/02/21 14:19:09 deraadt Exp $ 13.\" 14.Dd September 25, 1999 15.Dt SSH 1 16.Os 17.Sh NAME 18.Nm ssh 19.Nd OpenSSH secure shell client (remote login program) 20.Sh SYNOPSIS 21.Nm ssh 22.Op Fl l Ar login_name 23.Op Ar hostname | user@hostname 24.Op Ar command 25.Pp 26.Nm ssh 27.Op Fl afgknqtvxCPX46 28.Op Fl c Ar blowfish | 3des 29.Op Fl e Ar escape_char 30.Op Fl i Ar identity_file 31.Op Fl l Ar login_name 32.Op Fl o Ar option 33.Op Fl p Ar port 34.Oo Fl L Xo 35.Sm off 36.Ar port : 37.Ar host : 38.Ar hostport 39.Sm on 40.Xc 41.Oc 42.Oo Fl R Xo 43.Sm off 44.Ar port : 45.Ar host : 46.Ar hostport 47.Sm on 48.Xc 49.Oc 50.Op Ar hostname | user@hostname 51.Op Ar command 52.Sh DESCRIPTION 53.Nm 54(Secure Shell) is a program for logging into a remote machine and for 55executing commands on a remote machine. It is intended to replace 56rlogin and rsh, and provide secure encrypted communications between 57two untrusted hosts over an insecure network. X11 connections and 58arbitrary TCP/IP ports can also be forwarded over the secure channel. 59.Pp 60.Nm 61connects and logs into the specified 62.Ar hostname . 63The user must prove 64his/her identity to the remote machine using one of several methods. 65.Pp 66First, if the machine the user logs in from is listed in 67.Pa /etc/hosts.equiv 68or 69.Pa /etc/shosts.equiv 70on the remote machine, and the user names are 71the same on both sides, the user is immediately permitted to log in. 72Second, if 73.Pa \&.rhosts 74or 75.Pa \&.shosts 76exists in the user's home directory on the 77remote machine and contains a line containing the name of the client 78machine and the name of the user on that machine, the user is 79permitted to log in. This form of authentication alone is normally not 80allowed by the server because it is not secure. 81.Pp 82The second (and primary) authentication method is the 83.Pa rhosts 84or 85.Pa hosts.equiv 86method combined with RSA-based host authentication. It 87means that if the login would be permitted by 88.Pa \&.rhosts , 89.Pa \&.shosts , 90.Pa /etc/hosts.equiv , 91or 92.Pa /etc/shosts.equiv , 93and if additionally the server can verify the client's 94host key (see 95.Pa /etc/ssh_known_hosts 96and 97.Pa $HOME/.ssh/known_hosts 98in the 99.Sx FILES 100section), only then login is 101permitted. This authentication method closes security holes due to IP 102spoofing, DNS spoofing and routing spoofing. [Note to the 103administrator: 104.Pa /etc/hosts.equiv , 105.Pa \&.rhosts , 106and the rlogin/rsh protocol in general, are inherently insecure and should be 107disabled if security is desired.] 108.Pp 109As a third authentication method, 110.Nm 111supports RSA based authentication. 112The scheme is based on public-key cryptography: there are cryptosystems 113where encryption and decryption are done using separate keys, and it 114is not possible to derive the decryption key from the encryption key. 115RSA is one such system. The idea is that each user creates a public/private 116key pair for authentication purposes. The 117server knows the public key, and only the user knows the private key. 118The file 119.Pa $HOME/.ssh/authorized_keys 120lists the public keys that are permitted for logging 121in. When the user logs in, the 122.Nm 123program tells the server which key pair it would like to use for 124authentication. The server checks if this key is permitted, and if 125so, sends the user (actually the 126.Nm 127program running on behalf of the user) a challenge, a random number, 128encrypted by the user's public key. The challenge can only be 129decrypted using the proper private key. The user's client then decrypts the 130challenge using the private key, proving that he/she knows the private 131key but without disclosing it to the server. 132.Pp 133.Nm 134implements the RSA authentication protocol automatically. The user 135creates his/her RSA key pair by running 136.Xr ssh-keygen 1 . 137This stores the private key in 138.Pa \&.ssh/identity 139and the public key in 140.Pa \&.ssh/identity.pub 141in the user's home directory. The user should then 142copy the 143.Pa identity.pub 144to 145.Pa \&.ssh/authorized_keys 146in his/her home directory on the remote machine (the 147.Pa authorized_keys 148file corresponds to the conventional 149.Pa \&.rhosts 150file, and has one key 151per line, though the lines can be very long). After this, the user 152can log in without giving the password. RSA authentication is much 153more secure than rhosts authentication. 154.Pp 155The most convenient way to use RSA authentication may be with an 156authentication agent. See 157.Xr ssh-agent 1 158for more information. 159.Pp 160If other authentication methods fail, 161.Nm 162prompts the user for a password. The password is sent to the remote 163host for checking; however, since all communications are encrypted, 164the password cannot be seen by someone listening on the network. 165.Pp 166When the user's identity has been accepted by the server, the server 167either executes the given command, or logs into the machine and gives 168the user a normal shell on the remote machine. All communication with 169the remote command or shell will be automatically encrypted. 170.Pp 171If a pseudo-terminal has been allocated (normal login session), the 172user can disconnect with 173.Ic ~. , 174and suspend 175.Nm 176with 177.Ic ~^Z . 178All forwarded connections can be listed with 179.Ic ~# 180and if 181the session blocks waiting for forwarded X11 or TCP/IP 182connections to terminate, it can be backgrounded with 183.Ic ~& 184(this should not be used while the user shell is active, as it can cause the 185shell to hang). All available escapes can be listed with 186.Ic ~? . 187.Pp 188A single tilde character can be sent as 189.Ic ~~ 190(or by following the tilde by a character other than those described above). 191The escape character must always follow a newline to be interpreted as 192special. The escape character can be changed in configuration files 193or on the command line. 194.Pp 195If no pseudo tty has been allocated, the 196session is transparent and can be used to reliably transfer binary 197data. On most systems, setting the escape character to 198.Dq none 199will also make the session transparent even if a tty is used. 200.Pp 201The session terminates when the command or shell in on the remote 202machine exists and all X11 and TCP/IP connections have been closed. 203The exit status of the remote program is returned as the exit status 204of 205.Nm ssh . 206.Pp 207If the user is using X11 (the 208.Ev DISPLAY 209environment variable is set), the connection to the X11 display is 210automatically forwarded to the remote side in such a way that any X11 211programs started from the shell (or command) will go through the 212encrypted channel, and the connection to the real X server will be made 213from the local machine. The user should not manually set 214.Ev DISPLAY . 215Forwarding of X11 connections can be 216configured on the command line or in configuration files. 217.Pp 218The 219.Ev DISPLAY 220value set by 221.Nm 222will point to the server machine, but with a display number greater 223than zero. This is normal, and happens because 224.Nm 225creates a 226.Dq proxy 227X server on the server machine for forwarding the 228connections over the encrypted channel. 229.Pp 230.Nm 231will also automatically set up Xauthority data on the server machine. 232For this purpose, it will generate a random authorization cookie, 233store it in Xauthority on the server, and verify that any forwarded 234connections carry this cookie and replace it by the real cookie when 235the connection is opened. The real authentication cookie is never 236sent to the server machine (and no cookies are sent in the plain). 237.Pp 238If the user is using an authentication agent, the connection to the agent 239is automatically forwarded to the remote side unless disabled on 240command line or in a configuration file. 241.Pp 242Forwarding of arbitrary TCP/IP connections over the secure channel can 243be specified either on command line or in a configuration file. One 244possible application of TCP/IP forwarding is a secure connection to an 245electronic purse; another is going trough firewalls. 246.Pp 247.Nm 248automatically maintains and checks a database containing RSA-based 249identifications for all hosts it has ever been used with. The 250database is stored in 251.Pa \&.ssh/known_hosts 252in the user's home directory. Additionally, the file 253.Pa /etc/ssh_known_hosts 254is automatically checked for known hosts. Any new hosts are 255automatically added to the user's file. If a host's identification 256ever changes, 257.Nm 258warns about this and disables password authentication to prevent a 259trojan horse from getting the user's password. Another purpose of 260this mechanism is to prevent man-in-the-middle attacks which could 261otherwise be used to circumvent the encryption. The 262.Cm StrictHostKeyChecking 263option (see below) can be used to prevent logins to machines whose 264host key is not known or has changed. 265.Sh OPTIONS 266.Bl -tag -width Ds 267.It Fl a 268Disables forwarding of the authentication agent connection. This may 269also be specified on a per-host basis in the configuration file. 270.It Fl c Ar blowfish|3des 271Selects the cipher to use for encrypting the session. 272.Ar 3des 273is used by default. It is believed to be secure. 274.Ar 3des 275(triple-des) is an encrypt-decrypt-encrypt triple with three different keys. 276It is presumably more secure than the 277.Ar des 278cipher which is no longer supported in ssh. 279.Ar blowfish 280is a fast block cipher, it appears very secure and is much faster than 281.Ar 3des . 282.It Fl e Ar ch|^ch|none 283Sets the escape character for sessions with a pty (default: 284.Ql ~ ) . 285The escape character is only recognized at the beginning of a line. The 286escape character followed by a dot 287.Pq Ql \&. 288closes the connection, followed 289by control-Z suspends the connection, and followed by itself sends the 290escape character once. Setting the character to 291.Dq none 292disables any escapes and makes the session fully transparent. 293.It Fl f 294Requests 295.Nm 296to go to background just before command execution. This is useful 297if 298.Nm 299is going to ask for passwords or passphrases, but the user 300wants it in the background. This implies 301.Fl n . 302The recommended way to start X11 programs at a remote site is with 303something like 304.Ic ssh -f host xterm . 305.It Fl g 306Allows remote hosts to connect to local forwarded ports. 307.It Fl i Ar identity_file 308Selects the file from which the identity (private key) for 309RSA authentication is read. Default is 310.Pa \&.ssh/identity 311in the user's home directory. Identity files may also be specified on 312a per-host basis in the configuration file. It is possible to have 313multiple 314.Fl i 315options (and multiple identities specified in 316configuration files). 317.It Fl k 318Disables forwarding of Kerberos tickets and AFS tokens. This may 319also be specified on a per-host basis in the configuration file. 320.It Fl l Ar login_name 321Specifies the user to log in as on the remote machine. This may also 322be specified on a per-host basis in the configuration file. 323.It Fl n 324Redirects stdin from 325.Pa /dev/null 326(actually, prevents reading from stdin). 327This must be used when 328.Nm 329is run in the background. A common trick is to use this to run X11 330programs in a remote machine. For example, 331.Ic ssh -n shadows.cs.hut.fi emacs & 332will start an emacs on shadows.cs.hut.fi, and the X11 333connection will be automatically forwarded over an encrypted channel. 334The 335.Nm 336program will be put in the background. 337(This does not work if 338.Nm 339needs to ask for a password or passphrase; see also the 340.Fl f 341option.) 342.It Fl o Ar option 343Can be used to give options in the format used in the config file. 344This is useful for specifying options for which there is no separate 345command-line flag. The option has the same format as a line in the 346configuration file. 347.It Fl p Ar port 348Port to connect to on the remote host. This can be specified on a 349per-host basis in the configuration file. 350.It Fl P 351Use a non-privileged port for outgoing connections. 352This can be used if your firewall does 353not permit connections from privileged ports. 354Note that this option turns off 355.Cm RhostsAuthentication 356and 357.Cm RhostsRSAAuthentication . 358.It Fl q 359Quiet mode. Causes all warning and diagnostic messages to be 360suppressed. Only fatal errors are displayed. 361.It Fl t 362Force pseudo-tty allocation. This can be used to execute arbitary 363screen-based programs on a remote machine, which can be very useful 364e.g. when implementing menu services. 365.It Fl v 366Verbose mode. Causes 367.Nm 368to print debugging messages about its progress. This is helpful in 369debugging connection, authentication, and configuration problems. 370The verbose mode is also used to display 371.Xr skey 1 372challenges, if the user entered "s/key" as password. 373.It Fl x 374Disables X11 forwarding. This can also be specified on a per-host 375basis in a configuration file. 376.It Fl X 377Enables X11 forwarding. 378.It Fl C 379Requests compression of all data (including stdin, stdout, stderr, and 380data for forwarded X11 and TCP/IP connections). The compression 381algorithm is the same used by 382.Xr gzip 1 , 383and the 384.Dq level 385can be controlled by the 386.Cm CompressionLevel 387option (see below). Compression is desirable on modem lines and other 388slow connections, but will only slow down things on fast networks. 389The default value can be set on a host-by-host basis in the 390configuration files; see the 391.Cm Compress 392option below. 393.It Fl L Ar port:host:hostport 394Specifies that the given port on the local (client) host is to be 395forwarded to the given host and port on the remote side. This works 396by allocating a socket to listen to 397.Ar port 398on the local side, and whenever a connection is made to this port, the 399connection is forwarded over the secure channel, and a connection is 400made to 401.Ar host 402port 403.Ar hostport 404from the remote machine. Port forwardings can also be specified in the 405configuration file. Only root can forward privileged ports. 406IPv6 addresses can be specified with an alternative syntax: 407.Ar port/host/hostport 408.It Fl R Ar port:host:hostport 409Specifies that the given port on the remote (server) host is to be 410forwarded to the given host and port on the local side. This works 411by allocating a socket to listen to 412.Ar port 413on the remote side, and whenever a connection is made to this port, the 414connection is forwarded over the secure channel, and a connection is 415made to 416.Ar host 417port 418.Ar hostport 419from the local machine. Port forwardings can also be specified in the 420configuration file. Privileged ports can be forwarded only when 421logging in as root on the remote machine. 422.It Fl 4 423Forces 424.Nm 425to use IPv4 addresses only. 426.It Fl 6 427Forces 428.Nm 429to use IPv6 addresses only. 430.El 431.Sh CONFIGURATION FILES 432.Nm 433obtains configuration data from the following sources (in this order): 434command line options, user's configuration file 435.Pq Pa $HOME/.ssh/config , 436and system-wide configuration file 437.Pq Pa /etc/ssh_config . 438For each parameter, the first obtained value 439will be used. The configuration files contain sections bracketed by 440"Host" specifications, and that section is only applied for hosts that 441match one of the patterns given in the specification. The matched 442host name is the one given on the command line. 443.Pp 444Since the first obtained value for each parameter is used, more 445host-specific declarations should be given near the beginning of the 446file, and general defaults at the end. 447.Pp 448The configuration file has the following format: 449.Pp 450Empty lines and lines starting with 451.Ql # 452are comments. 453.Pp 454Otherwise a line is of the format 455.Dq keyword arguments . 456The possible 457keywords and their meanings are as follows (note that the 458configuration files are case-sensitive): 459.Bl -tag -width Ds 460.It Cm Host 461Restricts the following declarations (up to the next 462.Cm Host 463keyword) to be only for those hosts that match one of the patterns 464given after the keyword. 465.Ql \&* 466and 467.Ql ? 468can be used as wildcards in the 469patterns. A single 470.Ql \&* 471as a pattern can be used to provide global 472defaults for all hosts. The host is the 473.Ar hostname 474argument given on the command line (i.e., the name is not converted to 475a canonicalized host name before matching). 476.It Cm AFSTokenPassing 477Specifies whether to pass AFS tokens to remote host. The argument to 478this keyword must be 479.Dq yes 480or 481.Dq no . 482.It Cm BatchMode 483If set to 484.Dq yes , 485passphrase/password querying will be disabled. This 486option is useful in scripts and other batch jobs where you have no 487user to supply the password. The argument must be 488.Dq yes 489or 490.Dq no . 491.It Cm CheckHostIP 492If this flag is set to 493.Dq yes , 494ssh will additionally check the host ip address in the 495.Pa known_hosts 496file. This allows ssh to detect if a host key changed due to DNS spoofing. 497If the option is set to 498.Dq no , 499the check will not be executed. 500.It Cm Cipher 501Specifies the cipher to use for encrypting the session. Currently, 502.Dq blowfish , 503and 504.Dq 3des 505are supported. The default is 506.Dq 3des . 507.It Cm Compression 508Specifies whether to use compression. The argument must be 509.Dq yes 510or 511.Dq no . 512.It Cm CompressionLevel 513Specifies the compression level to use if compression is enable. The 514argument must be an integer from 1 (fast) to 9 (slow, best). The 515default level is 6, which is good for most applications. The meaning 516of the values is the same as in 517.Xr gzip 1 . 518.It Cm ConnectionAttempts 519Specifies the number of tries (one per second) to make before falling 520back to rsh or exiting. The argument must be an integer. This may be 521useful in scripts if the connection sometimes fails. 522.It Cm EscapeChar 523Sets the escape character (default: 524.Ql ~ ) . 525The escape character can also 526be set on the command line. The argument should be a single 527character, 528.Ql ^ 529followed by a letter, or 530.Dq none 531to disable the escape 532character entirely (making the connection transparent for binary 533data). 534.It Cm FallBackToRsh 535Specifies that if connecting via 536.Nm 537fails due to a connection refused error (there is no 538.Xr sshd 8 539listening on the remote host), 540.Xr rsh 1 541should automatically be used instead (after a suitable warning about 542the session being unencrypted). The argument must be 543.Dq yes 544or 545.Dq no . 546.It Cm ForwardAgent 547Specifies whether the connection to the authentication agent (if any) 548will be forwarded to the remote machine. The argument must be 549.Dq yes 550or 551.Dq no . 552.It Cm ForwardX11 553Specifies whether X11 connections will be automatically redirected 554over the secure channel and 555.Ev DISPLAY 556set. The argument must be 557.Dq yes 558or 559.Dq no . 560.It Cm GatewayPorts 561Specifies whether remote hosts are allowed to connect to local 562forwarded ports. 563The argument must be 564.Dq yes 565or 566.Dq no . 567The default is 568.Dq no . 569.It Cm GlobalKnownHostsFile 570Specifies a file to use instead of 571.Pa /etc/ssh_known_hosts . 572.It Cm HostName 573Specifies the real host name to log into. This can be used to specify 574nicnames or abbreviations for hosts. Default is the name given on the 575command line. Numeric IP addresses are also permitted (both on the 576command line and in 577.Cm HostName 578specifications). 579.It Cm IdentityFile 580Specifies the file from which the user's RSA authentication identity 581is read (default 582.Pa .ssh/identity 583in the user's home directory). 584Additionally, any identities represented by the authentication agent 585will be used for authentication. The file name may use the tilde 586syntax to refer to a user's home directory. It is possible to have 587multiple identity files specified in configuration files; all these 588identities will be tried in sequence. 589.It Cm KeepAlive 590Specifies whether the system should send keepalive messages to the 591other side. If they are sent, death of the connection or crash of one 592of the machines will be properly noticed. However, this means that 593connections will die if the route is down temporarily, and some people 594find it annoying. 595.Pp 596The default is 597.Dq yes 598(to send keepalives), and the client will notice 599if the network goes down or the remote host dies. This is important 600in scripts, and many users want it too. 601.Pp 602To disable keepalives, the value should be set to 603.Dq no 604in both the server and the client configuration files. 605.It Cm KerberosAuthentication 606Specifies whether Kerberos authentication will be used. The argument to 607this keyword must be 608.Dq yes 609or 610.Dq no . 611.It Cm KerberosTgtPassing 612Specifies whether a Kerberos TGT will be forwarded to the server. This 613will only work if the Kerberos server is actually an AFS kaserver. The 614argument to this keyword must be 615.Dq yes 616or 617.Dq no . 618.It Cm LocalForward 619Specifies that a TCP/IP port on the local machine be forwarded over 620the secure channel to given host:port from the remote machine. The 621first argument must be a port number, and the second must be 622host:port. Multiple forwardings may be specified, and additional 623forwardings can be given on the command line. Only the root can 624forward privileged ports. 625.It Cm LogLevel 626Gives the verbosity level that is used when logging messages from 627.Nm ssh . 628The possible values are: 629QUIET, FATAL, ERROR, INFO, CHAT and DEBUG. 630The default is INFO. 631.It Cm NumberOfPasswordPrompts 632Specifies the number of password prompts before giving up. The 633argument to this keyword must be an integer. Default is 3. 634.It Cm PasswordAuthentication 635Specifies whether to use password authentication. The argument to 636this keyword must be 637.Dq yes 638or 639.Dq no . 640.It Cm Port 641Specifies the port number to connect on the remote host. Default is 64222. 643.It Cm ProxyCommand 644Specifies the command to use to connect to the server. The command 645string extends to the end of the line, and is executed with /bin/sh. 646In the command string, %h will be substituted by the host name to 647connect and %p by the port. The command can be basically anything, 648and should read from its stdin and write to its stdout. It should 649eventually connect an 650.Xr sshd 8 651server running on some machine, or execute 652.Ic sshd -i 653somewhere. Host key management will be done using the 654HostName of the host being connected (defaulting to the name typed by 655the user). 656Note that 657.Cm CheckHostIP 658is not available for connects with a proxy command. 659.Pp 660.It Cm RemoteForward 661Specifies that a TCP/IP port on the remote machine be forwarded over 662the secure channel to given host:port from the local machine. The 663first argument must be a port number, and the second must be 664host:port. Multiple forwardings may be specified, and additional 665forwardings can be given on the command line. Only the root can 666forward privileged ports. 667.It Cm RhostsAuthentication 668Specifies whether to try rhosts based authentication. Note that this 669declaration only affects the client side and has no effect whatsoever 670on security. Disabling rhosts authentication may reduce 671authentication time on slow connections when rhosts authentication is 672not used. Most servers do not permit RhostsAuthentication because it 673is not secure (see RhostsRSAAuthentication). The argument to this 674keyword must be 675.Dq yes 676or 677.Dq no . 678.It Cm RhostsRSAAuthentication 679Specifies whether to try rhosts based authentication with RSA host 680authentication. This is the primary authentication method for most 681sites. The argument must be 682.Dq yes 683or 684.Dq no . 685.It Cm RSAAuthentication 686Specifies whether to try RSA authentication. The argument to this 687keyword must be 688.Dq yes 689or 690.Dq no . 691RSA authentication will only be 692attempted if the identity file exists, or an authentication agent is 693running. 694.It Cm SkeyAuthentication 695Specifies whether to use 696.Xr skey 1 697authentication. The argument to 698this keyword must be 699.Dq yes 700or 701.Dq no . 702The default is 703.Dq no . 704.It Cm StrictHostKeyChecking 705If this flag is set to 706.Dq yes , 707.Nm 708ssh will never automatically add host keys to the 709.Pa $HOME/.ssh/known_hosts 710file, and refuses to connect hosts whose host key has changed. This 711provides maximum protection against trojan horse attacks. However, it 712can be somewhat annoying if you don't have good 713.Pa /etc/ssh_known_hosts 714files installed and frequently 715connect new hosts. Basically this option forces the user to manually 716add any new hosts. Normally this option is disabled, and new hosts 717will automatically be added to the known host files. The host keys of 718known hosts will be verified automatically in either case. The 719argument must be 720.Dq yes 721or 722.Dq no . 723.It Cm UsePrivilegedPort 724Specifies whether to use a privileged port for outgoing connections. 725The argument must be 726.Dq yes 727or 728.Dq no . 729The default is 730.Dq yes . 731Note that setting this option to 732.Dq no 733turns off 734.Cm RhostsAuthentication 735and 736.Cm RhostsRSAAuthentication . 737.It Cm User 738Specifies the user to log in as. This can be useful if you have a 739different user name in different machines. This saves the trouble of 740having to remember to give the user name on the command line. 741.It Cm UserKnownHostsFile 742Specifies a file to use instead of 743.Pa $HOME/.ssh/known_hosts . 744.It Cm UseRsh 745Specifies that rlogin/rsh should be used for this host. It is 746possible that the host does not at all support the 747.Nm 748protocol. This causes 749.Nm 750to immediately exec 751.Xr rsh 1 . 752All other options (except 753.Cm HostName ) 754are ignored if this has been specified. The argument must be 755.Dq yes 756or 757.Dq no . 758.Sh ENVIRONMENT 759.Nm 760will normally set the following environment variables: 761.Bl -tag -width Ds 762.It Ev DISPLAY 763The 764.Ev DISPLAY 765variable indicates the location of the X11 server. It is 766automatically set by 767.Nm 768to point to a value of the form 769.Dq hostname:n 770where hostname indicates 771the host where the shell runs, and n is an integer >= 1. Ssh uses 772this special value to forward X11 connections over the secure 773channel. The user should normally not set DISPLAY explicitly, as that 774will render the X11 connection insecure (and will require the user to 775manually copy any required authorization cookies). 776.It Ev HOME 777Set to the path of the user's home directory. 778.It Ev LOGNAME 779Synonym for 780.Ev USER ; 781set for compatibility with systems that use this variable. 782.It Ev MAIL 783Set to point the user's mailbox. 784.It Ev PATH 785Set to the default 786.Ev PATH , 787as specified when compiling 788.Nm ssh . 789.It Ev SSH_AUTH_SOCK 790indicates the path of a unix-domain socket used to communicate with the 791agent. 792.It Ev SSH_CLIENT 793Identifies the client end of the connection. The variable contains 794three space-separated values: client ip-address, client port number, 795and server port number. 796.It Ev SSH_TTY 797This is set to the name of the tty (path to the device) associated 798with the current shell or command. If the current session has no tty, 799this variable is not set. 800.It Ev TZ 801The timezone variable is set to indicate the present timezone if it 802was set when the daemon was started (e.i., the daemon passes the value 803on to new connections). 804.It Ev USER 805Set to the name of the user logging in. 806.El 807.Pp 808Additionally, 809.Nm 810reads 811.Pa $HOME/.ssh/environment , 812and adds lines of the format 813.Dq VARNAME=value 814to the environment. 815.Sh FILES 816.Bl -tag -width Ds 817.It Pa $HOME/.ssh/known_hosts 818Records host keys for all hosts the user has logged into (that are not 819in 820.Pa /etc/ssh_known_hosts ) . 821See 822.Xr sshd 8 . 823.It Pa $HOME/.ssh/identity 824Contains the RSA authentication identity of the user. This file 825contains sensitive data and should be readable by the user but not 826accessible by others (read/write/execute). 827Note that 828.Nm 829ignores this file if it is accessible by others. 830It is possible to specify a passphrase when 831generating the key; the passphrase will be used to encrypt the 832sensitive part of this file using 3DES. 833.It Pa $HOME/.ssh/identity.pub 834Contains the public key for authentication (public part of the 835identity file in human-readable form). The contents of this file 836should be added to 837.Pa $HOME/.ssh/authorized_keys 838on all machines 839where you wish to log in using RSA authentication. This file is not 840sensitive and can (but need not) be readable by anyone. This file is 841never used automatically and is not necessary; it is only provided for 842the convenience of the user. 843.It Pa $HOME/.ssh/config 844This is the per-user configuration file. The format of this file is 845described above. This file is used by the 846.Nm 847client. This file does not usually contain any sensitive information, 848but the recommended permissions are read/write for the user, and not 849accessible by others. 850.It Pa $HOME/.ssh/authorized_keys 851Lists the RSA keys that can be used for logging in as this user. The 852format of this file is described in the 853.Xr sshd 8 854manual page. In the simplest form the format is the same as the .pub 855identity files (that is, each line contains the number of bits in 856modulus, public exponent, modulus, and comment fields, separated by 857spaces). This file is not highly sensitive, but the recommended 858permissions are read/write for the user, and not accessible by others. 859.It Pa /etc/ssh_known_hosts 860Systemwide list of known host keys. This file should be prepared by the 861system administrator to contain the public host keys of all machines in the 862organization. This file should be world-readable. This file contains 863public keys, one per line, in the following format (fields separated 864by spaces): system name, number of bits in modulus, public exponent, 865modulus, and optional comment field. When different names are used 866for the same machine, all such names should be listed, separated by 867commas. The format is described on the 868.Xr sshd 8 869manual page. 870.Pp 871The canonical system name (as returned by name servers) is used by 872.Xr sshd 8 873to verify the client host when logging in; other names are needed because 874.Nm 875does not convert the user-supplied name to a canonical name before 876checking the key, because someone with access to the name servers 877would then be able to fool host authentication. 878.It Pa /etc/ssh_config 879Systemwide configuration file. This file provides defaults for those 880values that are not specified in the user's configuration file, and 881for those users who do not have a configuration file. This file must 882be world-readable. 883.It Pa $HOME/.rhosts 884This file is used in 885.Pa \&.rhosts 886authentication to list the 887host/user pairs that are permitted to log in. (Note that this file is 888also used by rlogin and rsh, which makes using this file insecure.) 889Each line of the file contains a host name (in the canonical form 890returned by name servers), and then a user name on that host, 891separated by a space. One some machines this file may need to be 892world-readable if the user's home directory is on a NFS partition, 893because 894.Xr sshd 8 895reads it as root. Additionally, this file must be owned by the user, 896and must not have write permissions for anyone else. The recommended 897permission for most machines is read/write for the user, and not 898accessible by others. 899.Pp 900Note that by default 901.Xr sshd 8 902will be installed so that it requires successful RSA host 903authentication before permitting \s+2.\s0rhosts authentication. If your 904server machine does not have the client's host key in 905.Pa /etc/ssh_known_hosts , 906you can store it in 907.Pa $HOME/.ssh/known_hosts . 908The easiest way to do this is to 909connect back to the client from the server machine using ssh; this 910will automatically add the host key inxi 911.Pa $HOME/.ssh/known_hosts . 912.It Pa $HOME/.shosts 913This file is used exactly the same way as 914.Pa \&.rhosts . 915The purpose for 916having this file is to be able to use rhosts authentication with 917.Nm 918without permitting login with 919.Xr rlogin 1 920or 921.Xr rsh 1 . 922.It Pa /etc/hosts.equiv 923This file is used during 924.Pa \&.rhosts authentication. It contains 925canonical hosts names, one per line (the full format is described on 926the 927.Xr sshd 8 928manual page). If the client host is found in this file, login is 929automatically permitted provided client and server user names are the 930same. Additionally, successful RSA host authentication is normally 931required. This file should only be writable by root. 932.It Pa /etc/shosts.equiv 933This file is processed exactly as 934.Pa /etc/hosts.equiv . 935This file may be useful to permit logins using 936.Nm 937but not using rsh/rlogin. 938.It Pa /etc/sshrc 939Commands in this file are executed by 940.Nm 941when the user logs in just before the user's shell (or command) is started. 942See the 943.Xr sshd 8 944manual page for more information. 945.It Pa $HOME/.ssh/rc 946Commands in this file are executed by 947.Nm 948when the user logs in just before the user's shell (or command) is 949started. 950See the 951.Xr sshd 8 952manual page for more information. 953.It Pa $HOME/.ssh/environment 954Contains additional definitions for environment variables, see section 955.Sx ENVIRONMENT 956above. 957.It Pa libcrypto.so.X.1 958A version of this library which includes support for the RSA algorithm 959is required for proper operation. 960.Sh AUTHOR 961OpenSSH 962is a derivative of the original (free) ssh 1.2.12 release by Tatu Ylonen, 963but with bugs removed and newer features re-added. Rapidly after the 9641.2.12 release, newer versions of the original ssh bore successively 965more restrictive licenses, and thus demand for a free version was born. 966This version of OpenSSH 967.Bl -bullet 968.It 969has all components of a restrictive nature (i.e., patents, see 970.Xr ssl 8 ) 971directly removed from the source code; any licensed or patented components 972are chosen from 973external libraries. 974.It 975has been updated to support ssh protocol 1.5, making it compatible with 976all other ssh protocol 1 clients and servers. 977.It 978contains added support for 979.Xr kerberos 8 980authentication and ticket passing. 981.It 982supports one-time password authentication with 983.Xr skey 1 . 984.El 985.Pp 986The libraries described in 987.Xr ssl 8 988are required for proper operation. 989.Pp 990OpenSSH has been created by Aaron Campbell, Bob Beck, Markus Friedl, 991Niels Provos, Theo de Raadt, and Dug Song. 992.Sh SEE ALSO 993.Xr rlogin 1 , 994.Xr rsh 1 , 995.Xr scp 1 , 996.Xr ssh-add 1 , 997.Xr ssh-agent 1 , 998.Xr ssh-keygen 1 , 999.Xr telnet 1 , 1000.Xr sshd 8 , 1001.Xr ssl 8 1002