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