This element defines the network address family used for connections. If set to inet, the server will accept only IPv4 incoming connections. If set to inet6, the server will accept only IPv6 incoming connections. If set to any, the server will accept both IPv4 and IPv6 incoming connections, will resolve addresses of both families, and opens both IPv4 and IPv6 listeners for remote port forwarding.

<address-family type="inet|inet6|any" />

The default is inet. Command-line options override settings from configuration file.

This element selects the cryptographic library mode to be used. Either the standard version (standard) or the FIPS 140-2 certified version (fips) of the crypto library can be used. The library name is given as a value of the mode attribute. By default, standard crypto libraries are used. The OpenSSL cryptographic library is used in the FIPS mode.

<crypto-lib mode="standard" />

In the FIPS mode, the cryptographic operations are performed according to the rules of the FIPS 140-2 standard. The FIPS library includes the 3des-cbc, aes128-cbc, aes128-ctr, aes192-cbc, aes192-ctr, aes256-cbc, and aes256-ctr ciphers, and all the supported hmac-sha1 and hmac-sha2 variants of MAC. See also cipher and mac.

	Note
	Tectia Server has to be restarted after changing the FIPS mode setting. Extra checks are done when starting the Tectia Server and Connection Broker in the FIPS mode due to the OpenSSL FIPS crypto library health check. This will lead to a noticeable delay in the start of the process on slow machines.

For a list of platforms on which the FIPS library has been validated or tested, see Tectia Client/Server Product Description.

This element contains miscellaneous settings. It has the following attributes: signature-algorithms, proxy-scheme, xauth-path, x11-listen-address, pam-account-checking-only, resolve-client-hostname, ignore-aix-rlogin, ignore-aix-login, record-ptyless-sessions, user-config-dir, default-path, windows-logon-type, windows-terminal-mode, ignore-nisplus-no-permission, quiet-login and default-domain.

The signature-algorithms attribute can be used to specify a comma-separated list of public-key signature algorithms used for user authentication. The algorithms that can be used are those that are defined in both Tectia Server and Connection Broker configuration files. They are defined in an order of preference. The one that is selected to be used is the first common algorithm that both the client and server have in their configuration. This way the use of only certain algorithms, such as SHA-2, can be enforced.

<settings signature-algorithms="ssh-dss,ssh-rsa-sha256@ssh.com" />
  

The proxy-scheme attribute defines rules for HTTP or SOCKS proxy servers that Tectia Server uses when a client forwards a connection (local tunnel).

The format of the attribute value is a sequence of rules delimited by semicolons (;). Each rule has a format that resembles the URL format. In a rule, the connection type is given first. The type can be direct, socks, socks4, socks5, or http-connect (socks is a synonym for socks4). This is followed by the server address and port. If the port is not given, the default ports 1080 for SOCKS and 80 for HTTP are used.

After the address, zero or more conditions delimited by commas (,) are given. The conditions can specify IP addresses or DNS names.

direct:///[cond[,cond]...]
socks://server/[cond[,cond]...]
socks4://server/[cond[,cond]...]
socks5://server/[cond[,cond]...]
http-connect://server/[cond[,cond]...]

The IP address/port conditions have an address pattern and an optional port range:

ip_pattern[:port_range]

The ip_pattern may have one of the following forms:

The DNS name conditions consist of a hostname which may be a regular expression containing the characters "*" and "?" and a port range:

name_pattern[:port_range]

An example proxy-scheme is shown below. It causes the server to access the callback address and the ssh.com domain directly, access *.example with HTTP CONNECT, and all other destinations with SOCKS4.

"direct:///127.0.0.0/8,*.ssh.com;
 http-connect://http-proxy.ssh.com:8080/*.example;
 socks://fw.ssh.com:1080/"

The xauth-path attribute contains a path to a supplementary XAuth binary used with X11 forwarding on Unix platforms.

On Unix, the x11-listen-address attribute can be used to configure on what kind of address the x11 listener (used in X11 forwarding) is created. Possible values are:

On Unix, the pam-account-checking-only attribute can be used to define that only PAM will be used to check if the user is allowed to login (for example, the account is not locked). Generally, PAM can be used during authentication or in PAM account or session management via the pam-calls-with-commands setting.

