SSH

sshd2_config

sshd2_config — configuration file format for sshd2 on z/OS

Configuration File

sshd2 reads configuration data from /opt/tectia/etc/sshd2_config (or the file specified with -f on the command line). The file contains keyword-value pairs, one per line.

A configuration file can begin with "metaconfiguration" information, that is, information configuring the configuration language itself.

If the configuration file starts with a line matching the following egrep-style regular expression:

#.*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 regular expression:

#[# \t]+[A-Z0-9]+[ \t]+.*

The parsing of metaconfiguration directives stops with the first non-recognized line.

Version 1.1 and later recognize the following parameter:

REGEX-SYNTAX

This denotes the regex (regular expression) 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 something with the regex patterns specified in the configuration file.

The value can be egrep, ssh, zsh_fileglob or traditional (the arguments are not case-sensitive). zsh_fileglob and traditional are synonymous.

Subconfiguration files can be specified in the main configuration file, see HostSpecificConfig and UserSpecificConfig.

[Note]Note

If changes are made in the main configuration file, sshd2 will have to be restarted as instructed in Restarting and Stopping sshd2.

In the configuration file, empty lines and lines starting with '#' are ignored as comments.

Otherwise a line is of the format 'keyword arguments'. Note that it is possible to enclose arguments in quotes, and use the standard C convention.

[Note]Note

The keywords are not case-sensitive but the arguments are case-sensitive.

The possible keywords and their meanings are as follows :

AddressFamily

This keyword specifies the TCP/IP address families that sshd2 should use when listening for SSH connections and connecting to tunneled ports. The value may be inet for IPv4, inet6 for IPv6, or any, which means that sshd2 will listen on both protocols and connect to an IPv4 or IPv6 port, whichever it finds first. The default value is inet.

AllowAgentForwarding or ForwardAgent

Specifies whether agent forwarding is permitted. This parameter is implemented mainly for completeness. Usually, you should allow users to freely forward agent connections. The argument must be yes or no. The default is yes.

AllowedAuthentications

This keyword specifies the authentication methods that are allowed. Known authentication methods are: keyboard-interactive, password, publickey, and hostbased. The default is "publickey,password". The order of the listed authentication methods is important, as the first method will be used that matches the methods the client is proposing.

With RequiredAuthentications, the system administrator can force the users to complete several authentications before they are considered authenticated.

AllowGroups

This keyword can be followed by any number of group name patterns, separated by commas. If specified, login is allowed only if one of the groups the user belongs to matches one of the patterns. Patterns are matched using the egrep syntax (see sshregex(1)), or the syntax specified in the metaconfiguration header of the configuration file. You can use the comma character (,) in the patterns by escaping it with backslash (\). By default, all groups are allowed to log in.

AllowHosts

This keyword can be followed by any number of host name patterns, separated by commas. If specified, login is allowed only from hosts whose name matches one of the patterns. Patterns are matched using the egrep syntax (see sshregex(1)), or the syntax specified in the metaconfiguration section of the configuration file. If you want the pattern to be matched with the host's IP address only (ignoring the canonical host name), prefix your pattern with "\i". You can also use subnet masks (e.g 127.0.0.0/8) by prefixing the pattern with "\m". DNS is used to map the client's host name into a canonical host name. If the name cannot be mapped, the IP address is used as the host name. By default, all hosts are allowed to connect.

AllowSHosts

This keyword can be followed by any number of host name patterns, separated by commas, same as the option AllowHosts. The entries in .shosts, .rhosts, /etc/hosts.equiv and /etc/shosts.equiv are ignored if they do not match one of the patterns given here (if there are any).

AllowTcpForwarding

Specifies whether TCP forwarding is permitted.

[Note]Note

Disabling TCP forwarding does not improve security at all unless you deny the user shell access at the same time (see ssh-dummy-shell(1)): users that have a shell can always install their own forwarders.

The argument must be yes or no. The default is yes.

AllowTcpForwardingForGroups

The syntax is the same as in AllowGroups, but instead of login, this controls the ability to forward ports in remote or local forwarding. See the security note under option AllowTcpForwarding.

AllowTcpForwardingForUsers

The syntax is the same as in AllowUsers, but instead of login, this controls the ability to forward ports in remote or local forwarding. See the security note under option AllowTcpForwarding.

AllowUsers

This option can be followed by any number of patterns of the form user or user@host, separated by commas. The details explained under option AllowHosts apply accordingly. By default, all users are allowed to log in.

Note that all the other login authentication steps must still be successfully completed. AllowUsers and DenyUsers are additional restrictions.

AuthHostbased.Cert.Required

This keyword specifies whether the client must present a host certificate during user authentication. If this option is set to yes, also the AllowedAuthentications keyword must contain the value hostbased. If the server does not receive a certificate, the authentication fails. The argument must be yes or no. The default is no.

AuthHostbased.Cert.ValidationMethods

This keyword specifies the method used for certificate validation during host-based user authentication. Its value can be tectia or saf, or both (saf,tectia). The default is tectia.

If saf is specified, RACF/SAF is used for validating client host certificates. The host certificates must exist in a trusted key ring defined by the KnownHostsEkProvider keyword. Note that when only SAF validation is used, the certificate validity period and revocation status are not checked.

