The man2html from jbasney on pkilab2 works whereas the standard one doesn't.

[gssapi-openssh.git] / openssh / ssh.1

diff --git a/openssh/ssh.1 b/openssh/ssh.1
index f4c677628ce291aafb648d7bd23f9e6b59c171b4..6c6271ee4f74dc6a109b466ea513f224a4da7251 100644 (file)
--- a/openssh/ssh.1
+++ b/openssh/ssh.1
@@ -34,8 +34,8 @@
 .\" (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.253 2006/01/30 13:37:49 jmc Exp $
-.Dd September 25, 1999
+.\" $OpenBSD: ssh.1,v 1.283 2009/03/19 15:15:09 jmc Exp $
+.Dd $Mdocdate: March 19 2009 $

 .Dt SSH 1
 .Os
 .Sh NAME
 .Dt SSH 1
 .Os
 .Sh NAME


@@ -43,7 +43,7 @@
 .Nd OpenSSH SSH client (remote login program)
 .Sh SYNOPSIS
 .Nm ssh
 .Nd OpenSSH SSH client (remote login program)
 .Sh SYNOPSIS
 .Nm ssh

-.Op Fl 1246AaCfgkMNnqsTtVvXxY
+.Op Fl 1246AaCfgKkMNnqsTtVvXxYy

 .Op Fl b Ar bind_address
 .Op Fl c Ar cipher_spec
 .Oo Fl D\ \&
 .Op Fl b Ar bind_address
 .Op Fl c Ar cipher_spec
 .Oo Fl D\ \&


@@ -78,7 +78,8 @@
 .Oc
 .Op Fl S Ar ctl_path
 .Bk -words
 .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
 .Oo Ar user Ns @ Oc Ns Ar hostname
 .Op Ar command
 .Ek


@@ -190,26 +191,9 @@ For protocol version 2,
 .Ar cipher_spec
 is a comma-separated list of ciphers
 listed in order of preference.
 .Ar cipher_spec
 is a comma-separated list of ciphers
 listed in order of preference.

-The supported ciphers are:
-3des-cbc,
-aes128-cbc,
-aes192-cbc,
-aes256-cbc,
-aes128-ctr,
-aes192-ctr,
-aes256-ctr,
-arcfour128,
-arcfour256,
-arcfour,
-blowfish-cbc,
-and
-cast128-cbc.
-The default is:
-.Bd -literal -offset indent
-aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour128,
-arcfour256,arcfour,aes192-cbc,aes256-cbc,aes128-ctr,
-aes192-ctr,aes256-ctr
-.Ed
+See the
+.Cm Ciphers
+keyword for more information.

 .It Fl D Xo
 .Sm off
 .Oo Ar bind_address : Oc
 .It Fl D Xo
 .Sm off
 .Oo Ar bind_address : Oc


@@ -289,6 +273,15 @@ This implies
 The recommended way to start X11 programs at a remote site is with
 something like
 .Ic ssh -f host xterm .
 The recommended way to start X11 programs at a remote site is with
 something like
 .Ic ssh -f host xterm .

+.Pp
+If the
+.Cm ExitOnForwardFailure
+configuration option is set to
+.Dq yes ,
+then a client started with
+.Fl f
+will wait for all remote port forwards to be successfully established
+before placing itself in the background.

 .It Fl g
 Allows remote hosts to connect to local forwarded ports.
 .It Fl I Ar smartcard_device
 .It Fl g
 Allows remote hosts to connect to local forwarded ports.
 .It Fl I Ar smartcard_device


@@ -314,6 +307,9 @@ It is possible to have multiple
 .Fl i
 options (and multiple identities specified in
 configuration files).
 .Fl i
 options (and multiple identities specified in
 configuration files).

+.It Fl K
+Enables GSSAPI-based authentication and forwarding (delegation) of GSSAPI
+credentials to the server.

 .It Fl k
 Disables forwarding (delegation) of GSSAPI credentials to the server.
 .It Fl L Xo
 .It Fl k
 Disables forwarding (delegation) of GSSAPI credentials to the server.
 .It Fl L Xo


@@ -448,6 +444,7 @@ For full details of the options listed below, and their possible values, see
 .It ControlPath
 .It DynamicForward
 .It EscapeChar
 .It ControlPath
 .It DynamicForward
 .It EscapeChar

+.It ExitOnForwardFailure

 .It ForwardAgent
 .It ForwardX11
 .It ForwardX11Trusted
 .It ForwardAgent
 .It ForwardX11
 .It ForwardX11Trusted


@@ -493,6 +490,7 @@ For full details of the options listed below, and their possible values, see
 .It User
 .It UserKnownHostsFile
 .It VerifyHostKeyDNS
 .It User
 .It UserKnownHostsFile
 .It VerifyHostKeyDNS

