![]() | ![]() | |
![]() | ||
![]() |
ssh-broker-config
ssh-broker-config — SSH Connection Broker configuration file format
The Connection Broker configuration file ssh-broker-config.xml
is used by SSH Tectia Client and ConnectSecure on Unix and Windows and by SSH Tectia client tools on z/OS and z/Linux. It must be a valid XML file that follows the ssh-broker-ng-config-1.dtd
document type definition.
Connection Broker Files
The Connection Broker reads three configuration files (if all are available):
The
ssh-broker-config-default.xml
file is read first. It holds the factory default settings. It is not recommended to edit the file, but you can use it to view the default settings.This file must be available and correctly formatted for the Connection Broker to start.
Next, the Connection Broker reads the global configuration file. The settings in the global configuration file override the default settings.
If the global configuration file is missing or malformed, the Connection Broker will start normally, and will read the user-specific configuration file, instead. A malformed global configuration file is ignored and the default settings or user-specific settings, if they exist, are used instead.
Last, the Connection Broker reads the user-specific configuration file, if it is available. The settings in the user-specific configuration file override the settings in the global configuration file, with the following exceptions:
The following settings from the user-specific configuration are combined with the settings of the global configuration file:
In
general
element, thekey-stores
andcert-validation
settingsIn
profiles
element, all settingsIn
static-tunnels
element, all settings.
If a connection profile with the same name has been defined in both the global configuration file and user-specific configuration file, the latter one is used.
If the
crypto-lib
,strict-host-key-checking
,host-key-always-ask
, andaccept-unknown-host-keys
elements have different values in the global and user-specific configuration, the more secure of the values is used.If the
filter-engine
settings have been defined in the global configuration file, and the file is valid (not malformed), those settings are used, and anyfilter-engine
settings made in the user-specific configuration file are ignored.
If the user-specific configuration file is missing, the Connection Broker will start using the previously read configuration files. However, if a user-specific configuration exists but is malformed, the Connection Broker will not start at all.
On Unix, the default configuration file locations are as follows:
the default configuration:
/etc/ssh2/ssh-tectia/auxdata/ssh-broker-ng/ssh-broker-config-default.xml
the global configuration:
/etc/ssh2/ssh-broker-config.xml
the user-specific configuration:
$HOME/.ssh2/ssh-broker-config.xml
the XML DTD:
/etc/ssh2/ssh-tectia/auxdata/ssh-broker-ng/ssh-broker-ng-config-1.dtd
On Windows, the default configuration file locations are as follows:
the default configuration:
"
C:\Program Files\SSH Communications Security\SSH Tectia\SSH Tectia AUX\ssh-broker-ng\ssh-broker-config-default.xml
"the global configuration:
"
C:\Program Files\SSH Communications Security\SSH Tectia\SSH Tectia Broker\ssh-broker-config.xml
"the user-specific configuration: "
%APPDATA%\SSH\ssh-broker-config.xml
"the XML DTD:
"
C:\Program Files\SSH Communications Security\SSH Tectia\SSH Tectia AUX\ssh-broker-ng\ssh-broker-ng-config-1.dtd
"
The following sections describe the options available in the Connection Broker configuration file. For more information on the syntax of the configuration file, see Appendix B.
Environment Variables
Two kinds of environment variables can be used in the Connection Broker configuration file. In addition to the system-level environment variables, you can use special variables that are SSH Tectia specific. The environment variables take precedence over the special variables. So if an environment variable and a special variable have the same name, the environment variable will be used.
All alphanumeric characters and the underscore '_' sign are allowed in environment variables. The variable name ends to the first character that is not allowed.
You can define for example file or directory paths with environment variables, and they will be expanded to their values as explained below.
- %VARIABLENAME%
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.- $VARIABLENAME
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.
- ${VARIABLENAME}
text
Replaced with the value defined for '
$VARIABLENAME
' with the 'text
' appended to it.- ${VARIABLENAME:-
default_value
} Replaced with the value defined for '
$VARIABLENAME
', or replaced with the 'default_value
' if the variable is not set.
The SSH Tectia specific special variables are:
- %U or %username%
Replaced with the currently logged in user name.
- %username-without-domain%
Replaced with the currently logged in user name in short format, i.e. without the domain part. Available on Windows.
- %G or %groupname%
Replaced with the group name of the currently logged in user.
- %D or %homedir%
Replaced with the home directory defined for the currently logged in user.
- %IU or %userid%
Replaced with the user identifier defined for the currently logged in user.
- %IG or %groupid%
Replaced with the group identifier defined for the currently logged in user.
The special variables can also be entered using the Unix format, for example, $username
.
Document Type Declaration and the Root Element
The broker configuration file is a valid XML file and starts with the Document Type Declaration.
The root element in the configuration file is secsh-broker
. It can include general
, default-settings
, profiles
, static-tunnels
, gui
, filter-engine
, and logging
elements.
An example of an empty configuration file is shown below:
<!DOCTYPE secsh-broker SYSTEM "ssh-broker-ng-config-1.dtd"> <secsh-broker version="1.0"> <general /> <default-settings /> <profiles /> <static-tunnels /> <gui /> <filter-engine /> <logging /> </secsh-broker>
The gui
element is used on Windows only.
On SSH Tectia Client, the filter-engine
element is used only when the optional transparent TCP tunneling feature has been installed and activated.
The general
Element
The general
element contains settings such as the cryptographic library and the key stores to be used.
The general
element can contain zero or one instance of the following elements: crypto-lib
, cert-validation
, key-stores
, strict-host-key-checking
, host-key-always-ask
, accept-unknown-host-keys
; and multiple known-hosts
elements.
- crypto-lib
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 themode
attribute. By default, standard cryptographic libraries are used.FIPS mode will be used if it is so specified either in the global or the user configuration file (or both).
<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
,aes192-cbc
, andaes256-cbc
ciphers and thehmac-sha1
MAC.Note Setting the FIPS mode does not prevent using algorithms from the crypto plugins. For example, CryptiCore can be used even when the main cryptographic library is set into the FIPS mode. To enforce that only FIPS-compliant algorithms are used, disable the non-FIPS algorithms from the configuration. See cipher and mac.
For a list of platforms on which the FIPS library has been validated or tested, see SSH Tectia Client/Server Product Description.
- cert-validation
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
, andsocks-server-url
.The
end-point-identity-check
attribute specifies whether the client will verify the server's hostname or IP address against the Subject Name or Subject Alternative Name (DNS Address) specified in the server host certificate. The default value isyes
. If set tono
, 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.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. Thedefault-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 hostname and the certificate contains the full DNS address "rock.example.com
".The
http-proxy-url
attribute defines an HTTP proxy and thesocks-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) orhttp://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 port1080
for connections outside of networks192.196.0.0
(16-bit domain) and10.100.23.0
(8-bit domain), and to get these networks connected directly, setsocks-server-url
as follows:"socks://mylogin@socks.ssh.com:1080/192.196.0.0/16,10.100.23.0/24"
The
cert-validation
element can contain multipleldap-server
,ocsp-responder
,crl-prefetch
elements, onedod-pki
element, and multipleca-certificate
andkey-store
elements. The elements have to be in the listed order.- ldap-server
This element specifies an LDAP server
address
andport
used for fetching CRLs and/or subordinate CA certificates based on the issuer name of the certificate being validated. Several LDAP servers can be specified by using severalldap-server
elements.CRLs are automatically retrieved from the CRL distribution point defined in the certificate to be verified if the point exists.
The default value for
port
is389
.- ocsp-responder
This element specifies an OCSP (Online Certificate Status Protocol) responder service address in URL format with attribute
url
. Several OCSP responders can be specified by using severalocsp-responder
elements.If the certificate has a valid Authority Info Access extension with an OCSP Responder URL, it will be used instead of this setting. Note that for the OCSP validation to succeed, both the end-entity certificate and the OCSP Responder certificate must be issued by the same CA.
The
validity-period
(in seconds) can be optionally defined. During this time, new OCSP queries for the same certificate are not made but the old result is used. The default validity period is0
(a new query is made every time).- crl-prefetch
This element instructs SSH Tectia Client/ConnectSecure to periodically download a CRL from the specified URL. The
url
value can be an LDAP or HTTP URL, or it can refer to a local file. The file format must be either binary DER or base64, PEM is not supported.To download CRLs from the local file system, define the file URL in this format:
file:///absolute/path/name
To download CRLs from an LDAP server, define the LDAP URL in this format:
ldap://ldap.server.com:389/CN=Root%20CA,OU=certification %20authorities,DC=company,DC=com?certificaterevocationlist
Use the
interval
attribute to specify how often the CRL is downloaded. The default is3600
seconds.- dod-pki
This element defines whether the certificates are required to be compliant with the US Department of Defense Public-Key Infrastructure (DoD PKI). In practise, this means that the Digital Signature bit must be set in the Key Usage of the certificate. The
enable
attribute can have a value ofyes
orno
. The default isno
.- ca-certificate
This element defines a certification authority (CA) used in server authentication. It can have four attributes:
name
,file
,disable-crls
, anduse-expired-crls
.The
name
attribute must contain the name of the CA.The element must either contain the path to the X.509 CA certificate file as a value of the
file
attribute, or include the certificate as a base64-encoded ASCII block.CRL checking can be disabled by setting the
disable-crls
attribute toyes
. The default isno
.Expired CRLs can be used by setting a numeric value (in seconds) for the
use-expired-crls
attribute. The default is0
(do not use expired CRLs).- key-store
This element defines CA certificates stored in an external key store for server authentication. Currently it is used only on z/OS for CA certificates stored in System Authorization Facility (SAF).
CRL checking can be disabled by setting the
disable-crls
attribute toyes
. The default isno
.Expired CRLs can be used by setting a numeric value (in seconds) for the
use-expired-crls
attribute. The default is0
(do not use expired CRLs).
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>
- key-stores
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:
%U
=%USERNAME%
= user name%USERNAME-WITHOUT-DOMAIN%
= user name without the domain part%IU
=%USERID%
= user ID (not on Windows)%IG
=%GROUPID%
= user group ID (not on Windows)%D
=%HOMEDIR%
= the user's home directory%G
=%GROUPNAME%
= the name of the user's default group
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 variableHOME
is set).Note Short alias names (for example,
%U
) are case-sensitive and long alias names (for example,%USERNAME%
) are case-insensitive.- key-store
Each of the
key-store
elements configures one key store provider. Thekey-stores/key-store
element can take the following attributes:type
andinit
.The
type
attribute is the key store type. The currently supported types are"entrust"
,"mscapi"
,"pkcs11"
,"software"
, and"zos-saf"
.The
init
attribute is the initialization info specific to the key-store-provider. The initialization string can contain special strings explained above inkey-stores
, see key-stores.For key store configuration examples, see the section called “Key Store Configuration Examples”.
- user-keys
The
user-keys
element can be used to override the default directory for the user keys. Theuser-keys
element can take the following attributes:The
directory
attribute defines the directory where the user private keys are stored. Enter the full path.The
passphrase-timeout
attribute defines the time (in seconds) after which the passphrase-protected private key will time out, and the user must enter the passphrase again. The default is0
, meaning that the passphrase does not time out. The value of this element should be longer than thepassphrase-idle-timeout
value.By default, the Connection Broker keeps the passphrase-protected private keys open once the user has entered the passphrase successfully. This can be changed with the passphrase timeout options. When
passphrase-timeout
is set, the private key stays open (usable without further passphrase prompts) until the timeout expires. Thepassphrase-timeout
attribute sets the hard timeout, that is set only once when the key is opened and will not be reset even if the key is used multiple times.The
passphrase-idle-timeout
attribute defines the time (in seconds) after which the passphrase-protected private key will time out unless the user accesses or uses the key. Thepassphrase-idle-timeout
is reset every time the key is accessed. The default is0
, meaning that the passphrase never times out.Both of the timeout options can be set simultaneously, but notice that if the idle timeout is set longer than the hard timeout, the idle timeout has no effect.
- identification
The
identification
element can be used to override the default location of the identification file that defines the user keys. Theidentification
element can take the following attributes:The
file
attribute specifies the location of the identification file. Enter the full path.The
base-path
attribute defines the directory where the identification file expects the user private keys to be stored. This element can be used to override the default relative path interpretation of the identification file (paths relative to the identification file directory).The
passphrase-timeout
attribute defines the time (in seconds) after which the user must enter the passphrase again. The default is0
, meaning that the passphrase is not re-requested.The
passphrase-idle-timeout
attribute defines a time (in seconds) after which the passphrase times out if there are no user actions. The default is0
, meaning that the passphrase does not time out.The timeout settings affect only those private keys that are listed in the identification file.
- strict-host-key-checking
This element enables strict host key checking. If it is enabled, the Connection Broker never adds host keys to the user's
.ssh2/hostkeys
directory upon connection, and refuses to connect to hosts whose key has changed. This provides maximum protection against man-in-the-middle attacks. However, it can be somewhat annoying if you frequently connect to new hosts.The
strict-host-key-checking
element takes attributeenable
with valueyes
orno
. The default isno
, meaning that the user is asked whether to accept a new or changed host key).Strict host key checking will be used, if it is so specified in either the global or the user configuration file (or both). If different values have been defined in the global and user-specific configuration, the more secure of the values will be used.
<strict-host-key-checking enable="yes" />
When the
strict-host-key-check
is disabled (as by default), SSH Tectia Client will log information about changed and new host public keys with their fingerprints in the syslog (on Unix) or Event Viewer (on Windows).- host-key-always-ask
This element defines whether the Connection Broker should prompt the user to accept the proposed host key even if it is already known.
The word
yes
orno
is given as the value of theenable
attribute. The default isno
(known host keys are accepted without prompting).Host keys are always asked, if it is so specified in either the global or the user configuration file (or both).
<host-key-always-ask enable="yes" />
- accept-unknown-host-keys
This element defines whether the Connection Broker will automatically accept proposed new host keys. This element takes attribute
enable
with valueyes
orno
. The default isno
(unknown host keys are not automatically accepted).When transparent FTP tunneling or FTP-SFTP conversion is used, accepting the host key cannot be prompted from the user. Either this setting must be set to
yes
(not recommended)
or the host keys of the Secure Shell tunneling and SFTP servers must be obtained beforehand and stored based on the IP addresses of the servers.When accept-unknown-host-keys is enabled, the keys from new hosts are automatically accepted and stored to the host key database without prompting acceptance from the user. However, changed host keys (from hosts whose keys are already in the database) are not stored, but they are accepted for this connection. This has the same effect as automatically answering "
Once
" to all accept-host-key prompts.A warning message is displayed when a changed host key is offered, and information about both new and changed host keys is logged.
If this element is set to
no
either in the global or the user configuration file, the changed or new host keys are prompted normally. Setting this element toyes
takes effect only when bothstrict-host-key-checking
andhost-key-always-ask
are set tono
(or are not explicitly defined).<accept-unknown-host-keys enable="no" />
Caution Consider carefully before enabling this option. Disabling the host-key checks makes you vulnerable to man-in-the-middle attacks.
- known-hosts
This element can be used to specify locations for storing the host keys of known server hosts, and their storage format. If no
known-hosts
directories are specified, the default directories are used for storing the known host keys. See the section called “Files” for the default locations. On z/OS (only), this element can containkey-store
elements.This element can be used:
To specify non-default directories that contain the public-key data or public-key files of known server hosts.
To specify a non-default locations for OpenSSH-style known_hosts files that contain the public-key data of known server hosts.
(On z/OS) To specify a SAF key store that contains the certificates of known server hosts.
Enter a full path to the known-hosts file or directory as the value of the
path
attribute.<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" />
Server host keys are searched in the 'known-hosts' paths in the order they are specified in the configuration. 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.New host keys are always stored to the last specified directory. If no directories are specified, the new host keys are stored to the default location.
The
filename-format
attribute defines the format in which new host key files are stored. The alternatives arehash
(default) andplain
. With valuehash
, the file name format will bekeys_<hash>
, for example "keys_182166d2efe5a134d3fb948646e0b48f780bff6c
". With valueplain
, the file name format will bekey_<port>_<hostname>.pub
, where <port> is the port the Secure Shell server is running on and <host> is the hostname you use when connecting to the server; for example "key_22_my.example.com.pub
".For information on the host key storage formats, see Host Key Storage Formats.
- extended
This element is reserved for future use.
Key Store Configuration Examples
Software Provider
The software provider handles key pairs stored on disk in standard Secure Shell v2 or legacy OpenSSH formats and X.509 certificates stored in native X.509, PKCS#7, and PKCS#12 formats.
To add a single key file (for example, /u/exa/keys/enigma
and /etc/my_key
), specify both the private key file and the public key file:
<key-stores> <key-store type="software" init="key_files(/u/exa/keys/enigma.pub,/u/exa/keys/enigma)" /> <key-store type="software" init="key_files(/etc/my_key.pub,/etc/my_key)" /> </key-stores>
To add all keys from a specific directory (for example all keys from /u/exa/keys
and /etc/keys
):
<key-stores> <key-store type="software" init="directory(path(/u/exa/keys))" /> <key-store type="software" init="directory(path(/etc/keys))" /> </key-stores>
Entrust Provider
The Entrust provider handles keys and certificates stored in the proprietary Entrust format.
You should provide the initialization file and the profile-specific file for the Entrust provider. For example:
<key-stores> <key-store type="entrust" init="ini-file(/etc/entrust.ini),profile-file(/etc/profile.epf)" /> </key-stores>
PKCS#11 Provider
The PKCS#11 provider handles keys and certificates stored in PKCS#11 tokens (for example, smart cards or USB tokens).
Specify the dynamic library path for the PKCS provider and all or a specific slot. For example, with all slots:
<key-stores> <key-store type="pkcs11" init="dll(/usr/lib/pkcs.so),slots(all)" /> </key-stores>
For example, with one slot named sesam
:
<key-stores> <key-store type="pkcs11" init="dll(/usr/local/lib/pkcs.so),slots(sesam)" /> </key-stores>
The default-settings
Element
The default-settings
element defines the default connection-related settings. Profile-specific settings can override these settings. See the section called “The profiles
Element”.
The default-settings
element can contain zero or one instance of the following elements in the listed order: ciphers
, macs
, transport-distribution
, rekey
, authentication-methods
, hostbased-default-domain
, compression
, proxy
, idle-timeout
, tcp-connect-timeout
, keepalive-interval
, exclusive-connection
, server-banners
, forwards
, extended
, remote-environment
, server-authentication-methods
, authentication-success-message
, an sftpg3-mode
.
- ciphers
This element defines the ciphers that the client will propose to the server. The
ciphers
element can contain multiplecipher
elements.The ciphers are tried in the order they are specified.
With SSH Tectia Server for Linux on IBM System z, the client tools will automatically use hardware acceleration (CPACF), if it is available, on cryptographic operations with the 3DES and AES algorithms.
- cipher
This element selects a cipher
name
that the client requests for data encryption.The supported ciphers are
3des-cbc
,aes128-cbc
,aes192-cbc
,aes256-cbc
,aes128-ctr
,aes192-ctr
,aes256-ctr
,arcfour
,blowfish-cbc
,twofish-cbc
,twofish128-cbc
,twofish192-cbc
,twofish256-cbc
,crypticore128@ssh.com
,seed-cbc@ssh.com
, andnone
(no encryption).The default ciphers used by the Connection Broker are, in order:
crypticore128@ssh.com
(on Windows and Linux x86),aes128-cbc
,aes192-cbc
,aes256-cbc
,aes128-ctr
,aes192-ctr
,aes256-ctr
,3des
, andseed-cbc@ssh.com
.The ciphers that can operate in the FIPS mode are
aes128-cbc
,aes192-cbc
,aes256-cbc
, and3des-cbc
.
<ciphers> <cipher name="aes128-cbc" /> <cipher name="3des-cbc" /> </ciphers>
- macs
This element defines the MACs that the client will propose to the server. The
macs
element can contain multiplemac
elements.With SSH Tectia Server for Linux on IBM System z, the client tools will automatically use hardware acceleration (CPACF), if it is available, on cryptographic operations with the HMAC-SHA1 algorithms.
The MACs are tried in the order they are specified.
- mac
This element selects a MAC
name
that the client requests for data integrity verification.The supported MAC algorithms are
hmac-md5
,hmac-md5-96
,hmac-sha1
,hmac-sha1-96
,crypticore-mac@ssh.com
, andnone
(no data integrity verification).The default MACs used by the Connection Broker are, in order:
crypticore-mac@ssh.com
(on Windows and Linux x86),hmac-md5
, andhmac-sha1
.The
hmac-sha1
algorithm can operate in the FIPS mode.
<macs> <mac name="hmac-sha1" /> </macs>
- transport-distribution
This setting defines the number of transport channels used by the Secure Shell connection. Using more than one transport may increase the throughput over low bandwidth connections.
The number of transports is given as value of the
num-transports
attribute. Currently, a value of 1 to 8 transports is supported. On Unix, the default is1
transport. On Windows, the default is2
transports.<transport-distribution num-transports="1" />
- rekey
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" />
- authentication-methods
This element specifies the authentication methods that are requested by the SSH Tectia client components. The
authentication-methods
element can contain one of each:auth-hostbased
,auth-password
,auth-publickey
,auth-gssapi
, andauth-keyboard-interactive
. Alternatively, you can specify multipleauthentication-method
elements. The order of these elements is free.The authentication methods are tried in the order the
auth-*
orauthentication-method
elements are listed. This means that the least interactive methods should be placed first.- authentication-method
This element specifies an authentication method
name
. It is included for backwards compatibility. Use theauth-*
elements instead.The allowed authentication method names are:
gssapi-with-mic
,publickey
,keyboard-interactive
,password
, andhostbased
.SSH Tectia Client/ConnectSecure supports host-based authentication only on Unix platforms.
<authentication-methods> <authentication-method name="hostbased" /> <authentication-method name="gssapi-with-mic" /> <authentication-method name="publickey" /> <authentication-method name="keyboard-interactive" /> <authentication-method name="password" /> </authentication-methods>
- auth-hostbased
This element specifies that host-based authentication will be used.
The
auth-hostbased
element takes thelocal-hostname
element with attributename
to specify a name that will be advertised to the remote server. The remote server can use the client host name as a hint when locating the public key for the client host. This information is not significant to the authentication result, but makes it faster to find the relevant client host key, if the server has such a big storage of host identities, that trying them all would be infeasible.- auth-password
This element specifies that password authentication will be used.
- auth-publickey
This element specifies that public-key authentication will be used.
The
auth-publickey
element can include akey-selection
element.- key-selection
This element specifies the key selection policy the client uses when proposing user public keys to the server. The
policy
attribute can take the valuesautomatic
(default) andinteractive-shy
.In the
automatic
mode, the client tries keys in the following order:Keys with public key available and private key without a passphrase (no user interaction)
Keys with public key available but private key behind a passphrase (one passphrase query)
Keys that need a passphrase to get the public key but private key without passphrase (one user query for each key which is considered and proposed to server, but no user interation for actual public-key login)
The rest of the keys, that is, keys that need a passphrase to get the public key and also to get the private key
In the
interactive-shy
mode, the client does not try any keys automatically, but it prompts the user to select the key from a list of available keys. If the authentication with the selected key fails, the client will prompt the user again.The
key-selection
element can include apublic-key
element.
- auth-keyboard-interactive
This element specifies that keyboard-interactive methods will be used in authentication.
- auth-gssapi
This element specifies that GSSAPI will be used in authentication.
<authentication-methods> <auth-hostbased> <local-hostname name="host.example.com" /> </auth-hostbased> <auth-gssapi /> <auth-publickey> <key-selection policy="interactive-shy"> <public-key type="plain" /> </key-selection> </auth-publickey> <auth-keyboard-interactive /> <auth-password /> </authentication-methods>
- hostbased-default-domain
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.The default domain name is appended to the short hostname before transmitting it to the server. This is needed because some platforms (Solaris for instance) use the short format of the hostname, and with that the signature cannot be created.
The allowed formats of the default domain names are:
.example.com
andexample.com
(without the leading dot). For example:<hostbased-default-domain name=".example.com" />
- compression
This element specifies whether to use compression on all traffic. When activated, the compression is applied to all transferred data on-the-fly; note that this is different from compressing files for the duration of the transfer.
The name of the compression algorithm and the compression level can be given as attributes. The
name
attribute can be defined asnone
(compression not used) orzlib
, currently the only supported algorithm. By default, compression is not used.The
level
attribute can be given an integer from0
to9
. The default compression level is6
, when compression is activated but no level is given.Example: to activate compression on the maximum level, 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.
- proxy
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 bedirect
,socks
,socks4
,socks5
, orhttp-connect
(socks
is a synonym forsocks4
). 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:a single IP address
x.x.x.x
an IP address range of the form
x.x.x.x-y.y.y.y
an IP sub-network mask of the form
x.x.x.x/y
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
element is shown below. It causes the server to access the callback address and thessh.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/" />
- idle-timeout
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. Thetype
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" />
- tcp-connect-timeout
This element specifies a timeout for the TCP connection. When this setting is made, connection attempts to an 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 theprofiles
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" />
- keepalive-interval
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" />
- exclusive-connection
The
exclusive-connection
element can be used to specify that a new connection is opened for each new channel.The word
yes
orno
is given as the value of theenable
attribute. The default isno
(open connections are reused for new channels requested by a client).- server-banners
This element defines whether the server banner message file (if it exists) is visible to the user before login. The word
yes
orno
is given as the value of thevisible
attribute. The default isyes
.To eliminate server banners:
<server-banners visible="no" />
- forwards
This element contains
forward
elements that define whether X11 or agent forwarding (tunneling) are allowed on the client side.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>
For more information on using X11 and agent forwarding, see X11 Forwarding and Agent Forwarding.
- extended
This element is reserved for future use.
- server-authentication-methods
This element can be used to force the Connection Broker to use only certain methods in server authentication. This element can contain up to two
authentication-method
elements.- authentication-method
The
server-authentication-methods/authentication-method
element takes aname
attribute with valuescertificate
orpublickey
.If only
certificate
is specified, server certificate is needed. If no server certificate is received, connection fails.If only
publickey
or bothcertificate
andpublickey
are specified, server certificate is used if present. Otherwise server public key is used.<server-authentication-methods> <authentication-method name="publickey" /> <authentication-method name="certificate" /> </server-authentication-methods>
- authentication-success-message
This setting defines whether the
AuthenticationSuccessMsg
messages are output. Theauthentication-success-message
element takes attributeenable
with valueyes
orno
. The default isyes
, meaning that the messages are output and logged.- sftpg3-mode
This setting defines how the sftpg3 client behaves when transferring files. The
sftpg3-mode
element takes attributecompatibility-mode
with the following values:tectia
(the default) - sftpg3 fransfers files recursively, meaning that files from the current directory and all its subdirectories are transferred.ftp
- theget/put
commands are executed assget/sput
meaning that they transfer a single file; and commandsmget/mput
have recursion depth set to 1 meaning that they only transfer files from the specified directory, not from subdirectories.openssh
- commandsget/put/mget/mput
behave alike, and the recursion depth is set to 1, meaning that only files from the specified directory are transferred, not from subdirectories.
The mode set here can can be overridden by environment variable:
SSH_SFTP_CMD_GETPUT_MODE
.The recursion depth can also 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).- remote-environment
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.
- environment
This element defines the name and value of the environment variables, and whether the Connection Broker should process the value. Possible attributes are
name
,value
, andformat
.An example remote environment configuration:
<remote-environment> <environment name="FOO" value="bar" /> <environment name="QUX" value="%Ubaz" format="yes" /> <environment name="ZAPPA" value="%Ubaz" /> </remote-environment>
You can use
%U
in thevalue
to indicate a user name. Whenformat="yes"
is also defined, the Connection Broker processes the%U
into the actual user name before sending it to the server.Let's assume the user name is
joedoe
in this example. The example configuration results in the following environment variables on the server side, provided that the server allows setting the environment variables:FOO=bar QUX=joedoebaz ZAPPA=%Ubaz
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).
The profiles
Element
The profiles
element defines the connection profiles for connecting to the specified servers. Element profiles
can contain multiple profile
elements. Each profile defines the connection rules to one server. The settings in the profile
element override the default connection settings.
When a profile is used for the connection, the settings in the profile override the default settings. See the section called “The default-settings
Element”.
- profile
The
profile
element defines a connection profile. It has the following attributes:id
,name
,host
,port
,protocol
,connect-on-startup
,user
, andgateway-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 valuehost="*"
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 is22
.The
protocol
is a mandatory setting. It defines the used communications protocol. Currently the only allowed value issecsh2
.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 toyes
. In this case, give also theuser
attribute (the username the connection is made with). You also need to set up some form of non-interactive authentication for the connection.The
user
attribute specifies the user name for opening the connection. The value "%USERNAME%
" can be used to set the user name to the current user. The valueuser="*"
can be used to prompt the user to enter the user name when logging in.The
gateway-profile
attribute can be used to create nested tunnels. The tunnels defined under thelocal-tunnel
element of the profile, and the tunnels defined underfilter-engine
andstatic-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.- hostkey
This element gives the path to the remote server host public key file as a value of the
file
attribute.Alternatively, the public key can be included as a base64-encoded ASCII block.
- ciphers
This element defines the ciphers used with this profile. See ciphers for details.
- macs
This element defines the MACs used with this profile. See macs for details.
- transport-distribution
This element defines the transport distribution for this profile. See transport-distribution for details.
- rekey
This element defines the rekeying settings used with this profile. See rekey for details.
- authentication-methods
This element defines the authentication methods used with this profile. See authentication-methods for details.
- user-identities
This element specifies the identities used in user public-key authentication. In contrast to the
key-stores
element that specifies all the keys that are available for the Connection Broker, this element can be used to control the keys that are attempted in authentication when this connection profile is used and to specify the order in which they are attempted.The
user-identities
element can contain multipleidentity
elements. When multipleidentity
elements are used, they are tried out in the order they are listed.The
identity
element has the following attributes:identity-file
,file
,hash
,id
, anddata
.The
identity-file
attribute specifies that the user identity is read in the identification file used with public-key authentication. Enter the full path to the file if it is located somewhere else than the default identification file directory which is$HOME/.ssh2
. See also ssh-broker-g3(1).The
file
attribute specifies the path to the public-key file (primarily) or to a certificate. Enter the full path and file name as the value.The
hash
attribute is used to enter the hash of the public key that will be used to identify the related private key. The key must be available for the Connection Broker The public key hashes of the available keys can be listed with the ssh-broker-ctl tool. See also ssh-broker-ctl(1).The
id
attribute is reserved for future use.The
data
attribute is reserved for future use.An example
user-identities
element is shown below:<user-identities> <identity identity-file="C:\\ mykey" /> <identity file="$HOME/user/.ssh2/id_dsa_2048_a" /> <identity file="C:\\private_keys\id_dsa_2048_a" /> <identity hash="#a8edd3845005931aaa658b5573609e7d31e23afd" /> </user-identities>
- compression
This element defines the compression settings used with this profile. See compression for details.
- proxy
This element defines the HTTP proxy and SOCKS server settings used with this profile. See proxy for details.
If
gateway-profile
has been defined for this profile, the proxy setting is ignored and the default proxy setting or the proxy setting of the gateway profile is used instead.- idle-timeout
This element defines the idle timeout settings used with this profile. See idle-timeout for details.
- tcp-connect-timeout
This element defines the TCP connection timeout for this profile. The timeout is used to terminate connection attempts to Secure Shell servers that are down or unreachable. The default value is 5 seconds. See tcp-connect-timeout for details.
- keepalive-interval
This element defines an interval for sending keepalive messages to the Secure Shell server. The setting applies to this profile. The default value is 0, meaning that no keepalive messages are sent. See keepalive-interval for details.
- exclusive-connection
This element defines whether a new connection is opened for each new channel when a connection is made with this profile. See exclusive-connection for details.
- server-banners
This element defines the server banner setting used with this profile. See server-banners for details.
- forwards
This element defines the forwards allowed with this profile. See forwards for details.
- tunnels
The
tunnels
element defines the tunnels that are opened when a connection with this profile is made. The element can contain multiplelocal-tunnel
andremote-tunnel
elements.- local-tunnel
This element defines a local tunnel (port forwarding) that is opened automatically when a connection is made with the connection profile. It has five attributes:
type
,listen-port
,listen-address
,dst-host
,dst-port
, andallow-relay
.The
type
attribute defines the type of the tunnel. This can betcp
(default, no special processing),ftp
(temporary forwarding is created for FTP data channels, effectively securing the whole FTP session), orsocks
(SSH Tectia Client/ConnectSecure will act as a SOCKS server for other applications, creating forwards as requested by the SOCKS transaction).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. Value0.0.0.0
listens to all interfaces. The default is127.0.0.1
(localhost loopback address on the client). Setting any other value requires settingallow-relay="yes"
.Whenever a connection is made to the specified listener, the connection is tunneled over Secure Shell to the remote server and another connection is made from the server to a specified destination host and port (
dst-host
,dst-port
). The connection from the server onwards will not be secure, it is a normal TCP connection.The
dst-host
anddst-port
attributes define the destination host address and port. The value ofdst-host
can be either an IP address or a domain name. The default is127.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 isno
. If you useallow-relay="yes"
, it will check also thelisten-address
setting.For more information on using local tunnels, see Local Tunnels.
- remote-tunnel
This element defines a remote tunnel (port forwarding) that is opened automatically when a connection is made with the connection profile. It has four attributes:
type
,listen-port
,listen-address
,dst-host
,dst-port
, andallow-relay
.The
type
attribute defines the type of the tunnel. This can be eithertcp
(default, no special processing) orftp
(temporary forwarding is created for FTP data channels, effectively securing the FTP session between the client and server).The
listen-port
attribute defines the listener port number on the remote server.The
listen-address
attribute can be used to define which network interfaces on the server should be listened. Its value can be an IP address belonging to an interface on the server host. Value0.0.0.0
listens to all interfaces. The default is127.0.0.1
(localhost loopback address on the server). Setting any other value requires thatallow-relay="yes"
.Whenever a connection is made to this listener, the connection is tunneled over Secure Shell to the local client and another connection is made from the client to a specified destination host and port (
dst-host
,dst-port
). The connection from the client onwards will not be secure, it is a normal TCP connection.The
dst-host
anddst-port
attributes define the destination host address and port. The value ofdst-host
can be either an IP address or a domain name. The default is127.0.0.1
(localhost = client host).The
allow-relay
attribute defines whether connections to the listener port are allowed from outside the server host. The default isno
.For more information on using remote tunnels, see Remote Tunnels.
- extended
This element is reserved for future use.
- remote-environment
This element defines the remote environment settings used with this profile. Within the
remote-environment
element, define anenvironment
element for each environment variable to be passed to the server. See remote-environment for details.- server-authentication-methods
This element defines the server authentication methods allowed with this profile. See server-authentication-methods for details.
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> <authentication-method name="publickey" /> <authentication-method name="password" /> </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 static-tunnels
Element
The static-tunnels
setting is used to configure the behaviour of the automatic tunnels. You can create listeners for local tunnels automatically when the Connection Broker starts up. The actual tunnel is formed the first time a connection is made to the listener port. If the connection to the server is not open at that time, it will be opened automatically as well.
The static-tunnels
element can contain any number of tunnel
elements.
- tunnel
The
tunnel
element specifies a static tunnel. It has the following attributes:type
,listen-port
,listen-address
,dst-host
,dst-port
,allow-relay
, andprofile
.The
type
attribute defines the type of the tunnel. This can be eithertcp
orftp
.tcp
specifies a listener for generic TCP tunnelingftp
specifies a listener for FTP tunneling (also the FTP data channels are tunneled)
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. Value0.0.0.0
listens to all interfaces. The default is127.0.0.1
(localhost loopback address on the client). Setting any other value requires thatallow-relay="yes"
.The
dst-host
anddst-port
attributes define the destination host address and port. The value ofdst-host
can be either an IP address or a domain name. The default is127.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 isno
.The
profile
attribute specifies the connection profile id that is used for the tunnel.
<static-tunnels> <tunnel type="tcp" listen-address="127.0.0.1" listen-port="9000" dst-host="st.example.com" dst-port="9000" allow-relay="no" profile="id1" /> </static-tunnels>
The gui
Element (Windows only)
The gui
element is used to adjust the SSH Tectia terminal GUI settings. The gui
element takes the following attributes: hide-tray-icon
, show-exit-button
, show-admin
, enable-connector
, and show-security-notification
. The last two settings have effect only when transparent TCP tunneling is activated on the system. All of these must have yes
or no
as the value.
The hide-tray-icon
attribute controls whether the SSH Tectia icon is displayed in the system tray. The default is no
(the tray icon is displayed).
The show-exit-button
attribute controls whether the Exit command is displayed in the shortcut menu of the SSH Tectia icon. The default is yes
.
The show-admin
attribute defines whether the Configuration command is displayed in the SSH Tectia icon shortcut menu. The default is yes
. If the button is not displayed, the SSH Tectia Configuration tool can be started by running ssh-tectia-configuration.exe
, located by default in directory "C:\Program Files\SSH Communications Security\SSH Tectia\SSH Tectia Broker
".
The enable-connector
attribute defines whether transparent TCP tunneling is active and capturing application connections for tunneling. The default is yes
.
On Windows, the show-security-notification
attribute defines whether the SSH Tectia security notifications are shown upon establishing or closing transparent TCP or FTP tunnels. The default is yes
.
<gui hide-tray-icon="no" show-exit-button="yes" show-admin="yes" enable-connector="yes" show-security-notification="yes" />
The filter-engine
Element
The filter-engine
element handles the settings related to transparent TCP tunneling that has to be separately selected when installing the SSH Tectia Client.
![]() | Note |
---|---|
The On Unix, the global configuration is stored as |
For configuration examples, see these sample files:
On Unix:
etc/ssh2/ssh-broker-config-example-capture.xml
andetc/ssh2/ssh-broker-config-example.xml
On Windows: "
<INSTALLDIR>\SSH Tectia Broker\ssh-broker-config-example-capture.xml
" and "<INSTALLDIR>\SSH Tectia Broker\ssh-broker-config-example.xml
"
The top level element is filter-engine
. It has two attributes: ip-generate-start
and ftp-filter-at-signs
(used with SSH Tectia ConnectSecure, only).
The ip-generate-start
attribute defines the start address of the pseudo IP address space. Pseudo IPs are generated by the Connection Broker when applications do the DNS query through the SSH connection capture component.
With SSH Tectia ConnectSecure, the ftp-filter-at-signs
attribute can be used with FTP-SFTP conversion when scripts are used to open a connection directly from the FTP/SFTP client to the SFTP server, bypassing any proxies. This attribute defines that SSH Tectia ConnectSecure uses the FTP user name, FTP server name, and FTP server password specified in the FTP script.
The FTP script is expected to specify the username in format ftp-user@proxy-user@ftp-server
and the password in format ftp-password@proxy-password
. The @ sign is used to extract the relevant data from the strings.
The ftp-filter-at-signs
takes yes
and no
as values, no
is the default.
When ftp-filter-at-signs="yes"
, SSH Tectia ConnectSecure cuts the username string at the first @ sign to extract the ftp-user
and at the last @ sign to extract the ftp-server
, and the rest of the string is ignored. Likewise, the passwords string is cut at the last @ sign and the first part is used as the password on the SFTP server.
![]() | Note |
---|---|
Under the |
- network
The
network
element specifies a "location" where SSH Tectia Client/ConnectSecure is running. By using thenetwork
element, you can implement location-awareness for SSH Tectia Client/ConnectSecure. It has four attributes:id
,address
,domain
, andip-generate-start
.The
id
attribute specifies a unique identifier for thenetwork
element. Theaddress
attribute specifies the address of the network. It can be missing or empty, in which case it is not used. Thedomain
attribute contains the domain name of the computer. It can also be missing or empty, in which case it is not used. Theip-generate-start
attribute defines the start address of the pseudo IP space. If it is defined here, it overrides theip-generate-start
attribute of thefilter-engine
element.- dns
Note The
dns
element exists for backward-compatibility reasons. Currently therule
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
, andpseudo-ip
. For their descriptions, see rule below.- filter
Note The
filter
element exists for backward-compatibility reasons. Currently therule
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 adns
element.For the descriptions of the other attributes, see rule below.
- rule
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
.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 D.The
host
attribute specifies a target hostname. 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. If both the hostname and the IP address are defined, thehost
attribute takes precedence and theip-address
attribute is ignored.The
pseudo-ip
setting has the following effects when theip-address
is left empty and thehost
matches:When
pseudo-ip="yes"
, the Connection Broker assigns a pseudo IP address for the target host and SSH Tectia Server resolves the real IP address. The pseudo IP addresses should be used when accessing an internal network from the outside, because name resolution for the machines in the internal network is not available from the outside.When
pseudo-ip="no"
, a normal DNS query is made for the target hostname. The default value isno
.
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"
).Note For FTP-SFTP conversion, always specify the port unambiguosly if fallback mode is set. Do not use an asterisk (*), because it causes problems in passive mode file transfer when connected to a plaintext FTP server.
The
action
attribute specifies the action to be done when a filter matches. Its value can beDIRECT
,BLOCK
,TUNNEL
,FTP-TUNNEL
, orFTP-PROXY
.DIRECT
causes the connection to be made directly as plaintext without tunneling or FTP-SFTP conversion.BLOCK
causes the connection to be blocked.FTP-TUNNEL
activates transparent FTP tunnelingTUNNEL
activates transparent TCP tunnelingFTP-PROXY
causes the FTP-SFTP conversion to start and a connection to be made to the Secure Shell SFTP server.
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 andhostname-from-app="yes"
is specified, the Secure Shell connection is made to the server specified by the client application using default settings. If aprofile-id
is specified and alsohostname-from-app="yes"
is specified, or the referred profile has*
(an asterisk) or empty as the value of thehost
attribute, the Secure Shell connection is made to the server specified by the client application using the profile settings.The
destination
anddestination-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 inprofile-id
. The value isyes
orno
, and the default isno
.When
hostname-from-app="no"
, the tunnel will be created to the Secure Shell server specified in the connection profile referred in theprofile-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 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 usinghostname-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 thatfallback-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 isyes
orno
. The default isno
.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. Whenusername-from-app="no"
, the user name is taken from the connection profile defined with theprofile-id
attribute.The
fallback-to-plain
attribute can be used to define whether a direct (unsecured) connection is used if creating the tunnel fails or the connection to the Secure Shell server fails. The default value isno
. Normally, when the secured connection fails when applying a filter rule, the Connection Broker will return a "host not reachable" error. In FTP-SFTP conversion on Unix,fallback-to-plain
requires that option-F
is used with thessh-capture
command. For more details, see ??? manual page.Note Do not enable the
fallback-to-plain
andpseudo-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.
The logging
Element
The logging
element changes the logging settings that define the log event severities and logging facilities. The element contains one or more log-events
elements.
- log-events
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.
For the events,
facility
andseverity
can be set as attributes. The events itself should be listed inside thelog-events
element.The facility can be
normal
,daemon
,user
,auth
,local0
,local1
,local2
,local3
,local4
,local5
,local6
,local7
, ordiscard
. Setting the facility todiscard
causes the server to ignore the specified log events.On Windows, only the
normal
anddiscard
facilities are used.The severity can be
informational
,notice
,warning
,error
,critical
,security-success
, orsecurity-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.For a complete list of log events, see Appendix E.