.\" -*- nroff -*- .\" .\" ssh2_config.5 .\" .\" Author: Tatu Ylonen .\" Markku-Juhani Saarinen .\" Sami Lehtinen .\" Timo J. Rinne .\" .\" Copyright (c) 1998-2002 SSH Communications Security, Finland .\" All rights reserved .\" .TH SSH2_CONFIG 5 "May 16, 2002" "SSH2" "SSH2" .SH NAME ssh2_config \- format of configuration file for ssh2 .SH CONFIGURATION FILES \fBSsh2\fR obtains all configuration data from the following sources (in this order): the system's global configuration file (typically \fI/etc/ssh2/ssh2_config\fR), the user's configuration file (\fI\&$HOME/\s+2.\s0ssh2/ssh2_config\fR), and the command-line options. For each parameter, the last obtained value will be effective. A configuration file can begin with "metaconfig" information, that is, information configuring the configuration language itself. If the configuration file starts with a line matching the following egrep style regex #.*VERSION[ \\t\\f]+[0-9]+.[0-9]+ it is interpreted as the version of the configuration style. If this kind of line is not found, the version is considered to be "1.0". The version string can be followed by one or more metaconfiguration parameters. The lines have to start with '#', and they have to match the following egrep style regex #[# \\t]+[A-Z0-9]+[ \\t]+.* Parsing of metaconfig directives stops with the first non-recognized line. Version 1.1 and newer recognize the following parameter: .TP .B REGEX-SYNTAX This denotes the regex syntax used to parse the configuration file in question. The regex syntax is used in parsing the labels, lists, and so on, and when matching stuff with regex patterns specified in the configuration file. The value can be \fBegrep\fR, \fBssh\fR, \fBzsh_fileglob\fR or \fBtraditional\fR (the arguments are not case-sensitive). \fBzsh_fileglob\fR and \fBtraditional\fR are synonymous. .LP The configuration file has the following format: .IP \'expression' denotes the start of a per-host configuration block, where 'expression' is an arbitrary string which distinguishes this block from others. The 'expression' can contain wildcards. The \'expression' will be compared with the hostname obtained from the command line, and if it matches, the block will be evaluated. Evaluation stops at the next 'expression:' statement. If more than one match is found, all will be evaluated and the last obtained values for parameters will be effective. Note that the \'expression' does not have to be a real hostname, as long as the \'expression' block contains a "\fBHost\fR" configuration parameter, where the real hostname to connect is defined. .IP Empty lines and lines starting with \'#\' are ignored as comments. .IP Otherwise a line is of the format '\fIkeyword\fR \fIarguments\fR'. Note that it is possible to enclose arguments in quotes, and use the standard C convention. The possible keywords and their meanings are as follows (note that the configuration files are case-sensitive but the keywords are not case-sensitive): .ne 3 .de YN "\fByes\fR" or "\fBno\fR". .. .TP .B AllowedAuthentications This keyword specifies the authentication methods that are allowed. This is a comma-separated list currently consisting of the following words: .BR keyboard-interactive , .BR password , .BR publickey , .BR pam-1@ssh.com , .BR kerberos-2@ssh.com , .BR kerberos-tgt-2@ssh.com , .BR securid-1@ssh.com , and .BR hostbased . Each specifies an authentication method. The default is \'\fBpublickey, keyboard-interactive, password\fR'. The authentication methods are tried in the order in which they are specified with this configuration parameter. This means that the least interactive methods should be placed first in this list, for example '\fBhostbased, publickey, keyboard-interactive\fR' (because public-key authentication can be automated by the user, with \fBssh-agent\fR). .ne 3 .TP .B AuthenticationSuccessMsg Specifies whether to print "Authentication successful." after authentication has completed successfully. This is mainly to prevent malicious servers from getting information from the user by displaying additional password or passphrase prompts. The argument must be .YN The default is "\fByes\fR". .ne 3 .TP .B BatchMode If set to "\fByes\fR", .B ssh2 disables password/passhphrase querying. This is useful in scripts and other batch jobs where there is no user to supply the password. If the "\fBStrictHostKeyChecking\fR" parameter is set to "\fBask\fR", .B ssh2 assumes a "\fBno\fR" answer to queries (this is because ssh does not even try to get user input when invoked with "\fBBatchMode yes\fR"). The argument must be .YN The default is "\fBno\fR". .ne 3 .TP .B Cert.RSA.Compat.HashScheme Older SSH Secure Shell clients and servers used hashes in an incoherent manner (sometimes MD5, sometimes SHA-1). With this option, you can set what hash is used. Valid values are "\fBmd5\fR" and "\fBsha1\fR". The default is "\fBmd5\fR" (works in most cases). .ne 3 .TP .B Ciphers Specifies the ciphers to use for encrypting the session. Currently, .\" XXX Could this be made dist-dependent ? .IR aes , .IR blowfish , .IR twofish , .IR arcfour , .IR cast , .IR 3des , and .IR des are supported. Multiple ciphers can be specified as a comma-separated list. Special values to this option are .IR Any , .IR AnyStd that allows only standard (see below) ciphers (and '\fInone\fR'), and .IR AnyCipher that allows either any available cipher or excludes non-encrypting cipher mode .IR none but allows all others. .IR AnyStdCipher is the same as \fIAnyCipher\fR above, but includes only those ciphers mentioned in the IETF-SecSH-draft (excluding '\fBnone\fR'). \fIAnyStdCipher\fR is the default value. .ne 3 .TP .B ClearAllForwardings Specifies whether to clear all remote and local forwarded ports defined so far. The argument must be .YN Note that \fBscp\fR always automatically clears all forwarded ports. .ne 3 .TP .B Compression Specifies whether to use compression. The argument must be .YN .ne 3 .TP .B DebugLogFile Write debug messages to specified file. (Remember to enable debugging.) .ne 3 .TP .B DefaultDomain This option is only useful if set in the global configuration file. This is used by .B ssh2 and .B ssh-signer2 to find out the system name, if only the base part of the system name is available by normal means (those used by, for example, .BR hostname (1)). This is appended to the found system name, if the system name returned does not contain a dot ('.'). .ne 3 .TP .B DisableVersionFallback Whether to disable fallback compatibility code for older, or otherwise incompatible versions of software. Don't disable unless you know what you're doing. The argument must be .YN The default is "\fBno\fR". .ne 3 .TP .B DontReadStdin Redirect input from \fI/dev/null\fR, that is, do not read stdin. The argument must be .YN The default is "\fBno\fR". .ne 3 .TP .B EkInitString Specifies the initialization string for the external key provider for accessing external keys for user authentication. See .BR ssh-externalkeys (5) for further information. This feature is only available when external key support is included in the software. .ne 3 .TP .B EkProvider Specifies the external key provider for accessing external keys for user authentication. See .BR ssh-externalkeys (5) for further information. This feature is only available when external key support is included in the software. .ne 3 .TP .B EscapeChar Sets the escape character (default: ~). The escape character can also be set on the command line. The argument should be a single character, \'^\' followed by a letter, or "\fBnone\fR" to disable the escape character entirely (making the connection transparent for binary data). .ne 3 .TP .B ForcePTTYAllocation Allocate a tty even if a command is given. The argument must be .YN The default is "\fBno\fR". .ne 3 .TP .B ForwardAgent Specifies whether the connection to the authentication agent (if any) will be forwarded to the remote machine. The argument must be .YN The default is "\fByes\fR". .ne 3 .TP .B ForwardX11 Specifies whether X11 connections will be automatically redirected over the secure channel and DISPLAY set. The argument must be .YN The default is "\fByes\fR". .ne 3 .TP .B GatewayPorts Specifies that also remote hosts may connect to locally forwarded ports. The argument must be .YN The default is "\fBno\fR". .ne 3 .TP .B GoBackground Requests .B ssh2 to go to the background after authentication is done and the forwardings have been established. This is useful if .B ssh2 is going to ask for passwords or passphrases but the user wants it in the background. The argument must be "\fByes\fR", "\fBno\fR" or "\fBoneshot\fR". With "\fBoneshot\fR", .B ssh2 behaves the same way as with '\fB\-f\fIo\fR' command-line arguments. The default is "\fBno\fR". .ne 3 .TP .B Host The real host name to log into. With 'expression' above, this can be used to specify nicknames or abbreviations for hosts. The default is the name given on the command line. Numeric IP addresses are also permitted (both on the command line and in HostName specifications). .ne 3 .TP .B IdentityFile The name of the user's identification file. .ne 3 .TP .B KeepAlive Specifies whether the system should send 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 this annoying. The default is "\fByes\fR" (to send keepalives), and the client will notice if the network goes down or the remote host dies. This is important when using scripts, and many users want it. To disable keepalives, the value should be set to "\fBno\fR" in both the server and the client configuration files. .ne 3 .TP .B LocalForward The argument format is .IR port:host:hostport . See "\fB-L\fR" in .BR ssh2 (1) for more detailed information on forward definitions. .ne 3 .TP .B MACs Specifies the MAC (Message Authentication Code) algorithm to use for data integrity verification. Currently, .\" XXX Could this be made dist-dependent ? .IR hmac-sha1 , .IR hmac-sha1-96 , .IR hmac-md5 , .IR hmac-md5-96 , .IR hmac-ripemd160 , and .I hmac-ripemd160-96 are supported, of which .IR hmac-sha1 , .IR hmac-sha1-96 , .IR hmac-md5 , and .I hmac-md5-96 are included in all distributions. Multiple MACs can be specified as a comma-separated list. Special values for this option are .IR Any, .IR AnyStd, .IR none, .IR AnyMac, and \fIAnyStdMac\fR. \fIAny\fR allows all MACs including \fInone\fR; \fIAnyStd\fR allows only those mentioned in the IETF-SecSH draft and \fInone\fR; \fInone\fR forbids any use of MACs; \fIAnyMac\fR and \fIAnyStdMac\fR are analogous to the first two cases but exclude \fInone\fR. \fIAnyStdMac\fR is the default. .ne 3 .TP .B NoDelay If "\fByes\fR", enable socket option TCP_NODELAY. The argument must be .YN The default is "\fBno\fR". .ne 3 .TP .B NumberofPasswordPrompts Specifies the number of password prompts before giving up. The argument must be an integer. Note that the server also limits the number of attempts, so setting this value larger than the server's value does not have any effect. The default value is three (3). .ne 3 .TP .B PasswordPrompt Sets the password prompt that the user sees when connecting to a host. Variables '\fB%U\fR' and '\fB%H\fR' can be used to give the user's login name and host, respectively. .ne 3 .TP .B Port Specifies the port number to connect on the remote host. The default is 22. .ne 3 .TP .B QuietMode All warnings and diagnostic messages are suppressed. Only fatal errors are displayed. The argument must be .YN The default is "\fBno\fR". .ne 3 .TP .B RandomSeedFile The name of the user's random-seed file. .ne 3 .TP .B RekeyIntervalSeconds The number of seconds after which the key exchange is done again. The default is 3600 seconds (1 hour). Value '0' turns rekey requests off. This does not prevent the server from requesting rekeys. Other servers may not have rekey capabilities implemented correctly, and your connection may be cut off if you are connecting to a server other than \fBsshd2\fR. (The server may also crash, but this is not the fault of \fBssh2\fR.) .ne 3 .TP .B RemoteForward The argument format is .IR port:host:hostport . See "\fB-R\fR" in .BR ssh2 (1) for more detailed information on forward definitions. .ne 3 .TP .B SetRemoteEnv Specify an environment variable to set in the server before executing a shell or command. The value should be of form \'\fBVAR=val\fR'. '\fBval\fR' can be empty. You can specify multiple variables by using multiple options. Setting the variable may fail on the server end, e.g. because of policy decisions (see .BR SettableEnvironmentVars in \fBsshd2_config\fR(5)). NOTE: this feature is not implemented in .B sshd2 versions 3.0.x and earlier. .ne 3 .TP .B Ssh1AgentCompatibility Specifies whether to also forward an SSH1 agent connection. Legal values for this option are "\fBnone\fR", "\fBtraditional\fR", and "\fBssh2\fR". With value "\fBnone\fR" (default), the SSH1 agent connection is not forwarded at all. With value "\fBtraditional\fR", SSH1 agent connection is forwarded transparently like in SSH1. Value "\fBtraditional\fR" can always be used but it constitutes a security risk, because the agent does not get the information about the forwarding path. Value "\fBssh2\fR" makes SSH1 agent forwarding similar to SSH2 agent forwarding and with this mode agent gets the information about the agent forwarding path. Note that value "\fBssh2\fR" can only be used if you use \fBssh-agent2\fR in SSH1 compatibility mode. .ne 3 .TP .B Ssh1Compatibility Specifies whether to use SSH1 compatibility code. With this option, .B ssh1 is executed when the server supports only SSH 1.x protocols. The argument must be .YN .ne 3 .TP .B Ssh1InternalEmulation Specifies whether to use SSH1 internal emulation code. With this option, .B ssh2 can also communicate with ssh1 servers, without using an external .B ssh1 program. The argument must be .YN .ne 3 .TP .B Ssh1MaskPasswordLength Specifies whether to send \fBSSH_MSG_IGNORE\fR packets to mask the password length (otherwise, it is very easy to get, as the SSH1 protocol does not encrypt the length fields of packets). The argument must be .YN The default is "\fByes\fR". .ne 3 .TP .B Ssh1Path Specifies the path to .B ssh1 client, which is executed if the server supports only SSH 1.x protocols. The arguments for .B ssh2 are passed to the .B ssh1 client. .ne 3 .TP .B SocksServer Overrides the value of \fBSSH_SOCKS_SERVER\fR environment variable. The argument syntax is described in the \fBssh2\fR(1) manpage. .ne 3 .TP .B StrictHostKeyChecking If this flag is set to "\fByes\fR", .B ssh2 will never automatically add host keys to the .I $HOME/.ssh2/hostkeys directory, and refuses to connect to hosts whose key has changed. This provides maximum protection against man-in-the-middle attacks. However, it can be somewhat annoying if you frequently connect new hosts. The argument must be "\fByes\fR", "\fBno\fR", or "\fBask\fR". The default is "\fBask\fR", which means that new hosts will automatically be added to the known host files after you have acknowledged this. If a host key has changed, you will be asked whether you want to accept the new host key as the only valid one. If set to "\fBno\fR", the new host will automatically be added to \fI$HOME/.ssh2/hostkeys\fR. "\fByes\fR" forces the user to add all new hosts manually. The host keys of known hosts will be verified automatically in any case. .ne 3 .TP .B TrustX11Applications Specifies whether the Xserver should treat X11 client applications as trusted (with forwarding X11). Treating X11 applications as "untrusted" avoids the problem that logging into a compromised host allows applications on that host to "sniff" any input operations (e.g. key strokes, mouse movements, drag and drop and clipboard data transfers etc.) via the forwarded X11 connection (unless the security policy for this X server allows these operations for untrusted clients). You should only need this option if the X client program you are running needs exceptional privileges for the Xserver. Note that ssh1 internal emulation mode does not support the SECURITY extension. The argument must be .YN The default is "\fBno\fR". .ne 3 .TP .B User Specifies who the user will log in as. This can be useful if you have a different user name in different machines. This saves the trouble of having to remember to specify the user name on the command line. .ne 3 .TP .B UseSocks5 Use SOCKS5 instead of SOCKS4 when connecting to remote host. Note that you have to set .B SocksServer to a meaningful value. The argument must be .YN Default is "\fBno\fR" (i.e. use SOCKS4). .ne 3 .TP .B VerboseMode Causes \fBssh2\fR to print debugging messages about its progress. This is helpful when debugging connection, authentication, and configuration problems. The argument must be .YN The default is "\fBno\fR". .ne 3 .TP .B XauthPath Specifies where to find the "xauth" program. This option is mostly useful if you are using binaries and your X11 programs are installed to somewhere that .B ssh2 does not know about. The default is set by the .B configure script. .ne 3 .SH AUTHORS .LP SSH Communications Security Corp. For more information, see http://www.ssh.com. .SH SEE ALSO .BR ssh2 (1)