+.It VisualHostKey

 .It XAuthLocation
 .El
 .It Fl p Ar port
 .It XAuthLocation
 .El
 .It Fl p Ar port


@@ -501,7 +499,7 @@ This can be specified on a
 per-host basis in the configuration file.
 .It Fl q
 Quiet mode.
 per-host basis in the configuration file.
 .It Fl q
 Quiet mode.

-Causes all warning and diagnostic messages to be suppressed.
+Causes most warning and diagnostic messages to be suppressed.

 .It Fl R Xo
 .Sm off
 .Oo Ar bind_address : Oc
 .It Fl R Xo
 .Sm off
 .Oo Ar bind_address : Oc


@@ -535,7 +533,7 @@ using an alternative syntax:
 .Pp
 By default, the listening socket on the server will be bound to the loopback
 interface only.
 .Pp
 By default, the listening socket on the server will be bound to the loopback
 interface only.

-This may be overriden by specifying a
+This may be overridden by specifying a

 .Ar bind_address .
 An empty
 .Ar bind_address ,
 .Ar bind_address .
 An empty
 .Ar bind_address ,


@@ -548,6 +546,13 @@ will only succeed if the server's
 .Cm GatewayPorts
 option is enabled (see
 .Xr sshd_config 5 ) .
 .Cm GatewayPorts
 option is enabled (see
 .Xr sshd_config 5 ) .

+.Pp
+If the
+.Ar port
+argument is
+.Ql 0 ,
+the listen port will be dynamically allocated on the server and reported
+to the client at run time.

 .It Fl S Ar ctl_path
 Specifies the location of a control socket for connection sharing.
 Refer to the description of
 .It Fl S Ar ctl_path
 Specifies the location of a control socket for connection sharing.
 Refer to the description of


@@ -569,7 +574,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,
 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
 Multiple
 .Fl t
 options force tty allocation, even if


@@ -588,24 +593,35 @@ Multiple
 .Fl v
 options increase the verbosity.
 The maximum is 3.
 .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
 .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.
 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
 See also the
 .Cm Tunnel

-directive in
+and
+.Cm TunnelDevice
+directives in

 .Xr ssh_config 5 .
 .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.
 .It Fl X
 Enables X11 forwarding.
 This can also be specified on a per-host basis in a configuration file.


@@ -632,6 +648,11 @@ Disables X11 forwarding.
 Enables trusted X11 forwarding.
 Trusted X11 forwardings are not subjected to the X11 SECURITY extension
 controls.
 Enables trusted X11 forwarding.
 Trusted X11 forwardings are not subjected to the X11 SECURITY extension
 controls.

+.It Fl y
+Send log information using the
+.Xr syslog 3
+system module.
+By default this information is sent to stderr.

 .El
 .Pp
 .Nm
 .El
 .Pp
 .Nm


@@ -661,11 +682,12 @@ Both protocols support similar authentication methods,
 but protocol 2 is preferred since
 it provides additional mechanisms for confidentiality
 (the traffic is encrypted using AES, 3DES, Blowfish, CAST128, or Arcfour)
 but protocol 2 is preferred since
 it provides additional mechanisms for confidentiality
 (the traffic is encrypted using AES, 3DES, Blowfish, CAST128, or Arcfour)

-and integrity (hmac-md5, hmac-sha1, hmac-ripemd160).
+and integrity (hmac-md5, hmac-sha1, umac-64, hmac-ripemd160).

 Protocol 1 lacks a strong mechanism for ensuring the
 integrity of the connection.
 .Pp
 The methods available for authentication are:
 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,
 host-based authentication,
 public key authentication,
 challenge-response authentication,


@@ -866,13 +888,16 @@ Send a BREAK to the remote system
 .It Cm ~C
 Open command line.
 Currently this allows the addition of port forwardings using the
 .It Cm ~C
 Open command line.
 Currently this allows the addition of port forwardings using the

-.Fl L
-and
+.Fl L ,

 .Fl R
 .Fl R

+and
+.Fl D

 options (see above).
 It also allows the cancellation of existing remote port-forwardings
 using
 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
 .Ic !\& Ns Ar command
 allows the user to execute a local command if the
 .Ic PermitLocalCommand


@@ -1008,9 +1033,31 @@ Fingerprints can be determined using
 .Pp
 .Dl $ ssh-keygen -l -f /etc/ssh/ssh_host_rsa_key
 .Pp
 .Pp
 .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 already known, it can be matched