If tectia is specified (or the keyword is missing from the configuration), the Tectia Certificate Validator (ssh-certd) is used for validating client host certificates. The host certificates must be issued by a trusted certification authority defined in the HostCA, HostCANoCRLs, HostCAEkProvider, or HostCAEkProviderNoCRLs keyword of ssh_certd_config.

If both values are specified (saf,tectia), the RACF/SAF validation is performed first and after that the Tectia validation. The host certificates must exist in a trusted key ring defined by the KnownHostsEkProvider keyword. Also the CA certificate of the issuing certification authority must exist in a trusted key ring defined by the HostCAEkProvider or HostCAEkProviderNoCRLs keyword of ssh_certd_config.

AuthInteractiveFailureTimeout

Specifies the delay in seconds of the server after a failed attempt to log in using keyboard-interactive and password authentication. The default is 2.

AuthKbdInt.NumOptional

Specifies how many optional submethods must be passed before the authentication is considered a success (note that all required submethods must always be passed). See AuthKbdInt.Optional for specifying optional submethods, and AuthKbdInt.Required for required submethods. The default is 0, although if no required submethods are specified, the client must always pass at least one optional submethod.

AuthKbdInt.Optional

Specifies the optional submethods keyboard-interactive will use. Currently only the password and plugin submethods are supported on z/OS. AuthKbdInt.NumOptional specifies how many optional submethods must be passed. The keyboard-interactive authentication method is considered a success when the specified number of optional submethods and all required submethods are passed. The plugin submethod is special. It can be used if a system administrator wants to create a new authentication method. See also AuthKbdInt.NumOptional and AuthKbdInt.Required.

AuthKbdInt.Plugin

Specify this to point to a program that is used by the plugin submethod in keyboard-interactive. sshd2 converses with this program using a line-based protocol, so it is easy to implement it, for example as a shell script. If the plugin submethod is used, and this is not set, or the specified program does not exist or cannot be run, the submethod will fail, which may cause the whole user authentication to fail. This is not set by default. More information about the protocol can be found in the distribution package. RFC.kbdint_plugin_protocol has a description of the protocol used and an example script is called kbdint_plugin_example.sh. Note that the program is run with the privileges of the sshd2 process, typically root, so be careful.

AuthKbdInt.Required

Specifies the required submethods that must be passed before the keyboard-interactive authentication method can succeed. See AuthKbdInt.Optional.

AuthKbdInt.Retries

Specifies how many times the user can retry keyboard-interactive. The default is 3.

AuthorizationEkProvider

This keyword specifies the external key provider for accessing external public keys and certificates used for user public-key authentication. The value is of the format "provider:initstring". Currently, the only valid value for provider on z/OS is zos-saf. For the format of the initstring, see ssh-externalkeys(5).

AuthorizationEkInitStringMapper

This keyword specifies a path to an external program (for example, "/path/to/mapper.sh") that can be used for generating the initialization string used in public-key authentication with external keys. The usage of the mapper program should be the following:

mapper.sh username "initstring"

username is the name of the user found in the certificate, and initstring is the initialization string as it is given in the AuthorizationEkProvider keyword. The program should print the modified initialization string into standard output.

AuthorizationEkInitStringMapperTimeout

This keyword specifies a timeout (in seconds) for the AuthorizationEkInitStringMapper. If the server is unable to read the full output from the mapper in the given period, the operation will fail and the mapper program will be terminated. The default timeout is 10 seconds.

AuthorizationFile

Specifies the name of the user's authorization file. The default is $HOME/.ssh2/authorization.

AuthorizedKeysFile

Specifies the name of the user's authorized keys file. This is given as a pattern string which is expanded by sshd2.

%D is the user's home directory,
%U is the user's login name,
%IU is the user's user ID (uid),
%IG is the user's group ID (gid).

The file is a legacy-format file containing multiple public keys so that each line holds a single public key. Keys are in the ssh1/openssh public key format.

This option is disabled by default.

The public-key option from="host" is equivalent to allow-from="host" and from="!host" is equivalent to deny-from="host". Also the $SSH_ORIGINAL_COMMAND is equivalent to $SSH2_ORIGINAL_COMMAND. Note that the public-key option permitopen="host:port" is not supported, please see the ForwardACL configuration option to achieve a similar setup.

AuthPassword.ChangePlugin

Set this to the path of the password change plug-in, typically ssh-passwd-plugin (if you have the binary packages or you have configured the source with --with-passwd-plugin). This allows the password to be changed during the authentication phase, instead of using a system's passwd command to do it. This replaces the actual session, requiring the user to log in again. This option is also used by the password submethod of keyboard-interactive. By default this is not set.

AuthPublicKey.Algorithms

Specifies the public key signature algorithms to be used in client authentication.

The supported algorithms are ssh-dss, ssh-dss-sha224@ssh.com, ssh-dss-sha256@ssh.com, ssh-dss-sha384@ssh.com, ssh-dss-sha512@ssh.com, x509v3-sign-dss, x509v3-sign-dss-sha224@ssh.com, x509v3-sign-dss-sha256@ssh.com, x509v3-sign-dss-sha384@ssh.com, x509v3-sign-dss-sha512@ssh.com, ssh-rsa, ssh-rsa-sha224@ssh.com, ssh-rsa-sha256@ssh.com, ssh-rsa-sha384@ssh.com, ssh-rsa-sha512@ssh.com, x509v3-sign-rsa, x509v3-sign-rsa-sha224@ssh.com, x509v3-sign-rsa-sha256@ssh.com, x509v3-sign-rsa-sha384@ssh.com, and x509v3-sign-rsa-sha512@ssh.com.

