From 9f04903c50089acde55ef3ea7edd35161c5eac0c Mon Sep 17 00:00:00 2001 From: Ben Lindstrom Date: Fri, 21 Jun 2002 00:59:05 +0000 Subject: - stevesk@cvs.openbsd.org 2002/06/20 19:56:07 [ssh.1 sshd.8] move configuration file options from ssh.1/sshd.8 to ssh_config.5/sshd_config.5; ok deraadt@ millert@ --- ssh_config.5 | 621 +++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 621 insertions(+) create mode 100644 ssh_config.5 (limited to 'ssh_config.5') diff --git a/ssh_config.5 b/ssh_config.5 new file mode 100644 index 000000000..53cb0fe97 --- /dev/null +++ b/ssh_config.5 @@ -0,0 +1,621 @@ +.\" -*- nroff -*- +.\" +.\" Author: Tatu Ylonen +.\" Copyright (c) 1995 Tatu Ylonen , Espoo, Finland +.\" All rights reserved +.\" +.\" As far as I am concerned, the code I have written for this software +.\" can be used freely for any purpose. Any derived versions of this +.\" software must be clearly marked as such, and if the derived work is +.\" incompatible with the protocol description in the RFC file, it must be +.\" called by a name other than "ssh" or "Secure Shell". +.\" +.\" Copyright (c) 1999,2000 Markus Friedl. All rights reserved. +.\" Copyright (c) 1999 Aaron Campbell. All rights reserved. +.\" Copyright (c) 1999 Theo de Raadt. All rights reserved. +.\" +.\" Redistribution and use in source and binary forms, with or without +.\" modification, are permitted provided that the following conditions +.\" are met: +.\" 1. Redistributions of source code must retain the above copyright +.\" notice, this list of conditions and the following disclaimer. +.\" 2. Redistributions in binary form must reproduce the above copyright +.\" notice, this list of conditions and the following disclaimer in the +.\" documentation and/or other materials provided with the distribution. +.\" +.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR ``AS IS'' AND ANY EXPRESS OR +.\" IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES +.\" OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. +.\" IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, +.\" INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT +.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, +.\" DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY +.\" THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT +.\" (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_config.5,v 1.1 2002/06/20 19:56:07 stevesk Exp $ +.Dd September 25, 1999 +.Dt SSH_CONFIG 5 +.Os +.Sh NAME +.Nm ssh_config +.Nd OpenSSH SSH client configuration files +.Sh SYNOPSIS +.Bl -tag -width Ds -compact +.It Pa $HOME/.ssh/config +.It Pa /etc/ssh/ssh_config +.El +.Sh DESCRIPTION +.Nm ssh +obtains configuration data from the following sources in +the following order: +command line options, user's configuration file +.Pq Pa $HOME/.ssh/config , +and system-wide configuration file +.Pq Pa /etc/ssh/ssh_config . +.Pp +For each parameter, the first obtained value +will be used. +The configuration files contain sections bracketed by +.Dq 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 . +Configuration options may be separated by whitespace or +optional whitespace and exactly one +.Ql = ; +the latter format is useful to avoid the need to quote whitespace +when specifying configuration options using the +.Nm ssh , +.Nm scp +and +.Nm sftp +.Fl o +option. +.Pp +The possible +keywords and their meanings are as follows (note that +keywords are case-insensitive and arguments 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 . +This option applies to protocol version 1 only. +.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 no user +is present to supply the password. +The argument must be +.Dq yes +or +.Dq no . +The default is +.Dq no . +.It Cm BindAddress +Specify the interface to transmit from on machines with multiple +interfaces or aliased addresses. +Note that this option does not work if +.Cm UsePrivilegedPort +is set to +.Dq yes . +.It Cm ChallengeResponseAuthentication +Specifies whether to use challenge response authentication. +The argument to this keyword must be +.Dq yes +or +.Dq no . +The default is +.Dq yes . +.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. +The default is +.Dq yes . +.It Cm Cipher +Specifies the cipher to use for encrypting the session +in protocol version 1. +Currently, +.Dq blowfish , +.Dq 3des , +and +.Dq des +are supported. +.Ar des +is only supported in the +.Nm ssh +client for interoperability with legacy protocol 1 implementations +that do not support the +.Ar 3des +cipher. Its use is strongly discouraged due to cryptographic +weaknesses. +The default is +.Dq 3des . +.It Cm Ciphers +Specifies the ciphers allowed for protocol version 2 +in order of preference. +Multiple ciphers must be comma-separated. +The default is +.Pp +.Bd -literal + ``aes128-cbc,3des-cbc,blowfish-cbc,cast128-cbc,arcfour, + aes192-cbc,aes256-cbc'' +.Ed +.It Cm ClearAllForwardings +Specifies that all local, remote and dynamic port forwardings +specified in the configuration files or on the command line be +cleared. This option is primarily useful when used from the +.Nm ssh +command line to clear port forwardings set in +configuration files, and is automatically set by +.Xr scp 1 +and +.Xr sftp 1 . +The argument must be +.Dq yes +or +.Dq no . +The default is +.Dq no . +.It Cm Compression +Specifies whether to use compression. +The argument must be +.Dq yes +or +.Dq no . +The default is +.Dq no . +.It Cm CompressionLevel +Specifies the compression level to use if compression is enabled. +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 +.Xr gzip 1 . +Note that this option applies to protocol version 1 only. +.It Cm ConnectionAttempts +Specifies the number of tries (one per second) to make before exiting. +The argument must be an integer. +This may be useful in scripts if the connection sometimes fails. +The default is 1. +.It Cm DynamicForward +Specifies that a TCP/IP port on the local machine be forwarded +over the secure channel, and the application +protocol is then used to determine where to connect to from the +remote machine. The argument must be a port number. +Currently the SOCKS4 protocol is supported, and +.Nm ssh +will act as a SOCKS4 server. +Multiple forwardings may be specified, and +additional forwardings can be given on the command line. Only +the superuser can forward privileged ports. +.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 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 . +The default is +.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 . +The default is +.Dq no . +.It Cm GatewayPorts +Specifies whether remote hosts are allowed to connect to local +forwarded ports. +By default, +.Nm ssh +binds local port forwardings to the loopback address. This +prevents other remote hosts from connecting to forwarded ports. +.Cm GatewayPorts +can be used to specify that +.Nm ssh +should bind local port forwardings to the wildcard address, +thus allowing remote hosts to connect to forwarded ports. +The argument must be +.Dq yes +or +.Dq no . +The default is +.Dq no . +.It Cm GlobalKnownHostsFile +Specifies a file to use for the global +host key database instead of +.Pa /etc/ssh/ssh_known_hosts . +.It Cm HostbasedAuthentication +Specifies whether to try rhosts based authentication with public key +authentication. +The argument must be +.Dq yes +or +.Dq no . +The default is +.Dq no . +This option applies to protocol version 2 only and +is similar to +.Cm RhostsRSAAuthentication . +.It Cm HostKeyAlgorithms +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 . +.It Cm HostKeyAlias +Specifies an alias that should be used instead of the +real host name when looking up or saving the host key +in the host key database files. +This option is useful for tunneling ssh connections +or for multiple servers running on a single host. +.It Cm HostName +Specifies the real host name to log into. +This can be used to specify nicknames 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 a file from which the user's RSA or DSA authentication identity +is read. The default is +.Pa $HOME/.ssh/identity +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 +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 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. +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 . +.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 the specified host and port from the remote machine. +The first argument must be a port number, and the second must be +.Ar host:port . +IPv6 addresses can be specified with an alternative syntax: +.Ar host/port . +Multiple forwardings may be specified, and additional +forwardings can be given on the command line. +Only the superuser can forward privileged ports. +.It Cm LogLevel +Gives the verbosity level that is used when logging messages from +.Nm ssh . +The possible values are: +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. +The MAC algorithm is used in protocol version 2 +for data integrity protection. +Multiple algorithms must be comma-separated. +The default is +.Dq hmac-md5,hmac-sha1,hmac-ripemd160,hmac-sha1-96,hmac-md5-96 . +.It Cm NoHostAuthenticationForLocalhost +This option can be used if the home directory is shared across machines. +In this case localhost will refer to a different machine on each of +the machines and the user will get many warnings about changed host keys. +However, this option disables host authentication for localhost. +The argument to this keyword must be +.Dq yes +or +.Dq no . +The default is to check the host key for localhost. +.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 PasswordAuthentication +Specifies whether to use password authentication. +The argument to this keyword must be +.Dq yes +or +.Dq no . +The default is +.Dq yes . +.It Cm Port +Specifies the port number to connect on the remote host. +Default is 22. +.It Cm PreferredAuthentications +Specifies the order in which the client should try protocol 2 +authentication methods. This allows a client to prefer one method (e.g. +.Cm keyboard-interactive ) +over another method (e.g. +.Cm password ) +The default for this option is: +.Dq hostbased,publickey,keyboard-interactive,password . +.It Cm Protocol +Specifies the protocol versions +.Nm ssh +should support in order of preference. +The possible values are +.Dq 1 +and +.Dq 2 . +Multiple versions must be comma-separated. +The default is +.Dq 2,1 . +This means that +.Nm ssh +tries version 2 and falls back to version 1 +if version 2 is not available. +.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 +.Pa /bin/sh . +In the command string, +.Ql %h +will be substituted by the host name to +connect and +.Ql %p +by the port. +The command can be basically anything, +and should read from its standard input and write to its standard output. +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). +Note that +.Cm CheckHostIP +is not available for connects with a proxy command. +.Pp +.It Cm PubkeyAuthentication +Specifies whether to try public key authentication. +The argument to this keyword must be +.Dq yes +or +.Dq no . +The default is +.Dq yes . +This option applies to protocol version 2 only. +.It Cm RemoteForward +Specifies that a TCP/IP port on the remote machine be forwarded over +the secure channel to the specified host and port from the local machine. +The first argument must be a port number, and the second must be +.Ar host:port . +IPv6 addresses can be specified with an alternative syntax: +.Ar host/port . +Multiple forwardings may be specified, and additional +forwardings can be given on the command line. +Only the superuser 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. +Most servers do not permit RhostsAuthentication because it +is not secure (see +.Cm RhostsRSAAuthentication ) . +The argument to this keyword must be +.Dq yes +or +.Dq no . +The default is +.Dq no . +This option applies to protocol version 1 only. +.It Cm RhostsRSAAuthentication +Specifies whether to try rhosts based authentication with RSA host +authentication. +The argument must be +.Dq yes +or +.Dq no . +The default is +.Dq no . +This option applies to protocol version 1 only and requires +.Nm ssh +to be setuid root. +.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. +The default is +.Dq yes . +Note that this option applies to protocol version 1 only. +.It Cm SmartcardDevice +Specifies which smartcard device to use. The argument to this keyword is +the device +.Nm ssh +should use to communicate with a smartcard used for storing the user's +private RSA key. By default, no device is specified and smartcard support +is not activated. +.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 to hosts whose host key has changed. +This provides maximum protection against trojan horse attacks, +however, can be annoying when the +.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 +add all new hosts. +If this flag is set to +.Dq no , +.Nm ssh +will automatically add new host keys to the +user known hosts files. +If this flag is set to +.Dq ask , +new host keys +will be added to the user known host files only after the user +has confirmed that is what they really want to do, and +.Nm ssh +will refuse to connect to hosts whose host key has changed. +The host keys of +known hosts will be verified automatically in all cases. +The argument must be +.Dq yes , +.Dq no +or +.Dq ask . +The default is +.Dq ask . +.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 no . +Note that this option must be set to +.Dq yes +if +.Cm RhostsAuthentication +and +.Cm RhostsRSAAuthentication +authentications are needed with older servers. +.It Cm User +Specifies the user to log in as. +This can be useful when a different user name is used on 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 for the user +host key database instead of +.Pa $HOME/.ssh/known_hosts . +.It Cm XAuthLocation +Specifies the location of the +.Xr xauth 1 +program. +The default is +.Pa /usr/X11R6/bin/xauth . +.El +.Sh FILES +.Bl -tag -width Ds +.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 ssh +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 /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. +.El +.Sh AUTHORS +OpenSSH is a derivative of the original and free +ssh 1.2.12 release by Tatu Ylonen. +Aaron Campbell, Bob Beck, Markus Friedl, Niels Provos, +Theo de Raadt and Dug Song +removed many bugs, re-added newer features and +created OpenSSH. +Markus Friedl contributed the support for SSH +protocol versions 1.5 and 2.0. +.Sh SEE ALSO +.Xr ssh 1 -- cgit v1.2.3