+and the key can be accepted or rejected.
+Because of the difficulty of comparing host keys
+just by looking at hex strings,
+there is also support to compare host keys visually,
+using
+.Em random art .
+By setting the
+.Cm VisualHostKey
+option to
+.Dq yes ,
+a small ASCII graphic gets displayed on every login to a server, no matter
+if the session itself is interactive or not.
+By learning the pattern a known server produces, a user can easily
+find out that the host key has changed when a completely different pattern
+is displayed.
+Because these patterns are not unambiguous however, a pattern that looks
+similar to the pattern remembered only gives a good probability that the
+host key is the same, not guaranteed proof.
+.Pp
+To get a listing of the fingerprints along with their random art for
+all known hosts, the following command line can be used:
+.Pp
+.Dl $ ssh-keygen -lv -f ~/.ssh/known_hosts
+.Pp

 If the fingerprint is unknown,
 an alternative method of verification is available:
 SSH fingerprints verified by DNS.
 If the fingerprint is unknown,
 an alternative method of verification is available:
 SSH fingerprints verified by DNS.


@@ -1025,8 +1072,7 @@ In this example, we are connecting a client to a server,
 The SSHFP resource records should first be added to the zonefile for
 host.example.com:
 .Bd -literal -offset indent
 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.
+$ ssh-keygen -r host.example.com.

 .Ed
 .Pp
 The output lines will have to be added to the zonefile.
 .Ed
 .Pp
 The output lines will have to be added to the zonefile.


@@ -1062,12 +1108,22 @@ 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
 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:
+with remote network 10.0.99.0/24 using a point-to-point connection
+from 10.1.1.1 to 10.1.1.2,
+provided that the SSH server running on the gateway to the remote network,
+at 192.168.1.15, allows it.
+.Pp
+On the client:

 .Bd -literal -offset indent
 # ssh -f -w 0:1 192.168.1.15 true
 .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
+# ifconfig tun0 10.1.1.1 10.1.1.2 netmask 255.255.255.252
+# route add 10.0.99.0/24 10.1.1.2
+.Ed
+.Pp
+On the server:
+.Bd -literal -offset indent
+# ifconfig tun1 10.1.1.2 10.1.1.1 netmask 255.255.255.252
+# route add 10.0.50.0/24 10.1.1.1

 .Ed
 .Pp
 Client access may be more finely tuned via the
 .Ed
 .Pp
 Client access may be more finely tuned via the


@@ -1075,11 +1131,11 @@ Client access may be more finely tuned via the
 file (see below) and the
 .Cm PermitRootLogin
 server option.
 file (see below) and the
 .Cm PermitRootLogin
 server option.

-The following entry would permit connections on the first
+The following entry would permit connections on

 .Xr tun 4
 .Xr tun 4

-device from user
+device 1 from user

 .Dq jane
 .Dq jane

-and on the second device from user
+and on tun device 2 from user

 .Dq john ,
 if
 .Cm PermitRootLogin
 .Dq john ,
 if
 .Cm PermitRootLogin


@@ -1087,10 +1143,10 @@ is set to
 .Dq forced-commands-only :
 .Bd -literal -offset 2n
 tunnel="1",command="sh /etc/netstart tun1" ssh-rsa ... jane
 .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
+tunnel="2",command="sh /etc/netstart tun2" ssh-rsa ... john

 .Ed
 .Pp
 .Ed
 .Pp

-Since a SSH-based setup entails a fair amount of overhead,
+Since an 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
 it may be more suited to temporary setups,
 such as for wireless VPNs.
 More permanent VPNs are better provided by tools such as


@@ -1178,7 +1234,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
 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.
 on to new connections).
 .It Ev USER
 Set to the name of the user logging in.


@@ -1217,6 +1273,13 @@ This file is used in exactly the same way as
 but allows host-based authentication without permitting login with
 rlogin/rsh.
 .Pp
 but allows host-based authentication without permitting login with
 rlogin/rsh.
 .Pp

+.It ~/.ssh/
+This directory is the default location for all user-specific configuration
+and authentication information.
+There is no general requirement to keep the entire contents of this directory
+secret, but the recommended permissions are read/write/execute for the user,
+and not accessible by others.
+.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
 .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


@@ -1339,15 +1402,71 @@ manual page for more information.
 .Xr ssh-keysign 8 ,
 .Xr sshd 8
 .Rs
 .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
+.Rs
+.%R RFC 4716
+.%T "The Secure Shell (SSH) Public Key File Format"
+.%D 2006
+.Re
+.Rs
+.%T "Hash Visualization: a New Technique to improve Real-World Security"
+.%A A. Perrig
+.%A D. Song
+.%D 1999
+.%O "International Workshop on Cryptographic Techniques and E-Commerce (CrypTEC '99)"

 .Re
 .Sh AUTHORS
 OpenSSH is a derivative of the original and free
 .Re
 .Sh AUTHORS
 OpenSSH is a derivative of the original and free