Multiple public key signature algorithms can be specified as a comma-separated list. Special values for this option are:

  • Any - allows all the supported algorithms

  • AnyStd - allows only those mentioned in the IETF Secsh draft (x509v3-sign-dss, x509v3-sign-rsa, ssh-dss, ssh-rsa)

  • AnyPublicKeyAlgorithm - the same as Any

  • AnyStdPublicKeyAlgorithm - the same as AnyStd

The default list is: ssh-rsa, ssh-rsa-sha256@ssh.com, ssh-dss, ssh-dss-sha256@ssh.com, x509v3-sign-dss, x509v3-sign-dss-sha256@ssh.com, x509v3-sign-rsa, and x509v3-sign-rsa-sha256@ssh.com.

AuthPublicKey.Cert.Required

This keyword specifies whether the client must present a user certificate during user authentication. If this option is set to yes, also the AllowedAuthentications keyword must contain the value publickey. If the server does not receive a certificate, the authentication fails. The argument must be yes or no. The default is no.

AuthPublicKey.Cert.ValidationMethods

This keyword specifies the method used for certificate validation during user public-key authentication. Its value can be tectia or saf, or both (saf,tectia). The default is tectia.

If saf is specified, RACF/SAF is used for validating user certificates. The user certificates must exist in a trusted key ring defined by the AuthorizationEkProvider keyword. Note that when only SAF validation is used, the certificate validity period and revocation status are not checked.

If tectia is specified (or the keyword is missing from the configuration), the Tectia Certificate Validator (ssh-certd) is used for validating user certificates. The user certificates must be issued by a trusted certification authority defined in the Pki or PkiEkProvider keyword of ssh_certd_config.

If both values are specified, the user certificate is read from RACF/SAF and the user name is taken form the certificate. After that the Tectia validation is performed. The CA certificate of the issuing certification authority must exist in a trusted key ring defined by the PkiEkProvider keyword of ssh_certd_config.

AuthPublicKey.MaxSize

Specifies the maximum size of a public key that can be used to log in. Value 0 disables the check. The default is 0 (disabled).

AuthPublicKey.MinSize

Specifies the minimum size of a public key that can be used to log in. Value 0 disables the check. The default is 0 (disabled).

BannerMessageFile

Specifies the path to the message that is sent to the client before authentication. Note, however, that the client is not obliged to show this message.

The default is /opt/tectia/etc/ssh_banner_message (if defined).

CertdListenerPath

Specifies the path where the server tries to connect to the certificate validator. Mainly intended for debugging and testing. The default is /opt/tectia/var/run/ssh-certd-listener.

CheckMail

Makes sshd2 print information on whether there is new mail or not when a user logs in interactively. (On some systems this information is also printed by the shell, /etc/profile, or equivalent.) The argument must be yes or no. The default is yes.

ChRootGroups

This option works like ChRootUsers, except that it can be used to list groups instead of single users. Groups are listed on the server in /etc/group. Follows the logic of DenyGroups.

ChRootUsers

sshd2 gives all users listed here a chrooted environment (e.g. /home). This stops users from accessing sensitive information on the server's file system. Users are defined on the server in /etc/group. More than one group can be listed, separated by a comma. This is not a default option. The logic follows that of DenyUsers.

Ciphers

Specifies the ciphers to use for encrypting the session. The supported ciphers are aes128-cbc, aes192-cbc, aes256-cbc, 3des-cbc, arcfour, blowfish-cbc, cast128-cbc, twofish-cbc, twofish128-cbc, twofish192-cbc, twofish256-cbc, cast128-12-cbc@ssh.com, des-cbc@ssh.com, seed-cbc@ssh.com, and rijndael-cbc@ssh.com.

Multiple ciphers can be specified as a comma-separated list. Special values for this option are:

  • Any - allows all ciphers including none

  • AnyStd - allows only those mentioned in the IETF Secsh draft (aes128-cbc, 3des-cbc, twofish128-cbc, cast128-cbc, twofish-cbc, blowfish-cbc, idea-cbc, aes192-cbc, aes256-cbc, twofish192-cbc, twofish256-cbc, arcfour) plus none

  • none - no encryption; the data on the line is in plaintext

  • AnyCipher - the same as Any, but excludes none

  • AnyStdCipher - the same as AnyStd, but excludes none

The default list is aes128-cbc, aes192-cbc, aes256-cbc and 3des-cbc.

DenyGroups

This keyword can be followed by any number of group name patterns, separated by commas. If specified, login is denied if one of the groups the user belongs to matches one of the patterns. Otherwise, this option is parsed and matched identically to AllowGroups. By default, all users are allowed to log in.

If a user's group matches a pattern in both DenyGroups and AllowGroups, login is denied.

Note that all other authentication steps must still be successfully completed. AllowGroups and DenyGroups are additional restrictions and never increase the tolerance.

DenyHosts

This keyword can be followed by any number of host name patterns, separated by commas. If specified, login is denied from hosts whose names match any of the patterns. See AllowHosts.

DenySHosts

