Replaced with the value of the environment variable if one has been defined. The variable is matched case-insensitively. If the variable is not defined, the string '%VARIABLENAME%' is the result.

Replaced with the value of the environment variable if one has been defined. The variable is matched case-sensitively on Unix and case-insensitively on Windows. If the variable is not defined, it is replaced with an empty string.

Replaced with the value defined for '$VARIABLENAME' with the 'text' appended to it.

Replaced with the value defined for '$VARIABLENAME', or replaced with the 'default_value' if the variable is not set.

Replaced with the currently logged in user name.

Replaced with the currently logged in user name in short format, i.e. without the domain part. Available on Windows.

Replaced with the group name of the currently logged in user.

Replaced with the home directory defined for the currently logged in user.

Replaced with the user identifier defined for the currently logged in user.

Replaced with the group identifier defined for the currently logged in user.

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 cryptographic library can be used. The library name is given as a value of the mode attribute. By default, standard cryptographic libraries are used. The OpenSSL cryptographic library is used in the FIPS mode.

<crypto-lib mode="standard" />

	Note
	The FIPS library is not available on z/OS.

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

This element defines public-key infrastructure (PKI) settings used for validating remote server authentication certificates. The element can have the following attributes: end-point-identity-check, default-domain, http-proxy-url, socks-server-url and max-path-length.

The end-point-identity-check attribute specifies whether the client will verify the server's host name or IP address against the Subject Name or Subject Alternative Name (DNS Address) specified in the server host certificate. The default value is yes. If set to no, the fields in the server host certificate are not verified and the certificate is accepted based on the validity period and CRL check only.

	Caution
	Setting end-point-identity-check="no" is a security risk. Then anyone with a certificate issued by the same trusted certification authority (CA) that issues the server host certificates can perform a man-in-the-middle attack on the server.

Alternatively, if set to ask, the user can decide to either cancel or continue establishing the connection in case that the server's host name does not match the one in the certificate.

The default-domain attribute can be used when the end-point identity check is enabled. It specifies the default domain part of the remote system name and it is used if only the base part of the system name is available. The default-domain is appended to the system name if it does not contain a dot (.).

If the default domain is not specified, the end-point identity check fails, for example, when a user tries to connect to a host "rock" giving only the short host name and the certificate contains the full DNS address "rock.example.com".

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

The address of the server 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 server) or http://username@proxy_server:port/network/netmask,network/netmask ... (with an HTTP proxy).

For example, to make the SOCKS server use host socks.ssh.com and port 1080 for connections outside of networks 192.196.0.0 (16-bit domain) and 10.100.23.0 (8-bit domain), and to get these networks connected directly, set socks-server-url as follows:

"socks://mylogin@socks.ssh.com:1080/192.196.0.0/16,10.100.23.0/24"

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 multiple ldap-server, ocsp-responder, crl-prefetch elements, one dod-pki element, and multiple ca-certificate and key-store elements. The elements have to be in the listed order.

An example of a certificate validation configuration is shown below:

<cert-validation  end-point-identity-check="yes" 
                  default-domain="example.com"
                  http-proxy-url="http://proxy.example.com:8080">
  <ldap-server    address="ldap://ldap.example.com:389" />
  <ocsp-responder url="http://ocsp.example.com:8090" 
                  validity-period="0" /> 
  <crl-prefetch   url="file:///full.path.to.crlfile" 
                  interval="1800" />
  <dod-pki        enable="no" />
  <ca-certificate name="ssh_ca1"
                  file="ssh_ca1.crt"
                  disable-crls="no"
                  use-expired-crls="100" />
</cert-validation>         

This element defines settings for user public-key and certificate authentication.

Under the <general> element, there can be one <key-stores> instance which in turn can have any number of <key-store>, <user-keys>, and <identification> elements, and the order of the elements is free.

Special variables and environment variables can be used when defining the values for the elements. The following variables can be used and they will be expanded as follows:

