High Performance OPC UA Server SDK  1.7.1.383
Settings File Format

Overview

HP SDK Applications (server and/or clients) are configured using the global application configuration object (g_appconfig). The structure is defined in src/appconfig.h. It allows compiling configurations statically into the application binary (aka firmware) and thus make it working on systems without file system.

On systems with file system the g_appconfig instance can be filled by loading a configuration file at runtime.

Attention: You cannot mix loading dynamically and hard-coding value, as this could result in freeing C constants. Either use C constants (appconfig.c) or use dynamic loading from file. When the application configuration is created dynamically it will free those values on shutdown.

Config Loader

The config loader is a generic Ini file parser, that takes an array of configuration sections, which describes the file format. This way it can be configured to load any configuration file that uses Ini-style syntax.

This parser supports loading scalar values, strings, and arrays of those type. In addition you can extend this parser by providing callbacks for parsing custom data.

See config_load_from_file for more information on this function.

The HP SDK uses this parser to load the setting.conf files.

The function config_clear will free all the memory allocated using config_load_from_file.

Note that it does not track if the data was allocated or not. If the pointer is not NULL it will be freed using ipc_free. For this reason never assign hard-coded values to g_appconfig when using config_clear. If you need to set non-scalar values from code use IPC_ALLOC or ipc_strdup.

Syntax Format Description

All lines that start with # are comments and are ignored by the parser. Also empty lines will be ignored. Section names are enclosed in angular brackets. Sections can contain key/value pairs.

Example:

[section]
# commment
key = value

Support value types:

Type Description
BOOL The following strings are interpreted as true: "true", "yes", "on", "1". Other values are converted to false.
UINT8 A decimal uint8_t, e.g. 255. Numbers out of range will result in an error.
INT8 A decimal int8_t, e.g. -111. Numbers out of range will result in an error.
UINT16 A decimal uint16_t, e.g. 255. Numbers out of range will result in an error.
INT16 A decimal int16_t, e.g. -111. Numbers out of range will result in an error.
UINT32 A decimal uint32_t, e.g. 255. Numbers out of range will result in an error.
INT32 A decimal int32_t, e.g. -111. Numbers out of range will result in an error.
UINT64 A decimal uint64_t, e.g. 255. Numbers out of range will result in an error.
INT64 A decimal int64_t, e.g. -111. Numbers out of range will result in an error.
DOUBLE A floating point value like e.g. -1.234. The number is parsed internally using strtod.
STRING A string that may or may not be enclosed in apostrophes, e.g. "Hello World". The parser will remove leading and trailing whitespaces, but keeps spaces between words. If leading or trailing whitespaces should be preserved you need to enclose it in apostrophes.

Ini files do not directly support Arrays or hierarchical data. The parser can support such values by encoding additional information into the key names.

Array Example:

[section]
persons/size = 3
persons/0/name = Foo
persons/0/age = 20
persons/1/name = Bar
persons/1/age = 21
persons/2/name = Blub
persons/2/age = 22

The size element defines the number of elements in the array. The numeric index between array name and field name is the zero based array index. This size field is parsed as uint32_t.

This file could be mapped to a structure like this:

struct person {
char *name;
uint8_t age;
};
struct persons {
struct person *persons;
uint32_t num_persons;
};

When a configured key is missing in the file the value defaults to zero or NULL pointer.

Settings File Format Sections

This section describes the actual values used in the configuration file of UA servers and clients. The parameters have direct relation to appconfig.

For a well documented server settings example have a look at bin/settings.conf. A client settings example can be found in bin/settings_client.conf.

General Section

[general]

KeyDescription
num_timers The number of resources to allocate in the timer pool. Timers are needed in several places:
  • One timer for session management
  • One timer for for each subscription (subscription.num_subscriptions)
  • One timer for each monitored item (subscription.num_monitoreditems)
xml_max_dom_nodesThe number of resources to allocate in the XML parser's DOM node pool. You only need this when using the XML parser library of the SDK. By default you can omit this option.

Certificates Section

[certificates]

This section configures the certificates to be used by the application.

