document feature-specific user configuration files (config.gssapi, config.krb)

and Gssapi configuration options

diff --git a/openssh/ssh.1 b/openssh/ssh.1
index ad3c96023de221c359fab3c4bb7b42a3c236cf83..71a3f364004d15c7d69c56c0b0e7de891da8747a 100644 (file)
--- a/openssh/ssh.1
+++ b/openssh/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.141 2001/11/08 17:49:53 markus Exp $
+.\" $OpenBSD: ssh.1,v 1.151 2002/05/06 23:34:33 millert Exp $
 .Dd September 25, 1999
 .Dt SSH 1
 .Os
@@ -126,7 +126,7 @@ or
 .Pa /etc/shosts.equiv ,
 and if additionally the server can verify the client's
 host key (see
-.Pa /etc/ssh_known_hosts
+.Pa /etc/ssh/ssh_known_hosts
 and
 .Pa $HOME/.ssh/known_hosts
 in the
@@ -207,8 +207,8 @@ the password cannot be seen by someone listening on the network.
 .Pp
 .Ss SSH protocol version 2
 .Pp
-When a user connects using the protocol version 2
-different authentication methods are available.
+When a user connects using protocol version 2
+similar authentication methods are available.
 Using the default values for
 .Cm PreferredAuthentications ,
 the client will try to authenticate first using the hostbased method;
@@ -297,6 +297,12 @@ Background ssh at logout when waiting for forwarded connection / X11 sessions
 to terminate
 .It Cm ~?
 Display a list of escape characters
+.It Cm ~C
+Open command line (only useful for adding port forwardings using the
+.Fl L
+and
+.Fl R
+options)
 .It Cm ~R
 Request rekeying of the connection (only useful for SSH protocol version 2
 and if the peer supports it)
@@ -365,7 +371,7 @@ Host keys are stored in
 .Pa $HOME/.ssh/known_hosts
 in the user's home directory.
 Additionally, the file
-.Pa /etc/ssh_known_hosts
+.Pa /etc/ssh/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
@@ -443,11 +449,15 @@ something like
 .It Fl g
 Allows remote hosts to connect to local forwarded ports.
 .It Fl i Ar identity_file
-Selects the file from which the identity (private key) for
+Selects a file from which the identity (private key) for
 RSA or DSA authentication is read.
-Default is
+The default is
 .Pa $HOME/.ssh/identity
-in the user's home directory.
+for protocol version 1, and
+.Pa $HOME/.ssh/id_rsa
+and
+.Pa $HOME/.ssh/id_dsa
+for protocol version 2.
 Identity files may also be specified on
 a per-host basis in the configuration file.
 It is possible to have multiple
@@ -517,7 +527,6 @@ for older servers.
 .It Fl q
 Quiet mode.
 Causes all warning and diagnostic messages to be suppressed.
-Only fatal errors are displayed.
 .It Fl s
 May be used to request invocation of a subsystem on the remote system. Subsystems are a feature of the SSH2 protocol which facilitate the use
 of SSH as a secure transport for other applications (eg. sftp). The
@@ -570,7 +579,7 @@ option below.
 Specifies an alternative per-user configuration file.
 If a configuration file is given on the command line,
 the system-wide configuration file
-.Pq Pa /etc/ssh_config
+.Pq Pa /etc/ssh/ssh_config
 will be ignored.
 The default for the per-user configuration file is
 .Pa $HOME/.ssh/config .
@@ -642,10 +651,31 @@ to use IPv6 addresses only.
 .Nm
 obtains configuration data from the following sources in
 the following order:
-command line options, user's configuration file
+command line options, 
+feature-specific user configuration file(s) (see below),
+user's configuration file
 .Pq Pa $HOME/.ssh/config ,
 and system-wide configuration file
-.Pq Pa /etc/ssh_config .
+.Pq Pa /etc/ssh/ssh_config .
+For compatibility with other
+.Nm
+versions, the following feature-specific user configuration files
+will be processed after the command line options but before the user's 
+main configuration file, so options that other
+.Nm
+versions may not support don't need to go in the main configuration file:
+.Bl -tag -width Ds
+.It Pa $HOME/.ssh/config.gssapi
+Read if GSSAPI authentication is supported.  This is a good place for
+the GssapiAuthentication and GssapiDelegateCredentials options.
+.It Pa $HOME/.ssh/config.krb
+Read if Kerberos authentication is supported.  This is a good place
+for the KerberosAuthentication and KerberosTgtPassing options.
+.It Pa $HOME/.ssh/config.afs
+Read if AFS token passing is supported.  This is a good place for the
+AfsTokenPassing option.
+.El
+.Pp
 For each parameter, the first obtained value
 will be used.
 The configuration files contain sections bracketed by
@@ -883,7 +913,18 @@ The default is
 .It Cm GlobalKnownHostsFile
 Specifies a file to use for the global
 host key database instead of
-.Pa /etc/ssh_known_hosts .
+.Pa /etc/ssh/ssh_known_hosts .
+.It Cm GssapiAuthentication
+Specifies whether authentication based on GSSAPI may be used, either using
+the result of a successful key exchange, or using GSSAPI user
+authentication.
+The default is 
+.Dq yes .
+.It Cm GssapiDelegateCredentials
+Specifies whether GSSAPI credentials will be delegated (forwarded) to
+the server.
+The default is
+.Dq yes .
 .It Cm HostbasedAuthentication
 Specifies whether to try rhosts based authentication with public key
 authentication.
@@ -900,7 +941,7 @@ is similar to
 Specifies the protocol version 2 host key algorithms
 that the client wants to use in order of preference.
 The default for this option is:
-.Dq ssh-rsa,ssh-dss
+.Dq ssh-rsa,ssh-dss .
 .It Cm HostKeyAlias
 Specifies an alias that should be used instead of the
 real host name when looking up or saving the host key
@@ -915,10 +956,14 @@ 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 or DSA authentication identity
-is read (default
+Specifies a file from which the user's RSA or DSA authentication identity
+is read. The default is
 .Pa $HOME/.ssh/identity
-in the user's home directory).
+for protocol version 1, and
+.Pa $HOME/.ssh/id_rsa
+and
+.Pa $HOME/.ssh/id_dsa
+for protocol version 2.
 Additionally, any identities represented by the authentication agent
 will be used for authentication.
 The file name may use the tilde
@@ -927,7 +972,7 @@ 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
+Specifies whether the system should send TCP 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.
@@ -942,8 +987,7 @@ 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.
+.Dq no .
 .It Cm KerberosAuthentication
 Specifies whether Kerberos authentication will be used.
 The argument to this keyword must be
@@ -971,8 +1015,9 @@ Only the superuser can forward privileged ports.
 Gives the verbosity level that is used when logging messages from
 .Nm ssh .
 The possible values are:
-QUIET, FATAL, ERROR, INFO, VERBOSE and DEBUG.
-The default is INFO.
+QUIET, FATAL, ERROR, INFO, VERBOSE, DEBUG, DEBUG1, DEBUG2 and DEBUG3.
+The default is INFO.  DEBUG and DEBUG1 are equivalent.  DEBUG2
+and DEBUG3 each specify higher levels of verbose output.
 .It Cm MACs
 Specifies the MAC (message authentication code) algorithms
 in order of preference.
@@ -1013,7 +1058,7 @@ authentication methods. This allows a client to prefer one method (e.g.
 over another method (e.g.
 .Cm password )
 The default for this option is:
-.Dq hostbased,publickey,keyboard-interactive,password
+.Dq hostbased,publickey,keyboard-interactive,password .
 .It Cm Protocol
 Specifies the protocol versions
 .Nm
@@ -1137,7 +1182,7 @@ will never automatically add host keys to the
 file, and refuses to connect to hosts whose host key has changed.
 This provides maximum protection against trojan horse attacks,
 however, can be annoying when the
-.Pa /etc/ssh_known_hosts
+.Pa /etc/ssh/ssh_known_hosts
 file is poorly maintained, or connections to new hosts are
 frequently made.
 This option forces the user to manually
@@ -1305,7 +1350,7 @@ to the environment.
 .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 .
+.Pa /etc/ssh/ssh_known_hosts .
 See
 .Xr sshd 8 .
 .It Pa $HOME/.ssh/identity, $HOME/.ssh/id_dsa, $HOME/.ssh/id_rsa
@@ -1360,7 +1405,7 @@ In the simplest form the format is the same as the .pub
 identity files.
 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
+.It Pa /etc/ssh/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
@@ -1383,13 +1428,13 @@ to verify the client host when logging in; other names are needed because
 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
+.It Pa /etc/ssh/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 /etc/ssh_host_key, /etc/ssh_host_dsa_key, /etc/ssh_host_rsa_key
+.It Pa /etc/ssh/ssh_host_key, /etc/ssh/ssh_host_dsa_key, /etc/ssh/ssh_host_rsa_key
 These three files contain the private parts of the host keys
 and are used for
 .Cm RhostsRSAAuthentication
@@ -1424,7 +1469,7 @@ Note that by default
 will be installed so that it requires successful RSA host
 authentication before permitting \s+2.\s0rhosts authentication.
 If the server machine does not have the client's host key in
-.Pa /etc/ssh_known_hosts ,
+.Pa /etc/ssh/ssh_known_hosts ,
 it can be stored in
 .Pa $HOME/.ssh/known_hosts .
 The easiest way to do this is to
@@ -1438,7 +1483,7 @@ The purpose for
 having this file is to be able to use rhosts authentication with
 .Nm
 without permitting login with
-.Xr rlogin 1
+.Nm rlogin
 or
 .Xr rsh 1 .
 .It Pa /etc/hosts.equiv
@@ -1461,7 +1506,7 @@ This file is processed exactly as
 This file may be useful to permit logins using
 .Nm
 but not using rsh/rlogin.
-.It Pa /etc/sshrc
+.It Pa /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.
@@ -1481,6 +1526,10 @@ Contains additional definitions for environment variables, see section
 .Sx ENVIRONMENT
 above.
 .El
+.Sh DIAGNOSTICS
+.Nm
+exits with the exit status of the remote command or with 255
+if an error occurred.
 .Sh AUTHORS
 OpenSSH is a derivative of the original and free
 ssh 1.2.12 release by Tatu Ylonen.
@@ -1491,7 +1540,6 @@ created OpenSSH.
 Markus Friedl contributed the support for SSH
 protocol versions 1.5 and 2.0.
 .Sh SEE ALSO
-.Xr rlogin 1 ,
 .Xr rsh 1 ,
 .Xr scp 1 ,
 .Xr sftp 1 ,
@@ -1507,7 +1555,7 @@ protocol versions 1.5 and 2.0.
 .%A T. Rinne
 .%A S. Lehtinen
 .%T "SSH Protocol Architecture"
-.%N draft-ietf-secsh-architecture-09.txt
-.%D July 2001
+.%N draft-ietf-secsh-architecture-12.txt
+.%D January 2002
 .%O work in progress material
 .Re