Also environment variables are replaced with their current values. For example it is possible to use strings $HOME or %HOME% to expand to user's home directory (if environment variable HOME is set).

	Note
	Short alias names (for example, %U) are case-sensitive and long alias names (for example, %USERNAME%) are case-insensitive.

	Note
	This element is deprecated starting from Tectia client tools for z/OS version 6.1.4.

This element is supported in configuration for backwards compatibility and used only if the policy attribute of the server-authentication-methods/auth-server-publickey element under default-settings or profiles/profile is not defined. In this case, the host key policy is interpreted based on the values of this option and the host-key-always-ask and accept-unknown-host-keys options. See auth-server-publickey for details.

	Note
	This element is deprecated starting from Tectia client tools for z/OS version 6.1.4.

This element is supported in configuration for backwards compatibility and used only if the policy attribute of the server-authentication-methods/auth-server-publickey element under default-settings or profiles/profile is not defined. In this case, the host key policy is interpreted based on the values of this option and the strict-host-key-checking and accept-unknown-host-keys options. See auth-server-publickey for details.

	Note
	This element is deprecated starting from Tectia client tools for z/OS version 6.1.4.

This element is supported in configuration for backwards compatibility and used only if the policy attribute of the server-authentication-methods/auth-server-publickey element under default-settings or profiles/profile is not defined. In this case, the host key policy is interpreted based on the values of this option and the strict-host-key-checking and host-key-always-ask options. See auth-server-publickey for details.

	Caution
	Consider carefully before enabling this option. Disabling the host-key checks makes you vulnerable to man-in-the-middle attacks.

This element can be used to change the storage location of the user-specific configuration files away from the default which is $HOME/.ssh2/ on Unix, and "%APPDATA%\SSH" on Windows. It can be used for example, if you want to store all client-side configurations to a centralized location.

When this element is added to the global configuration file, the Connection Broker reads the following user-specific files in the defined location:

	Note
	Stop all existing SSH applications before modifying the user-config-directory setting in the Connection Broker configuration. The user-config-directory setting affects all Tectia products running on the same host, for example Tectia Client and Tectia ConnectSecure.

The user-config-directory option takes an attribute path, whose value can be either a directory path or one of the following variables:

The default is %USER_CONFIG_DIRECTORY%. This variable refers to the user-specific configuration directory: $HOME/.ssh2 on Unix, and %APPDATA%\SSH on Windows. The %USER_CONFIG_DIRECTORY% variable cannot be used in other settings.

On Unix, this element can be used to enable checking of file access permissions defined for the global and user-specific configuration files, and for the private keys files. If the permissions are not as expected, the Connection Broker will refuse to start, or to use certain private keys.

By default this setting is disabled. On Windows, this element has no effect.

The file permissions are checked differently, if the file-access-control element is set in both the global and user configuration files, or just in one of them.

In the table: "no" means file-access-control enable="no". The "-" sign means that the setting is not defined in the file at all.

When the file access permissions are checked, the controls are applied as follows:

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 can be used to specify locations for storing the host keys of known server hosts, and to define the storage format of the host key files. If no known-hosts directories are specified, the known host keys are stored to the default directories. See the section called “Files” for the default locations. On z/OS (only), this element can contain key-store elements.

This element can be used:

The server host keys are searched in the known-hosts paths in the order they are specified in the configuration. The settings of the last defined known-hosts element are used when storing new host keys.

If you define any known-hosts file settings, the default OpenSSH files will be overridden. So if you wish to make the Connection Broker use both the default OpenSSH locations and other locations specified in the configuration, you need to specify all the locations separately.

You can define several known-hosts elements, and each of them can contain one or several attributes: path, directory, file and filename-format.

The path attribute requires a full path to the known-hosts file or directory as the value. For example:

<known-hosts path="/u/username/.ssh/known_hosts" />
<known-hosts path="/etc/ssh2/hostkeys" />
<known-hosts path="/u/username/.ssh2/hostkeys" />
<known-hosts path="/h/username/hostkeys" filename-format="plain" />