Possible values for the pam-account-checking-only attribute are:

The resolve-client-hostname attribute can be used to define whether Tectia Server should try to resolve the client host name from the client IP address during connection setup.

If an IP address of the client host is defined with the Allow/Deny-from option in the authorization file, then the resolve-client-hostname attribute is ignored. But if a hostname is defined with the Allow/Deny-from option, then this attribute is used.

	Note
	This attribute does not affect the resolution of TCP tunnel endpoints and Tectia Server will try to resolve the client host name when creating a TCP tunnel.

Possible values for the resolve-client-hostname attribute are:

The ignore-aix-rlogin attribute defines whether the server should ignore the remote login restriction on AIX. Possible values are:

The ignore-aix-login attribute defines whether the server should ignore the local login restriction on AIX. Possible values are:

The record-ptyless-sessions attribute can be used to control whether sessions without PTYs are recorded as user logins in the operating system. Sessions without PTYs are for example remote commands and SFTP sessions. By default, all sessions are recorded. However, some system utilities (such as finger on Solaris) do not allow sessions without PTYs to be recorded because these sessions do not have a valid TTY name. On these systems, only real shell logins should be recorded and others turned off by setting record-ptyless-sessions=no. The value must be yes or no. The default is yes.

The user-config-dir attribute can be used to specify a directory where user-specific configuration data is to be found, if the data is not stored in the default location. With this setting, the administrator can control those options that are usually controlled by the user. Tectia Server expects Tectia-style directory structure under the given directory, for example, the /authorized_keys directory, and the /authorization file, if they are being used.

For user-config-dir, the default is %D/.ssh2. The directory path can include pattern strings which will be expanded by Tectia Server. The following pattern strings can be used:

On Unix, the default-path attribute can be used to define the default PATH value for the user environment. This path will be applied after connection to a server unless anything else is defined in the system settings. Alternatively, the default environment can be set by using the environment variable PATH.

On Windows, the windows-logon-type attribute can be used to define what kind of user logon methods for the local host are accepted by Tectia Server. The defined logon type affects password authentication. This attribute takes values batch, interactive, network, and network-cleartext. The default value is interactive.

For example, to enable accounts that do not have the access right to log on locally, make the following setting:

<settings windows-logon-type="network" />

For information on the attribute values, refer to Microsoft documentation on the Windows logon types.

On Windows, the windows-terminal-mode attribute can be used to define the mode of operation of a terminal session on the server side. This attribute takes values console and stream.

If set to console (default), the server reads the screen buffer in a loop and detects modifications based on current cursor location. If set to stream, the server reads the stdout and stderr of cmd.exe as a stream of data, while providing basic facilities for command-line editing.

On Linux and Solaris, the ignore-nisplus-no-permission attribute can be used to define whether Tectia Server should ignore it if NIS+ gives no permission to the user during authentication. The value can be yes or no. The default is no.

When set to yes, and when the user to authenticate is not root, the server will ignore it if the NIS+ returns *NP* when querying for shadow password. *NP* indicates no permission to read the password information.

	Note
	When NIS+ returns *NP*, the user will NOT be able to use password authentication or the keyboard-interactive with password authentication to authenticate the session. However, the keyboard-interactive with PAM is possible.

The quiet-login attribute can be used to define whether to suppress the messages about last login, password expiry, messages of the day and other such information during login. This can be useful in case third party applications are used to launch a shell, and the messages are useless or even confusing to the applications. The attribute value can be yes or no. The default is no.

The default-domain attribute can be used to append a domain to server hostnames that are not fully qualified domain names (FQDN). For example, if the hostname is server01 and you define:

<settings default-domain="example.com"/>

then the resulting FQDN will be server01.example.com.

Example of the settings element and its attributes:

<settings 
 proxy-scheme="direct:///10.0.0.0/8,localhost;socks5://fw.example.com:1080/" 
 xauth-path="/usr/X11R6/bin/xauth" 
 ignore-aix-rlogin="no"
 ignore-aix-login="no" 
 record-ptyless-sessions="yes"
 user-config-dir="%D/.ssh2"
 default-path=""
 windows-logon-type="interactive"
 windows-terminal-mode="console"
 ignore-nisplus-no-permission="no"
 default-domain="example.com"
 quiet-login="no" />