This keyword can be followed by any number of host name patterns, separated by commas, just as the option DenyHosts. The entries in .shosts, .rhosts, /etc/hosts.equiv and /etc/shosts.equiv are ignored if they match one of the patterns given here (if there are any). See AllowSHosts.

DenyTcpForwardingForGroups

The syntax is the same as in DenyGroups, but instead of login, this controls the ability to forward ports, in remote or local forwarding. See the security note under option AllowTcpForwarding.

DenyTcpForwardingForUsers

The syntax is the same as in DenyUsers, but instead of login, this controls the ability to forward ports, in remote or local forwarding. See the security note under option AllowTcpForwarding.

DenyUsers

This is the opposite of AllowUsers and works accordingly. If a user's name matches a pattern in both DenyUsers and AllowUsers, login is denied.

Note that all other authentication steps must still be successfully completed. AllowUsers and DenyUsers are additional restrictions.

DisableVersionFallback

Selects whether to disable fallback compatibility code for earlier, or otherwise incompatible versions of software. Do not disable this unless you know what you are doing. The argument must be yes or no. The default is no.

ExternalAuthorizationProgram

If set, this program is run to verify whether the user is authorized to log in. sshd2 converses with this program using a line-based protocol, so it is easy to implement for example as a shell script. If this is set, and the program does not exist or cannot be run, authorization (user login) will be denied. This will not be set by default. More information about the protocol can be found in the distribution package, RFC.authorization_program_protocol has a description of the protocol used and an example script is called ext_authorization_example.sh. Note that the program is run with the privileges of the sshd2 process, typically root, so be careful.

ForwardACL

With this option, you can have more fine-grained control over what the client is allowed to forward and where. The format for this option is

(allow|deny) (local|remote) user-pat forward-pat [originator-pat]

user-pat will be used to match the client user, as specified under the option UserSpecificConfig.

forward-pat is a pattern of format host-id[%port]. This has different interpretations depending on whether the ACL is specified for local or remote forwardings. For local forwardings, host-id will match with target host of the forwarding, as specified under option AllowHosts. port will match the target port. Also, if the client sent a host name, the IP is looked up from the DNS, which will be used to match the pattern. For remote forwardings, where the forwarding target is not known (the client handles that end of the connection), this will be used to match the listen address specified by the user (and as such is not as usable as with local forwardings). port will match the port the server is supposed to be listening to with this forwarding.

With local forwards, originator-pat will match the originator address that the client has reported. Remember, if you do not administer the client machine, or the users on that machine have shell access, they may use a modified copy of ssh that can be used to lie about the originator address. Also, with NATs (Network Address Translation) the originator address will not be meaningful (it will probably be an internal network address). Therefore you should not rely on the originator address with local forwardings, unless you know exactly what you are doing. With remote forwardings, on the other hand, originator-pat will match with the IP address of the host connecting to the forwarded port. This will be valid information, as it is the server checking the information.

If you specify any allow directives, all forwardings in that class (local or remote) not specifically allowed will be denied. (Note that local and remote forwardings are separate in this respect; e.g. if you have one "allow remote" definition, local forwardings are still allowed, pending other restrictions.) If a forwarding matches both allow and deny directives, the forwarding will be denied. Also, if you have specified any of the options {Allow,Deny}TcpForwardingFor{Users,Groups} or AllowTcpForwarding, and the forwarding for the user is disabled with those, an allow directive will not re-enable the forwarding for the user. Forwarding is enabled by default.

ForwardAgent

See AllowAgentForwarding or ForwardAgent.

HostbasedAuthForceClientHostnameDNSMatch

If the host name given by the client does not match the one found in DNS, fail host-based authentication. Defaults to no. Note that this differs from 2.4 and earlier releases.

HostCertificateFile

This keyword works very much like PublicHostKeyFile, except that the file is assumed to contain an X.509 certificate in binary format. The keyword must be paired with a corresponding HostKeyFile option. If multiple certificates with the same public-key type (DSA or RSA) are specified, only the first one is used.

HostIdMappingHostnames

A user certificate might contain a HostIdMapping field. That field is used by SAF to determine the local user name of the user. If the HostIdMapping field should be processed in Tectia Server for IBM z/OS, the HostIdMappingHostnames keyword can be used. It specifies the list of host names that the server recognizes. If the user certificate has the correct host name in the HostIdMapping host name field, the user name associated with that host name (specified in the certificate) is used. Note that if HostIdMappingHostnames is used, the Tectia certificate validation must be performed (the AuthPublicKey.Cert.ValidationMethods keyword must be set to saf,tectia).

HostKeyAlgorithms

Specifies the host key signature algorithm to be used in server authentication and host-based authentication.

The supported algorithms are ssh-dss, ssh-dss-sha224@ssh.com, ssh-dss-sha256@ssh.com, ssh-dss-sha384@ssh.com, ssh-dss-sha512@ssh.com, x509v3-sign-dss, x509v3-sign-dss-sha224@ssh.com, x509v3-sign-dss-sha256@ssh.com, x509v3-sign-dss-sha384@ssh.com, x509v3-sign-dss-sha512@ssh.com, ssh-rsa, ssh-rsa-sha224@ssh.com, ssh-rsa-sha256@ssh.com, ssh-rsa-sha384@ssh.com, ssh-rsa-sha512@ssh.com, x509v3-sign-rsa, x509v3-sign-rsa-sha224@ssh.com, x509v3-sign-rsa-sha256@ssh.com, x509v3-sign-rsa-sha384@ssh.com, and x509v3-sign-rsa-sha512@ssh.com.

