Configuration File Structure

Configuration File Structure — Organization of the configuration file

The configuration file is an .ini-style key file. Keys assignments take the form: key=value or key=value1;value2;..., depending on the needs of the particular key.

Section [Main]

This section controls which plugins are loaded; which services are authorized; the size of the threadpool and the behavior of Libdexter channels and servers.

The following keys are mandatory:

LoadPlugins

[key1;key2;...] List of keys from the [Plugins] section indicating which plugins to load.

AuthorizedServices

[key1;key2;...] List of keys from the [Services] section indicating which services to authorize. This feature is needed since you may wish to run fewer services than are actually registered by a plugin.

The following keys are optional:

ServerHost

[IPv4 or IPv6 host, default: 127.0.0.1] Indicates the default server host to be used when dexter_server_new() is called with NULL host indicated.

ServerService

[service name or port number, default: 3663] Indicates the default server service or port to be used when dexter_server_new() is called with NULL service indicated.

ServerSocketOptions

Tab or space-delimited list of the following socket options:

SO_KEEPALIVE[=<0 or 1>]
SO_SNDBUF=<n>
SO_RCVBUF=<n>
SO_REUSEPORT[=<0 or 1>]
SO_SNDLOWAT=<n>
SO_RCVLOWAT=<n>
SO_SNDTIMEO=<n>
SO_RCVTIMEO=<n>
TCP_FASTACK[=<0 or 1>]
TCP_KEEPCNT=<n>
TCP_KEEPIDLE=<n>
TCP_KEEPINTVL=<n>
IPTOS_LOWDELAY
IPTOS_THROUGHPUT

Refer to your network documentation for more information on these options. Some may not be available on your platform. Note that Libdexter always uses options SO_REUSEADDR (listening socket) and TCP_NODELAY (to avoid Nagle delays).

ServerMaxBacklog

[any n > 0, default: 16] Indicates the number of data messages that the server holds in its (per-channel) backlog queue. If the server is producing data messages faster than can be delivered to you, (or a connection problem develops), a backlog queue begins to fill. The server will not produce new data messages once the backlog queue is full.

ServerMaxClients

[any n > 0, default: 5] Indicates the maximum number of clients that each server instance may handle simulateously. The threadpool is used to service clients, so be sure that ThreadPoolNumThreads is set high enough to handle ServerMaxClients.

ServerRecvBufferSize

[any n > 0, default: 4096] Indicates the size of each service socket's receive buffer.

ServerTLSSupportFlag

[n=0,1 or 2, default: 0] Flag indicating server support for TLS. See DexterServerTLSSupportFlag.

ServerTLSClientCertFlag

[n=0,1 or 2, default: 1] Flag indicating server requirements for client certificates. See DexterServerTLSClientCertFlag.

ServerTLSCertFile

[default: /etc/ssl/libdexter/server-cert.pem] Full path to X.509 certificate file in PEM format.

ServerTLSKeyFile

[default: /etc/ssl/libdexter/server-key.pem] Full path to X.509 certificate private key file in PEM format.

ServerTLSTrustFile

[default: /etc/ssl/libdexter/server-trust.pem] Full path to X.509 trust file in PEM format.

ServerTLSCrlFile

[default: /etc/ssl/libdexter/server-crl.pem] Full path to X.509 certificate revocation list file in PEM format.

ServerTLSVerifyHostname

[true|1 or false|0, default: false] Indicates whether or not the server requires the client's DNS hostname to match its X.509 certificate.

ChannelHost

[IPv4 or IPv6 host, default: 127.0.0.1] Indicates the default channel host to be used when dexter_channel_new() is called with NULL host indicated.

ChannelService

[service name or port number, default: 3663] Indicates the default channel service or port to be used when dexter_channel_new() is called with NULL service indicated.

ChannelSocketOptions

The same socket options as listed above for ServerSocketOptions are available.

ChannelRecvBufferSize

[any n > 0, default: 4096] Indicates the size of each channel socket's receive buffer.

ChannelTimeoutMsecs

[msecs >= 0, default: 30000] The number of milliseconds a channel object will wait to receive a server response before timing out. Channel objects include channels, service brokers, samplers and timed samplers. A value of zero means wait forever for server response.

ChannelTLSCertFile

[default: /etc/ssl/libdexter/channel-cert.pem] Full path to X.509 certificate file in PEM format.

ChannelTLSKeyFile

[default: /etc/ssl/libdexter/channel-key.pem] Full path to X.509 certificate private key file in PEM format.

ChannelTLSTrustFile

[default: /etc/ssl/libdexter/channel-trust.pem] Full path to X.509 trust file in PEM format.

ChannelTLSCrlFile

[default: /etc/ssl/libdexter/channel-crl.pem] Full path to X.509 certificate revocation list file in PEM format.

ChannelTLSVerifyHostname

[true|1 or false|0, default: true] Indicates whether or not the client requires the server's DNS hostname to match its X.509 certificate.

ThreadPoolNumThreads

[any n > 0, default: 10] The number of threads to run in the threadpool. Be sure to set this high enough to allow for (number of servers * ServerMaxClients), plus at least two more for Libdexter's internal threading activity, i.e. timing loop, callbacks and events.

ThreadPoolExitWait

[true|1 or false|0, default: true] Indicates whether or not the threadpool exit routine waits for all running threads to finish or not. Setting this value to false causes dexter_exit () to return without delay.

Section [Plugins]

This section contains specifiers of the form: key=/full/path/to/plugin, one for each plugin that you may wish to load with LoadPlugins=key1;key2;... in section [Main]. The full path to the plugin must be used. Libdexter will not load plugins on relative paths. The shared library suffix for your platform (e.g. .so) may be omitted.

Section [Services]

This section contains specifiers of the form: key=uuid, one for each service you wish to authorize for use in your application with AuthorizedServices=key1;key2;...in section [Main]. The uuid's must be specified using the 36-byte string form, e.g. 9e50a183-2269-4dd8-9d79-ab3b52de368c.

Section [<UUID>]

Each uuid-specified service has its own section in the configuration file, if required. This section is reserved for service-specific settings and/or keys that the plugin may require to initialize itself on your platform. This is distinguished from the instance initialization that users perform, e.g. on samplers, with dexter_sampler_initialize().