This element can be used to define defaults for PAM account management and session management with the following attributes:

The settings made in pluggable-authentication-modules can be overriden locally by adding PAM-related settings also to the authentication-methods block. Under the auth-keyboard-interactive element you can define the submethod-pam element with attributes service-name and dll-path.

With the following example configuration, the factory settings are overriden by defining sshd2 as the service for PAM (in the pluggable-authentication-modules setting). This service will be used by ssh-user-exec, for example. To make the PAM submethod to use the ssh-server-g3 service, it is specified with the service-name in the submethod-pam setting.

<params>
 <pluggable-authentication-modules service-name="sshd2"/>
</params>
         <!-- ... -->
<authentication-methods>
  <authentication action="allow" name="allow-default">
    <auth-keyboard-interactive>
      <submethod-pam service-name="ssh-server-g3" />
    </auth-keyboard-interactive>
  </authentication>
</authentication-methods>

This element contains protocol-specific values that can be used to tune the performance. It should be used only in very specific environments. In normal situations the default values should be used.

The threads attribute can be used to define the number of threads the protocol library uses (fast path dispatcher threads). This attribute can be used to allow more concurrent cryptographic transforms in the protocol on systems with more than four CPUs. If the value is set to zero, the default value is used.

Example of the threads attribute:

<protocol-parameters threads="8" />

This element defines the location of the private host key and optionally the location of the public key and/or certificate. The elements inside the element must be given in the right order (private key before public).

Inside one hostkey element either the public key or the certificate can be given, not both.

Giving the public key in the configuration file is not mandatory. It will be derived from the private key if it is not found otherwise. However, specifying the public key will decrease the start-up time for the software, as deriving the public key is a fairly slow operation.

Sample hostkey elements are shown below:

<hostkey>      
  <private file="/etc/ssh2/hostkey_dsa" />
  <public file="/etc/ssh2/hostkey_dsa.pub" />
</hostkey>

<hostkey>      
  <private file="/etc/ssh2/hostcert_rsa" />
  <x509-certificate file="/etc/ssh2/hostcert_rsa.crt" />
</hostkey>

<hostkey>      
  <externalkey type="entrust" 
               init-info="profile-file(/etc/ssh2/hostcertprofile.epf)" />
</hostkey>

For PKCS#12, the <hostkey> settings are as follows:

<hostkey>      
  <externalkey type="software" 
               init-info="key_file(/etc/ssh2/server-cert.p12)
                          key_passphrase_file(/etc/ssh2/my-passphrase)" />
</hostkey>

In the PKCS#12 sample output, the hostkey setting reads the PKCS#12 file server-cert.p12 and if it needs a passphrase to open it, it will read the my-passphrase file and use the contents as the passphrase. The file can also contain additional certificates but they are ignored in Tectia Server.

In the init-info string, the following keywords are supported:

This element is used to specify where the Secure Shell server listens for connections. The element has three attributes: id, address, and port.

The id must be given as an attribute. The value must be unique. The value must begin with a letter, it can contain alphanumeric characters or underscore characters but no any whitespaces. Also the port and network interface address can be given. The default port for listeners is 22.

Several listeners can be created to the same IP address to different ports. Each must have an unique ID. If the address is not specified, the server will listen to the given port on all interfaces.

Sample listener elements are shown below:

<listener id="internet" address="192.0.2.62" />
<listener id="intranet" address="10.0.0.1" />
<listener id="admin-private" port="222" />

On Windows, you can add this optional domain-policy setting to define how Tectia Server will handle user names when a user logs in without specifying the prefix (indicating local or domain user). This setting defines where the server will look for the user account, and how it will fill in the missing prefix part.

The windows-domain-precedence element defines a comma-separated list of trusted domains and special values %default% and %local%. The list is read in order, and the first domain that has an account for the user name will be used to log in the user and the rest will be ignored. If the user name is not found in any of the specified domains, the user account is assumed not to exist.

Value %local% means that a user without a specified prefix will be treated as a local user (username → localmachine_name\username).