Multiple algorithms can be specified as a comma separated list. Special values for this option are:

  • Any - allows all host key algorithms

  • AnyStd - allows only the host key algorithms mentioned in the IETF Secsh draft (x509v3-sign-dss, x509v3-sign-rsa, ssh-dss and ssh-rsa)

  • AnyHostKeyAlgorithm - the same as Any

  • AnyStdHostKeyAlgorithm - the same as AnyStd

The default list is ssh-rsa, ssh-rsa-sha256@ssh.com, ssh-dss, ssh-dss-sha256@ssh.com, x509v3-sign-dss, x509v3-sign-dss-sha256@ssh.com, x509v3-sign-rsa and x509v3-sign-rsa-sha256@ssh.com.

HostKeyFile

Specifies the file containing the private host key (default /opt/tectia/etc/hostkey). The directory should be readable only by root.

HostKeyEkInitString

Specifies the initialization string for the external host key provider. This is ignored when the keyword HostKeyEkProvider is not present. The key specification must define exactly one key. It must be a personal RSA key that contains both a private key and a certificate. See ssh-externalkeys(5) for details about specifying initialization strings.

HostKeyEkProvider

Specifies the external key provider for accessing the server host key. Currently, the only valid value on z/OS is zos-saf. See ssh-externalkeys(5) for details about specifying providers.

HostKey.Cert.Required

This keyword specifies whether the local server must present a host certificate to the remote client during server authentication (or whether the local client must present a host certificate to a remote server during host-based user authentication).

If set to yes, a certificate must be defined either with the HostCertificateFile keyword or with the HostKeyEkProvider keyword.

If set to no, a certificate is not required. In this case, if the HostKeyEkProvider keyword specifies a certificate in SAF, only the public key found in the certificate is used (but HostCertificateFile is used normally, if defined).

If set to optional, both certificate and public key are used. In this case, if the HostKeyEkProvider keyword specifies a certificate in SAF, the certificate and the public key found in the certificate are used (but HostCertificateFile is used normally, if defined).

The argument must be yes, no, or optional. The default is no.

HostSpecificConfig

Specifies a subconfiguration file for sshd2. The syntax for this option is:

pattern subconfig-file

pattern is used to match the client host, as specified under option AllowHosts. The file subconfig-file is read, and configuration data is amended accordingly. The file is read before any actual protocol transactions begin, and you can specify most of the options allowed in the main configuration file. You can specify more than one subconfiguration file, in which case the patterns are matched and the files read in the specified order. Configuration option values defined later will either override or amend the previous value, depending on the option. The effect of redefining an option is described in the documentation for each option. For example, setting Ciphers in the subconfiguration file will override the old value, but setting AllowUsers will amend the value. See sshd2_subconfig(5) for more thorough documentation on what you can set in this subconfiguration file.

See also option UserSpecificConfig.

IdentityDispatchUsers

This keyword is used in conjunction with certificate authentication. It is followed by a user name pattern as in the AllowUsers keyword. If the login user name given by the client matches to the pattern, it is not used, but instead the user name is taken from the user certificate.

IdleTimeOut

Sets the idle timeout limit to time either in seconds (s or nothing after the number), in minutes (m), in hours (h), in days (d), or in weeks (w). If the connection has been idle (all channels) this long, the connection is closed. The default is 0 (zero), which disables idle timeouts.

IgnoreLoginRestrictions.PasswordExpiration

This option has no effect on z/OS.

IgnoreRhosts

Specifies that the .rhosts and .shosts files will not be used in host-based authentication (see AllowedAuthentications). /etc/hosts.equiv and /etc/shosts.equiv are still used as before. The argument must be yes or no. The default is no.

IgnoreRootRhosts

Specifies that the .rhosts and .shosts files will not be used in authentication for root. The default is the value of IgnoreRhosts.

KeepAlive

Specifies whether the system should send keepalive messages to the other side. If they are sent, a broken 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 this can be annoying in some situations. On the other hand, if keepalive messages are not sent, sessions may hang indefinitely on the server, leaving "ghost" users and consuming server resources.

The default is yes (to send keepalives), and the server will notice if the network goes down or the client host reboots. This avoids infinitely hanging sessions.

To disable keepalives, the value should be set to no in both the server and the client configuration files.

KEXs

Specifies the key exchange algorithm to be used. The supported algorithms are:

diffie-hellman-group14-sha1
diffie-hellman-group1-sha1
diffie-hellman-group14-sha224@ssh.com
diffie-hellman-group14-sha256@ssh.com
diffie-hellman-group15-sha256@ssh.com
diffie-hellman-group15-sha384@ssh.com
diffie-hellman-group16-sha384@ssh.com
diffie-hellman-group16-sha512@ssh.com
diffie-hellman-group18-sha512@ssh.com

Multiple KEXs can be specified as a comma-separated list. Special values for this option are:

  • Any - allows all KEXs

  • AnyStd - allows only the KEXs mentioned in the IETF Secsh draft (diffie-hellman-group14-sha1, diffie-hellman-goup1-sha1)

  • AnyKEX - the same as Any

  • AnyStdKEX - the same as AnyStd