The directory attribute is used to define that known host keys are saved to a non-default directory. Enter the complete path to the directory as the value. If the defined directory does not exist, it will be created during the first connection attempt. If a file is found in its place, the connection will be made but the host key will not be stored, and the user gets a warning about it. The filename-format attribute can be used together with the directory setting to define in which format the host key files will be stored. Example of the directory attribute:

<known-hosts directory="<path_to_dir>/MyKEYS" 
             filename-format="plain" />

The path or directory (whichever is present) defined in the last known-hosts element in the configuration file will be used when storing new known host keys. If both attributes are present in the last known-hosts element, the location specified in the directory attribute will be used.

The file attribute is used to point to an OpenSSH-style known_hosts file. Enter the complete path to the file as the value. If a directory is found in its place, it is considered an error, and the connection attempt will fail. In case the known-hosts element only contains the file attribute, and the defined OpenSSH known_hosts file exists, the received host keys are searched first in the defined file, and if not found there, the search continues in the default Tectia-specific locations.

Example of the file attribute:

<known-hosts file="<path_to_file>/.ssh2/openSSH_keys" />

An empty file or path attribute will disable the handling of the OpenSSH known_hosts file:

<known-hosts file="" />
or
<known-hosts path="" />

The filename-format attribute defines the format in which new host key files are stored. The filename-format attribute is only relevant for the last specified known-hosts element and for the default directory.

The filename-format attribute takes the values: hash (default), plain, and default (equals to hash).

With value hash, the host key files will be stored in format: keys_<hash>, for example "keys_182166d2efe5a134d3fb948646e0b48f780bff6c".

With value plain, the file name format will be key_<port>_<hostname>.pub, where <port> is the port the Secure Shell server is running on and <hostname> is the host name you use when connecting to the server; for example "key_22_my.example.com.pub".

Setting <known-hosts filename-format="plain" /> changes the storage format of host key files for the next known-hosts elements or for the default storage location if no other known-hosts elements are present.

The filename-format="default" alternative can be used as the last option when the same known-hosts element is used to define several locations for the host keys some of which store the keys in plain format.

For more information on the host key storage formats, see Host Key Storage Formats.

This element is reserved for future use.

This element defines the ciphers that the client will propose to the server. The ciphers element can contain multiple cipher elements.

The ciphers are tried in the order they are specified.

<ciphers>
  <cipher name="aes128-cbc" />
  <cipher name="3des-cbc" />
</ciphers>

This element defines the MACs that the client will propose to the server. The macs element can contain multiple mac elements.

The MACs are tried in the order they are specified.

<macs>
  <mac name="hmac-sha1" />
</macs>

This element defines the key exchange methods (KEXs) that the client will propose to the server. The kexs element can contain multiple kex elements.

The KEXs are tried in the order they are specified.

<kexs>
   <kex name="diffie-hellman-group1-sha1" />
   <kex name="diffie-hellman-group14-sha256@ssh.com" />
</kexs>

This element defines the host key signature algorithms used for server authentication. The algorithms that will be used are those that are defined in both Tectia Server and Connection Broker configuration files. This way the use of only certain algorithms, such as SHA-2, can be enforced by the server. The hostkey-algorithms element can contain multiple hostkey-algorithm elements.

The hostkey algorithms are tried in the order they are specified. Exception: If a host key of a server already exists in the host key store of the client, its algorithm is preferred.

<hostkey-algorithms>
   <hostkey-algorithm name="ssh-dss-sha512@ssh.com" />
   <hostkey-algorithm name="ssh-rsa-sha224@ssh.com" />
</hostkey-algorithms>

This element specifies the number of transferred bytes after which the key exchange is done again. The value "0" turns rekey requests off. This does not prevent the server from requesting rekeys, however. The default is 1000000000 (1 GB).

<rekey bytes="1000000000" />

This element specifies the authentication methods that are requested by the client-side components. The authentication-methods element can contain one of each: auth-hostbased, auth-password, auth-publickey, auth-gssapi, and auth-keyboard-interactive. Alternatively, you can specify multiple authentication-method elements. The order of these elements is free.

The authentication methods are tried in the order the auth-* or authentication-method elements are listed. This means that the least interactive methods should be placed first.