Key Description
certificates/size Defines the number of used certificates.
certificates/N/certificate Sets the name of the certificate and the location. Store usage: "store://server4k" indicates the certificate is stored in the pki store and named with "server4k". File usage: "file://server4k". The certificate is stored as a file.
certificates/N/key Sets the name of the key associated to the above certificate. Usage is the same as above.
certificates/N/store Defines the index of the store be be used for this certificate.
certificates/N/certificate_type_id Defines the certificate type of the certificate. Currently supported is "UA_RSA_256_TYPE" and "UA_RSA_MIN_TYPE".
certificates/N/days_valid Defines how long is the certificate valid. This is only evaluated if the certificate or a CreateSigningRequest is created.
certificates/N/algorithm Algorithm to be used for signing of the certificate. This is only evaluated if the certificate or a CreateSigningRequest is created. Possible values are: "sha1", "sha224", "sha256", "sha384", "sha512".
certificates/N/key_usage Defines the setting of the key usage parameter in the certificate. This is only evaluated if the certificate or a CreateSigningRequest is created. Possible values are: "server_auth", "client_auth" and "client_and_serverauth".
certificates/N/key_length Defines the length of the private key associated with the certificate. This is only evaluated if the certificate or a CreateSigningRequest is created. Supported values are 1024, 2048, 3072, 4096. The key length must fit to the certificate_type_id. UA_RSA_256_TYPE: 2048, 3072 and 4096. UA_RSA_MIN_TYPE: 1024 and 2048.
certificates/N/create Indicates if the certificate and key shall be created if not found during startup.

IPC Section

[ipc]

The SDK uses one heap for allocating data with dynamic length (e.g. strings and arrays), which is an own Memory Pool implementation and not C malloc/free. Then it uses a number of Object Pools for allocating fixed size objects. All this memory pools are layed out in one big memory chunk (called IPC memory) provided by the platform [layer](layer) function ua_ipc_mem_create.

Key Description
ipc_size The size of IPC memory to allocate on startup (in bytes).
heap_size The size of heap memory pool (in bytes). If set to 0, the heap uses the rest of the IPC memory, which is not used by other object pools.
queue_size The IPC queue size. This is the max number of messages that can be stored in one IPC queue.
num_queues The number of IPC queues. This is the size of the IPC queue object pool. Each IPC component has one such message queue. If you don't add your own IPC componetns you can keep the default value.
num_messages The number of IPC message. This is the size of IPC message object pool.
num_services The number of IPC service messages. Size of IPC service object pool.
outprocess_encoder Start encoder as separated child process (linux only).
outprocess_seconv Start secconv as separated child process (linux only).

Network Section

[network]

This configures the low level network settings like sockets and buffers.

Key Description
buffer_size Size of one buffer for serializing/deserializing UA messages. When multiplying this value with uatcpmsg.num_chunks you get the maximum UA message size. Note that UA requires a minimum buffer size of 8KB to be able to establish a connection. With lower values most UA implementation will not accept the connection.
num_buffers The maximum number of buffers available. This is the size of the buffer object pool.
num_buffers_per_connection The maximum number of buffers that can be used by one connection. Using this settings you can prevent that one connection is consuming all resources.
max_connections_per_ip The maximum number of TCP connections, that can be created from one IP address.

Encoder Section

[encoder]

Key Description
max_call_depth This limits the maximum recursion depth of nested datatypes to avoid stack overflows.
max_string_length Maximum length of a string that can be decoded. If strings are longer, the decoder will create a decoding error. This is a safety measure to prevent consuming all memory.
max_bytestring_length Maximum length of a bytestring that can be decoded. Note that certificates are also transmitted as bytestrings, so you should not make this too small.
max_array_length Maximum length of arrays that can be decoded. Note that this is also the upper bound of service operation limits. See also Session Section (server only).

Subscription Section (server only)

[subscription]