The default algorithms are diffie-hellman-group14-sha1, diffie-hellman-group1-sha1 and diffie-hellman-group14-sha256@ssh.com.

KnownHostsEkProvider

Specifies the external key provider for accessing external host public keys used for host-based user authentication. The value is of the format "provider:initstring". Currently, the only valid value for provider on z/OS is zos-saf. For the format of the initstring, see ssh-externalkeys(5).

ListenAddress

Specifies the IP address of the interface where the sshd2 server socket is bound. The format for this option is

ip-address [port] ,

where port is optional. IPv6 addresses may be enclosed in brackets and must be if they start with a colon. The port, if not defined here, will be the value of the last Port definition (or the default, 22, if Port has not been defined). If the specified IP address is any, sshd2 will listen to all interfaces. If sshd2 should listen to only some interfaces, specify the ListenAddress parameter for each interface.

The default is any.

ListenerRetryInterval

Declares how often sshd2 tries/retries to create listeners which fail to open initially or later get deleted by the operating system.

The interval is given either in seconds (s or nothing after the number), in minutes (m), in hours (h), in days (d), or in weeks (w).

The default is 0 (zero), which means sshd2 does not retry but gives up and exits immediately when a listener fails to open or dies.

LoadControl.Active

Specifies whether load control is enabled. The purpose of load control is to help keep the server running when the load is high, that is, when the number of current connections is near MaxConnections. The argument must be yes or no. The default is yes.

[Note]Note

If MaxConnections is set to 0 or 1, load control is disabled even if LoadControl.Active is set to yes.

LoadControl.DiscardLimit

When Tectia Server for IBM z/OS's load is high, connections from IP addresses that have not recently had a successful authentication are discarded. This keyword specifies the number of connections accepted from any IP address. The allowed value range is from 1 to MaxConnections-1. The default is 90 percent of the value of MaxConnections.

LoadControl.WhitelistSize

Specifies the length of the white list in which Tectia Server for IBM z/OS keeps the IP addresses of connections that have had a successful authentication. The default is 1000.

LoginGraceTime

The server disconnects after this time if the user has not successfully logged in. If the value is 0, there is no time limit. The default is 600 (seconds).

MACs

Specifies the MAC (Message Authentication Code) algorithm to use for data integrity verification. The supported algorithms are:

hmac-md5
hmac-md5-96
hmac-sha1
hmac-sha1-96
hmac-sha2-256
hmac-sha256-2@ssh.com
hmac-sha224@ssh.com
hmac-sha256@ssh.com
hmac-sha-384@ssh.com
hmac-sha2-512
hmac-sha512@ssh.com

Multiple MACs can be specified as a comma-separated list. Special values for this option are:

  • Any - allows all MACs including none

  • AnyStd - allows only the MACs mentioned in the IETF Secsh draft (hmac-md5, hmac-md5-96, hmac-sha1, hmac-sha1-96, hmac-sha2-256, hmac-sha2-512)

  • none - no cryptographic data integrity method is used

  • AnyMac - the same as Any but excludes none

  • AnyStdMac - the same as AnyStd but excludes none

The default algorithms are hmac-sha1, hmac-sha1-96, hmac-sha2-256, hmac-sha256-2@ssh.com, hmac-sha224@ssh.com, hmac-sha256@ssh.com, hmac-sha384@ssh.com, hmac-sha2-512 and hmac-sha512@ssh.com.

MaxBroadcastsPerSecond

Specifies how many UDP broadcasts the server handles per second. The default value is 0 and no broadcasts are handled at all. Broadcasts that exceed the limit are silently ignored. Received unrecognized UDP datagrams also consume the capacity defined by this option.

MaxConnections

Specifies the maximum number of connections that sshd2 will handle simultaneously. This is useful against flooding attacks (attempts to interrupt the server from working properly by opening a high number of new connections). The argument is a positive number. The value 0 means that the number of connections is not limited. The default is 1000.

[Note]Note

MaxConnections must be greater than 1 when load control is used. For more information on load control, see Load Control.

Note that by using (at least) xinetd you achieve the same effect on a more generic level.

NoDelay

If set to yes, enables socket option TCP_NODELAY. The argument must be yes or no. The default is no.

PasswdPath

Specifies the location of the passwd program (or equivalent). By default this is set to where the configure script found it. This program will be run with the privileges of the user logging in.

PasswordGuesses

Specifies the number of tries that the user has when using password authentication. The default is 3.

PermitEmptyPasswords

When password authentication is allowed, this keyword specifies whether the server allows login to accounts with empty password strings. The argument must be yes or no. The default is no.

PermitRootLogin

Specifies whether root can log in using sshg3. The options are yes, nopwd, and no.

The default is yes, allowing root logins through any of the authentication types allowed for other users. The nopwd value disables password-authenticated root logins. The no value disables root logins through any of the authentication methods. (The values nopwd and no are equivalent unless you have some other means of authentication for root, e.g. public key.)

Root login with public-key authentication when the command option has been specified will be allowed regardless of the value of this setting (which may be useful for taking remote backups even if root login is normally not allowed).

PidFile

Specifies the file where the process ID of the server is written. The default is /opt/tectia/var/run/sshd2_22.pid.

Port

Specifies the port number that sshd2 listens to. The current default is 22.

PrintMotd