When several interactive authentication methods are defined as allowed, Tectia client tools for z/OS will alternate between the methods and offers each of them in turn to the server in case the previous method failed.

An example of authentication-methods configuration is shown below:

<authentication-methods>
  <auth-hostbased>
    <local-hostname name="host.example.com" />
  </auth-hostbased>
  <auth-gssapi allow-ticket-forwarding="yes"/>
  <auth-publickey>
    <key-selection policy="interactive-shy">
      <public-key type="plain" />
    </key-selection>
  </auth-publickey>
  <auth-keyboard-interactive />
  <auth-password>
    <password file="/path/filename" />
  </auth-password>
</authentication-methods>

This element specifies the host's default domain name (as name). This element is used to make sure the fully qualified domain name (FQDN) of the client host is transmitted to the server when using host-based user authentication.

	Note
	This element is not used by Tectia Server 6.4 for IBM z/OS. Instead the DefaultDomain keyword of ssh2_config is used for the same purpose. See Tectia Server for IBM z/OS Administrator Manual for more information.

This element specifies whether the client sends the data compressed (PUT operation). When activated, compression is applied on-the-fly to all data sent out through the connection and on all channels in it.

The name of the compression algorithm and the compression level can be given as attributes. The name attribute can be defined as none (compression not used) or zlib, currently the only supported algorithm. By default, compression is not used.

For zlib compression, the level attribute can be given an integer from 0 to 9. The default compression level is 6, when compression is activated but no level is given (or level is set to 0).

Example: to activate maximum level compression of sent data, make the following setting:

<compression name="zlib" level="9" />

Compression can also be activated per connection with command line tools. For information, see the sshg3(1), sftpg3(1) and scpg3(1) man pages.

Note that this compression setting does not affect received data (GET operations), but their compression is defined on the Secure Shell server. Tectia Server always uses compression level 6.

This element defines rules for HTTP proxy or SOCKS servers the client will use for connections. It has a single attribute: ruleset.

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 are used: 1080 for SOCKS and 80 for HTTP.

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 host name which may be a regular expression containing the characters "*" and "?" and a port range:

name_pattern[:port_range]

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

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

This element specifies how long idle time (after all connection channels are closed) is allowed for a connection before automatically closing the connection. The time is given in seconds. The type is always connection.

The default setting is 5 seconds. Setting a longer time allows the connection to the server to remain open even after a session (for example, sshg3) is closed. During this time, a new session to the server can be initiated without re-authentication. Setting the time to 0 (zero) terminates the connection immediately when the last channel to the server is closed.

<idle-timeout time="5" />

This element specifies a timeout for the TCP connection. When this setting is made, connection attempts to a Secure Shell server are stopped after the defined time if the remote host is down or unreachable. This timeout overrides the default system TCP timeout, and this timeout setting can be overridden by defining a tcp-connect-timeout setting per connection profile (in the profiles settings) or per connection (on command line).

The time is given in seconds. The factory default is 5 seconds. Value 0 (zero) disables this feature and the default system TCP timeout will be used.

<tcp-connect-timeout time="5" />

This element specifies an interval for sending keepalive messages to the Secure Shell server. The time value is given in seconds. The default setting is 0, meaning that the keepalive messages are disabled.

<keepalive-interval time="0" />

In the Connection Broker configuration file, the exclusive-connection element can be used to specify that a new connection is opened for each new channel. This setting takes one attribute enable, with value yes or no. The default is no, meaning that open connections are reused for new channels requested by a client.

On z/OS, the SOCKS Proxy always uses the exclusive connection type, meaning it opens a new connection for each new channel. This element is not needed in the SOCKS Proxy configuration file, and irrespective of the value set by the user, the SOCKS Proxy always interprets this setting as: exclusive-connection enable="yes".

This element defines whether the server banner message file (if it exists) is visible to the user before login. The word yes or no is given as the value of the visible attribute. The default is yes.

To eliminate server banners:

<server-banners visible="no" />

This element contains forward elements that define whether X11 or agent forwarding (tunneling) are allowed on the client side.

	Note
	X11 forwarding is not available on z/OS.