Key Description
max_sessions_with_subscriptions Maximum number of subscriptions, that can have a subscription.
num_publishrequests_per_session Maximum number of queued published requests for one session.
num_notificationmessages_per_session Maximum number of notifications messages for one session (aka retransmission queue). Shall be at least twice as big as num_publishrequests_per_session.
num_subscriptions_per_session Maximum number of subscriptions for one session.
num_subscriptions Total maximum number of subscriptions. This is the subscription pool size.
num_monitoreditems_per_subscription Maximum number of monitored items for one subscription.
num_monitoreditems Total maximum number of monitored items. This is the monitored item pool size.
max_monitoreditem_queue_size Maximum number of values, that can be queued in a monitored item.
max_monitoreditem_event_queue_size Maximum number of events, that can be queued in a monitored item.
max_notifications_per_publish Maximum number of values and events for one publish response.
min_publishing_interval Minimum supported publishing interval (milliseconds).
max_publishing_interval Maximum supported publishing interval (milliseconds).
min_sampling_interval Minimum supported sampling interval (milliseconds).
max_sampling_interval Maximum supported sampling interval (milliseconds).
min_lifetime Minimum lifetime for subscription before timing out (milliseconds).
max_lifetime Maximum lifetime for subscription before timing out (milliseconds).
num_eventnotifiers Number of event notifiers and event sources.
num_eventfields Number of possible event fields.

Session Section (server only)

[session]

Key Description
num_sessions Maximum number of sessions. This is the session pool size.
num_calls Maximum number of parallel service calls (should be same as uatcpmsg.num_ctxts)
lifetime_check_interval Time interval in seconds at which session lifetime will be checked.
lifetime_min Minimum session lifetime in milliseconds.
lifetime_max Maximum session lifetime in milliseconds.
keep_spare_session When true, the oldest, not connected session is deleted if num_sessions is reached.
max_references_per_node Maximum number of references per node returned in Browse and BrowseNext, must be <= max_array_length.
Authentication
authentication_num_users Maximum number of users supported for authentication.
authentication_passwd_file Location of the user passwords file, which contains the cryptographically hashed passwords for each user.
authentication_store PKI store used for user certificates.
Authorization
authorization_roles_file Location of the roles configuration file, optional. For information on the content see Roles Configuration File.
Operation Limits
max_nodes_per_read Maximum number of nodes per Read request. Must be <=encoder.max_array_length.
max_nodes_per_write Maximum number of nodes per Write request. Must be <=encoder.max_array_length.
max_nodes_per_methodcall Maximum number of nodes per Call request. Must be <=encoder.max_array_length.
max_nodes_per_browse Maximum number of nodes per Browse(Next) request. Must be <=encoder.max_array_length.
max_nodes_per_registernodes Maximum number of nodes per (Un)RegisterNodes request. Must be <=encoder.max_array_length.
max_nodes_per_translate Maximum number of nodes per TranslateBrowsePathsToNodeids request. Must be <=encoder.max_array_length.
max_nodes_per_nodemanagement Maximum number of nodes per node management request. Must be <=encoder.max_array_length.
max_nodes_per_historyread Maximum number of nodes per HistoryRead request. Must be <=encoder.max_array_length.
max_nodes_per_historyupdate Maximum number of nodes per HistoryUpdate request. Must be <=encoder.max_array_length.
max_monitoreditems_per_call Maximum number of monitored items per call. Must be <=encoder.max_array_length.

UATCPMSG Section

[uatcpmsg]

These parameters configure the UA TCP protocol layer.

Key Description
num_conns Maximum number of parallel TCP client connections.
num_listeners Maximum number of TCP listen sockets. One is needed for each UA endpoint.
num_ctxts Maximum number of TCP message contexts (should be the same as session.num_calls).
num_chunks Maximum number of chunks per message. See network.buffer_size.

SeConv Section

[seconv]

These parameters configure the UA Secure Conversation protocol layer.

Key Description
num_channels Maximum number of parallel secure channels.
keep_spare_channel When true, the oldest channel without an activated session is deleted if num_channels is reached.
min_security_token_lifetime Minimum number of milliseconds for a secure channel before it times out (default=30000).
max_security_token_lifetime Minimum number of milliseconds for a secure channel before it times out (default=3600000).

PKIStore Section

[pkistore]

These parameters configure the available PKI stores. A typical use-case is to have one PKI store for application instance certificates and one for user certificates.

Key Description
pkistores/size Number of PKI stores.
pkistores/N/config A configuration string for the PKI store with index N.
pkistores/N/import An import directory for importing certificate on startup. This is only provided for backwards compatibility. It is recommended to use the uacertmgr application or GDS Push to configure a server.
  • N stands for the zero based numeric index of the array element. If e.g. size=2, then N can 0 or 1. The same convention will be used in the following sections.

PKI Store File Backend Configuration

The config string for the file backend of the PKI store uses the following format: store_root_path;max_trusted;max_issuers;max_rejected;max_private