Specifies whether sshd2 should print /etc/motd (message of the day) when a user logs in interactively. The default is yes. The argument must be yes or no.

ProxyServer

With this option, sshd2 can use a SOCKS (v4 or v5) or an HTTP proxy when a client forwards a connection. The server will use the value of this option when connecting. With SOCKS, you can specify whether to use SOCKS5 with the option UseSocks5.

The format of the variable is socks://username@socks_server:port/network/netmask,network/netmask ... (with SOCKS proxy) or http://username@socks_server:port/network/netmask,network/netmask ... (with HTTP proxy).

For instance, by setting ProxyServer to

socks://mylogin@socks.ssh.com:1080/203.123.0.0/16,198.74.23.0/24

host socks.ssh.com and port 1080 are used as your SOCKS server for connections outside of networks 203.123.0.0 (16-bit domain) and 198.74.23.0 (8-bit domain). Those networks are connected directly.

If this option is set, it should almost always contain the local loopback network (127.0.0.0/8) as a network that is connected directly.

This option and the option SocksServer behave identically. Specifying both will cause the later definition to override the first.

PublicHostKeyFile

Specifies the file containing the public host key. The default is /opt/tectia/etc/hostkey.pub.

QuietMode

If set to yes, nothing is logged in the system log, except fatal errors. The argument must be yes or no. The default is no.

RandomSeedFile

Specifies the name of the random seed file.

RekeyIntervalSeconds

The number of seconds after which the key exchange is done again. The default is 3600 seconds (1 hour). The value 0 (zero) turns rekey requests off. This does not prevent the client from requesting rekeys. Other clients (not sshg3) may not have rekey capabilities implemented correctly, and they might not be able to handle rekey requests. This means that they may possibly close the connection or even crash.

RequiredAuthentications

Analogous to AllowedAuthentications, with one difference: the authentication methods listed here must all succeed before a user is considered authenticated. Leaving this list empty is equivalent to not using the option at all.

If this option is set, AllowedAuthentications is ignored.

[Note]Note

Versions of sshd2 before 3.1.0 required RequiredAuthentications to be a subset of AllowedAuthentications. This is no longer the case.

RequireReverseMapping

This is used to check whether the host name DNS lookup must succeed when checking whether connections from hosts are allowed using AllowHosts and DenyHosts. If this is set to yes, and the name lookup fails, the connection is denied. If set to no, and name lookup fails, the remote host's IP address is used to check whether it is allowed to connect. This is probably not what you want if you have specified only host names (not IP addresses) with {Allow,Deny}Hosts. See also ResolveClientHostName. The argument must be yes or no. The default is no.

ResolveClientHostName

This parameter controls whether sshd2 will try to resolve the client IP at all. This is useful when you know that the DNS cannot be reached, and the query would cause additional delay in logging in. Note that if you set this to no, you should not set RequireReverseMapping to yes. The argument must be yes or no. The default is yes.

SettableEnvironmentVars

This keyword can be followed by any number of patterns, separated by commas. Patterns are matched using the egrep syntax (see sshregex(1)), or the syntax specified in the metaconfiguration header of the configuration file. You can use the comma ',' character in the patterns by escaping it with a backslash '\'. By default, no environment variables can be set (but the default /opt/tectia/etc/sshd2_config file specifies some common and safe environment variables).

With this option, you can allow setting some or all environment variables. This option is used to check whether setting is allowed by the client (sshg3), by the user's $HOME/.ssh2/environment file or public key options. This is not used when setting variables from /etc/environment or other "root-only" files, as the user does not have control over those anyway.

Note that this option only changes the settings of environment variables before the user's shell is run. After that, the users are of course free to set whichever variables they want in the environment.

SftpSysLogFacility

As SysLogFacility, but defines the log facility the sft-server-g3 subsystem will use. The default is DAEMON.

SftpSmfType

Defines the SMF record type used in SMF accounting in sshd2 and the sft-server-g3 subsystem. By default, this has no value, i.e. no accounting is performed. The possible values are: none, TYPE119.

ShellAccountCodeset

Specifies the code set of terminal session data in user's shell. The default is IBM-1047.

ShellAccountLineDelimiter

Specifies the line delimiter of terminal session data in user's shell. Special values for this option are DOS, MAC, MVS and UNIX. The default is MVS.

ShellConvert

Defines whether conversions are to be done for shell access and remote command execution. Possible values are yes and no. The default is yes.

ShellTransferCodeset

Defines the coded character set (CCS) on the line. The default is ISO8859-1.

ShellTransferLineDelimiter

Specifies the line delimiter of terminal session data during transfer. Special values for this option are DOS, MAC, MVS and UNIX. The default is UNIX.

ShellTranslateTable

Defines the MVS translate table to be used from line to shell.

SocksServer

Equal to ProxyServer.

StrictModes

Specifies whether sshd2 should check file modes and ownership of the user's home directory and .rhosts files before accepting login using host-based authentication. This is normally desirable because novices sometimes accidentally leave their directory or files world-writable, in which case anyone can edit the .rhosts files.

If this is set, permissions are checked during public-key authentication for the user's .ssh2 directory, public keys used and the authorization file.

Also the hostkey is checked for invalid permissions. The hostkey must only be readable and writable by the root user, the user public keys and authorization file must only be writable by the user. The permission check of the user's .ssh2 directory (and with host-based authentication, the user's home directory) can be further controlled by using the StrictModes.UserDirMaskBits configuration option.