Value %default% means that a user without a specified prefix will be treated as a domain user, and the domain name is expected to be the default domain of the local machine (username → defaultdomain_name\username).

If this setting is not defined in the Tectia Server configuration, and a user logs in without specifying the prefix, Tectia Server first checks if the given user name is valid in the default domain where the local machine exists. If no match is found, for example because the machine is standalone, the user will be treated as a local user.

A sample domain-policy setting is shown below:

<domain-policy
windows-domain-precedence="%local%, %default%, domainA, domainB" />

This element changes the logging settings that define the log event severities and logging facilities. The element contains one or more log-events elements.

The following example sets the facility of the Auth_method_failure event to auth and the severity to notice. It also sets the facility of the Server_reconfig_started and Server_starting events to discard (the events will not be logged). All other events use the default settings.

<logging>
  <log-events facility="auth" severity="notice">
    Auth_method_failure
  </log-events>
  <log-events facility="discard">
    Server_reconfig_started Server_starting
  </log-events>
</logging>

This element sets the maximum number of connections and processes the server will handle. Tectia Server uses a distributed architecture where the master server process launches several servant server processes that handle the actual connections. The element can also contain zero or more servant-lifetime elements.

The max-processes attribute defines the maximum number of servant processes the master server will launch. The value range is 1-40. The default value is 40.

The max-connections attribute defines the maximum number of client connections allowed per servant. The value range is 1-256. The default value is 256.

This setting is useful in systems with low resources. The server has to be restarted to use the changed setting.

A sample limits element is shown below:

<limits max-connections="256" max-processes="40" />

This element contains the CA certificates used in validation of the host-based and public-key authentication certificates. The element can have the following attributes: http-proxy-url, socks-server-url, cache-size, max-crl-size, external-search-timeout, max-ldap-response-length, ldap-idle-timeout, and max-path-length.

The http-proxy-url attribute defines a HTTP proxy and the socks-server-url attribute defines a SOCKS proxy for making LDAP or OCSP queries for certificate validity.

The address of the proxy is given as the value of the attribute. The format of the address is socks://username@socks_server:port/network/netmask,network/netmask ... (with a SOCKS proxy) or http://username@proxy_server:port/network/netmask,network/netmask ... (with an HTTP proxy).

For example, by setting socks-server-url to "socks://mylogin@socks.ssh.com:1080/192.168.0.0/16,10.100.23.0/24", the host socks.ssh.com and port 1080 are used as your SOCKS server for connections outside of networks 192.168.0.0 (16-bit domain) and 10.100.23.0 (8-bit domain). Those networks are connected directly.

The cache-size attribute defines the maximum size (in megabytes) of in-memory cache for the certificates and CRLs. The allowed value range is 1 to 512; and the default value is 35 MB.

The max-crl-size attribute defines the maximum size (in megabytes) of CRLs accepted. Processing large CRLs can consume a considerable amount of memory and processing power, so in some environments its advisable to limit their size. The allowed value range is 1 to 512; and the default value is 11 MB.

The external-search-timeout attribute defines the time limit (in seconds) for external HTTP and LDAP searches for CRLs and certificates. The allowed value range is 1 to 3600 seconds; and the default value is 60 seconds.

The max-ldap-response-length attribute defines the maximum size (in megabytes) of LDAP responses accepted. The allowed value range is 1 to 512; and the default value is 11 MB.

The ldap-idle-timeout attribute defines an idle timeout for LDAP connections. The validation engine retains LDAP connections and reuses them in forthcoming searches. The connection is closed only after the LDAP idle timeout has been reached. The allowed value range is 1 to 3600 seconds; and the default idle timeout is 30 seconds.

The max-path-length attribute limits the length of the certification paths when validating certificates. It can be used to safeguard the paths or to optimize against the paths getting too long in a deeply hierarchical PKI or when the PKI is heavily cross-certified with other PKIs. Using the attributes requires knowing the upper limit of the paths used in certificate validation. For example:

<cert-validation max-path-length="6">
  <ldap-server address="ldap://myldap.com" port="389" />
  <dod-pki enable="yes" />
  <ca-certificate name="CA 1" file="ca-certificate1.crt" />
