- (tim) [configure.ac] Add AC_REVISION. Add sys/time.h to lastlog.h test

[openssh.git] / ssh.1

diff --git a/ssh.1 b/ssh.1
index 27a51b69000f2e32bdb4835396b2a6a95a418287..f4c677628ce291aafb648d7bd23f9e6b59c171b4 100644 (file)
--- a/ssh.1
+++ b/ssh.1
@@ -34,7 +34,7 @@
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
 .\" (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF
 .\" THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"

-.\" $OpenBSD: ssh.1,v 1.239 2006/01/03 16:55:18 jmc Exp $
+.\" $OpenBSD: ssh.1,v 1.253 2006/01/30 13:37:49 jmc Exp $

 .Dd September 25, 1999
 .Dt SSH 1
 .Os
 .Dd September 25, 1999
 .Dt SSH 1
 .Os


@@ -89,7 +89,7 @@ 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.
 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
+X11 connections and arbitrary TCP ports

 can also be forwarded over the secure channel.
 .Pp
 .Nm
 can also be forwarded over the secure channel.
 .Pp
 .Nm


@@ -146,7 +146,7 @@ of the connection.
 Only useful on systems with more than one address.
 .It Fl C
 Requests compression of all data (including stdin, stdout, stderr, and
 Only useful on systems with more than one address.
 .It Fl C
 Requests compression of all data (including stdin, stdout, stderr, and

-data for forwarded X11 and TCP/IP connections).
+data for forwarded X11 and TCP connections).

 The compression algorithm is the same used by
 .Xr gzip 1 ,
 and the
 The compression algorithm is the same used by
 .Xr gzip 1 ,
 and the


@@ -477,6 +477,7 @@ For full details of the options listed below, and their possible values, see
 .It Protocol
 .It ProxyCommand
 .It PubkeyAuthentication
 .It Protocol
 .It ProxyCommand
 .It PubkeyAuthentication

+.It RekeyLimit

 .It RemoteForward
 .It RhostsRSAAuthentication
 .It RSAAuthentication
 .It RemoteForward
 .It RhostsRSAAuthentication
 .It RSAAuthentication


@@ -643,7 +644,7 @@ The file format and configuration options are described in
 exits with the exit status of the remote command or with 255
 if an error occurred.
 .Sh AUTHENTICATION
 exits with the exit status of the remote command or with 255
 if an error occurred.
 .Sh AUTHENTICATION

-The OpenSSH SSH client supports OpenSSH protocols 1 and 2.
+The OpenSSH SSH client supports SSH protocols 1 and 2.

 Protocol 2 is the default, with
 .Nm
 falling back to protocol 1 if it detects protocol 2 is unsupported.
 Protocol 2 is the default, with
 .Nm
 falling back to protocol 1 if it detects protocol 2 is unsupported.


@@ -809,15 +810,6 @@ The
 option can be used to control logins to machines whose
 host key is not known or has changed.
 .Pp
 option can be used to control logins to machines whose
 host key is not known or has changed.
 .Pp

-.Nm
-can be configured to verify host identification using fingerprint resource
-records (SSHFP) published in DNS.
-The
-.Cm VerifyHostKeyDNS
-option can be used to control how DNS lookups are performed.
-SSHFP resource records can be generated using
-.Xr ssh-keygen 1 .
-.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.
 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.


@@ -834,7 +826,7 @@ On most systems, setting the escape character to
 will also make the session transparent even if a tty is used.
 .Pp
 The session terminates when the command or shell on the remote
 will also make the session transparent even if a tty is used.
 .Pp
 The session terminates when the command or shell on the remote

-machine exits and all X11 and TCP/IP connections have been closed.
+machine exits and all X11 and TCP connections have been closed.

 .Sh ESCAPE CHARACTERS
 When a pseudo-terminal has been requested,
 .Nm
 .Sh ESCAPE CHARACTERS
 When a pseudo-terminal has been requested,
 .Nm


@@ -893,7 +885,64 @@ option.
 Request rekeying of the connection
 (only useful for SSH protocol version 2 and if the peer supports it).
 .El
 Request rekeying of the connection
 (only useful for SSH protocol version 2 and if the peer supports it).
 .El