The argument must be yes or no. The default is yes.

StrictModes.UserDirMaskBits

Specifies the permission mask for the user's .ssh2 directory if StrictModes configuration option is used. The bits set with this option are not allowed to be set in the actual permissions. This means that with StrictModes and this option set to "077", the user's .ssh2 directory may not have any permissions to group or others (only for the user). The default is "022".

Subsystem-<subsystem name>

Specifies a subsystem. The argument is a command that is executed when the subsystem is requested.

sftpg3 uses a subsystem of sshd2 to transfer files securely. In order to use the SFTP server, you must have the following subsystem definition:

subsystem-sftp sft-server-g3

SysLogFacility

Gives the facility code that is used when logging messages from sshd2. The possible values are: DAEMON, USER, AUTH, LOCAL0, LOCAL1, LOCAL2, LOCAL3, LOCAL4, LOCAL5, LOCAL6, LOCAL7. The default is AUTH.

Terminal.AllowUsers

Lists users that are allowed terminal access to the server host. This option can be followed by any number of patterns of the form user or user@host, separated by commas. The details explained under the AllowHosts option apply accordingly.

If this configuration option is used, only users that match the users listed under Terminal.AllowUsers may gain terminal access (provided that they are not restricted by other configuration options). By default, all users are allowed terminal access.

Note that all the other login authentication steps must still be successfully completed. Terminal.AllowUsers and Terminal.DenyUsers are additional restrictions.

Terminal.DenyUsers

Lists users that are denied terminal access to the server host. This is the opposite of Terminal.AllowUsers and works accordingly.

If a user matches a pattern in both Terminal.AllowUsers and Terminal.DenyUsers then terminal access is denied.

Note that when terminal access is denied so is remote command execution, forced commands (including commands related to public-key authentication and forced password changes), X11 forwarding, and agent forwarding. As a user has no shell access, any password changes (using system commands) will not be possible.

Access to subsystems (such as SFTP) and TCP tunneling (port forwarding) are still possible.

If a client requests terminal access (in addition to any other services, such as tunneling) the client may disconnect upon being refused terminal access. To prevent this, the client should be configured to not request terminal access, for example, by using the -S option in the ssh command (the option may vary with the ssh implementation).

Terminal.AllowGroups

Similar to Terminal.AllowUsers but matches groups rather than user names. The details explained under the AllowGroups option apply accordingly.

Terminal.DenyGroups

Similar to Terminal.DenyUsers but matches groups rather than user names. This is the opposite of Terminal.AllowGroups and works accordingly.

UseCryptoHardware

Specifies how cryptographic hardware is utilized. The value for this option is a comma-separated list of algorithm:support_level pairs. The list may start with a sole support level specifier.

Valid values for support_level are:

  • yes - cryptographic hardware is used for this algorithm if available and software cryptography is used if hardware cryptography is not available

  • no - software cryptography is used for this algorithm

  • must - only cryptographic hardware is used for the algorithm

Valid values for algorithm are:

  • 3des - Triple DES symmetric cipher used for encrypting the session

  • aes - AES symmetric cipher used for encrypting the session

  • sha - SHA-1 or SHA-2 algorithm used for MAC (Message Authentication Code)

  • rng - Random number generator. The hardware is used to generate entropy for the random seed at start-up and for reseeding the random number generator algorithm periodically during execution.)

Example 1. Use cryptographic hardware for AES and SHA; all others should use software:

  UseCryptoHardware        no,aes:must,sha:must

This could be coupled with allowing only AES ciphers and SHA-based MACs with Ciphers and MACs options.

Example 2. Use cryptographic hardware for all algorithms except for AES:

  UseCryptoHardware        yes,aes:no

UserConfigDirectory

Specifies where user-specific configuration data is found. With this the administrator can control those options that are usually controlled by the user. This is given as a pattern string which is expanded by sshd2.

%D is the user's home directory,
%U is the user's login name,
%IU is the user's user ID (uid),
%IG is the user's group ID (gid).

The default is %D/.ssh2.

UserKnownHosts

Specifies whether $HOME/.ssh2/knownhosts/ can be used to fetch host public keys when using host-based authentication. The argument must be yes or no. The default is yes.

UserSpecificConfig

As HostSpecificConfig, but these configuration files are read later, when the user name that the client is trying to log in as is known. Also the range of configuration options available is smaller, due to the fact that they would not make sense in these files. You can use patterns of form "user[%group][@host]", where user is matched with the user name and UID, group is matched with the user's primary and any secondary groups, both group name and GID, and host is matched as described under option AllowHosts.

See sshd2_subconfig(5) for more thorough documentation on what you can set in this subconfiguration file.

UseSocks5

Use SOCKS5 instead of SOCKS4 when connecting to remote host. Note that you have to set SocksServer to a meaningful value. The argument must be yes or no. The default is no (i.e. use SOCKS4).

VerboseMode

Causes sshd2 to print debugging messages about its progress. This is helpful in debugging connection, authentication, and configuration problems. Also causes sshd2 to not fork on connection, so only one connection is handled at the time.

WTORoutingCodes

Specifies the z/OS routing codes for WTO messages. Valid values for routing codes are from 1 to 128. The default is 1,11.