</cert-validation>

In the example, the path is limited to six certificates, including the end-entity and root CA certificates. If not specified, the default value is 10. Decrease the value to optimize the validation if the maximum length of the encountered paths in the certificate validation is known.

The cert-validation element can contain sub- elements. You can use maximum one each of elements cert-cache-file, crl-auto- update, and dod-pki, and multiple instances of the other elements.

The validity of a received certificate is checked separately using each of the defined ca-certificate elements in turn until they are exhausted (in which case the authentication fails), or a positive result is achieved. If the certificate is valid, the connections and authentication-methods elements determine whether the certificate allows the user to log in (of course, the correct signature generated by a matching private key is always required in addition to everything else).

A sample cert-validation element is shown below:

<cert-validation http-proxy-url="http://proxy.example.com:800">
 <ldap-server address="ldap.example.com" port="389" />
 <ocsp-responder validity-period="60" url="http://ca.example.com/ocsp-1/" />
 <cert-cache-file file="/var/cert-cache.dat" />
 <crl-auto-update update-before="30" minimum-interval="600" />
 <crl-prefetch interval="1800" url="http://ca.example.com/default.crl" />
 <dod-pki enable="no" />
 <ca-certificate name="exa-ca1" file="/etc/ssh2/exa-ca1.crt" />
 <ca-certificate name="exa-ca2" file="/etc/ssh2/exa-ca2.crt"
     use-expired-crls="3600" />
 <ca-certificate name="testonly-ca" file="/etc/ssh2/testonly-ca.crt"
     disable-crls="yes" />
</cert-validation>    

Each connection element specifies either an allow or deny rule for connections. The element can have three attributes: name, action, and tcp-keepalive.

The word allow or deny is given as a value of the action attribute. By default, if the action attribute is omitted, the connection is allowed.

The name attribute can be used to give an identifier to the connection rule. The value must be a valid XML name beginning with a letter and containing alphanumeric characters or the underscore character without any whitespace. The identifier can be used, for example, in auditing.

The tcp-keepalive attribute defines 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 value must be yes or no. The default is no (do not send keepalives).

The connection element can include one or more selectors, a rekey setting, and cipher and MAC definitions.

A sample connection element that allows connections from a specified IP address range is shown below:

<connection name="conn1" action="allow" tcp-keepalive="yes">
  <selector>
    <ip address="192.168.0.42-192.168.0.82" />
  </selector>
  <rekey seconds="600" bytes="500000000" />
  <cipher name="crypticore128@ssh.com" />
  <mac name="crypticore-mac@ssh.com" />
  <kex name="diffie-hellman-group-exchange-sha256" />
  <hostkey-algorithm name="ssh-dss-sha256@ssh.com" />
</connection>

A sample connection element that denies all connections is shown below. As the element does not contain any selectors, it matches always. This can be used as the last element in the connections element to deny all connections that were not explicitly allowed by the previous elements. (By default, non-matching connections would be allowed.)

<connection action="deny" />

This element specifies the path to the message that is sent to the client before authentication. The path is given as a value of the file attribute. Alternatively, the banner message can be given as the contents of the banner-message element.

Note, however, that the client is not obliged to show this message.

<banner-message file="/etc/ssh2/banner-message">
  This is the server banner message. If file attribute is set,
  this inlined text is ignored, and the file is read instead
  (like in this example).
</banner-message>

This element specifies whether Tectia Server on Unix platforms should check permissions and ownership of the user's key files used for public-key authentication or the directory where they are stored.

The word yes or no is given as a value of the strict attribute. If set to yes, the permissions and ownership of the .ssh2 directory, the .ssh2/authorization file (if used), the .ssh2/authorized_keys directory (if used), and the keys listed in the authorization file or present in the authorized_keys directory are checked.

This is normally desirable because users sometimes accidentally leave their directory or files world-writable, in which case anyone can edit the authorization and key files. The default is yes.

The mask-bits attribute can be used to specify the forbidden permission bits in octal format. This setting controls both the file and directory permissions when used without dir-mask-bits. The default is 022 (group and others must not have the write permission).

The ownership of the checked files and directories must be either root or the user.

The value of mask-bits is given with 3 digits:

<auth-file-modes strict="yes" mask-bits="022" />

The dir-mask-bits attribute can be used to specify the forbidden permission bits in octal format (with 4 digits) for the directory where the user's key files are stored.

If only dir-mask-bits is defined, the value of mask-bits is assumed to be 022, and it is only applied to files.

<auth-file-modes strict="yes" dir-mask-bits="0222"/>

When the server has been configured to use strict mode for public-key authentication, you can define different permissions for the user's key files and for their directory. In this case, define both the mask-bits and dir-mask-bits settings together, for example as follows:

<auth-file-modes strict="yes" mask-bits="222" dir-mask-bits="0222"/>

Each authentication element specifies a chain of authentication methods. It can include one or more selectors and different authentication methods. It may also include other authentication elements.

Defining nesting authentication elements within each other sets the child elements as required (all must be passed for the authentication to be successful). Setting multiple authentication methods at the same level sets them as optional (one of the methods must be passed for the authentication to be successful).

The authentication elements are read in top-down order. For elements on the same level, the first matching element is used and the remaining elements are ignored. If the element has nested child elements, they are matched next using the same procedure.

In the authentication element, the action attribute takes values allow or deny. The allow value means that users who match a selector will be allowed into the system. The deny value means that access will be denied from users who match a selector. By default, if the action attribute is omitted, authentication is allowed.

If an authentication chain ends in a deny action, or if the user does not match to any selectors in the authentication elements, the user is not allowed to log in.

	Note
	Note that the behavior has changed in Tectia Server 5.1. In Tectia Server 5.0, a non-matching user was allowed the default authentication methods.

In a nested chain of authentication elements, it is possible, for example, to set the parent method to deny authentication and a child element with a selector to allow authentication. If the user matches the selector and successfully completes the authentication method(s), login is allowed.

For more information on using authentication chains, see Configuring User Authentication Chains.

The authentication element can additionally take a set-group attribute, which sets a group for the users that pass the particular authentication chain. The group definition can be later used in the services element.

If set-group is used here, it overrides any group definitions in the services element. See the section called “The services Block”.

The authentication name can be optionally given as an attribute. The value of name must be a valid XML name beginning with a letter and containing alphanumeric characters or the underscore character without any whitespace. The authentication name can be used, for example, in auditing.

	Caution
	Consider carefully before putting an empty authentication element in the ssh-server-config.xml file. It will allow the matching users (everyone, if no selectors are used) to log in without authentication.

Creates a group that can be used as a basis for restricting services. Groups are defined based on selectors.

The name must be given as an attribute. The value of name must be a valid XML name beginning with a letter and containing alphanumeric characters or the underscore character without any whitespace.

If the user was already put to a group during authentication using the set-group attribute, the group definitions in the services element are ignored.

Sample group elements are shown below:

<!-- Remote access. -->
<group name="remote-access">
  <selector>
    <interface address="192.0.2.62" />
  </selector>
</group>

<!-- Backup. -->
<group name="backup">
  <selector>
    <user name="backup" />
  </selector>
</group>

<!-- Password change needed. -->
<group name="passwd-change">
  <selector>
    <user-password-change-needed />
  </selector>
</group>

This element defines a rule for the specified group of users. Rules can be used to restrict the services and commands the server allows to the users. The element can have three attributes: group, idle-timeout, and print-motd.

The rules are read in order, and the first rule that matches the user's group is used. The match must be exact. No wildcards are allowed in the group attribute. If no group is specified, the rule matches to all users.

The idle-timeout attribute sets the idle timeout limit in seconds. If the connection (all channels) has been idle this long, the connection is closed. The default is 0 (zero), which disables idle timeouts.

The print-motd attribute defines whether the message of the day (/etc/motd) is printed when a user logs in interactively to a Unix server. The value must be yes or no. The default is yes.

Each rule can contain environment, terminal, subsystem, tunnel-agent, tunnel-x11, tunnel-local, tunnel-remote, and command elements.

An empty rule allows the specified group to perform all actions.

	Note
	The default (unnamed) rule allows all users access to all services. Keep the default rule as the last rule, so it will match to users that are not set in any group. Remember to edit the rule according to your security policy.