X-Git-Url: http://andersk.mit.edu/gitweb/openssh.git/blobdiff_plain/aaa18db99cda6616d9694861687bf47779bc7621..aa56f760ea15248e3eeea92349bc5d0f27b053e3:/ssh.1

diff --git a/ssh.1 b/ssh.1
index cfe1655e..6e41bcd8 100644
--- 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.
 .\"
-.\" $OpenBSD: ssh.1,v 1.244 2006/01/06 13:27:32 jmc Exp $
+.\" $OpenBSD: ssh.1,v 1.263 2006/07/11 18:50:48 markus Exp $
 .Dd September 25, 1999
 .Dt SSH 1
 .Os
@@ -78,7 +78,8 @@
 .Oc
 .Op Fl S Ar ctl_path
 .Bk -words
-.Op Fl w Ar tunnel : Ns Ar tunnel
+.Oo Fl w Ar local_tun Ns
+.Op : Ns Ar remote_tun Oc
 .Oo Ar user Ns @ Oc Ns Ar hostname
 .Op Ar command
 .Ek
@@ -89,7 +90,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.
-X11 connections and arbitrary TCP/IP ports
+X11 connections and arbitrary TCP ports
 can also be forwarded over the secure channel.
 .Pp
 .Nm
@@ -146,7 +147,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
-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
@@ -448,6 +449,7 @@ For full details of the options listed below, and their possible values, see
 .It ControlPath
 .It DynamicForward
 .It EscapeChar
+.It ExitOnForwardFailure
 .It ForwardAgent
 .It ForwardX11
 .It ForwardX11Trusted
@@ -477,6 +479,7 @@ For full details of the options listed below, and their possible values, see
 .It Protocol
 .It ProxyCommand
 .It PubkeyAuthentication
+.It RekeyLimit
 .It RemoteForward
 .It RhostsRSAAuthentication
 .It RSAAuthentication
@@ -568,7 +571,7 @@ Disable pseudo-tty allocation.
 Force pseudo-tty allocation.
 This can be used to execute arbitrary
 screen-based programs on a remote machine, which can be very useful,
-e.g., when implementing menu services.
+e.g. when implementing menu services.
 Multiple
 .Fl t
 options force tty allocation, even if
@@ -587,24 +590,35 @@ Multiple
 .Fl v
 options increase the verbosity.
 The maximum is 3.
-.It Fl w Ar tunnel : Ns Ar tunnel
-Requests a
+.It Fl w Xo
+.Ar local_tun Ns Op : Ns Ar remote_tun
+.Xc
+Requests
+tunnel
+device forwarding with the specified
 .Xr tun 4
-device on the client
-(first
-.Ar tunnel
-arg)
-and server
-(second
-.Ar tunnel
-arg).
+devices between the client
+.Pq Ar local_tun
+and the server
+.Pq Ar remote_tun .
+.Pp
 The devices may be specified by numerical ID or the keyword
 .Dq any ,
 which uses the next available tunnel device.
+If
+.Ar remote_tun
+is not specified, it defaults to
+.Dq any .
 See also the
 .Cm Tunnel
-directive in
+and
+.Cm TunnelDevice
+directives in
 .Xr ssh_config 5 .
+If the
+.Cm Tunnel
+directive is unset, it is set to the default tunnel mode, which is
+.Dq point-to-point .
 .It Fl X
 Enables X11 forwarding.
 This can also be specified on a per-host basis in a configuration file.
@@ -643,7 +657,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
-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.
@@ -665,6 +679,7 @@ Protocol 1 lacks a strong mechanism for ensuring the
 integrity of the connection.
 .Pp
 The methods available for authentication are:
+GSSAPI-based authentication,
 host-based authentication,
 public key authentication,
 challenge-response authentication,
@@ -809,15 +824,6 @@ The
 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.
@@ -834,7 +840,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
-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
@@ -880,7 +886,9 @@ and
 options (see above).
 It also allows the cancellation of existing remote port-forwardings
 using