-.Sh X11 AND TCP FORWARDING
+.Sh TCP FORWARDING
+Forwarding of arbitrary TCP connections over the secure channel can
+be specified either on the command line or in a configuration file.
+One possible application of TCP forwarding is a secure connection to a
+mail server; another is going through firewalls.
+.Pp
+In the example below, we look at encrypting communication between
+an IRC client and server, even though the IRC server does not directly
+support encrypted communications.
+This works as follows:
+the user connects to the remote host using
+.Nm ,
+specifying a port to be used to forward connections
+to the remote server.
+After that it is possible to start the service which is to be encrypted
+on the client machine,
+connecting to the same local port,
+and
+.Nm
+will encrypt and forward the connection.
+.Pp
+The following example tunnels an IRC session from client machine
+.Dq 127.0.0.1
+(localhost)
+to remote server
+.Dq server.example.com :
+.Bd -literal -offset 4n
+$ ssh -f -L 1234:localhost:6667 server.example.com sleep 10
+$ irc -c '#users' -p 1234 pinky 127.0.0.1
+.Ed
+.Pp
+This tunnels a connection to IRC server
+.Dq server.example.com ,
+joining channel
+.Dq #users ,
+nickname
+.Dq pinky ,
+using port 1234.
+It doesn't matter which port is used,
+as long as it's greater than 1023
+(remember, only root can open sockets on privileged ports)
+and doesn't conflict with any ports already in use.
+The connection is forwarded to port 6667 on the remote server,
+since that's the standard port for IRC services.
+.Pp
+The
+.Fl f
+option backgrounds
+.Nm
+and the remote command
+.Dq sleep 10
+is specified to allow an amount of time
+(10 seconds, in the example)
+to start the service which is to be tunnelled.
+If no connections are made within the time specified,
+.Nm
+will exit.
+.Sh X11 FORWARDING

 If the
 .Cm ForwardX11
 variable is set to
 If the
 .Cm ForwardX11
 variable is set to


@@ -948,11 +997,106 @@ and
 options above) and
 the user is using an authentication agent, the connection to the agent
 is automatically forwarded to the remote side.
 options above) and
 the user is using an authentication agent, the connection to the agent
 is automatically forwarded to the remote side.

+.Sh VERIFYING HOST KEYS
+When connecting to a server for the first time,
+a fingerprint of the server's public key is presented to the user
+(unless the option
+.Cm StrictHostKeyChecking
+has been disabled).
+Fingerprints can be determined using
+.Xr ssh-keygen 1 :

 .Pp
 .Pp

-Forwarding of arbitrary TCP/IP connections over the secure channel can
-be specified either on the 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 through firewalls.
+.Dl $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key
+.Pp
+If the fingerprint is already known,
+it can be matched and verified,
+and the key can be accepted.
+If the fingerprint is unknown,
+an alternative method of verification is available:
+SSH fingerprints verified by DNS.
+An additional resource record (RR),
+SSHFP,
+is added to a zonefile
+and the connecting client is able to match the fingerprint
+with that of the key presented.
+.Pp
+In this example, we are connecting a client to a server,
+.Dq host.example.com .
+The SSHFP resource records should first be added to the zonefile for
+host.example.com:
+.Bd -literal -offset indent
+$ ssh-keygen -f /etc/ssh/ssh_host_rsa_key.pub -r host.example.com.
+$ ssh-keygen -f /etc/ssh/ssh_host_dsa_key.pub -r host.example.com.
+.Ed
+.Pp
+The output lines will have to be added to the zonefile.
+To check that the zone is answering fingerprint queries:
+.Pp
+.Dl $ dig -t SSHFP host.example.com
+.Pp
+Finally the client connects:
+.Bd -literal -offset indent
+$ ssh -o "VerifyHostKeyDNS ask" host.example.com
+[...]
+Matching host key fingerprint found in DNS.
+Are you sure you want to continue connecting (yes/no)?
+.Ed
+.Pp
+See the
+.Cm VerifyHostKeyDNS
+option in
+.Xr ssh_config 5
+for more information.
+.Sh SSH-BASED VIRTUAL PRIVATE NETWORKS
+.Nm
+contains support for Virtual Private Network (VPN) tunnelling
+using the
+.Xr tun 4
+network pseudo-device,
+allowing two networks to be joined securely.
+The
+.Xr sshd_config 5
+configuration option
+.Cm PermitTunnel
+controls whether the server supports this,
+and at what level (layer 2 or 3 traffic).
+.Pp
+The following example would connect client network 10.0.50.0/24
+with remote network 10.0.99.0/24, provided that the SSH server
+running on the gateway to the remote network,
+at 192.168.1.15, allows it:
+.Bd -literal -offset indent
+# ssh -f -w 0:1 192.168.1.15 true
+# ifconfig tun0 10.0.50.1 10.0.99.1 netmask 255.255.255.252
+.Ed
+.Pp
+Client access may be more finely tuned via the
+.Pa /root/.ssh/authorized_keys
+file (see below) and the
+.Cm PermitRootLogin
+server option.
+The following entry would permit connections on the first
+.Xr tun 4
+device from user
+.Dq jane
+and on the second device from user
+.Dq john ,
+if
+.Cm PermitRootLogin
+is set to
+.Dq forced-commands-only :
+.Bd -literal -offset 2n
+tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane
+tunnel="2",command="sh /etc/netstart tun1" ssh-rsa ... john
+.Ed
+.Pp
+Since a SSH-based setup entails a fair amount of overhead,
+it may be more suited to temporary setups,
+such as for wireless VPNs.
+More permanent VPNs are better provided by tools such as
+.Xr ipsecctl 8
+and
+.Xr isakmpd 8 .

 .Sh ENVIRONMENT
 .Nm
 will normally set the following environment variables:
 .Sh ENVIRONMENT
 .Nm
 will normally set the following environment variables:


@@ -1055,19 +1199,9 @@ option in
 .Sh FILES
 .Bl -tag -width Ds -compact
 .It ~/.rhosts
 .Sh FILES
 .Bl -tag -width Ds -compact
 .It ~/.rhosts

-This file is used in
-.Cm RhostsRSAAuthentication
-and
-.Cm HostbasedAuthentication
-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.
+This file is used for host-based authentication (see above).

 On some machines this file may need to be
 On some machines this file may need to be

-world-readable if the user's home directory is on a NFS partition,
+world-readable if the user's home directory is on an NFS partition,

 because
 .Xr sshd 8
 reads it as root.
 because
 .Xr sshd 8
 reads it as root.


@@ -1077,40 +1211,17 @@ The recommended
 permission for most machines is read/write for the user, and not
 accessible by others.
 .Pp
 permission for most machines is read/write for the user, and not
 accessible by others.
 .Pp

-Note that
-.Xr sshd 8
-allows authentication only in combination with client host key
-authentication before permitting log in.
-If the server machine does not have the client's host key in
-.Pa /etc/ssh/ssh_known_hosts ,
-it can be stored in
-.Pa ~/.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 to
-.Pa ~/.ssh/known_hosts .
-.Pp

 .It ~/.shosts
 .It ~/.shosts

-This file is used exactly the same way as
-.Pa .rhosts .
-The purpose for
-having this file is to be able to use
-.Cm RhostsRSAAuthentication
-and
-.Cm HostbasedAuthentication
-authentication without permitting login with
-.Xr rlogin
-or
-.Xr rsh 1 .
+This file is used in exactly the same way as
+.Pa .rhosts ,
+but allows host-based authentication without permitting login with
+rlogin/rsh.

 .Pp
 .It ~/.ssh/authorized_keys
 Lists the public keys (RSA/DSA) that can be used for logging in as this user.
 The format of this file is described in the
 .Xr sshd 8
 manual page.
 .Pp
 .It ~/.ssh/authorized_keys
 Lists the public keys (RSA/DSA) 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
-.Pa .pub
-identity files.

 This file is not highly sensitive, but the recommended
 permissions are read/write for the user, and not accessible by others.
 .Pp
 This file is not highly sensitive, but the recommended
 permissions are read/write for the user, and not accessible by others.
 .Pp


@@ -1145,48 +1256,32 @@ sensitive part of this file using 3DES.
 Contains the public key for authentication.
 These files are not
 sensitive and can (but need not) be readable by anyone.
 Contains the public key for authentication.
 These files are not
 sensitive and can (but need not) be readable by anyone.

-They are
-never used automatically and are not necessary: they are only provided for
-the convenience of the user.

 .Pp
 .It ~/.ssh/known_hosts
 .Pp
 .It ~/.ssh/known_hosts