An example forward configuration, which denies X11 forwarding and allows agent forwarding globally, is shown below:

<forwards>
  <forward type="x11" state="denied" />
  <forward type="agent" state="on" />
</forwards>

This element is reserved for future use.

This element contains environment elements which define the environment variables to be passed to the server from the client side. The environment variables are then set on the server when requesting a command, shell or subsystem.

Note that the server can restrict the setting of environment variables.

You can override the remote environment settings made in the configuration file if you use the sshg3 command with the following arguments on the command-line client: --remote-environment or --remote-environment-format

For information on the command-line options, see sshg3(1).

This server-authentication-methods element can be used to force the Connection Broker to use only certain methods in server authentication. This element can contain auth-server-publickey and auth-server-certificate elements (one of each). The order of these elements is free.

If only auth-server-certificate is specified, server certificate is needed. If no server certificate is received, connection fails.

If only auth-server-publickey is specified, (plain) server public key is needed. If no server public key is received, connection fails.

If both auth-server-certificate and auth-server-publickey are specified, server certificate is used if present. Otherwise server public key is used.

An example server-authentication-methods element is shown below:

<server-authentication-methods>
  <auth-server-publickey policy="ask" />
  <auth-server-certificate />
</server-authentication-methods>

This setting defines whether the AuthenticationSuccessMsg messages are output. The authentication-success-message element takes attribute enable with value yes or no. The default is yes, meaning that the messages are output and logged.

This setting defines how the sftpg3 client behaves when transferring files. The sftpg3-mode element takes attribute compatibility-mode with the following values:

The recursion depth can be overridden by using the sftpg3 client's commands get/put/mget/mput with command-line option --max-depth="LEVEL". For more information, see sftpg3(1).

This element defines how the Tectia terminal behaves when the user selects text with double-clicks. The element takes one attribute: selection-type, whose value can be:

select-words - double-clicking selects one word at a time, space and all punctuation characters are used as delimiters. This is the default.

select-paths - selects strings of characters between spaces, meaning a selection is extended over characters \/.-_, so that for example a path to a file can be selected by double-clicking anywhere in the path.

This element defines whether Tectia terminal repeats audible notifications from the destination server. This option is only applied to connections with Unix servers. The element takes one attribute, bell-style, whose value can be:

none - no audible notifications are used

pc-speaker - the user's PC speakers beep when an audible notification is indicated by the destination server

system-default - the Tectia terminal sounds the default alerts defined in the system on the destination server. This is the default.

This element defines that also the Tectia terminal window is to be closed while disconnecting from a server session by pressing CTRL+D. The element takes one attribute, enable, whose value can be yes or no. The default is no meaning that CTRL+D closes only the server connection but the Tectia terminal window remains open.

This setting defines whether the command line clients should suppress warnings, error messages and authentication success messages. The quiet-mode element takes attribute enable with value yes or no. The default is no, meaning that the errors and messages are output and logged.

The quiet-mode element affects command line tools scpg3, sshg3, and sftpg3. Enabling the quiet mode here with setting quiet-mode enable="yes" is the same as running these clients with option -q. Note that the -q command line parameter will take priority over the quiet-mode element set in this configuration file.

The checksum element can be used to define a default setting for comparing checksums. This default overwrites the factory setting that checksums are not checked for files smaller than 32kB.

The checksum element takes attribute type, whose value can be:

yes|YES - MD5 checksums are checked on files larger than 32kB. This is the default value.

no|NO - checksums are not used.

md5|MD5 - only MD5 checksums are checked on files larger than 32kB. When the --fips parameter is set with the command line clients scpg3 and sftpg3, this hash is not used.

sha1|SHA1 - only SHA1 checksums are checked on files larger than 32kB. When the --fips parameter is set with the command line clients scpg3 and sftpg3, this hash is used.

md5-force|MD5-FORCE - MD5 checksums are forced, except when the --fips parameter is set with the command line tools scpg3 and sftpg3.

sha1-force|SHA1-FORCE - SHA1 checksums are forced on all files.

