ssh-broker-config — SSH Connection Broker configuration file format
The Connection Broker configuration file ssh-broker-config.xml
is a valid XML file.
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. A malformed global configuration file is ignored and the default settings 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, the key-stores
and
cert-validation
settings
In profiles
element, all settings
In 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
, and
accept-unknown-host-keys
elements have different values in the
global and user-specific configuration, the more secure of these values is
used.
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.
On Unix, the default configuration file locations are:
/etc/ssh2/ssh-tectia/auxdata/ssh-broker-ng/ssh-broker-config-default.xml
for the default configuration
/etc/ssh2/ssh-broker-config.xml
for the global configuration
$HOME/.ssh2/ssh-broker-config.xml
for the user-specific configuration.
/etc/ssh2/ssh-tectia/auxdata/ssh-broker-ng
(directory)
for the XML DTD.
On Windows, the default configuration file locations are:
"C:\Program Files\SSH Communications Security\SSH Tectia\SSH Tectia AUX\ssh-broker-ng\ssh-broker-config-default.xml
"
for the default configuration
"C:\Program Files\SSH Communications Security\SSH Tectia\SSH Tectia Broker\ssh-broker-config.xml
"
for the global configuration
"%USERPROFILE%\Application Data\SSH\ssh-broker-config.xml
"
for the user-specific configuration.
"C:\Program Files\SSH Communications Security\SSH Tectia\SSH Tectia AUX\ssh-broker-ng
" (directory)
for the XML DTD.
This section describes the options available in the Connection Broker configuration file. See Appendix D for more information on the syntax of the configuration file.
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 with SSH Tectia Connector only. The
filter-engine
element is used with SSH Tectia Client with EFT Expansion Pack and SSH Tectia Connector.
general
ElementThe general
element contains settings such as the
cryptographic library and the key stores to be used.
This element selects the cryptographic library mode to be
used. Either the standard version (standard
) or the
FIPS 140-2 certified version (fips
) of the crypto
library can be used. The library name is given as a value of the
mode
attribute. By default, standard crypto libraries
are used.
FIPS mode will be used, if it is so specified either in global or in 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
,
and
aes256-cbc
ciphers and the
hmac-sha1
MAC.
Note | |
---|---|
Setting the FIPS mode does not prevent using algorithms from crypto plugins. For example, CryptiCore can be used even when the main crypto library is set in 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.
This element defines public-key infrastructure (PKI) settings
used for validating remote server authentication certificates. The
element can have three attributes: end-point-identity-check
,
default-domain
, http-proxy-url
, and
socks-server-url
.
The end-point-identity-check
attribute specifies
whether the client will verify the server's hostname against the
Subject Name or Subject Alternative Name (DNS Address) in the
server's certificate. If set to no
, the fields in the
server host certificate are not verified and the certificate is
accepted based on validity period and CRL check only. Note that
this is a possible security risk, as anyone with a certificate
issued by the same trusted CA that issues the server host
certificates can perform a man-in-the-middle attack on the server if
a client has the end-point identity check disabled. The default
value is yes
.
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 hostname 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
proxy for making LDAP or OCSP queries for certificate validity.
The address of the proxy is given as the value of the
attribute. The format of the address is
socks://username@socks_server:port/network/netmask,network/netmask ...
(with a SOCKS proxy) or
http://username@proxy_server:port/network/netmask,network/netmask ...
(with an HTTP proxy).
For example, 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 cert-validation
element can contain multiple
ldap-server
, ocsp-responder
, and
crl-prefetch
elements, a dod-pki
element, and multiple ca-certificate
elements.
This element specifies an LDAP server address
and
port
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
several ldap-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
is 389
.
This element specifies an OCSP (Online Certificate Status
Protocol) responder service address in URL format
(url
). Several OCSP responders can be specified by
using several ocsp-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 is 0
(a new query is made every time).
This element instructs SSH Tectia Client to periodically download a CRL from
the specified url
. The url
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 is 3600
(seconds).
This element defines whether the certificates are required to
be compliant with the DoD PKI (US Department of Defense Public-Key
Infrastructure). 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 of yes
or no
. The default is no
.
This element defines a CA used in server authentication.
It can have four attributes: name
, file
,
disable-crls
, and use-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 to yes
. The default
is no
.
Expired CRLs can be used by setting a numeric value (in
seconds) for the use-expired-crls
attribute. The
default is 0
(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>
There can be one <key-stores>
instance
under the <general>
element. It can have any
amount of <key-store>
elements each of which
configures one key store provider.
See the section called “Key Store Configuration Examples” for key store configuration examples.
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 word yes
or no
is given as the
value of the enable
attribute. The default is
no
(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).
<strict-host-key-checking enable="yes" />
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
or no
is given as the
value of the enable
attribute. The default is
no
(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" />
This element defines whether the Connection Broker will always accept the
proposed host key without saving the key. It is the equivalent of
automatically answering "Once
" to all accept-host-key
prompts.
The word yes
or no
is given as the
value of the enable
attribute. The default is
no
(unknown host keys are not automatically accepted).
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. Additionally, setting this element to yes
takes
effect only when both strict-host-key-checking
and
host-key-always-ask
are set to no
(or are not
explicitly defined).
<accept-unknown-host-keys enable="no" />
Caution | |
---|---|
Consider carefully before enabling this option. Disabling the host-key checks can make you vulnerable to a man-in-the-middle attack. |
This element specifies the location of an OpenSSH-style
known-hosts file that contains the public key data of known server hosts.
The full path to the known_hosts
file must be given as a
value of the path
attribute.
<known-hosts path="/u/username/.ssh/known_hosts" />
The hostname(s) in the file must be in clear-text format. Hashed hostnames are not supported.
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>
default-settings
ElementThe default-settings
element defines the default
connection-related settings. Profile-specific settings can override
these settings.
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.
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
,
arcfour
,
blowfish-cbc
,
twofish-cbc
,
twofish128-cbc
,
twofish192-cbc
,
twofish256-cbc
,
crypticore128@ssh.com
,
seed-cbc@ssh.com
,
and
none
(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
,
3des
, and
seed-cbc@ssh.com
.
The ciphers that can operate in the FIPS mode are
aes128-cbc
,
aes192-cbc
,
aes256-cbc
,
and
3des-cbc
.
<ciphers> <cipher name="crypticore128@ssh.com" /> <cipher name="aes128-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.
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
,
and
none
(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
, and
hmac-sha1
.
The hmac-sha1
algorithm can operate in the FIPS mode.
<macs> <mac name="hmac-sha1" /> </macs>
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 is 1
transport.
On Windows, the default is 2
transports.
<transport-distribution num-transports="1" />
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. The authentication-methods
element can
contain multiple authentication-method
elements.
The authentication methods are tried in the order of the
authentication-method
elements. This means that the least
interactive methods should be placed first.
<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>
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
and
example.com
(without the leading dot). For example:
<hostbased-default-domain name=".example.com" />
This element specifies whether to use compression.
The name
of the compression algorithm and the
compression level
can be given as attributes. Currently
only zlib
is supported as the algorithm. The
level
can be an integer from 0
to
9
. By default, compression is not used.
<compression name="none" />
This element defines rules for HTTP or SOCKS proxy 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 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 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 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 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
.
<server-banners visible="no" />
This element contains forward
elements that
define whether X11 or agent forwarding (tunneling) are allowed on
the client side.
An example forward configuration, which allows X11 forwarding and denies 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.
This element contains environment
elements that define
the environment variables to be passed to the server from the client side by default.
The environment variables are then set on the server when requesting a
command, shell or subsystem.
You can define the environment variables also for each connection profile.
See remote-environment under the profiles
element.
Note that the server can restrict the setting of environment variables.
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
, and
format
.
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 the value
to indicate a
user name. When format="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
--remote-environment
or --remote-environment-format
arguments on the command-line client.
See --remote-environment
name=value
in the
sshg3
description.
profiles
ElementThe profiles
element defines the connection profiles for connecting
to different servers. It can contain multiple profile
elements. Each profile defines the connection rules to one server.
The profile
element defines a connection
profile. It has seven attributes: id
,
name
, host
, port
,
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. Define a unique name for each profile.
The host
is a mandatory setting. The address can be
either an IP address or a domain name. The value '*
' can be used to prompt the user to enter the hostname
when logging in. With the Connector, '%DESTINATION_HOSTNAME%
'
can be given as the hostname. Then the Connector will pick up the
destination IP address from the tunneled application, and open a tunnel
to the same host. This way it is no longer necessary to create a
separate connection profile for each destination host.
The port
is a mandatory setting.
The default port is 22
.
If you want to make the connection specified by the profile
automatically at reboot, set the value of the
connect-on-startup
attribute to yes
. In
this case, give also the user
attribute (the username
the connection is made with). You also need to set up some form of
non-interactive authentication for the connection.
In the user
attribute, the value
'%USERNAME%
' can be used to set the user name to the
current user. The value '*
'
can be used to prompt the user to enter the user name when loggin in.
The gateway-profile
attribute can be used to
create nested tunnels. 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.
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.
This element defines the ciphers used with this profile. See
the section called “The default-settings
Element”.
This element defines the MACs used with this profile. See
the section called “The default-settings
Element”.
This element defines the transport distribution for this
profile. See the section called “The default-settings
Element”.
This element defines the rekeying settings used with this
profile. See the section called “The default-settings
Element”.
This element defines the authentication methods used with this
profile. See the section called “The default-settings
Element”.
This element defines the compression settings used with this
profile. See the section called “The default-settings
Element”.
This element defines the proxy settings used with this
profile. See the section called “The default-settings
Element”.
If a gateway profile (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.
This element defines the idle timeout settings used with this
profile. See the section called “The default-settings
Element”.
This element defines the server banner setting used with this
profile. See the section called “The default-settings
Element”.
This element defines the forwards allowed with this profile.
See the section called “The default-settings
Element”.
The tunnels
element defines the tunnels that are
opened when a connection with this profile is made. The element can
contain multiple local-tunnel
and remote-tunnel
elements.
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
,
dst-host
, dst-port
, and allow-relay
.
This allocates a listener port (listen-port
) on the
local client. Whenever a connection is made to this 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 type
attribute defines the type of the tunnel.
This can be tcp
(default, no special processing),
ftp
(temporary forwarding is created for FTP data
channels, effectively securing the whole FTP session), or
socks
(SSH Tectia Client will act as a SOCKS server for other
applications, creating forwards as requested by the SOCKS
transaction).
The listen-port
attribute defines the local
port to be listened. 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
.
For more information on using local tunnels, see Local Tunnels.
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
,
dst-host
, dst-port
, and allow-relay
.
This allocates a listener port (listen-port
) on the
remote server. 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 type
attribute defines the type of the tunnel.
This can be either tcp
(default, no special processing)
or ftp
(temporary forwarding is created for FTP data
channels, effectively securing the whole FTP session).
The listen-port
attribute defines the remote
port to be listened. 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 = client host).
The allow-relay
attribute defines whether
connections to the listened port are allowed from outside the
server host. The default is no
.
For more information on using remote tunnels, see Remote Tunnels.
This element defines the remote environment settings used with this
profile. Within the remote-environment
element, define an
environment
element for each environment variable to be passed
to the server. For the values, see remote-environment
under the default-settings
element.
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>
static-tunnels
ElementWith the static-tunnels
setting, 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.
The tunnel
element specifies a static tunnel.
It has six attributes: type
, listen-port
,
dst-host
, dst-port
,
allow-relay
, and profile
.
The type
attribute defines the type of the
tunnel. This can be either tcp
or ftp
.
The listen-port
attribute defines the local port to be
listened. 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.
<static-tunnels> <tunnel type="tcp" listen-port="9000" dst-host="st.example.com" dst-port="9000" allow-relay="no" profile="id1" /> </static-tunnels>
gui
ElementThe gui
element contains only one element
(gui
), which is used to adjust the Connection Broker GUI settings. The
gui
element has five attributes: hide-tray-icon
,
show-exit-button
, show-admin
, enable-connector
, and show-security-notification
.
All of these must have yes
or no
as the value. The
last two settings have effect only if SSH Tectia Connector has been installed on the
system.
The hide-tray-icon
attribute controls whether the SSH Tectia
tray 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 tray icon shortcut menu.
The default is yes
.
The show-admin
attribute defines whether the
Configuration command is displayed in the tray 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 the
"C:\Program Files\SSH Communications Security\SSH Tectia\SSH Tectia Broker
" directory.
The enable-connector
attribute defines whether SSH Tectia Connector (if
present) is active and capturing connections. The default is
yes
.
The show-security-notification
attribute defines
whether the SSH Tectia Connector security notification is shown upon establishing a
secure application tunnel. The default is yes
.
<gui hide-tray-icon="no" show-exit-button="yes" show-admin="yes" enable-connector="yes" show-security-notification="yes" />
filter-engine
Element (EFT Expansion Pack , SSH Tectia Connector)Note | |
---|---|
The |
The filter-engine
element defines the SSH Tectia Connector
filter rules and SSH Tectia Client (with EFT) FTP-SFTP conversion rules. These settings
have no effect if only the basic SSH Tectia Client has been installed on the system.
The top level element is filter-engine
. It has two
attributes: ip-generate-start
and
ftp-filter-at-signs
.
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 Capture DLL.
The ftp-filter-at-signs
attribute defines
that the @ sign is used to extract the FTP user name, FTP
server name, and the FTP server password from a string used also when
connecting to an FTP server via a proxy. This is needed when FTP-SFTP
conversion is used to connect to the FTP server directly from the FTP/SFTP
client, bypassing any proxies. The ftp-filter-at-signs
takes
yes
and no
as values, no
is the default.
Users apply a script to connect to an FTP server via a proxy. The
script defines the username as ftp-user@proxy-user@ftp-server
and the password as ftp-password@proxy-password
. When FTP-SFTP
conversion is used instead, make the setting
ftp-filter-at-signs=yes
, and the following will be done:
SSH Tectia 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 preciding part is used as the password on the FTP server.
Under the filter-engine
element there can be any amount of elements of the type
network
, dns
, or filter
. The order of
the elements is important, because the filter engine uses the elements in
the order they were specified in the configuration file.
The network
element specifies a "location"
where SSH Tectia Connector is running. Using the network
elements you can implement location-awareness for SSH Tectia Connector. It
has four attributes: id
, address
,
domain
, and ip-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 IP space. If it is defined here, it overrides the
ip-generate-start
attribute of the filter-engine
element.
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
.
The id
attribute specifies a unique identifier
for the dns
element. The network-id
attribute
contains a reference to a network
element. This can be
left empty if the dns
entry does not bind to a specific
network. The application
attribute specifies the
application for which this DNS entry is used. This can be a regular
expression.
The host
attribute specifies a target hostname. It
can be a regular expression. The ip-address
attribute
specifies the target host IP address. It can be a regular expression.
When both the hostname and the IP address are defined, the
host
attribute takes precedence and the ip-address
attribute is ignored. When the ip-address
is
left empty and the host
matches one of the following things
happen:
When the pseudo-ip
attribute is set to
yes
, the Connection Broker assigns a pseudo IP address for the target
host and SSH Tectia Server resolves the real IP address.
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 the pseudo-ip
attribute is set to to
no
, a normal DNS query is made for the target hostname.
The filter
element specifies an action for a
connection. It has five attributes: dns-id
,
ports
, action
, profile-id
, and
fallback-to-plain
.
The dns-id
attribute is a reference to a
dns
element.
The ports
attribute can be a single port or a range.
A range is specified with a dash between two integers (such as
"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 is used. Its value can be
DIRECT
, BLOCK
,
TUNNEL
(with SSH Tectia Connector), or
FTP-PROXY
(with SSH Tectia Client with EFT Expansion Pack).
DIRECT
causes the connection
to be made directly as plaintext without tunneling or FTP-SFTP
conversion.
BLOCK
causes the connection to be
blocked.
TUNNEL
causes the connection to be
tunneled through a Secure Shell server specified with the profile-id
attribute.
FTP-PROXY
causes the FTP-SFTP connection
to be made to the Secure Shell server specified with the
profile-id
attribute.
If the profile-id
attribute is left empty or the referred
profile has *
(an asterisk) as the value of the
host
attribute, the connection is made to the server
specified by the FTP client application.
When applying the filter rule, if creating the tunnel fails (or
the connection to the Secure Shell server fails) the Connection Broker will normally
return a "host not reachable" error. However, if the
fallback-to-plain
attribute is set to yes
,
a direct (unsecured) connection is used instead. In FTP-SFTP conversion
on Unix, this requires that option -F
is used with the
ssh-convert-ftp
command.
See ssh-convert-ftp (EFT Expansion Pack on Unix)(1).
The fallback-to-plain
and pseudo-ip
options should not be enabled at the same time. If they are, and the secure
connection fails, the application will try a direct connection with the
pseudo IP, which will not work.
An example filter engine configuration with SSH Tectia Connector is shown below.
<filter-engine ip-generate-start="188.1.1.1"> <network id="office" address="10.1.48.0" domain=".*\.ssh\.com" ip-generate-start="" /> <dns id="www-proxy-dns" network-id="office" application="" host="www-cache.*" ip-address="" pseudo-ip="no" /> <dns id="telnet-app-dns" network-id="office" application="telnet.exe" host=".*" ip-address=".*" pseudo-ip="yes" /> <dns id="all-dns" network-id="office" application="" host=".*" ip-address=".*" pseudo-ip="yes" /> <filter dns-id="www-proxy-dns" ports="8080" action="DIRECT" fallback-to-plain="no" /> <filter dns-id="telnet-app-dns" ports="23" action="TUNNEL" profile-id="rock" fallback-to-plain="no" /> <filter dns-id="all-dns" ports="21" action="BLOCK" fallback-to-plain="no" /> <filter dns-id="all-dns" ports="1-65535" action="TUNNEL" profile-id="firewall" fallback-to-plain="no" /> </filter-engine>
This configuration specifies the following:
Connections to a WWW proxy host are passed through directly.
Connections from a Telnet application are tunneled through a profile named rock
.
Connections to FTP ports are blocked.
All other connections are tunneled through a profile named firewall
.
All of the rules are only used in the "office"
network which is
specified by network address 10.1.48.0
. Pseudo IPs are generated
starting from 188.1.1.1
.
An example filter engine configuration with SSH Tectia Client with EFT Expansion Pack on Unix is shown below.
<filter-engine> <dns id="ftp-proxy" application="ftp" host=".*" ip-address=".*" pseudo-ip="no" /> <filter dns-id="ftp-proxy" ports="21" action="FTP-PROXY" profile-id="" fallback-to-plain="no" /> </filter-engine>
This configuration specifies that all connections from a FTP application are converted to SFTP and the connection is made to the server specified by the FTP application.
Note | |
---|---|
On Unix platforms, specifying the application with a long application name (with the path) will not work in all cases. Use short application names. |
logging
ElementThe logging
element changes the logging settings that
define the log event severities and logging facilities. The element
contains one or more log-events
elements.
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
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 specifed log events.
On Windows, only the normal
and
discard
facilities are used.
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 setting a severity value for it.
For a complete list of log events, see Appendix F.