Config Parameter Description
store_root_path File path for the PKI store. This can be an absolute or relative path.
max_trusted Maximum number of trusted certificates.
max_issuers Maximum number of issuer certificates.
max_rejected Maximum number of rejected certificates.
max_private Maximum number of private key files.

CAGroup Section

[cagroup]

This sections configures the mapping of UA certificate groups to the SDK PKI stores.

If cagroupid is "DefaultApplicationGroup" the corresponding UA node is ns=0;i=UA_ID_SERVERCONFIGURATION_CERTIFICATEGROUPS_DEFAULTAPPLICATIONGROUP. This group is defined by the OPC UA specification.

For other values, the NodeId within the server is derived from the value of cagroupid. These nodes will be created in namespace 1 (server namespace).

Example: cagroupid = "MyGroup" -> "ns=1;s=MyGroup"

Key Description
cagroups/size Number of CA groups.
cagroups/N/cagroupid The name of the CA group. The NodeId is derived from this name.
cagroups/N/store_index The PKI store index, which corresponds to this CA group.
cagroups/N/certificates A comma separated list of certificate indices, which identify the application's "own" certificates, which should be managed by GDS.

Endpoint Section (server only)

[endpoint]

This sections configures the list of endpoints and their security parameters, that the server should open at startup.

Key Description
User Tokens
user_token/size Number of supported user tokens.
user_token/N/name The user token name, which is used in UA to identify the toke type. This name can chosen by the server.
user_token/N/type The user token type, which is defined by the OPC UA specification. This can be Anonymous, Username, Certificate.
user_token/N/policy_id Selects the security policy that should be supported with this token type. All token types except Anonymous require cryptography to secure the credentials, so this is a required parameter for secure user tokens.
Security Policies
security_policies/size Number of supported security policies.
security_policies/N/policy_id Selected the security policy to use. This can be http://opcfoundation.org/UA/SecurityPolicy#None, http://opcfoundation.org/UA/SecurityPolicy#Basic256, or http://opcfoundation.org/UA/SecurityPolicy#Basic256Sha256. Note that Basic128Rsa15 is a deprecated policy, that should not be used anymore.
security_policies/N/store Selects the PKI store that should be used for this security policy.
security_policies/N/check_complete_chain When enabled the complete chain is validated and can produce multiple errors. If disabled the validation stops when encountering the first error.
security_policies/N/max_verify_results Defines the maximum number of certificate verification results.
security_policies/N/max_chain_length Defines the maximum certificate chain length before stopping the validation.
security_policies/N/mode_sign When true, the message mode SignOnly (no encryption) can be used. For security policy http://opcfoundation.org/UA/SecurityPolicy#None this must be false.
security_policies/N/mode_sign_and_encrypt When true, the message mode SignAndEncrypt can be used. For security policy http://opcfoundation.org/UA/SecurityPolicy#None this must be false.
security_policies/N/mode_none When true, the insecure message mode None is enabled. This is only possible with security policy http://opcfoundation.org/UA/SecurityPolicy#None.
security_policies/N/cagroupid Defines what GDS certificate group is used to manager this policy, e.g. DefaultApplicationGroup.
security_policies/N/certificate_type_id Defines what GDS certificate type should be used for this endpoint. Possible values are UA_RSA_MIN_TYPE and UA_RSA_256_TYPE.
Endpoints
endpoints/size Number of endpoints to open.
endpoint/N/endpoint_url This is the endpoint URL that should advertised using the UA discover services (e.g. opc.tcp://myhostname:4840). Note that you can use the placeholder "[hostname]", which gets replaced with the host's hostname.
endpoint/N/bind_address This is the IP address, that the TCP listen socket should be bound to. You can use the IPv4 ANY-address 0.0.0.0 or IPv6 ANY-address [::] to bind to socket to all network devices, or use a specific IP address to bind only to one network device.
endpoint/N/bind_port This is the port number that the TCP listen socket should be bound to. The IANA registered default port number for OPC UA is 4840.
endpoint/N/security_policies This is a comma separated list of integers, which reference one of the configured security policies, which should be available on this endpoint.
endpoint/N/user_tokens This is a comma separated list of integers, which reference one of the configured user tokens, which should be supported on this endpoint.

Supported Endpoint Schemes

The only officially supported endpoint scheme is opc.tcp://<hostname>:<port> which creates an endpoint using the UA Binary protocol on TCP/IP. When using this scheme you need to define the bind_address and bind_port for binding the TCP port to the desired address/port combination.

As an experimental feature there is also support for opc.unix://<path> which creates a UNIX Domain Socket instead of a TCP socket. It uses the same binary protocol/encoding as in opc.tcp, but avoids the overhead of TCP/IP. This can be used for efficient local communication. When using this scheme you need to define a local socket file as bind_address (e.g. /tmp/opcua), the port is not needed.

Example:

endpoints/0/endpoint_url = opc.unix:///tmp/opcua
endpoints/0/bind_address = /tmp/opcua

Suppression of Security Errors

Attention: You should never use these settings, because you render your system insecure! It might be necessary to connect to outdated or buggy implementations, though.

Key Description
allow_deprecated_policies When true, you enable the usage of the deprecated security policies http://opcfoundation.org/UA/SecurityPolicy#Basic128Rsa15 and http://opcfoundation.org/UA/SecurityPolicy#Basic256. By default these policies cannot be used in the security policy configuration.
allow_plaintext_credentials When true, it is possible to configure user tokens which transfer credentials as plaintext. By default the Secure Channel or the credential itself (or both) must be encrypted.
Security Policies
security_policies/N/ign_time When true, certificate expiration errors are ignored.
security_policies/N/ign_issuer_time When true, certificate expiration errors for issuer certificates (CA) are ignored.
security_policies/N/ign_miss_crl When true, a missing CRL for the issuing CA, that issued the UA application instance certificate, are ignored.
security_policies/N/ign_miss_issuer_crl When true, missing CRLs for CAs, which issued other intermediate CA certificates, are ignored.
security_policies/N/ign_untrusted When true, untrusted certificate errors will be ignored, which leads to accepting all untrusted but valid certificates.
security_policies/N/ign_key_usage When true, invalid certificate key_usage errors will be ignored.
security_policies/N/ign_ext_key_usage When true, invalid certificate extended_key_usage errors will be ignored.
security_policies/N/disable_crl_check When true, no CRL checks are carried out.
security_policies/N/disable_cert_validate When true, no certificate checks are done at all. You should never use this in production!

Server Section (server only)

[server]

Key Description
max_dimensions Maximum number of dimensions supported in array_dimensions attribute.
num_methods Maximum number of methods that can be registered at the call table.
num_fileobjects Maximum number of file objects.
num_filehandles Maximum number of file handles (opened files).
filehandle_timeout Timeout [sec] when inactive filehandle get reclaimed.
Supported Server Profiles
serverprofiles/size Number of supported profiles.
serverprofiles/N/uri Profile URI entry. E.g. http://opcfoundation.org/UA-Profile/Server/MicroEmbeddedDevice2017
Supported Server Capabilities
servercapabilities/size Number of supported capabilities.
servercapabilities/N/cabability Sever capability entry. Possible capabilities are e.g. DA, HD, AC, HE, GDS, ...

Client Section (client only)

[client]

Key Description
num_clients Maximum number of client instances.
num_subscriptions Maximum number of client subscription instances.
store PKI store index for trust check.
certificate Own client certificate/keypair.

GDS Section (server only)

This section defines how the GDS component inside the server SDK handles certificates it receives from a global discovery server (GDS).

[gds]

Key Description
max_trustlist_size Maximum size of transmitted trustlist object. 0 = 8000 bytes.
allow_private_key_delivery When true, private keys within the UpdateCertificate message are accepted. Private key transition is not suggested. A private key shall never leave the device.
gds_config_path Path where the internal GDS configuration is stored. Default: "gds_data"
gds_config_file File name of the internal GDS configuration file. Default: "gds_data.conf"

Suppression of Security Errors

Attention: You should never use these settings, because you render your system insecure! It might be necessary if the GDS uses invalid certificates, which should never be the case.

Key Description
disable_crl_check When true, no CRL checks are carried out.
ign_issuer_time When true, certificate expiration errors for issuer certificates (CA) are ignored.
ign_time When true, certificate expiration errors are ignored.
ign_miss_crl When true, a missing CRL for the issuing CA, that issued the UA application instance certificate, are ignored.
ign_miss_issuer_crl When true, missing CRLs for CAs, which issued other intermediate CA certificates, are ignored.
ign_untrusted When true, untrusted certificate errors will be ignored, which leads to accepting all untrusted but valid certificates.
ign_csr_parameter_validation When true, the certificate received in the UpdateCertificate message is not checked against the requested parameter in the CreateSigningRequest message.

Certificate Data Section

This section configures the certificate details for self-signed certificates, that the SDK can created on startup if the configured certificates are missing. The same information is also used to create certificate signing requests (CSR) when using a GDS.

[certificate_data]

Key Description
organization_unit The X509v3 subject organization unit (OU).
organization The X509v3 subject organization (O).
locality The X509v3 subject locality (L).
state The X509v3 subject state (S).
country The X509v3 subject country ( C ).
email The X509v3 subject email (Email).
domain_component The X509v3 subject domain component (DC).
ips The X509v3 subject alternative name IP field. This can be a comma separated list of IP addresses.
dns The X509v3 subject alternative name DNS field. This can be a comma separated list of domain names.

See RFC 5280 for more information.

NS0 Config Section (server only)

[ns0_config]

When the server loads a binary information model it allocated memory pools as large as necessary to load all data from file, but nothing more. To be able to add additional nodes and references to that namespace after loading the file you need to increase the memory pools. The following settings define how much pool should be increased when loading the file.

Note that when loading additional namespaces you need at least spare references in NS0 to be able to connect nodes from NS0 to other namespaces.

Key Description
add_variables The number of additional variables to reserve.
add_methods The number of additional methods to reserve.
add_references The number of additional references to reserve.
add_strings The number of additional strings to reserve.
add_objects The number of additional objects to reserve.
add_variabletypes The number of additional variable types to reserve.
add_referencetypes The number of additional reference types to reserve.
add_objecttypes The number of additional object types to reserve.
add_datatypes The number of additional data types to reserve.
add_views The number of additional vies to reserve.
add_guids The number of additional GUIDs to reserve.
add_dimensions The number of additional dimension objects to reserve.

NS1 Config Section (server only)

[ns1_config]

This section is identical to NS0Config section, but for NS1.

PubSub Section (server only)

[pubsub]

Key Description
config_filename Filename of the pubsub configuration file.
keyfile_name Filename of the pubsub security keyfile used to cache keys.
publisherid_config Filename of the settings file used to store the default publisher id.
enable_security_key_server Enable SKS functionality (only GetSecurityKeys supported for managed security groups).
enable_security_key_pull Enable functionality to pull security keys from a SKS (requires implementation of client functionality to pull the keys from SKS).
enable_security_key_push Enable functionality to get security keys pushed by a SKS with SetSecurityKeys.
max_config_size Maximum size of the pubsub configuration.
max_connections Maximum number of PubSub connections that can be configured.
max_writer_groups Maximum number of writer groups that can be configured.
max_reader_groups Maximum number of reader groups that can be configured.
max_dataset_writers Maximum number of dataset writers that can be configured.
max_dataset_readers Maximum number of dataset readers that can be configured.
max_security_groups Maximum number of security groups that can be configured.
pull_retry_interval Retry interval for failed key pull operations in [ms].
max_keylifetime Maximum key lifetime that can be configured for a security group in [ms].
min_keylifetime Minimum key lifetime that can be configured for a security group in [ms].
max_past_key_cnt Maximum past key count that can be configured for a security group.
min_past_key_cnt Minimum past key count that can be configured for a security group.
max_future_key_cnt Maximum future key count that can be configured for security group.
min_future_key_cnt Minimum future key count that can be configured for security group.

PubSub Publisher Id Section (server only)

[pubsub_publisherid]

In this section the pubsub default publisher id is configured. The default publisher id is 0 the server will generate on first startup and write it back. This section must not be added to the main settings file. Instead it should be included via !include <publisherid_config>. This prevents overwriting the main settings file.

Key Description
default_publisherid Pubsub default publisher id.

Application description section

[application_desc]

Key Description
application_type Type of the application: Allowed values are: UA_APPLICATIONTYPE_SERVER, UA_APPLICATIONTYPE_CLIENT, UA_APPLICATIONTYPE_CLIENTANDSERVER, UA_APPLICATIONTYPE_DISCOVERYSERVER. The default is UA_APPLICATIONTYPE_SERVER.