checkpoint|CHECKPOINT - checkpointing is forced on large files that are transferred one by one.

	Note
	If the Connection Broker is started in FIPS mode and the md5 attribute is defined in the configuration file, but scpg3 or sftpg3 are not started with the --fips parameter, then md5 is used.

Note that checksums can also be defined with the command line clients scpg3 and sftpg3, or with environment variables. The order of priority of the three checksum settings (in case they are different) is as follows, the later one always overwrites the previous value:

The address-family element defines the IP address family. Give the address family as the value of the type attribute. Tectia client tools for z/OS will operate using IPv4 (inet) addressing, IPv6 (inet6), or both (any). The default value for type is any.

The profile element defines a connection profile. It has the following attributes: id, name, host, port, protocol, host-type, connect-on-startup, user, and gateway-profile.

The profile id must be a unique identifier that does not change during the lifetime of the profile.

An additional name can be given to the profile. This is a free-form text string. The name can be used for connecting with the profile on the command line, so define a unique name for each profile.

The host attribute defines the address of the Secure Shell server host and it is a mandatory setting. The address can be either an IP address or a domain name. The value host="*" can be used to prompt the user to enter the host address when starting the session.

An empty value host="" can be used when the profile is used with transparent TCP or FTP tunneling or FTP-SFTP conversion and the host name is taken from the application (filter-engine/rule[@hostname-from-app="yes"]). See rule for details.

The port is a mandatory setting. It defines the port number of the Secure Shell server listener. The default port is 22.

The protocol is a mandatory setting. It defines the used communications protocol. Currently the only allowed value is secsh2.

If you want to make the connection specified by the profile automatically when the Connection Broker is started, set the value of the connect-on-startup attribute to yes. In this case, give also the user attribute (the user name the connection is made with). You also need to set up some form of non-interactive authentication for the connection.

The host-type attribute sets the server type for ASCII (text) file transfer. This specifies the line break convention that is used for ASCII files. The default value is default, meaning that the line break convention is determined by the local platform. If the client is running on Windows, Windows compatible line breaks (CR + LF, '\r\n') are used. If the client is running on any other platform, Unix compatible line breaks (LF, '\n') are used. Other possible values for host-type are windows (for Windows remote host) and unix (for Unix remote host). Define the value if you are using any other server than Tectia Server.

For FTP-SFTP conversion, set the server type here according to your target server to transfer ASCII files with correct line break convention.

The user attribute specifies the user name for opening the connection. The value "%USERNAME%" can be used to apply the user name of the currently logged in user. The value user="*" can be used to prompt the user to enter the user name when logging in. When the user attribute is not defined, the user name defined in the default connection settings will be used.

An empty value user="" can be used when the profile is used with transparent FTP tunneling or FTP-SFTP conversion and the user name is taken from the application (filter-engine/rule[@username-from-app="yes"]). See rule for details.

The gateway-profile attribute can be used to create nested tunnels. The tunnels defined under the local-tunnel element of the profile, and the tunnels defined under filter-engine and static-tunnels that refer to the profile can be nested. The profile name through which the connection is made is given as the value of the attribute. The first tunnel is created using the gateway host profile and from there the second tunnel is created to the host defined in this profile.

An example connection profile is shown below:

<profile name="rock"
         id="id1"
         host="rock.example.com"
         port="22"
         connect-on-startup="no"
         user="doct">

  <hostkey file="key_22_rock.pub">
  </hostkey>

  <authentication-methods>
    <auth-publickey />
    <auth-password />
  </authentication-methods>

  <server-authentication-methods>
    <auth-server-publickey policy="strict" />
  </server-authentication-methods>

  <server-banners visible="yes" />

  <forwards>
    <forward type="agent" state="on" />
    <forward type="x11" state="on" />
  </forwards>

  <tunnels>
    <local-tunnel type="tcp"
                  listen-port="143"
                  dst-host="imap.example.com"
                  dst-port="143"
                  allow-relay="no" />
  </tunnels>

  <remote-environment>
    <environment name="FOO" value="bar" />
    <environment name="QUX" value="%Ubaz" format="yes" />
    <environment name="ZAPPA" value="%Ubaz" />
  </remote-environment>