-Records host keys for all hosts the user has logged into that are not
-in
-.Pa /etc/ssh/ssh_known_hosts .
+Contains a list of host keys for all hosts the user has logged into
+that are not already in the systemwide list of known host keys.

 See
 See

-.Xr sshd 8 .
+.Xr sshd 8
+for further details of the format of this file.

 .Pp
 .It ~/.ssh/rc
 Commands in this file are executed by
 .Nm
 .Pp
 .It ~/.ssh/rc
 Commands in this file are executed by
 .Nm

-when the user logs in just before the user's shell (or command) is
+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.
 .Pp
 .It /etc/hosts.equiv
 started.
 See the
 .Xr sshd 8
 manual page for more information.
 .Pp
 .It /etc/hosts.equiv

-This file is used during
-.Cm RhostsRSAAuthentication
-and
-.Cm HostbasedAuthentication
-authentication.
-It contains
-canonical hosts names, one per line (the full format is described in 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 client host key authentication is required.
-This file should only be writable by root.
+This file is for host-based authentication (see above).
+It should only be writable by root.

 .Pp
 .It /etc/shosts.equiv
 .Pp
 .It /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.
+This file is used in exactly the same way as
+.Pa hosts.equiv ,
+but allows host-based authentication without permitting login with
+rlogin/rsh.

 .Pp
 .It Pa /etc/ssh/ssh_config
 Systemwide configuration file.
 .Pp
 .It Pa /etc/ssh/ssh_config
 Systemwide configuration file.


@@ -1197,24 +1292,18 @@ The file format and configuration options are described in
 .It /etc/ssh/ssh_host_dsa_key
 .It /etc/ssh/ssh_host_rsa_key
 These three files contain the private parts of the host keys
 .It /etc/ssh/ssh_host_dsa_key
 .It /etc/ssh/ssh_host_rsa_key
 These three files contain the private parts of the host keys

-and are used for
-.Cm RhostsRSAAuthentication
-and
-.Cm HostbasedAuthentication .
-If the protocol version 1
-.Cm RhostsRSAAuthentication
-method is used,
+and are used for host-based authentication.
+If protocol version 1 is used,

 .Nm
 must be setuid root, since the host key is readable only by root.
 For protocol version 2,
 .Nm
 uses
 .Xr ssh-keysign 8
 .Nm
 must be setuid root, since the host key is readable only by root.
 For protocol version 2,
 .Nm
 uses
 .Xr ssh-keysign 8

-to access the host keys for
-.Cm HostbasedAuthentication .
-This eliminates the requirement that
+to access the host keys,
+eliminating the requirement that

 .Nm
 .Nm

-be setuid root when that authentication method is used.
+be setuid root when host-based authentication is used.

 By default
 .Nm
 is not setuid root.
 By default
 .Nm
 is not setuid root.


@@ -1224,42 +1313,27 @@ 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 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, public key 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 in the
-.Xr sshd 8
-manual page.
-.Pp
-The canonical system name (as returned by name servers) is used by
+It should be world-readable.
+See

 .Xr sshd 8
 .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.
+for further details of the format of this file.

 .Pp
 .It /etc/ssh/sshrc
 Commands in this file are executed by
 .Nm
 .Pp
 .It /etc/ssh/sshrc
 Commands in this file are executed by
 .Nm

-when the user logs in just before the user's shell (or command) is started.
+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.
 .El
 .Sh SEE ALSO
 See the
 .Xr sshd 8
 manual page for more information.
 .El
 .Sh SEE ALSO

-.Xr gzip 1 ,
-.Xr rsh 1 ,

 .Xr scp 1 ,
 .Xr sftp 1 ,
 .Xr ssh-add 1 ,
 .Xr ssh-agent 1 ,
 .Xr ssh-keygen 1 ,
 .Xr scp 1 ,
 .Xr sftp 1 ,
 .Xr ssh-add 1 ,
 .Xr ssh-agent 1 ,
 .Xr ssh-keygen 1 ,

-.Xr telnet 1 ,
+.Xr ssh-keyscan 1 ,
+.Xr tun 4 ,

 .Xr hosts.equiv 5 ,
 .Xr ssh_config 5 ,
 .Xr ssh-keysign 8 ,
 .Xr hosts.equiv 5 ,
 .Xr ssh_config 5 ,
 .Xr ssh-keysign 8 ,