From bf740959e9ae4e1954ac43f41edbf1a25a4a8c5d Mon Sep 17 00:00:00 2001 From: damien Date: Thu, 28 Oct 1999 23:15:49 +0000 Subject: [PATCH] Re-imported OpenBSD manpages --- scp.1 | 110 ++++++ ssh-add.1 | 116 +++++++ ssh-agent.1 | 163 +++++++++ ssh-keygen.1 | 155 +++++++++ ssh.1 | 966 +++++++++++++++++++++++++++++++++++++++++++++++++++ sshd.8 | 781 +++++++++++++++++++++++++++++++++++++++++ 6 files changed, 2291 insertions(+) create mode 100644 scp.1 create mode 100644 ssh-add.1 create mode 100644 ssh-agent.1 create mode 100644 ssh-keygen.1 create mode 100644 ssh.1 create mode 100644 sshd.8 diff --git a/scp.1 b/scp.1 new file mode 100644 index 00000000..d8207664 --- /dev/null +++ b/scp.1 @@ -0,0 +1,110 @@ +.\" -*- nroff -*- +.\" +.\" scp.1 +.\" +.\" Author: Tatu Ylonen +.\" +.\" Copyright (c) 1995 Tatu Ylonen , Espoo, Finland +.\" All rights reserved +.\" +.\" Created: Sun May 7 00:14:37 1995 ylo +.\" +.\" $Id$ +.\" +.Dd September 25, 1999 +.Dt SCP 1 +.Os +.Sh NAME +.Nm scp +.Nd secure copy (remote file copy program) +.Sh SYNOPSIS +.Nm scp +.Op Fl pqrvC +.Op Fl P Ar port +.Op Fl c Ar cipher +.Op Fl i Ar identity_file +.Sm off +.Oo +.Op Ar user@ +.Ar host1 No : +.Oc Ns Ar file1 +.Sm on +.Op Ar ... +.Sm off +.Oo +.Op Ar user@ +.Ar host2 No : +.Oc Ar file2 +.Sm on +.Sh DESCRIPTION +.Nm +copies files between hosts on a network. It uses +.Xr ssh 1 +for data transfer, and uses the same authentication and provides the +same security as +.Xr ssh 1 . +Unlike +.Xr rcp 1 , +.Nm +will ask for passwords or passphrases if they are needed for +authentication. +.Pp +Any file name may contain a host and user specification to indicate +that the file is to be copied to/from that host. Copies between two +remote hosts are permitted. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl c Ar cipher +Selects the cipher to use for encrypting the data transfer. This +option is directly passed to +.Xr ssh 1 . +.It Fl i Ar identity_file +Selects the file from which the identity (private key) for RSA +authentication is read. This option is directly passed to +.Xr ssh 1 . +.It Fl p +Preserves modification times, access times, and modes from the +original file. +.It Fl r +Recursively copy entire directories. +.It Fl v +Verbose mode. Causes +.Nm +and +.Xr ssh 1 +to print debugging messages about their progress. This is helpful in +debugging connection, authentication, and configuration problems. +.It Fl B +Selects batch mode (prevents asking for passwords or passphrases). +.It Fl q +Disables the progress meter. +.It Fl C +Compression enable. Passes the +.Fl C +flag to +.Xr ssh 1 +to enable compression. +.It Fl P Ar port +Specifies the port to connect to on the remote host. Note that this +option is written with a capital +.Sq P , +because +.Fl p +is already reserved for preserving the times and modes of the file in +.Xr rcp 1 . +.Sh AUTHORS +Timo Rinne and Tatu Ylonen +.Sh HISTORY +.Nm +is based on the +.Xr rcp 1 +program in BSD source code from the Regents of the University of +California. +.Sh SEE ALSO +.Xr rcp 1 , +.Xr ssh 1 , +.Xr ssh-add 1 , +.Xr ssh-agent 1 , +.Xr ssh-keygen 1 , +.Xr sshd 8 diff --git a/ssh-add.1 b/ssh-add.1 new file mode 100644 index 00000000..ebc07e33 --- /dev/null +++ b/ssh-add.1 @@ -0,0 +1,116 @@ +.\" -*- nroff -*- +.\" +.\" ssh-add.1 +.\" +.\" Author: Tatu Ylonen +.\" +.\" Copyright (c) 1995 Tatu Ylonen , Espoo, Finland +.\" All rights reserved +.\" +.\" Created: Sat Apr 22 23:55:14 1995 ylo +.\" +.\" $Id$ +.\" +.Dd September 25, 1999 +.Dt SSH-ADD 1 +.Os +.Sh NAME +.Nm ssh-add +.Nd adds identities for the authentication agent +.Sh SYNOPSIS +.Nm ssh-add +.Op Fl ldD +.Op Ar +.Sh DESCRIPTION +.Nm +adds identities to the authentication agent, +.Xr ssh-agent 1 . +When run without arguments, it adds the file +.Pa $HOME/.ssh/identity . +Alternative file names can be given on the +command line. If any file requires a passphrase, +.Nm +asks for the passphrase from the user. +The Passphrase it is read from the user's tty. +.Pp +The authentication agent must be running and must be an ancestor of +the current process for +.Nm +to work. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl l +Lists all identities currently represented by the agent. +.It Fl d +Instead of adding the identity, removes the identity from the agent. +.It Fl D +Deletes all identities from the agent. +.El +.Sh FILES +.Bl -tag -width Ds +.Pa $HOME/.ssh/identity +Contains the RSA authentication identity of the user. This file +should not be readable by anyone but the user. +Note that +.Nm +ignores this file if it is accessible by others. +It is possible to +specify a passphrase when generating the key; that passphrase will be +used to encrypt the private part of this file. This is the +default file added by +.Nm +when no other files have been specified. +.Pp +If +.Nm +needs a passphrase, it will read the passphrase from the current +terminal if it was run from a terminal. If +.Nm +does not have a terminal associated with it but +.Ev DISPLAY +is set, it +will open an X11 window to read the passphrase. This is particularly +useful when calling +.Nm +from a +.Pa .Xsession +or related script. (Note that on some machines it +may be necessary to redirect the input from +.Pa /dev/null +to make this work.) +.Sh AUTHOR +Tatu Ylonen +.Pp +OpenSSH +is a derivative of the original (free) ssh 1.2.12 release, but with bugs +removed and newer features re-added. Rapidly after the 1.2.12 release, +newer versions bore successively more restrictive licenses. This version +of OpenSSH +.Bl -bullet +.It +has all components of a restrictive nature (ie. patents, see +.Xr ssl 8 ) +directly removed from the source code; any licensed or patented components +are chosen from +external libraries. +.It +has been updated to support ssh protocol 1.5. +.It +contains added support for +.Xr kerberos 8 +authentication and ticket passing. +.It +supports one-time password authentication with +.Xr skey 1 . +.El +.Pp +The libraries described in +.Xr ssl 8 +are required for proper operation. +.Sh SEE ALSO +.Xr ssh 1 , +.Xr ssh-agent 1 , +.Xr ssh-keygen 1 , +.Xr sshd 8 , +.Xr ssl 8 diff --git a/ssh-agent.1 b/ssh-agent.1 new file mode 100644 index 00000000..8b9504fa --- /dev/null +++ b/ssh-agent.1 @@ -0,0 +1,163 @@ +.\" $OpenBSD: ssh-agent.1,v 1.7 1999/10/28 08:43:10 markus Exp $ +.\" +.\" -*- nroff -*- +.\" +.\" ssh-agent.1 +.\" +.\" Author: Tatu Ylonen +pp.\" +.\" Copyright (c) 1995 Tatu Ylonen , Espoo, Finland +.\" All rights reserved +.\" +.\" Created: Sat Apr 23 20:10:43 1995 ylo +.\" +.Dd September 25, 1999 +.Dt SSH-AGENT 1 +.Os +.Sh NAME +.Nm ssh-agent +.Nd authentication agent +.Sh SYNOPSIS +.Nm ssh-agent +.Op Fl c Li | Fl s +.Op Fl k +.Oo +.Ar command +.Op Ar args ... +.Oc +.Sh DESCRIPTION +.Nm +is a program to hold authentication private keys. The +idea is that +.Nm +is started in the beginning of an X-session or a login session, and +all other windows or programs are started as clients to the ssh-agent +program. Through use of environment variables the agent can be located +and automatically used for RSA authentication when logging in to other +machines using +.Xr ssh 1 . +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl c +Generate C-shell commands on +.Dv stdout . +This is the default if +.Ev SHELL +looks like it's a csh style of shell. +.It Fl s +Generate Bourne shell commands on +.Dv stdout . +This is the default if +.Ev SHELL +does not look like it's a csh style of shell. +.It Fl k +Kill the current agent (given by the +.Ev SSH_AGENT_PID +environment variable). +.El +.Pp +If a commandline is given, this is executed as a subprocess of the agent. +When the command dies, so does the agent. +.Pp +The agent initially does not have any private keys. Keys are added +using +.Xr ssh-add 1 . +When executed without arguments, +.Xr ssh-add 1 +adds the +.Pa $HOME/.ssh/identity +file. If the identity has a passphrase, +.Xr ssh-add 1 +asks for the passphrase (using a small X11 application if running +under X11, or from the terminal if running without X). It then sends +the identity to the agent. Several identities can be stored in the +agent; the agent can automatically use any of these identities. +.Ic ssh-add -l +displays the identities currently held by the agent. +.Pp +The idea is that the agent is run in the user's local PC, laptop, or +terminal. Authentication data need not be stored on any other +machine, and authentication passphrases never go over the network. +However, the connection to the agent is forwarded over SSH +remote logins, and the user can thus use the privileges given by the +identities anywhere in the network in a secure way. +.Pp +There are two main ways to get an agent setup: Either you let the agent +start a new subcommand into which some environment variables are exported, or +you let the agent print the needed shell commands (either +.Xr sh 1 +or +.Xr csh 1 +syntax can be generated) which can be evalled in the calling shell. +Later +.Xr ssh 1 +look at these variables and use them to establish a connection to the agent. +.Pp +A unix-domain socket is created +.Pq Pa /tmp/ssh-XXXXXXXX/agent. , +and the name of this socket is stored in the +.Ev SSH_AUTH_SOCK +environment +variable. The socket is made accessible only to the current user. +This method is easily abused by root or another instance of the same +user. +.Pp +The +.Ev SSH_AGENT_PID +environment variable holds the agent's PID. +.Pp +The agent exits automatically when the command given on the command +line terminates. +.Sh FILES +.Bl -tag -width Ds +.It Pa $HOME/.ssh/identity +Contains the RSA authentication identity of the user. This file +should not be readable by anyone but the user. It is possible to +specify a passphrase when generating the key; that passphrase will be +used to encrypt the private part of this file. This file +is not used by +.Nm +but is normally added to the agent using +.Xr ssh-add 1 +at login time. +.It Pa /tmp/ssh-XXXX/agent. , +Unix-domain sockets used to contain the connection to the +authentication agent. These sockets should only be readable by the +owner. The sockets should get automatically removed when the agent +exits. +.Sh AUTHOR +Tatu Ylonen +.Pp +OpenSSH +is a derivative of the original (free) ssh 1.2.12 release, but with bugs +removed and newer features re-added. Rapidly after the 1.2.12 release, +newer versions bore successively more restrictive licenses. This version +of OpenSSH +.Bl -bullet +.It +has all components of a restrictive nature (ie. patents, see +.Xr ssl 8 ) +directly removed from the source code; any licensed or patented components +are chosen from +external libraries. +.It +has been updated to support ssh protocol 1.5. +.It +contains added support for +.Xr kerberos 8 +authentication and ticket passing. +.It +supports one-time password authentication with +.Xr skey 1 . +.El +.Pp +The libraries described in +.Xr ssl 8 +are required for proper operation. +.Sh SEE ALSO +.Xr ssh 1 , +.Xr ssh-add 1 , +.Xr ssh-keygen 1 , +.Xr sshd 8 , +.Xr ssl 8 diff --git a/ssh-keygen.1 b/ssh-keygen.1 new file mode 100644 index 00000000..7daab9b2 --- /dev/null +++ b/ssh-keygen.1 @@ -0,0 +1,155 @@ +.\" -*- nroff -*- +.\" +.\" ssh-keygen.1 +.\" +.\" Author: Tatu Ylonen +.\" +.\" Copyright (c) 1995 Tatu Ylonen , Espoo, Finland +.\" All rights reserved +.\" +.\" Created: Sat Apr 22 23:55:14 1995 ylo +.\" +.\" $Id$ +.\" +.Dd September 25, 1999 +.Dt SSH-KEYGEN 1 +.Os +.Sh NAME +.Nm ssh-keygen +.Nd authentication key generation +.Sh SYNOPSIS +.Nm ssh-keygen +.Op Fl q +.Op Fl b Ar bits +.Op Fl N Ar new_passphrase +.Op Fl C Ar comment +.Nm ssh-keygen +.Fl p +.Op Fl P Ar old_passphrase +.Op Fl N Ar new_passphrase +.Nm ssh-keygen +.Fl c +.Op Fl P Ar passphrase +.Op Fl C Ar comment +.Sh DESCRIPTION +.Nm +generates and manages authentication keys for +.Xr ssh 1 . +Normally each user wishing to use SSH +with RSA authentication runs this once to create the authentication +key in +.Pa $HOME/.ssh/identity . +Additionally, the system administrator may use this to generate host keys. +.Pp +Normally this program generates the key and asks for a file in which +to store the private key. The public key is stored in a file with the +same name but +.Dq .pub +appended. The program also asks for a +passphrase. The passphrase may be empty to indicate no passphrase +(host keys must have empty passphrase), or it may be a string of +arbitrary length. Good passphrases are 10-30 characters long and are +not simple sentences or otherwise easily guessable (English +prose has only 1-2 bits of entropy per word, and provides very bad +passphrases). The passphrase can be changed later by using the +.Fl p +option. +.Pp +There is no way to recover a lost passphrase. If the passphrase is +lost or forgotten, you will have to generate a new key and copy the +corresponding public key to other machines. +.Pp +There is also a comment field in the key file that is only for +convenience to the user to help identify the key. The comment can +tell what the key is for, or whatever is useful. The comment is +initialized to +.Dq user@host +when the key is created, but can be changed using the +.Fl c +option. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl b Ar bits +Specifies the number of bits in the key to create. Minimum is 512 +bits. Generally 1024 bits is considered sufficient, and key sizes +above that no longer improve security but make things slower. The +default is 1024 bits. +.It Fl c +Requests changing the comment in the private and public key files. +The program will prompt for the file containing the private keys, for +passphrase if the key has one, and for the new comment. +.It Fl p +Requests changing the passphrase of a private key file instead of +creating a new private key. The program will prompt for the file +containing the private key, for the old passphrase, and twice for the +new passphrase. +.It Fl q +Silence +.Nm ssh-keygen . +Used by +.Pa /etc/rc +when creating a new key. +.It Fl C Ar comment +Provides the new comment. +.It Fl N Ar new_passphrase +Provides the new passphrase. +.It Fl P Ar passphrase +Provides the (old) passphrase. +.El +.Sh FILES +.Bl -tag -width Ds +.It Pa $HOME/.ssh/random_seed +Used for seeding the random number generator. This file should not be +readable by anyone but the user. This file is created the first time +the program is run, and is updated every time. +.It Pa $HOME/.ssh/identity +Contains the RSA authentication identity of the user. This file +should not be readable by anyone but the user. It is possible to +specify a passphrase when generating the key; that passphrase will be +used to encrypt the private part of this file using 3DES. This file +is not automatically accessed by +.Nm +but it is offered as the default file for the private key. +.It Pa $HOME/.ssh/identity.pub +Contains the public key for authentication. The contents of this file +should be added to +.Pa $HOME/.ssh/authorized_keys +on all machines +where you wish to log in using RSA authentication. There is no +need to keep the contents of this file secret. +.Sh AUTHOR +Tatu Ylonen +.Pp +OpenSSH +is a derivative of the original (free) ssh 1.2.12 release, but with bugs +removed and newer features re-added. Rapidly after the 1.2.12 release, +newer versions bore successively more restrictive licenses. This version +of OpenSSH +.Bl -bullet +.It +has all components of a restrictive nature (ie. patents, see +.Xr ssl 8 ) +directly removed from the source code; any licensed or patented components +are chosen from +external libraries. +.It +has been updated to support ssh protocol 1.5. +.It +contains added support for +.Xr kerberos 8 +authentication and ticket passing. +.It +supports one-time password authentication with +.Xr skey 1 . +.El +.Pp +The libraries described in +.Xr ssl 8 +are required for proper operation. +.Sh SEE ALSO +.Xr ssh 1 , +.Xr ssh-add 1 , +.Xr ssh-agent 1, +.Xr sshd 8 , +.Xr ssl 8 diff --git a/ssh.1 b/ssh.1 new file mode 100644 index 00000000..865d07c8 --- /dev/null +++ b/ssh.1 @@ -0,0 +1,966 @@ +.\" -*- nroff -*- +.\" +.\" ssh.1.in +.\" +.\" Author: Tatu Ylonen +.\" +.\" Copyright (c) 1995 Tatu Ylonen , Espoo, Finland +.\" All rights reserved +.\" +.\" Created: Sat Apr 22 21:55:14 1995 ylo +.\" +.\" $Id$ +.\" +.Dd September 25, 1999 +.Dt SSH 1 +.Os +.Sh NAME +.Nm ssh +.Nd OpenSSH secure shell client (remote login program) +.Sh SYNOPSIS +.Nm ssh +.Op Fl l Ar login_name +.Op Ar hostname | user@hostname +.Op Ar command +.Pp +.Nm ssh +.Op Fl afgknqtvxCPX +.Op Fl c Ar blowfish | 3des +.Op Fl e Ar escape_char +.Op Fl i Ar identity_file +.Op Fl l Ar login_name +.Op Fl o Ar option +.Op Fl p Ar port +.Oo Fl L Xo +.Sm off +.Ar host : +.Ar port : +.Ar hostport +.Sm on +.Xc +.Oc +.Oo Fl R Xo +.Sm off +.Ar host : +.Ar port : +.Ar hostport +.Sm on +.Xc +.Oc +.Op Ar hostname | user@hostname +.Op Ar command +.Sh DESCRIPTION +.Nm +(Secure Shell) is a program for logging into a remote machine and for +executing commands on a remote machine. It is intended to replace +rlogin and rsh, and provide secure encrypted communications between +two untrusted hosts over an insecure network. X11 connections and +arbitrary TCP/IP ports can also be forwarded over the secure channel. +.Pp +.Nm +connects and logs into the specified +.Ar hostname . +The user must prove +his/her identity to the remote machine using one of several methods. +.Pp +First, if the machine the user logs in from is listed in +.Pa /etc/hosts.equiv +or +.Pa /etc/shosts.equiv +on the remote machine, and the user names are +the same on both sides, the user is immediately permitted to log in. +Second, if +.Pa \&.rhosts +or +.Pa \&.shosts +exists in the user's home directory on the +remote machine and contains a line containing the name of the client +machine and the name of the user on that machine, the user is +permitted to log in. This form of authentication alone is normally not +allowed by the server because it is not secure. +.Pp +The second (and primary) authentication method is the +.Pa rhosts +or +.Pa hosts.equiv +method combined with RSA-based host authentication. It +means that if the login would be permitted by +.Pa \&.rhosts , +.Pa \&.shosts , +.Pa /etc/hosts.equiv , +or +.Pa /etc/shosts.equiv , +and if additionally the server can verify the client's +host key (see +.Pa /etc/ssh_known_hosts +in the +.Sx FILES +section), only then login is +permitted. This authentication method closes security holes due to IP +spoofing, DNS spoofing and routing spoofing. [Note to the +administrator: +.Pa /etc/hosts.equiv , +.Pa \&.rhosts , +and the rlogin/rsh protocol in general, are inherently insecure and should be +disabled if security is desired.] +.Pp +As a third authentication method, +.Nm +supports RSA based authentication. +The scheme is based on public-key cryptography: there are cryptosystems +where encryption and decryption are done using separate keys, and it +is not possible to derive the decryption key from the encryption key. +RSA is one such system. The idea is that each user creates a public/private +key pair for authentication purposes. The +server knows the public key, and only the user knows the private key. +The file +.Pa $HOME/.ssh/authorized_keys +lists the public keys that are permitted for logging +in. When the user logs in, the +.Nm +program tells the server which key pair it would like to use for +authentication. The server checks if this key is permitted, and if +so, sends the user (actually the +.Nm +program running on behalf of the user) a challenge, a random number, +encrypted by the user's public key. The challenge can only be +decrypted using the proper private key. The user's client then decrypts the +challenge using the private key, proving that he/she knows the private +key but without disclosing it to the server. +.Pp +.Nm +implements the RSA authentication protocol automatically. The user +creates his/her RSA key pair by running +.Xr ssh-keygen 1 . +This stores the private key in +.Pa \&.ssh/identity +and the public key in +.Pa \&.ssh/identity.pub +in the user's home directory. The user should then +copy the +.Pa identity.pub +to +.Pa \&.ssh/authorized_keys +in his/her home directory on the remote machine (the +.Pa authorized_keys +file corresponds to the conventional +.Pa \&.rhosts +file, and has one key +per line, though the lines can be very long). After this, the user +can log in without giving the password. RSA authentication is much +more secure than rhosts authentication. +.Pp +The most convenient way to use RSA authentication may be with an +authentication agent. See +.Xr ssh-agent 1 +for more information. +.Pp +If other authentication methods fail, +.Nm +prompts the user for a password. The password is sent to the remote +host for checking; however, since all communications are encrypted, +the password cannot be seen by someone listening on the network. +.Pp +When the user's identity has been accepted by the server, the server +either executes the given command, or logs into the machine and gives +the user a normal shell on the remote machine. All communication with +the remote command or shell will be automatically encrypted. +.Pp +If a pseudo-terminal has been allocated (normal login session), the +user can disconnect with +.Ic ~. , +and suspend +.Nm +with +.Ic ~^Z . +All forwarded connections can be listed with +.Ic ~# +and if +the session blocks waiting for forwarded X11 or TCP/IP +connections to terminate, it can be backgrounded with +.Ic ~& +(this should not be used while the user shell is active, as it can cause the +shell to hang). All available escapes can be listed with +.Ic ~? . +.Pp +A single tilde character can be sent as +.Ic ~~ +(or by following the tilde by a character other than those described above). +The escape character must always follow a newline to be interpreted as +special. The escape character can be changed in configuration files +or on the command line. +.Pp +If no pseudo tty has been allocated, the +session is transparent and can be used to reliably transfer binary +data. On most systems, setting the escape character to +.Dq none +will also make the session transparent even if a tty is used. +.Pp +The session terminates when the command or shell in on the remote +machine exists and all X11 and TCP/IP connections have been closed. +The exit status of the remote program is returned as the exit status +of +.Nm ssh . +.Pp +If the user is using X11 (the +.Ev DISPLAY +environment variable is set), the connection to the X11 display is +automatically forwarded to the remote side in such a way that any X11 +programs started from the shell (or command) will go through the +encrypted channel, and the connection to the real X server will be made +from the local machine. The user should not manually set +.Ev DISPLAY . +Forwarding of X11 connections can be +configured on the command line or in configuration files. +.Pp +The +.Ev DISPLAY +value set by +.Nm +will point to the server machine, but with a display number greater +than zero. This is normal, and happens because +.Nm +creates a +.Dq proxy +X server on the server machine for forwarding the +connections over the encrypted channel. +.Pp +.Nm +will also automatically set up Xauthority data on the server machine. +For this purpose, it will generate a random authorization cookie, +store it in Xauthority on the server, and verify that any forwarded +connections carry this cookie and replace it by the real cookie when +the connection is opened. The real authentication cookie is never +sent to the server machine (and no cookies are sent in the plain). +.Pp +If the user is using an authentication agent, the connection to the agent +is automatically forwarded to the remote side unless disabled on +command line or in a configuration file. +.Pp +Forwarding of arbitrary TCP/IP connections over the secure channel can +be specified either on command line or in a configuration file. One +possible application of TCP/IP forwarding is a secure connection to an +electronic purse; another is going trough firewalls. +.Pp +.Nm +automatically maintains and checks a database containing RSA-based +identifications for all hosts it has ever been used with. The +database is stored in +.Pa \&.ssh/known_hosts +in the user's home directory. Additionally, the file +.Pa /etc/ssh_known_hosts +is automatically checked for known hosts. Any new hosts are +automatically added to the user's file. If a host's identification +ever changes, +.Nm +warns about this and disables password authentication to prevent a +trojan horse from getting the user's password. Another purpose of +this mechanism is to prevent man-in-the-middle attacks which could +otherwise be used to circumvent the encryption. The +.Cm StrictHostKeyChecking +option (see below) can be used to prevent logins to machines whose +host key is not known or has changed. +.Sh OPTIONS +.Bl -tag -width Ds +.It Fl a +Disables forwarding of the authentication agent connection. This may +also be specified on a per-host basis in the configuration file. +.It Fl c Ar blowfish|3des +Selects the cipher to use for encrypting the session. +.Ar 3des +is used by default. It is believed to be secure. +.Ar 3des +(triple-des) is an encrypt-decrypt-encrypt triple with three different keys. +It is presumably more secure than the +.Ar des +cipher which is no longer supported in ssh. +.Ar blowfish +is a fast block cipher, it appears very secure and is much faster than +.Ar 3des . +.It Fl e Ar ch|^ch|none +Sets the escape character for sessions with a pty (default: +.Ql ~ ) . +The escape character is only recognized at the beginning of a line. The +escape character followed by a dot +.Pq Ql \&. +closes the connection, followed +by control-Z suspends the connection, and followed by itself sends the +escape character once. Setting the character to +.Dq none +disables any escapes and makes the session fully transparent. +.It Fl f +Requests +.Nm +to go to background after authentication. This is useful +if +.Nm +is going to ask for passwords or passphrases, but the user +wants it in the background. This implies +.Fl n . +The recommended way to start X11 programs at a remote site is with +something like +.Ic ssh -f host xterm . +.It Fl i Ar identity_file +Selects the file from which the identity (private key) for +RSA authentication is read. Default is +.Pa \&.ssh/identity +in the user's home directory. Identity files may also be specified on +a per-host basis in the configuration file. It is possible to have +multiple +.Fl i +options (and multiple identities specified in +configuration files). +.It Fl g +Allows remote hosts to connect to local forwarded ports. +.It Fl k +Disables forwarding of Kerberos tickets and AFS tokens. This may +also be specified on a per-host basis in the configuration file. +.It Fl l Ar login_name +Specifies the user to log in as on the remote machine. This may also +be specified on a per-host basis in the configuration file. +.It Fl n +Redirects stdin from +.Pa /dev/null +(actually, prevents reading from stdin). +This must be used when +.Nm +is run in the background. A common trick is to use this to run X11 +programs in a remote machine. For example, +.Ic ssh -n shadows.cs.hut.fi emacs & +will start an emacs on shadows.cs.hut.fi, and the X11 +connection will be automatically forwarded over an encrypted channel. +The +.Nm +program will be put in the background. +(This does not work if +.Nm +needs to ask for a password or passphrase; see also the +.Fl f +option.) +.It Fl o Ar option +Can be used to give options in the format used in the config file. +This is useful for specifying options for which there is no separate +command-line flag. The option has the same format as a line in the +configuration file. +.It Fl p Ar port +Port to connect to on the remote host. This can be specified on a +per-host basis in the configuration file. +.It Fl P +Use a non-privileged port for outgoing connections. +This can be used if your firewall does +not permit connections from privileged ports. +Note that this option turns of +.Cm RhostsAuthentication +and +.Cm RhostsRSAAuthentication . +.It Fl q +Quiet mode. Causes all warning and diagnostic messages to be +suppressed. Only fatal errors are displayed. +.It Fl t +Force pseudo-tty allocation. This can be used to execute arbitary +screen-based programs on a remote machine, which can be very useful +e.g. when implementing menu services. +.It Fl v +Verbose mode. Causes +.Nm +to print debugging messages about its progress. This is helpful in +debugging connection, authentication, and configuration problems. +The verbose mode is also used to display +.Xr skey 1 +challenges, if the user entered "s/key" as password. +.It Fl x +Disables X11 forwarding. This can also be specified on a per-host +basis in a configuration file. +.It Fl X +Enables X11 forwarding. +.It Fl C +Requests compression of all data (including stdin, stdout, stderr, and +data for forwarded X11 and TCP/IP connections). The compression +algorithm is the same used by gzip, and the +.Dq level +can be controlled by the +.Cm CompressionLevel +option (see below). Compression is desirable on modem lines and other +slow connections, but will only slow down things on fast networks. +The default value can be set on a host-by-host basis in the +configuration files; see the +.Cm Compress +option below. +.It Fl L Ar port:host:hostport +Specifies that the given port on the local (client) host is to be +forwarded to the given host and port on the remote side. This works +by allocating a socket to listen to +.Ar port +on the local side, and whenever a connection is made to this port, the +connection is forwarded over the secure channel, and a connection is +made to +.Ar host:hostport +from the remote machine. Port forwardings can also be specified in the +configuration file. Only root can forward privileged ports. +.It Fl R Ar port:host:hostport +Specifies that the given port on the remote (server) host is to be +forwarded to the given host and port on the local side. This works +by allocating a socket to listen to +.Ar port +on the remote side, and whenever a connection is made to this port, the +connection is forwarded over the secure channel, and a connection is +made to +.Ar host:hostport +from the local machine. Port forwardings can also be specified in the +configuration file. Privileged ports can be forwarded only when +logging in as root on the remote machine. +.El +.Sh CONFIGURATION FILES +.Nm +obtains configuration data from the following sources (in this order): +command line options, user's configuration file +.Pq Pa $HOME/.ssh/config , +and system-wide configuration file +.Pq Pa /etc/ssh_config . +For each parameter, the first obtained value +will be used. The configuration files contain sections bracketed by +"Host" specifications, and that section is only applied for hosts that +match one of the patterns given in the specification. The matched +host name is the one given on the command line. +.Pp +Since the first obtained value for each parameter is used, more +host-specific declarations should be given near the beginning of the +file, and general defaults at the end. +.Pp +The configuration file has the following format: +.Pp +Empty lines and lines starting with +.Ql # +are comments. +.Pp +Otherwise a line is of the format +.Dq keyword arguments . +The possible +keywords and their meanings are as follows (note that the +configuration files are case-sensitive): +.Bl -tag -width Ds +.It Cm Host +Restricts the following declarations (up to the next +.Cm Host +keyword) to be only for those hosts that match one of the patterns +given after the keyword. +.Ql \&* +and +.Ql ? +can be used as wildcards in the +patterns. A single +.Ql \&* +as a pattern can be used to provide global +defaults for all hosts. The host is the +.Ar hostname +argument given on the command line (i.e., the name is not converted to +a canonicalized host name before matching). +.It Cm AFSTokenPassing +Specifies whether to pass AFS tokens to remote host. The argument to +this keyword must be +.Dq yes +or +.Dq no . +.It Cm BatchMode +If set to +.Dq yes , +passphrase/password querying will be disabled. This +option is useful in scripts and other batch jobs where you have no +user to supply the password. The argument must be +.Dq yes +or +.Dq no . +.It Cm Cipher +Specifies the cipher to use for encrypting the session. Currently, +.Dq blowfish , +and +.Dq 3des +are supported. The default is +.Dq 3des . +.It Cm Compression +Specifies whether to use compression. The argument must be +.Dq yes +or +.Dq no . +.It Cm CompressionLevel +Specifies the compression level to use if compression is enable. The +argument must be an integer from 1 (fast) to 9 (slow, best). The +default level is 6, which is good for most applications. The meaning +of the values is the same as in GNU GZIP. +.It Cm ConnectionAttempts +Specifies the number of tries (one per second) to make before falling +back to rsh or exiting. The argument must be an integer. This may be +useful in scripts if the connection sometimes fails. +.It Cm EscapeChar +Sets the escape character (default: +.Ql ~ ) . +The escape character can also +be set on the command line. The argument should be a single +character, +.Ql ^ +followed by a letter, or +.Dq none +to disable the escape +character entirely (making the connection transparent for binary +data). +.It Cm FallBackToRsh +Specifies that if connecting via +.Nm +fails due to a connection refused error (there is no +.Xr sshd 8 +listening on the remote host), +.Xr rsh 1 +should automatically be used instead (after a suitable warning about +the session being unencrypted). The argument must be +.Dq yes +or +.Dq no . +.It Cm ForwardAgent +Specifies whether the connection to the authentication agent (if any) +will be forwarded to the remote machine. The argument must be +.Dq yes +or +.Dq no . +.It Cm ForwardX11 +Specifies whether X11 connections will be automatically redirected +over the secure channel and +.Ev DISPLAY +set. The argument must be +.Dq yes +or +.Dq no . +.It Cm GatewayPorts +Specifies whether remote hosts are allowed to connect to local +forwarded ports. +The argument must be +.Dq yes +or +.Dq no . +The default is +.Dq no . +.It Cm GlobalKnownHostsFile +Specifies a file to use instead of +.Pa /etc/ssh_known_hosts . +.It Cm HostName +Specifies the real host name to log into. This can be used to specify +nicnames or abbreviations for hosts. Default is the name given on the +command line. Numeric IP addresses are also permitted (both on the +command line and in +.Cm HostName +specifications). +.It Cm IdentityFile +Specifies the file from which the user's RSA authentication identity +is read (default +.Pa .ssh/identity +in the user's home directory). +Additionally, any identities represented by the authentication agent +will be used for authentication. The file name may use the tilde +syntax to refer to a user's home directory. It is possible to have +multiple identity files specified in configuration files; all these +identities will be tried in sequence. +.It Cm KeepAlive +Specifies whether the system should send keepalive messages to the +other side. If they are sent, death of the connection or crash of one +of the machines will be properly noticed. However, this means that +connections will die if the route is down temporarily, and some people +find it annoying. +.Pp +The default is +.Dq yes +(to send keepalives), and the client will notice +if the network goes down or the remote host dies. This is important +in scripts, and many users want it too. +.Pp +To disable keepalives, the value should be set to +.Dq no +in both the server and the client configuration files. +.It Cm KerberosAuthentication +Specifies whether Kerberos authentication will be used. The argument to +this keyword must be +.Dq yes +or +.Dq no . +.It Cm KerberosTgtPassing +Specifies whether a Kerberos TGT will be forwarded to the server. This +will only work if the Kerberos server is actually an AFS kaserver. The +argument to this keyword must be +.Dq yes +or +.Dq no . +.It Cm LocalForward +Specifies that a TCP/IP port on the local machine be forwarded over +the secure channel to given host:port from the remote machine. The +first argument must be a port number, and the second must be +host:port. Multiple forwardings may be specified, and additional +forwardings can be given on the command line. Only the root can +forward privileged ports. +.It Cm PasswordAuthentication +Specifies whether to use password authentication. The argument to +this keyword must be +.Dq yes +or +.Dq no . +.It Cm NumberOfPasswordPrompts +Specifies the number of password prompts before giving up. The +argument to this keyword must be an integer. Default is 3. +.It Cm Port +Specifies the port number to connect on the remote host. Default is +22. +.It Cm ProxyCommand +Specifies the command to use to connect to the server. The command +string extends to the end of the line, and is executed with /bin/sh. +In the command string, %h will be substituted by the host name to +connect and %p by the port. The command can be basically anything, +and should read from its stdin and write to its stdout. It should +eventually connect an +.Xr sshd 8 +server running on some machine, or execute +.Ic sshd -i +somewhere. Host key management will be done using the +HostName of the host being connected (defaulting to the name typed by +the user). +.Pp +.It Cm RemoteForward +Specifies that a TCP/IP port on the remote machine be forwarded over +the secure channel to given host:port from the local machine. The +first argument must be a port number, and the second must be +host:port. Multiple forwardings may be specified, and additional +forwardings can be given on the command line. Only the root can +forward privileged ports. +.It Cm RhostsAuthentication +Specifies whether to try rhosts based authentication. Note that this +declaration only affects the client side and has no effect whatsoever +on security. Disabling rhosts authentication may reduce +authentication time on slow connections when rhosts authentication is +not used. Most servers do not permit RhostsAuthentication because it +is not secure (see RhostsRSAAuthentication). The argument to this +keyword must be +.Dq yes +or +.Dq no . +.It Cm RhostsRSAAuthentication +Specifies whether to try rhosts based authentication with RSA host +authentication. This is the primary authentication method for most +sites. The argument must be +.Dq yes +or +.Dq no . +.It Cm RSAAuthentication +Specifies whether to try RSA authentication. The argument to this +keyword must be +.Dq yes +or +.Dq no . +RSA authentication will only be +attempted if the identity file exists, or an authentication agent is +running. +.It Cm CheckHostIP +If this flag is set to +.Dq yes , +ssh will additionally check the host ip address in the +.Pa known_hosts +file. This allows ssh to detect if a host key changed due to DNS spoofing. +If the option is set to +.Dq no , +the check will not be executed. +.It Cm StrictHostKeyChecking +If this flag is set to +.Dq yes , +.Nm +ssh will never automatically add host keys to the +.Pa $HOME/.ssh/known_hosts +file, and refuses to connect hosts whose host key has changed. This +provides maximum protection against trojan horse attacks. However, it +can be somewhat annoying if you don't have good +.Pa /etc/ssh_known_hosts +files installed and frequently +connect new hosts. Basically this option forces the user to manually +add any new hosts. Normally this option is disabled, and new hosts +will automatically be added to the known host files. The host keys of +known hosts will be verified automatically in either case. The +argument must be +.Dq yes +or +.Dq no . +.It Cm User +Specifies the user to log in as. This can be useful if you have a +different user name in different machines. This saves the trouble of +having to remember to give the user name on the command line. +.It Cm UserKnownHostsFile +Specifies a file to use instead of +.Pa $HOME/.ssh/known_hosts . +.It Cm UsePrivilegedPort +Specifies whether to use a privileged port for outgoing connections. +The argument must be +.Dq yes +or +.Dq no . +The default is +.Dq yes . +Note that setting this option to +.Dq no +turns of +.Cm RhostsAuthentication +and +.Cm RhostsRSAAuthentication . +.It Cm UseRsh +Specifies that rlogin/rsh should be used for this host. It is +possible that the host does not at all support the +.Nm +protocol. This causes +.Nm +to immediately exec +.Xr rsh 1 . +All other options (except +.Cm HostName ) +are ignored if this has been specified. The argument must be +.Dq yes +or +.Dq no . +.Sh ENVIRONMENT +.Nm +will normally set the following environment variables: +.Bl -tag -width Ds +.It Ev DISPLAY +The +.Ev DISPLAY +variable indicates the location of the X11 server. It is +automatically set by +.Nm +to point to a value of the form +.Dq hostname:n +where hostname indicates +the host where the shell runs, and n is an integer >= 1. Ssh uses +this special value to forward X11 connections over the secure +channel. The user should normally not set DISPLAY explicitly, as that +will render the X11 connection insecure (and will require the user to +manually copy any required authorization cookies). +.It Ev HOME +Set to the path of the user's home directory. +.It Ev LOGNAME +Synonym for +.Ev USER ; +set for compatibility with systems that use this variable. +.It Ev MAIL +Set to point the user's mailbox. +.It Ev PATH +Set to the default +.Ev PATH , +as specified when compiling +.Nm ssh . +.It Ev SSH_AUTH_SOCK +indicates the path of a unix-domain socket used to communicate with the +agent. +.It Ev SSH_CLIENT +Identifies the client end of the connection. The variable contains +three space-separated values: client ip-address, client port number, +and server port number. +.It Ev SSH_TTY +This is set to the name of the tty (path to the device) associated +with the current shell or command. If the current session has no tty, +this variable is not set. +.It Ev TZ +The timezone variable is set to indicate the present timezone if it +was set when the daemon was started (e.i., the daemon passes the value +on to new connections). +.It Ev USER +Set to the name of the user logging in. +.El +.Pp +Additionally, +.Nm +reads +.Pa $HOME/.ssh/environment , +and adds lines of the format +.Dq VARNAME=value +to the environment. +.Sh FILES +.Bl -tag -width $HOME/.ssh/known_hosts +.It Pa $HOME/.ssh/known_hosts +Records host keys for all hosts the user has logged into (that are not +in +.Pa /etc/ssh_known_hosts ) . +See +.Xr sshd 8 . +.It Pa $HOME/.ssh/random_seed +Used for seeding the random number generator. This file contains +sensitive data and should read/write for the user and not accessible +for others. This file is created the first time the program is run +and updated automatically. The user should never need to read or +modify this file. +.It Pa $HOME/.ssh/identity +Contains the RSA authentication identity of the user. This file +contains sensitive data and should be readable by the user but not +accessible by others (read/write/execute). +Note that +.Nm +ignores this file if it is accessible by others. +It is possible to specify a passphrase when +generating the key; the passphrase will be used to encrypt the +sensitive part of this file using 3DES. +.It Pa $HOME/.ssh/identity.pub +Contains the public key for authentication (public part of the +identity file in human-readable form). The contents of this file +should be added to +.Pa $HOME/.ssh/authorized_keys +on all machines +where you wish to log in using RSA authentication. This file is not +sensitive and can (but need not) be readable by anyone. This file is +never used automatically and is not necessary; it is only provided for +the convenience of the user. +.It Pa $HOME/.ssh/config +This is the per-user configuration file. The format of this file is +described above. This file is used by the +.Nm +client. This file does not usually contain any sensitive information, +but the recommended permissions are read/write for the user, and not +accessible by others. +.It Pa $HOME/.ssh/authorized_keys +Lists the RSA keys that can be used for logging in as this user. The +format of this file is described in the +.Xr sshd 8 +manual page. In the simplest form the format is the same as the .pub +identity files (that is, each line contains the number of bits in +modulus, public exponent, modulus, and comment fields, separated by +spaces). This file is not highly sensitive, but the recommended +permissions are read/write for the user, and not accessible by others. +.It Pa /etc/ssh_known_hosts +Systemwide list of known host keys. This file should be prepared by the +system administrator to contain the public host keys of all machines in the +organization. This file should be world-readable. This file contains +public keys, one per line, in the following format (fields separated +by spaces): system name, number of bits in modulus, public exponent, +modulus, and optional comment field. When different names are used +for the same machine, all such names should be listed, separated by +commas. The format is described on the +.Xr sshd 8 +manual page. +.Pp +The canonical system name (as returned by name servers) is used by +.Xr sshd 8 +to verify the client host when logging in; other names are needed because +.Nm +does not convert the user-supplied name to a canonical name before +checking the key, because someone with access to the name servers +would then be able to fool host authentication. +.It Pa /etc/ssh_config +Systemwide configuration file. This file provides defaults for those +values that are not specified in the user's configuration file, and +for those users who do not have a configuration file. This file must +be world-readable. +.It Pa $HOME/.rhosts +This file is used in +.Pa \&.rhosts +authentication to list the +host/user pairs that are permitted to log in. (Note that this file is +also used by rlogin and rsh, which makes using this file insecure.) +Each line of the file contains a host name (in the canonical form +returned by name servers), and then a user name on that host, +separated by a space. One some machines this file may need to be +world-readable if the user's home directory is on a NFS partition, +because +.Xr sshd 8 +reads it as root. Additionally, this file must be owned by the user, +and must not have write permissions for anyone else. The recommended +permission for most machines is read/write for the user, and not +accessible by others. +.Pp +Note that by default +.Xr sshd 8 +will be installed so that it requires successful RSA host +authentication before permitting \s+2.\s0rhosts authentication. If your +server machine does not have the client's host key in +.Pa /etc/ssh_known_hosts , +you can store it in +.Pa $HOME/.ssh/known_hosts . +The easiest way to do this is to +connect back to the client from the server machine using ssh; this +will automatically add the host key inxi +.Pa $HOME/.ssh/known_hosts . +.It Pa $HOME/.shosts +This file is used exactly the same way as +.Pa \&.rhosts . +The purpose for +having this file is to be able to use rhosts authentication with +.Nm +without permitting login with +.Xr rlogin 1 +or +.Xr rsh 1 . +.It Pa /etc/hosts.equiv +This file is used during +.Pa \&.rhosts authentication. It contains +canonical hosts names, one per line (the full format is described on +the +.Xr sshd 8 +manual page). If the client host is found in this file, login is +automatically permitted provided client and server user names are the +same. Additionally, successful RSA host authentication is normally +required. This file should only be writable by root. +.It Pa /etc/shosts.equiv +This file is processed exactly as +.Pa /etc/hosts.equiv . +This file may be useful to permit logins using +.Nm +but not using rsh/rlogin. +.It Pa /etc/sshrc +Commands in this file are executed by +.Nm +when the user logs in just before the user's shell (or command) is started. +See the +.Xr sshd 8 +manual page for more information. +.It Pa $HOME/.ssh/rc +Commands in this file are executed by +.Nm +when the user logs in just before the user's shell (or command) is +started. +See the +.Xr sshd 8 +manual page for more information. +.It Pa libcrypto.so.X.1 +A version of this library which includes support for the RSA algorithm +is required for proper operation. +.Sh AUTHOR +Tatu Ylonen +.Pp +Issues can be found from the SSH WWW home page: +.Pp +.Dl http://www.cs.hut.fi/ssh +.Pp +OpenSSH +is a derivative of the original (free) ssh 1.2.12 release, but with bugs +removed and newer features re-added. Rapidly after the 1.2.12 release, +newer versions bore successively more restrictive licenses. This version +of OpenSSH +.Bl -bullet +.It +has all components of a restrictive nature (ie. patents, see +.Xr ssl 8 ) +directly removed from the source code; any licensed or patented components +are chosen from +external libraries. +.It +has been updated to support ssh protocol 1.5. +.It +contains added support for +.Xr kerberos 8 +authentication and ticket passing. +.It +supports one-time password authentication with +.Xr skey 1 . +.El +.Pp +The libraries described in +.Xr ssl 8 +are required for proper operation. +.Sh SEE ALSO +.Xr rlogin 1 , +.Xr rsh 1 , +.Xr scp 1 , +.Xr ssh-add 1 , +.Xr ssh-agent 1 , +.Xr ssh-keygen 1 , +.Xr telnet 1 , +.Xr sshd 8 , +.Xr ssl 8 diff --git a/sshd.8 b/sshd.8 new file mode 100644 index 00000000..d422d3af --- /dev/null +++ b/sshd.8 @@ -0,0 +1,781 @@ +.\" -*- nroff -*- +.\" +.\" sshd.8.in +.\" +.\" Author: Tatu Ylonen +.\" +.\" Copyright (c) 1995 Tatu Ylonen , Espoo, Finland +.\" All rights reserved +.\" +.\" Created: Sat Apr 22 21:55:14 1995 ylo +.\" +.\" $Id$ +.\" +.Dd September 25, 1999 +.Dt SSHD 8 +.Os +.Sh NAME +.Nm sshd +.Nd secure shell daemon +.Sh SYNOPSIS +.Nm sshd +.Op Fl diq +.Op Fl b Ar bits +.Op Fl f Ar config_file +.Op Fl g Ar login_grace_time +.Op Fl h Ar host_key_file +.Op Fl k Ar key_gen_time +.Op Fl p Ar port +.Sh DESCRIPTION +.Nm +(Secure Shell Daemon) is the daemon program for +.Xr ssh 1 . +Together these programs replace rlogin and rsh programs, and +provide secure encrypted communications between two untrusted hosts +over an insecure network. The programs are intended to be as easy to +install and use as possible. +.Pp +.Nm +is the daemon that listens for connections from clients. It is +normally started at boot from +.Pa /etc/rc . +It forks a new +daemon for each incoming connection. The forked daemons handle +key exchange, encryption, authentication, command execution, +and data exchange. +.Pp +.Nm +works as follows. Each host has a host-specific RSA key +(normally 1024 bits) used to identify the host. Additionally, when +the daemon starts, it generates a server RSA key (normally 768 bits). +This key is normally regenerated every hour if it has been used, and +is never stored on disk. +.Pp +Whenever a client connects the daemon, the daemon sends its host +and server public keys to the client. The client compares the +host key against its own database to verify that it has not changed. +The client then generates a 256 bit random number. It encrypts this +random number using both the host key and the server key, and sends +the encrypted number to the server. Both sides then start to use this +random number as a session key which is used to encrypt all further +communications in the session. The rest of the session is encrypted +using a conventional cipher, currently Blowfish and 3DES, with 3DES +being is used by default. The client selects the encryption algorithm +to use from those offered by the server. +.Pp +Next, the server and the client enter an authentication dialog. The +client tries to authenticate itself using +.Pa .rhosts +authentication, +.Pa .rhosts +authentication combined with RSA host +authentication, RSA challenge-response authentication, or password +based authentication. +.Pp +Rhosts authentication is normally disabled +because it is fundamentally insecure, but can be enabled in the server +configuration file if desired. System security is not improved unless +.Xr rshd 8 , +.Xr rlogind 8 , +.Xr rexecd 8 , +and +.Xr rexd 8 +are disabled (thus completely disabling +.Xr rlogin 1 +and +.Xr rsh 1 +into that machine). +.Pp +If the client successfully authenticates itself, a dialog for +preparing the session is entered. At this time the client may request +things like allocating a pseudo-tty, forwarding X11 connections, +forwarding TCP/IP connections, or forwarding the authentication agent +connection over the secure channel. +.Pp +Finally, the client either requests a shell or execution of a command. +The sides then enter session mode. In this mode, either side may send +data at any time, and such data is forwarded to/from the shell or +command on the server side, and the user terminal in the client side. +.Pp +When the user program terminates and all forwarded X11 and other +connections have been closed, the server sends command exit status to +the client, and both sides exit. +.Pp +.Nm +can be configured using command-line options or a configuration +file. Command-line options override values specified in the +configuration file. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl b Ar bits +Specifies the number of bits in the server key (default 768). +.Pp +.It Fl d +Debug mode. The server sends verbose debug output to the system +log, and does not put itself in the background. The server also will +not fork and will only process one connection. This option is only +intended for debugging for the server. +.It Fl f Ar configuration_file +Specifies the name of the configuration file. The default is +.Pa /etc/sshd_config . +.Nm +refuses to start if there is no configuration file. +.It Fl g Ar login_grace_time +Gives the grace time for clients to authenticate themselves (default +300 seconds). If the client fails to authenticate the user within +this many seconds, the server disconnects and exits. A value of zero +indicates no limit. +.It Fl h Ar host_key_file +Specifies the file from which the host key is read (default +.Pa /etc/ssh_host_key ) . +This option must be given if +.Nm +is not run as root (as the normal +host file is normally not readable by anyone but root). +.It Fl i +Specifies that +.Nm +is being run from inetd. +.Nm +is normally not run +from inetd because it needs to generate the server key before it can +respond to the client, and this may take tens of seconds. Clients +would have to wait too long if the key was regenerated every time. +However, with small key sizes (e.g. 512) using +.Nm +from inetd may +be feasible. +.It Fl k Ar key_gen_time +Specifies how often the server key is regenerated (default 3600 +seconds, or one hour). The motivation for regenerating the key fairly +often is that the key is not stored anywhere, and after about an hour, +it becomes impossible to recover the key for decrypting intercepted +communications even if the machine is cracked into or physically +seized. A value of zero indicates that the key will never be regenerated. +.It Fl p Ar port +Specifies the port on which the server listens for connections +(default 22). +.It Fl q +Quiet mode. Nothing is sent to the system log. Normally the beginning, +authentication, and termination of each connection is logged. +.It Fl Q +Do not print an error message if RSA support is missing. +.El +.Sh CONFIGURATION FILE +.Nm +reads configuration data from +.Pa /etc/sshd_config +(or the file specified with +.Fl f +on the command line). The file +contains keyword-value pairs, one per line. Lines starting with +.Ql # +and empty lines are interpreted as comments. +.Pp +The following keywords are possible. +.Bl -tag -width Ds +.It Cm AFSTokenPassing +Specifies whether an AFS token may be forwarded to the server. Default is +.Dq yes . +.It Cm AllowGroups +This keyword can be followed by a number of group names, separated +by spaces. If specified, login is allowed only for users whose primary +group matches one of the patterns. +.Ql \&* +and +.Ql ? +can be used as +wildcards in the patterns. Only group names are valid, a numerical group +id isn't recognized. By default login is allowed regardless of +the primary group. +.Pp +.It Cm AllowUsers +This keyword can be followed by a number of user names, separated +by spaces. If specified, login is allowed only for users names that +match one of the patterns. +.Ql \&* +and +.Ql ? +can be used as +wildcards in the patterns. Only user names are valid, a numerical user +id isn't recognized. By default login is allowed regardless of +the user name. +.Pp +.It Cm CheckMail +Specifies whether +.Nm +should check for new mail for interactive logins. +The default is +.Dq no . +.It Cm DenyGroups +This keyword can be followed by a number of group names, separated +by spaces. Users whose primary group matches one of the patterns +aren't allowed to log in. +.Ql \&* +and +.Ql ? +can be used as +wildcards in the patterns. Only group names are valid, a numerical group +id isn't recognized. By default login is allowed regardless of +the primary group. +.Pp +.It Cm DenyUsers +This keyword can be followed by a number of user names, separated +by spaces. Login is allowed disallowed for user names that match +one of the patterns. +.Ql \&* +and +.Ql ? +can be used as +wildcards in the patterns. Only user names are valid, a numerical user +id isn't recognized. By default login is allowed regardless of +the user name. +.Pp +.It Cm FascistLogging +Specifies whether to use verbose logging. Verbose logging violates +the privacy of users and is not recommended. The argument must be +.Dq yes +or +.Dq no . +The default is +.Dq no . +.It Cm HostKey +Specifies the file containing the private host key (default +.Pa /etc/ssh_host_key ) . +Note that +.Nm +does not start if this file is group/world-accessible. +.It Cm IgnoreRhosts +Specifies that rhosts and shosts files will not be used in +authentication. +.Pa /etc/hosts.equiv +and +.Pa /etc/shosts.equiv +are still used. The default is +.Dq no . +.It Cm KeepAlive +Specifies whether the system should send keepalive messages to the +other side. If they are sent, death of the connection or crash of one +of the machines will be properly noticed. However, this means that +connections will die if the route is down temporarily, and some people +find it annoying. On the other hand, if keepalives are not send, +sessions may hang indefinitely on the server, leaving +.Dq ghost +users and consuming server resources. +.Pp +The default is +.Dq yes +(to send keepalives), and the server will notice +if the network goes down or the client host reboots. This avoids +infinitely hanging sessions. +.Pp +To disable keepalives, the value should be set to +.Dq no +in both the server and the client configuration files. +.It Cm KerberosAuthentication +Specifies whether Kerberos authentication is allowed. This can +be in the form of a Kerberos ticket, or if +.Cm PasswordAuthentication +is yes, the password provided by the user will be validated through +the Kerberos KDC. Default is +.Dq yes . +.It Cm KerberosOrLocalPasswd +If set then if password authentication through Kerberos fails then +the password will be validated via any additional local mechanism +such as +.Pa /etc/passwd +or SecurID. Default is +.Dq yes . +.It Cm KerberosTgtPassing +Specifies whether a Kerberos TGT may be forwarded to the server. +Default is +.Dq no , +as this only works when the Kerberos KDC is actually an AFS kaserver. +.It Cm KerberosTicketCleanup +Specifies whether to automatically destroy the user's ticket cache +file on logout. Default is +.Dq yes . +.It Cm KeyRegenerationInterval +The server key is automatically regenerated after this many seconds +(if it has been used). The purpose of regeneration is to prevent +decrypting captured sessions by later breaking into the machine and +stealing the keys. The key is never stored anywhere. If the value is +0, the key is never regenerated. The default is 3600 +(seconds). +.It Cm ListenAddress +Specifies what local address +.Nm +should listen on. +The default is to listen to all local addresses. +.It Cm LoginGraceTime +The server disconnects after this time if the user has not +successfully logged in. If the value is 0, there is no time limit. +The default is 600 (seconds). +.It Cm PasswordAuthentication +Specifies whether password authentication is allowed. +The default is +.Dq yes . +.It Cm PermitEmptyPasswords +When password authentication is allowed, it specifies whether the +server allows login to accounts with empty password strings. The default +is +.Dq yes . +.It Cm PermitRootLogin +Specifies whether the root can log in using +.Xr ssh 1 . +The argument must be +.Dq yes , +.Dq without-password +or +.Dq no . +The default is +.Dq yes . +If this options is set to +.Dq without-password +only password authentication is disabled for root. +.Pp +Root login with RSA authentication when the +.Ar command +option has been +specified will be allowed regardless of the value of this setting +(which may be useful for taking remote backups even if root login is +normally not allowed). +.It Cm Port +Specifies the port number that +.Nm +listens on. The default is 22. +.It Cm PrintMotd +Specifies whether +.Nm +should print +.Pa /etc/motd +when a user logs in interactively. (On some systems it is also +printed by the shell, +.Pa /etc/profile , +or equivalent.) The default is +.Dq yes . +.It Cm QuietMode +Specifies whether the system runs in quiet mode. In quiet mode, +nothing is logged in the system log, except fatal errors. The default +is +.Dq no . +.It Cm RandomSeed +Obsolete. Random number generation uses other techniques. +.It Cm RhostsAuthentication +Specifies whether authentication using rhosts or /etc/hosts.equiv +files is sufficient. Normally, this method should not be permitted +because it is insecure. +.Cm RhostsRSAAuthentication +should be used +instead, because it performs RSA-based host authentication in addition +to normal rhosts or /etc/hosts.equiv authentication. +The default is +.Dq no . +.It Cm RhostsRSAAuthentication +Specifies whether rhosts or /etc/hosts.equiv authentication together +with successful RSA host authentication is allowed. The default is +.Dq yes . +.It Cm RSAAuthentication +Specifies whether pure RSA authentication is allowed. The default is +.Dq yes . +.It Cm ServerKeyBits +Defines the number of bits in the server key. The minimum value is +512, and the default is 768. +.It Cm SkeyAuthentication +Specifies whether +.Xr skey 1 +authentication is allowed. The default is +.Dq yes . +Note that s/key authentication is enabled only if +.Cm PasswordAuthentication +is allowed, too. +.It Cm StrictModes +Specifies whether +.Nm +should check file modes and ownership of the +user's files and home directory before accepting login. This +is normally desirable because novices sometimes accidentally leave their +directory or files world-writable. The default is +.Dq yes . +.It Cm SyslogFacility +Gives the facility code that is used when logging messages from +.Nm sshd . +The possible values are: DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2, +LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7. The default is AUTH. +.It Cm UseLogin +Specifies whether +.Xr login 1 +is used. The default is +.Dq no . +.It Cm X11Forwarding +Specifies whether X11 forwarding is permitted. The default is +.Dq yes . +Note that disabling X11 forwarding does not improve security in any +way, as users can always install their own forwarders. +.It Cm X11DisplayOffset +Specifies the first display number available for +.Nm sshd Ns 's +X11 forwarding. This prevents +.Nm +from interfering with real X11 servers. +.El +.Sh LOGIN PROCESS +When a user successfully logs in, +.Nm +does the following: +.Bl -enum -offset indent +.It +If the login is on a tty, and no command has been specified, +prints last login time and +.Pa /etc/motd +(unless prevented in the configuration file or by +.Pa $HOME/.hushlogin ; +see the +.Sx FILES +section). +.It +If the login is on a tty, records login time. +.It +Checks +.Pa /etc/nologin ; +if it exists, prints contents and quits +(unless root). +.It +Changes to run with normal user privileges. +.It +Sets up basic environment. +.It +Reads +.Pa $HOME/.ssh/environment +if it exists. +.It +Changes to user's home directory. +.It +If +.Pa $HOME/.ssh/rc +exists, runs it; else if +.Pa /etc/sshrc +exists, runs +it; otherwise runs xauth. The +.Dq rc +files are given the X11 +authentication protocol and cookie in standard input. +.It +Runs user's shell or command. +.El +.Sh AUTHORIZED_KEYS FILE FORMAT +The +.Pa $HOME/.ssh/authorized_keys +file lists the RSA keys that are +permitted for RSA authentication. Each line of the file contains one +key (empty lines and lines starting with a +.Ql # +are ignored as +comments). Each line consists of the following fields, separated by +spaces: options, bits, exponent, modulus, comment. The options field +is optional; its presence is determined by whether the line starts +with a number or not (the option field never starts with a number). +The bits, exponent, modulus and comment fields give the RSA key; the +comment field is not used for anything (but may be convenient for the +user to identify the key). +.Pp +Note that lines in this file are usually several hundred bytes long +(because of the size of the RSA key modulus). You don't want to type +them in; instead, copy the +.Pa identity.pub +file and edit it. +.Pp +The options (if present) consists of comma-separated option +specifications. No spaces are permitted, except within double quotes. +The following option specifications are supported: +.Bl -tag -width Ds +.It Cm from="pattern-list" +Specifies that in addition to RSA authentication, the canonical name +of the remote host must be present in the comma-separated list of +patterns ('*' and '?' serve as wildcards). The list may also contain +patterns negated by prefixing them with '!'; if the canonical host +name matches a negated pattern, the key is not accepted. The purpose +of this option is to optionally increase security: RSA authentication +by itself does not trust the network or name servers or anything (but +the key); however, if somebody somehow steals the key, the key +permits an intruder to log in from anywhere in the world. This +additional option makes using a stolen key more difficult (name +servers and/or routers would have to be compromised in addition to +just the key). +.It Cm command="command" +Specifies that the command is executed whenever this key is used for +authentication. The command supplied by the user (if any) is ignored. +The command is run on a pty if the connection requests a pty; +otherwise it is run without a tty. A quote may be included in the +command by quoting it with a backslash. This option might be useful +to restrict certain RSA keys to perform just a specific operation. An +example might be a key that permits remote backups but nothing +else. Notice that the client may specify TCP/IP and/or X11 +forwardings unless they are explicitly prohibited. +.It Cm environment="NAME=value" +Specifies that the string is to be added to the environment when +logging in using this key. Environment variables set this way +override other default environment values. Multiple options of this +type are permitted. +.It Cm no-port-forwarding +Forbids TCP/IP forwarding when this key is used for authentication. +Any port forward requests by the client will return an error. This +might be used, e.g., in connection with the +.Cm command +option. +.It Cm no-X11-forwarding +Forbids X11 forwarding when this key is used for authentication. +Any X11 forward requests by the client will return an error. +.It Cm no-agent-forwarding +Forbids authentication agent forwarding when this key is used for +authentication. +.It Cm no-pty +Prevents tty allocation (a request to allocate a pty will fail). +.El +.Ss Examples +1024 33 12121.\|.\|.\|312314325 ylo@foo.bar +.Pp +from="*.niksula.hut.fi,!pc.niksula.hut.fi" 1024 35 23.\|.\|.\|2334 ylo@niksula +.Pp +command="dump /home",no-pty,no-port-forwarding 1024 33 23.\|.\|.\|2323 backup.hut.fi +.Sh SSH_KNOWN_HOSTS FILE FORMAT +The +.Pa /etc/ssh_known_hosts +and +.Pa $HOME/.ssh/known_hosts +files contain host public keys for all known hosts. The global file should +be prepared by the admistrator (optional), and the per-user file is +maintained automatically: whenever the user connects an unknown host +its key is added to the per-user file. +.Pp +Each line in these files contains the following fields: hostnames, +bits, exponent, modulus, comment. The fields are separated by spaces. +.Pp +Hostnames is a comma-separated list of patterns ('*' and '?' act as +wildcards); each pattern in turn is matched against the canonical host +name (when authenticating a client) or against the user-supplied +name (when authenticating a server). A pattern may also be preceded +by +.Ql ! +to indicate negation: if the host name matches a negated +pattern, it is not accepted (by that line) even if it matched another +pattern on the line. +.Pp +Bits, exponent, and modulus are taken directly from the host key; they +can be obtained, e.g., from +.Pa /etc/ssh_host_key.pub . +The optional comment field continues to the end of the line, and is not used. +.Pp +Lines starting with +.Ql # +and empty lines are ignored as comments. +.Pp +When performing host authentication, authentication is accepted if any +matching line has the proper key. It is thus permissible (but not +recommended) to have several lines or different host keys for the same +names. This will inevitably happen when short forms of host names +from different domains are put in the file. It is possible +that the files contain conflicting information; authentication is +accepted if valid information can be found from either file. +.Pp +Note that the lines in these files are typically hundreds of characters +long, and you definitely don't want to type in the host keys by hand. +Rather, generate them by a script +or by taking +.Pa /etc/ssh_host_key.pub +and adding the host names at the front. +.Ss Examples +closenet,closenet.hut.fi,.\|.\|.\|,130.233.208.41 1024 37 159.\|.\|.93 closenet.hut.fi +.Sh FILES +.Bl -tag -width Ds +.It Pa /etc/sshd_config +Contains configuration data for +.Nm sshd . +This file should be writable by root only, but it is recommended +(though not necessary) that it be world-readable. +.It Pa /etc/ssh_host_key +Contains the private part of the host key. +This file should only be owned by root, readable only by root, and not +accessible to others. +Note that +.Nm +does not start if this file is group/world-accessible. +.It Pa /etc/ssh_host_key.pub +Contains the public part of the host key. +This file should be world-readable but writable only by +root. Its contents should match the private part. This file is not +really used for anything; it is only provided for the convenience of +the user so its contents can be copied to known hosts files. +These two files are created using +.Xr ssh-keygen 1 . +.It Pa /var/run/sshd.pid +Contains the process ID of the +.Nm +listening for connections (if there are several daemons running +concurrently for different ports, this contains the pid of the one +started last). The contents of this file are not sensitive; it can be +world-readable. +.It Pa $HOME/.ssh/authorized_keys +Lists the RSA keys that can be used to log into the user's account. +This file must be readable by root (which may on some machines imply +it being world-readable if the user's home directory resides on an NFS +volume). It is recommended that it not be accessible by others. The +format of this file is described above. +.It Pa /etc/ssh_known_hosts +This file is consulted when using rhosts with RSA host +authentication to check the public key of the host. The key must be +listed in this file to be accepted. +.It Pa $HOME/.ssh/known_hosts +The client uses this file +and +.Pa /etc/ssh_known_hosts +to verify that the remote host is the one we intended to +connect. These files should be writable only by root/the owner. +.Pa /etc/ssh_known_hosts +should be world-readable, and +.Pa $HOME/.ssh/known_hosts +can but need not be world-readable. +.It Pa /etc/nologin +If this file exists, +.Nm +refuses to let anyone except root log in. The contents of the file +are displayed to anyone trying to log in, and non-root connections are +refused. The file should be world-readable. +.It Pa /etc/hosts.allow, /etc/hosts.deny +If compiled with +.Sy LIBWRAP +support, tcp-wrappers access controls may be defined here as described in +.Xr hosts_access 5 . +.It Pa $HOME/.rhosts +This file contains host-username pairs, separated by a space, one per +line. The given user on the corresponding host is permitted to log in +without password. The same file is used by rlogind and rshd. +The file must +be writable only by the user; it is recommended that it not be +accessible by others. +.Pp +If is also possible to use netgroups in the file. Either host or user +name may be of the form +@groupname to specify all hosts or all users +in the group. +.It Pa $HOME/.shosts +For ssh, +this file is exactly the same as for +.Pa .rhosts . +However, this file is +not used by rlogin and rshd, so using this permits access using SSH only. +.Pa /etc/hosts.equiv +This file is used during +.Pa .rhosts +authentication. In the +simplest form, this file contains host names, one per line. Users on +those hosts are permitted to log in without a password, provided they +have the same user name on both machines. The host name may also be +followed by a user name; such users are permitted to log in as +.Em any +user on this machine (except root). Additionally, the syntax +.Dq +@group +can be used to specify netgroups. Negated entries start with +.Ql \&- . +.Pp +If the client host/user is successfully matched in this file, login is +automatically permitted provided the client and server user names are the +same. Additionally, successful RSA host authentication is normally +required. This file must be writable only by root; it is recommended +that it be world-readable. +.Pp +.Sy "Warning: It is almost never a good idea to use user names in" +.Pa hosts.equiv . +Beware that it really means that the named user(s) can log in as +.Em anybody , +which includes bin, daemon, adm, and other accounts that own critical +binaries and directories. Using a user name practically grants the +user root access. The only valid use for user names that I can think +of is in negative entries. +.Pp +Note that this warning also applies to rsh/rlogin. +.It Pa /etc/shosts.equiv +This is processed exactly as +.Pa /etc/hosts.equiv . +However, this file may be useful in environments that want to run both +rsh/rlogin and ssh. +.It Pa $HOME/.ssh/environment +This file is read into the environment at login (if it exists). It +can only contain empty lines, comment lines (that start with +.Ql # ) , +and assignment lines of the form name=value. The file should be writable +only by the user; it need not be readable by anyone else. +.It Pa $HOME/.ssh/rc +If this file exists, it is run with /bin/sh after reading the +environment files but before starting the user's shell or command. If +X11 spoofing is in use, this will receive the "proto cookie" pair in +standard input (and +.Ev DISPLAY +in environment). This must call +.Xr xauth 1 +in that case. +.Pp +The primary purpose of this file is to run any initialization routines +which may be needed before the user's home directory becomes +accessible; AFS is a particular example of such an environment. +.Pp +This file will probably contain some initialization code followed by +something similar to: "if read proto cookie; then echo add $DISPLAY +$proto $cookie | xauth -q -; fi". +.Pp +If this file does not exist, +.Pa /etc/sshrc +is run, and if that +does not exist either, xauth is used to store the cookie. +.Pp +This file should be writable only by the user, and need not be +readable by anyone else. +.It Pa /etc/sshrc +Like +.Pa $HOME/.ssh/rc . +This can be used to specify +machine-specific login-time initializations globally. This file +should be writable only by root, and should be world-readable. +.Sh AUTHOR +Tatu Ylonen +.Pp +Information about new releases, mailing lists, and other related +issues can be found from the SSH WWW home page: +.Pp +.Dl http://www.cs.hut.fi/ssh. +.Pp +OpenSSH +is a derivative of the original (free) ssh 1.2.12 release, but with bugs +removed and newer features re-added. Rapidly after the 1.2.12 release, +newer versions bore successively more restrictive licenses. This version +of OpenSSH +.Bl -bullet +.It +has all components of a restrictive nature (ie. patents, see +.Xr ssl 8 ) +directly removed from the source code; any licensed or patented components +are chosen from +external libraries. +.It +has been updated to support ssh protocol 1.5. +.It +contains added support for +.Xr kerberos 8 +authentication and ticket passing. +.It +supports one-time password authentication with +.Xr skey 1 . +.El +.Pp +The libraries described in +.Xr ssl 8 +are required for proper operation. +.Sh SEE ALSO +.Xr rlogin 1 , +.Xr rsh 1 , +.Xr scp 1 , +.Xr ssh 1 , +.Xr ssh-add 1 , +.Xr ssh-agent 1 , +.Xr ssh-keygen 1 , +.Xr ssl 8 -- 2.45.2