</profile>

The tunnel element specifies a static tunnel. It has the following attributes: type, listen-port, listen-address, dst-host, dst-port, allow-relay, and profile.

The type attribute defines the type of the tunnel. This can be either tcp, ftp, or socks-proxy.

The listen-port attribute defines the listener port number on the local client.

The listen-address attribute can be used to define which network interfaces on the client should be listened. Its value can be an IP address belonging to an interface on the local host. Value 0.0.0.0 listens to all interfaces. The default is 127.0.0.1 (localhost loopback address on the client). Setting any other value requires that allow-relay="yes".

For address-family option inet6, the default listen address is ::1. To listen on all interfaces, specify ::. For address-family option any, the listen address is both 127.0.0.1 and ::1 by default; to listen on all interfaces, specify ::.

The dst-host and dst-port attributes define the destination host address and port. The value of dst-host can be either an IP address or a domain name. The default is 127.0.0.1 (localhost = server host).

The allow-relay attribute defines whether connections to the listened port are allowed from outside the client host. The default is no.

The profile attribute specifies the connection profile ID that is used for the tunnel.

The network element specifies a "location" where Tectia client tools for z/OS is running. By using the network element, you can implement location-awareness for Tectia client tools for z/OS. It has five attributes: id, address, domain, ip-generate-start and ip6-generate-start.

The id attribute specifies a unique identifier for the network element. The address attribute specifies the address of the network. It can be missing or empty, in which case it is not used. The domain attribute contains the domain name of the computer. It can also be missing or empty, in which case it is not used. The ip-generate-start attribute defines the start address of the pseudo IPv4 space. If it is defined here, it overrides the ip-generate-start attribute of the filter-engine element. The ip6-generate-start attribute is similar to ip-generate-start, but it defines the start address of the pseudo IPv6 address space.

	Note
	The dns element exists for backward-compatibility reasons. Currently the rule element is used for the same settings.

The dns element creates a DNS rule for the filter engine. It has six attributes: id, network-id, application, host, ip-address, and pseudo-ip. For their descriptions, see rule below.

	Note
	The filter element exists for backward-compatibility reasons. Currently the rule element is used for the same settings.

The filter element specifies an action for a connection. It has the following attributes: dns-id, ports, action, profile-id, destination, destination-port, fallback-to-plain.

The dns-id attribute is a reference to a dns element.

For the descriptions of the other attributes, see rule below.

The rule element specifies how a filtered connection will be handled. It has the following attributes: application, host, ip-address, pseudo-ip, ports, action, profile-id, destination, destination-port, username, hostname-from-app, username-from-app, fallback-to-plain, show-sftp-server-banner.

The application attribute can be used to specify one or more applications to which the rule is applied. This can be a regular expression using the egrep syntax. For information on the syntax, see Appendix C.

The host attribute specifies a target host name. It can be a regular expression using the egrep syntax.

The ip-address attribute specifies the target host IP address. It can be a regular expression using the egrep syntax. In this case the Connection Broker does the string matching with the assumption that the IP address is written in its canonical form. If both the host name and the IP address are defined, the host attribute takes precedence and the ip-address attribute is ignored.

The pseudo-ip setting has the following effects when the ip-address is left empty and the host matches:

The ports attribute can be a single port or a range. A range is specified with a hyphen between two integers (for example "21-25").

The action attribute specifies the action to be done when a filter matches. Its value can be DIRECT, BLOCK, TUNNEL, FTP-TUNNEL, or FTP-PROXY.

The profile-id attribute can be used to specify the connection profile that defines the connection settings.

If the profile-id attribute is left empty and hostname-from-app="yes" is specified, the Secure Shell connection is made to the server specified by the client application using default settings. If a profile-id is specified and also hostname-from-app="yes" is specified, or the referred profile has * (an asterisk) or empty as the value of the host attribute, the Secure Shell connection is made to the server specified by the client application using the profile settings.

