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