-.Fl KR Ar hostport .
+.Sm off
+.Fl KR Oo Ar bind_address : Oc Ar port .
+.Sm on
 .Ic !\& Ns Ar command
 allows the user to execute a local command if the
 .Ic PermitLocalCommand
@@ -893,7 +901,64 @@ option.
 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
@@ -948,11 +1013,105 @@ and
 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
-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 -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
+.Xr tun 4
+device 1 from user
+.Dq jane
+and on tun device 2 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 tun2" 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:
@@ -1034,7 +1193,7 @@ If the current session has no tty,
 this variable is not set.
 .It Ev TZ
 This variable is set to indicate the present time zone if it
-was set when the daemon was started (i.e., the daemon passes the value
+was set when the daemon was started (i.e. the daemon passes the value
 on to new connections).
 .It Ev USER
 Set to the name of the user logging in.
@@ -1078,9 +1237,6 @@ 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
@@ -1115,9 +1271,6 @@ 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.
-They are
-never used automatically and are not necessary: they are only provided for
-the convenience of the user.
 .Pp
 .It ~/.ssh/known_hosts
 Contains a list of host keys for all hosts the user has logged into
@@ -1129,7 +1282,7 @@ for further details of the format of this file.
 .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
@@ -1154,24 +1307,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
-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
-to access the host keys for
-.Cm HostbasedAuthentication .
-This eliminates the requirement that
+to access the host keys,
+eliminating the requirement that
 .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.
@@ -1189,7 +1336,7 @@ for further details of the format of this file.
 .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.
@@ -1201,20 +1348,65 @@ manual page for more information.
 .Xr ssh-agent 1 ,
 .Xr ssh-keygen 1 ,
 .Xr ssh-keyscan 1 ,
+.Xr tun 4 ,
 .Xr hosts.equiv 5 ,
 .Xr ssh_config 5 ,
 .Xr ssh-keysign 8 ,
 .Xr sshd 8
 .Rs
-.%A T. Ylonen
-.%A T. Kivinen
-.%A M. Saarinen
-.%A T. Rinne
-.%A S. Lehtinen
-.%T "SSH Protocol Architecture"
-.%N draft-ietf-secsh-architecture-12.txt
-.%D January 2002
-.%O work in progress material
+.%R RFC 4250
+.%T "The Secure Shell (SSH) Protocol Assigned Numbers"
+.%D 2006
+.Re
+.Rs
+.%R RFC 4251
+.%T "The Secure Shell (SSH) Protocol Architecture"
+.%D 2006
+.Re
+.Rs
+.%R RFC 4252
+.%T "The Secure Shell (SSH) Authentication Protocol"
+.%D 2006
+.Re
+.Rs
+.%R RFC 4253
+.%T "The Secure Shell (SSH) Transport Layer Protocol"
+.%D 2006
+.Re
+.Rs
+.%R RFC 4254
+.%T "The Secure Shell (SSH) Connection Protocol"
+.%D 2006
+.Re
+.Rs
+.%R RFC 4255
+.%T "Using DNS to Securely Publish Secure Shell (SSH) Key Fingerprints"
+.%D 2006
+.Re
+.Rs
+.%R RFC 4256
+.%T "Generic Message Exchange Authentication for the Secure Shell Protocol (SSH)"
+.%D 2006
+.Re
+.Rs
+.%R RFC 4335
+.%T "The Secure Shell (SSH) Session Channel Break Extension"
+.%D 2006
+.Re
+.Rs
+.%R RFC 4344
+.%T "The Secure Shell (SSH) Transport Layer Encryption Modes"
+.%D 2006
+.Re
+.Rs
+.%R RFC 4345
+.%T "Improved Arcfour Modes for the Secure Shell (SSH) Transport Layer Protocol"
+.%D 2006
+.Re
+.Rs
+.%R RFC 4419
+.%T "Diffie-Hellman Group Exchange for the Secure Shell (SSH) Transport Layer Protocol"
+.%D 2006
 .Re
 .Sh AUTHORS
 OpenSSH is a derivative of the original and free