The destination and destination-port attributes can be used to define a static destination address and port number that will be used as the end point of the connection instead of the original address and port given by the application.

The username attribute can be used to define the user name used for connecting to the Secure Shell server, or you can define the path from where the Connection Broker should retrieve the user name.

The hostname-from-app attribute defines whether the Connection Broker should extract the Secure Shell server's host name from data sent by the application, or use a Secure Shell server defined by the connection profile in profile-id. The value is yes or no, and the default is no.

When hostname-from-app="no", the tunnel or FTP-SFTP conversion will be created to the Secure Shell server specified in the connection profile referred in the profile-id attribute. Note that with transparent tunneling, the connection from the Secure Shell server to the final destination application will be unsecured and in plaintext. To achieve end-to-end security, the Secure Shell server should reside on the same host as the application.

When hostname-from-app="yes", the tunnel or FTP-SFTP conversion will be created to the destination server specified by the application. This setting can be used with both FTP and TCP tunneling and FTP-SFTP conversion. When using hostname-from-app="yes", it is no longer necessary to create a separate connection profile for each destination host. Note that this requires that a Secure Shell server is installed to each destination server (or, in the case of tunneling, that fallback-to-plain is enabled to allow direct connections to those servers that do not have Secure Shell installed).

The username-from-app attribute defines whether the FTP tunneling or FTP-SFTP conversion extracts the user name from data sent by the FTP application. The value is yes or no. The default is no.

When username-from-app="yes", the user name received from the FTP client application is used. This setting can be used with FTP tunneling and FTP-SFTP conversion. This setting will override any user name settings made in a related connection profile. When username-from-app="no", the user name is taken from the connection profile defined with the profile-id attribute.

In transparent tunneling, the fallback-to-plain attribute can be used to define whether a direct (unsecured) connection is used if creating the tunnel fails. The default value is no. Normally, when creating the secure tunnel fails when applying a filter rule, the Connection Broker will return an error about not being able to establish a connection.

	Note
	Do not enable the fallback-to-plain and pseudo-ip options at the same time. If they both are enabled, and a secure connection fails, the application will try a direct connection with the pseudo IP, which will not work.

In FTP-SFTP conversion, if the target SFTP server is configured to send a banner to the client, the show-sftp-server-banner attribute can be used to make the Connection Broker forward the SFTP server banner to the FTP client. The allowed values for show-sftp-server-banner are yes and no. The default value is no (the SFTP server banner is not forwarded to the FTP client).

	Note
	If you have made changes to the Connection Broker default configuration, make sure that showing the server banner is enabled (server-banners visible="yes") in the default-settings or in profiles.

	Note
	Sending the SFTP server banner to the FTP client will cause an extra connection opening to the target SFTP server for retrieving the banner message.

In case of a failure in retrieving the banner message from the target SFTP server, the banner that Connection Broker forwards to the FTP client includes an error description, a default banner, and the following text:

Can't fetch banner from SFTP Server

This element specifies the log target for auditing. By default, the broker does not log anything. This element can be used to direct log data to a file or syslog.

The log-target element can have file and type as attributes.

The type attribute specifies the logging facility where the audit data is output to. The value can be file, syslog or discard.

The file attribute sets the file system path where the audit data is written to. If the type attribute has syslog or discard set, the file attribute is not allowed.

This element sets the severity and facility of different logging events. The events have reasonable default values, which are used if no explicit logging settings are made. This setting allows customizing the default values.

The element can also contain one or more log-target elements. When defined here, the log-target element will override the definition given in the logging/log-target.

For the events, facility and severity can be set as attributes. The events itself should be listed inside the log-events element.

The facility can be normal, daemon, user, auth, local0, local1, local2, local3, local4, local5, local6, local7, or discard. Setting the facility to discard causes the server to ignore the specified log events.

The severity can be informational, notice, warning, error, critical, security-success, or security-failure.

Any events that are not specifically defined in the configuration file will use the default values. The defaults can be overridden for all remaining events by giving an empty log-events element after all other definitions and by setting a severity value for it.

In the names of log events, the characters '*' and '?' can be used as wildcards.