UA Bundle SDK .NET  2.4.1.366
 All Classes Namespaces Functions Variables Enumerations Enumerator Properties Events Modules Pages
Configuration Schema

Overview

The ApplicationInstance depends on an XML configuration file which specifies various parameters needed by the application to run. Most of these parameters have suitable default values; however, some are required to properly configure security. In these cases, the SDK will pick suitable defaults to ensure an application can run without a configuration file, however, Application Developers must provide them before deploying any real application.

The schema for this configuration file is based on the SecuredApplication schema defined in Annex D of Part 6 of the OPC UA Specification. Configuration specific to the SDK or to applications built with the SDK can be added to the Extensions element defined by the SecuredApplication schema. This can be found in the folder "configurationschema". The methods ParseExtension<T> and UpdateExtension<T> on the ApplicationInstance object can be used to read or update any individual extension. These methods require a class which supports serialization with the WCF DataContract serializer or with the standard .NET XML serializer.

The SDK defines several standard extensions for different groups of configuration parameters which, by convention, all end with the suffix ‘Settings’. These standard extensions are described below along with the mandatory elements from the SecuredApplication schema. The SDK supports the use of file paths relative to special folder names. This allows the same configuration file to be used on different machines. The syntax replaces the drive letter with a special folder name enclosed in percent signs (%). For example, the following path refers to the Documents folder for the current user:

%MyDocuments%/Logs/LogFile.txt

The complete set of special folder names is defined by the Environment.SpecialFolder enumeration.

SecuredApplication

This is the base schema for the application configuration file.

Certificate Management

Certificates are blobs of data which can be stored on disk or in a Windows certificate store. Each certificate has a public key and a private key. The private key must be protected and is only accessible to the owner of the certificate. The public key and private key are stored in separate files for this reason.

Certificates and revocation lists have to be stored in DER format. Allowed file extensions are .der or .cer for certificates and .crl for revocation lists.

The private key is usually stored in a PKSC#12 format (*.pfx or *.p12 extension) or a PEM format (*.pem extension). If a certificate is placed a Windows certificate store, the private key is placed in a file managed by Windows.

Certificates are placed into a subfolder of the trusted certificate store, and issuer certificate store respectively, named “certs” (see the table below). Existing certificate revocation lists are placed into a subfolder named “crl”. If the crl folder exists, every CA certificate needs to have a crl file. This behavior can be deactivated by setting the DisableCertificateRevocationUnknown attribute or DisableCertificateIssuerRevocationUnknown respectively in the extension CertificateCheckSettings.

A more detailed explanation of certificate management can be found on the website of the OPC Foundation: The OPC UA Security Model for Administrators (pdf document).

Note
All HTTPS certificates must be placed in the “LocalMachine\My” store because of issues with Windows HTTPS.SYS configuration. The TrustList for HTTPS certificates is “LocalMachine\Root”. HTTPS certificates must also be explicitly bound to a port and a network interface. The SDK takes care of creating these bindings and uses the existing bindings to find the certificate for the endpoint.
ElementDescription
ApplicationName A human readable name for the application.
The value has a default chosen by the application vendor but can be changed by the administrators of the application.
ApplicationUri A globally unique identifier for the application instance. This must be a valid URI which should include the DNS name of the machine, the name of the product and the name of the application.
ApplicationType The type of application.
May be Server_0 or Client_1.
Product Name A human readable name for the product.
This value is set by the application vendor.
ApplicationCertificate Location and identifier for the application instance certificate.
The default StorePath is (StoreType is “Directory”):
"%CommonApplicationData%\UnifiedAutomation\CertificateStores\PrivateKeys"
TrustedCertificateStore Location of the trusted certificate store. Peer and CA certificates which the application trusts are placed here.
See paragraphs above for more information on file format and folder structure.
The default StorePath is (StoreType is “Directory”):
"%CommonApplicationData%\UnifiedAutomation\CertificateStores\Trusted"
IssuerCertificateStore Location of the issuer certificate store. Certificates which are needed to validate certificate chains are placed here.
See paragraphs above for more information on file format and folder structure.
The default StorePath is (StoreType is “Directory”):
"%CommonApplicationData%\UnifiedAutomation\CertificateStores\Issuers"
RejectedCertificatesStore Location of the rejected certificate store.
Stores certificates which have been rejected because they are untrusted.
The default StorePath is (StoreType is “Directory”):
"%CommonApplicationData%\UnifiedAutomation\CertificateStores\Rejected"
BaseAddressesThe list of endpoint URLs supported by Server.
Any URL with “localhost” as the domain is bound to all machine IP addresses. The “localhost” is changed to the default DNS name of the machine during initialization.
A URL with “127.0.0.1” as the domain is only accessible to Clients running on the same machine.
For each URI scheme the following transport profiles are assumed:
opc.tcpUaTcpTransport
httpWsHttpXmlOrBinaryTransport
https HttpsXmlOrBinaryTransport
nosecurityhttpHttpsXmlOrBinaryTransport
SecurityProfilesA list of supported security profiles.
If omitted then the Basic256 and None profiles are used as defaults.
ExtensionsA list of SDK and application specific configuration settings.
Any valid XML is allowed. The XML is parsed when the ApplicationInstance.ParseExtension<T> method is called by the application.

CertificateCheckSettings

This set of configuration options can be used to set default certificate checks which are enforced by the application as well as to override these default checks for single certificates.

See Certificate Validation for more information.

The following code shows a configuration example:

<Extension>
<CertificateCheckSettings xmlns="http://unifiedautomation.com/schemas/2011/12/Application.xsd">
<!-- This element sets the default certificate checks which are enforced by the application -->
DisableDomainCheck="false"
DisableApplicationUriCheck="false"
DisableCertificateTimeInvalid="false"
DisableCertificateIssuerTimeInvalid="false"
DisableCertificateRevocationUnknown="false"
DisableCertificateIssuerRevocationUnknown="false" />
<!-- These elements override the default certificate checks for a single certificate -->
<!--
<Certificate Thumbprint="9F94EBF4473CE8589F348FD853D1DBF3A3514A7D" DisableApplicationUriCheck="true" DisableCertificateRevocationUnknown="true" />
<Certificate Thumbprint="8B2B4864EDAD10D73DBFFBC0BC820E76A7A6A22C" DisableCertificateRevocationUnknown="true" />
-->
</CertificateCheckSettings>
</Extension>
ElementDescription
DisableDomainCheck If set to TRUE, the domain in the endpoint URL will not be compared to the certificate domains. This parameter is only validated by the Client SDK. The Server SDK will ignore this parameter, because it doesn’t check the domain.
AllowPartialChains Allows a certificate to be trusted even if the chain cannot be verified. The default value is FALSE. Complete chains are required for compliance. It is not recommended to change this setting.
DisableApplicationUriCheck If set to TRUE, the application URI will not be compared to the application URI in the certificate. The check is required for compliant OPC UA servers but older clients may provide a wrong ApplicationUri. It is not recommended to change this setting.
DisableCertificateTimeInvalid If set to TRUE, expired or not yet valid certificates will be accepted.
DisableCertificateIssuerTimeInvalid If set to TRUE, expired or not yet valid issuer certificates will be accepted.
DisableCertificateRevocationUnknown If set to TRUE, certificates will be accepted even if it is not possible to check their revocation status.
DisableCertificateIssuerRevocationUnknown If set to TRUE, issuer certificates will be accepted even if it is not possible to check their revocation status.

TransportSettings

These values specify various limits used by the transport layer.

ElementDescription
MaxBufferSizeThe maximum size of any buffers allocated.
If not specified, the default is 65,536.
MaxStringLengthThe maximum length of any encoded String value.
If not specified, the default is 16,777,216.
MaxByteStringLengthThe maximum length of any encoded ByteString value.
If not specified, the default is 16,777,216.
MaxArrayLengthThe maximum length of any encoded array value.
If not specified, the default is 65,536.
MaxMessageSizeThe maximum size of any encoded message.
If not specified, the default is 16,777,216.
OperationTimeoutThe default timeout, in milliseconds, for any service request.
If not specified, the default is 120,000.
ChannelLifetimeThe lifetime, in milliseconds, of a secure channel.
If not specified, the default is 60,000.
SecurityTokenLifetimeThe lifetime, in milliseconds, of a security token.
If not specified, the default is 3,600,000.

InstallationSettings

These values specify various options used during installation/uninstallation.

ElementDescription
GenerateCertificateIfNoneIf TRUE a new certificate is generated if a valid one does not exist.
If not specified, the default is TRUE.
CertificateKeyLengthThe length of the auto-created certificate in bits.
The default is 2048. Supported values are 1024, 2048, 3072 and 4096.
CertificateHashAlgorithmThe hash algorithm used on the auto-created certificate.
The default is 'sha256'. Supported values are 'sha1' and 'sha256'.
DeleteCertificateOnUninstallIf TRUE the application certificate is deleted during uninstall.
If not specified, the default is TRUE.
ConfigureFirewallIf TRUE the firewall is configured to open or close ports used by the endpoints specified for the application.
If not specified, the default is FALSE.
ConfigureHttpAccessIf TRUE any HTTP or HTTPS endpoints are configured to allow access by a process running with the credentials of the UsersGroup.
If not specified, the default is TRUE.
InstallAsServiceIf TRUE a Server is configured to run as a Windows Service.
If not specified, the default is FALSE.
The service will run as 'Local System'.
ServiceNameThe name of the Windows Service created during install.
Must be specified if InstallAsService is set to TRUE.
ServiceDescriptionA human readable description for the Windows Service.
If not specified, the default is an empty string.
ServiceStartModeThe following values are possible: Auto, Manual, Disabled.
If not specified, the default is Manual
UsersGroupThe name of the Windows Account Group which is allowed to run the application. If not specified, the default is the ‘Users’ built-in group.
AdministratorsGroupThe name of the Windows Account Group which is allowed to administer the application.
If not specified, the default is the ‘Administrators’ built-in group.
DisableSetFilePermissionsIf FALSE access permissions are set for the executable, the configuration file and the certificate store.
If not specified, the default is FALSE.
DisableLdsCertificateExchangeIf FALSE the application instance certificate is pushed to the trusted certificate store of the Local Discovery Server (LDS) and the certificate of the LDS is pulled to the own trusted store.
If not specified, the default is FALSE.

TraceSettings

These values control the information written to the trace log files.

ElementDescription
TraceFileThe location of the trace file.
If not specified, then no trace information is written to a file.
MaxEntriesPerLogThe maximum number of entries per log file.
If not specified, then default is 0 (no limit).
MaxLogFileBackupsThe maximum number of backup for log files.
If not specified, then default is 0 (no backups).
FastTraceIf TRUE, the trace file is kept open. If FALSE, the trace file is opened and closed for each log message written.
If not specified then the default is FALSE.
MasterTraceEnabledIf FALSE, all tracing is disabled.
If not specified then the default is FALSE.
DefaultTraceLevelThe default trace level.
If not specified, then the default is “Error”.
TimestampFormatThe string format of the Timestamp within the trace entry.
If not specified, then the default is “HH:mm.sss”.
This setting is used to call DateTime.ToString(string format).
ModuleSettingsA list of settings for each trace module in the process.
ModuleNameThe name of the trace module.
If not specified, then the module is ignored.
TraceEnabledIf FALSE, then tracing is disabled for the module.
If not specified, then the default is TRUE.
TraceLevelThe default trace level for the module.
If not specified, then the default is “Default”.

TraceLevels

These are the possible trace levels that can be specified.

LevelDescription
DefaultUse the default trace level.
NoneTurn all tracing off.
ErrorUnexpected errors that require the attention of developers or administrators.
WarningLess critical issues that also require the attention of developers or administrators.
SystemGeneral system messages.
InfoInformational messages.
InterfaceCallThe entry and exit messages for major API methods.
ConstructorThe constructors of major API objects.
ProgramFlowAdditional entry and exit messages for minor API methods.
DataVerbose information when the state of objects changes during processing.

ClientSettings

These values control the information written to the trace log files.

ElementDescription
ProductUriA globally unique identifier for the product that client belongs to.
If not specified then the default is an empty string.
DiagnosticMasksThe diagnostic masks to use with each request.
If not specified, then the default is 0 (no diagnostics).
RequestTimeoutThe timeout in milliseconds for each service request.
If not specified, then the default is 30,000.
MaxOperationsPerRequestThe maximum number of operations per request.
If a request is passed to the SDK with more than this number, then the SDK will break the call into separate requests.
If a service request is broken into multiple requests, then the RequestTimeout is for the entire set of requests.
If not specified, then the default is 1,000.
SessionTimeoutThe requested timeout, in milliseconds, for a session.
If not specified, then the default is 600,000.
WatchdogCycleTimeThe time interval, in milliseconds, between cycles of the watchdog which checks the status of the connection with the Server.
If not specified then the default is 5,000.
WatchdogTimeoutThe maximum time, in milliseconds, that the watchdog waits for a response from the Server before starting the reconnection process.
If not specified then the default is 10,000.
AutomaticReconnectIf TRUE, the watchdog will attempt to reconnect to the Server when it detects an error after it has connected.
If not specified, then the default is TRUE.
RetryInitialConnectIf TRUE, the server will keep trying to connect if the initial attempt fails.
It will stop when a timeout occurs.
If not specified, then the default is TRUE.
ReconnectDelayThe time in milliseconds between reconnect attempts.
If not specified, then the default is 10,000.
DisableIncludeChains If FALSE, the entire chain is sent over the wire. If true, only the application instance certificate is sent over the wire. This setting allows for backward compatibility with applications that cannot handle a certificate chain or can be used in environments where issuer certificates are stored locally on the server.

ServerSettings

These values control the base configuration for the Server.

ElementDescription
ProductUriA globally unique identifier for the product that server belongs to.
The default is constructued with the ApplicationUri.
ProductNameA human readable name for the product that server belongs to.
The default is the Product attribute for the EXE assembly.
ManufacturerNameA human readable name for the manufacurer of the product.
The default is the Company attribute for the EXE assembly.
SoftwareVersionA string representing the version of the Server software.
The default is the first 2 fields from the EXE assembly FileVersion attribute.
BuildNumberA string representing the build of the Server software.
The default is the last 2 fields from the EXE assembly FileVersion attribute.
BuildDateWhen the Server software was built.
The last write time for the EXE assembly is the default.
IsAuditActivatedIf true, the Server will produce audit events.
The default is FALSE.
IsDiagnosticsEnabledIf true, the Server will track diagnostics information.
The default is FALSE.
AvailableLocaleIdsA list of locales supported by the Server. The syntax is defined by RFC 1766.
The default is "en-US".
AvailableServerProfilesA list of profiles supported by the Server.
No profiles are specified by default.
UserIdentityThe user identities supported by the server.
DiscoveryRegistrationThe discovery registration settings for servers.

EndpointSettings

These values control the security options and network interface used by a base address.

ElementDescription
EndpointUrl The URL which the settings apply to. This URL must match one of the URLs in the SecuredApplication.BaseAddresses list.
NetworkInterface The IP address to use when binding the socket. It can be an IPv4 or IPv6 address. If omitted, then the socket is bound to all IP addresses for the machine.
DisableNoSecurity If true, the None message security mode is disabled for this endpoint. The default value is FALSE.
EnableSignOnly If true, the SignOnly message security mode is enabled for this endpoint. The default value is FALSE.
DisableSignAndEncrypt If true, the SignAndEncryp message security mode is disabled for this endpoint. The default value is FALSE.
EnableXmlEncoding

If set to TRUE, the endpoint will only accept XML encoded messages.
If it is FALSE, then the messages must be UA Binary encoded.

UserIdentitySettings

These values control what user identity tokens are accepted by a Server.

ElementDescription
EnableAnonymousWhether anonymous users are allowed.
Enabled if the UserIdentitySettings are missing from the configuration.
EnableUserNameWhether authentication with a username and password is allowed.
Disabled if the UserIdentitySettings are missing from the configuration.
EnableCertificateWhether authentication with an X509 certificate is allowed.
Disabled if the UserIdentitySettings are missing from the configuration.

DiscoveryRegistrationSettings

These values control how a server registers with the local discovery server.

ElementDescription
UrlThe URL of the discovery server the server must register with.
The default is 'opc.tcp://localhost:4840'.
EnabledWhether the server should attempt to register with the discovery server.
The default is TRUE.
RegistrationIntervalThe interval in milliseconds between registration attempts.
The default and maximum is 30,000.

ThreadPoolSettings

These values control the thread pool used by the server.

ElementDescription
MinThreadCountThe minimum number of threads.
The default and minimum value is 10.
MaxThreadCountThe maximum number of threads.
The default is 1000 and the minimum value is 10.
MaxRequestCountThe maximum number of requests in the queue waiting for a thread.
The default is 2000 and the minimum value is 100.

SessionSettings

These values control the behavoir of the SessionManager in the Server.

ElementDescription
MaxRequestAgeThe maximum difference in milliseconds between the timestamp of the request and the current time.
The minimum and default is 600,000.
MaxSessionCountThe maximum number of open sessions.
The default is 100 and the minimum is 10.
MinSessionTimeoutThe minimum timeout in milliseconds for sessions.
The default is 20,000 and the minimum is 1,000.
MaxSessionTimeoutThe maximum timeout in milliseconds for sessions.
The default and the minimum is the MinSessionTimeout. The maximum is 600,000.
MaxBrowseContinuationPointsThe maximum number of browse continuation points per session.
The default and minimum is the MaxNodesPerBrowse.
MaxHistoryContinuationPointsThe maximum number of history continuation points per session.
The default and minimum is the MaxNodesPerHistoryDataRead.
MaxNodesPerReadThe maximum number of read operations per request.
The default and minimum is 10,000.
MaxNodesPerWriteThe maximum number of write operations per request.
The default and minimum is 10,000.
MaxNodesPerHistoryDataReadThe maximum number of history data read operations per request.
The default and minimum is 1,000.
MaxNodesPerHistoryDataUpdateThe maximum number of history data update operations per request.
The default and minimum is 1,000.
MaxNodesPerHistoryEventReadThe maximum number of history event read operations per request.
The default and minimum is 1,000.
MaxNodesPerHistoryEventUpdateThe maximum number of history event update operations per request.
The default and minimum is 1,000.
MaxNodesPerMethodCallThe maximum number of call operations per request.
The default and minimum is 10,000.
MaxNodesPerBrowseThe maximum number of browse operations per request.
The default and minimum is 1,000.
MaxNodesPerRegisterNodesThe maximum number of register node operations per request.
The default and minimum is 1,000.
MaxNodesPerTranslateBrowsePathsToNodeIdsThe maximum number of translate browse operations per request.
The default and minimum is 1,000.
MaxNodesPerNodeManagementThe maximum number of add or delete node operations per request.
The default and minimum is 100.
MaxMonitoredItemsPerCallThe maximum number of monitored item operations per request.
The default and minimum is 10,000.
MinNonceLengthThe minimum nonce length.
The default and minimum is 32.

SubscriptionSettings

These values control the behavoir of the SubscriptionManager in the Server.

ElementDescription
MinPublishingIntervalThe minimum publishing interval in milliseconds.
The minimum and default is PublishingIntervalResolution.
MaxPublishingIntervalThe maximum publishing interval in milliseconds.
The minimum and default is the MinPublishingInterval. The maximum is 60,000.
MaxKeepAliveIntervalThe maximum keep alive interval in milliseconds.
The minimum and default is the MinKeepAliveInterval. The maximum is 3,600,000.
MinKeepAliveIntervalThe minimum keep alive interval in milliseconds.
The minimum and default is 1,000.
MinLifetimeThe minimum subscription lifetime in milliseconds.
The minimum and default is the larger of 20,000 or the MinKeepAliveInterval.
MaxLifetimeThe maximum subscription lifetime in milliseconds.
The minimum and default is the MinLifetime. The maximum is 3,600,000.
PublishingIntervalResolutionThe minimum publish interval in milliseconds.
The default is 100. The minimum is 50.
MaxPublishRequestCountThe maximum number of queued publish requests per session.
The default is 100. The minimum is 2.
MaxSubscriptionCountThe maximum number of subscriptions.
The default and minimum is 10.
MaxNotificationsPerPublishThe maximum number of notifications per publish request.
.The default is 10,000.
MaxMessageQueueSizeThe maximum of saved messages per subscription.
The default is 100.
MaxDataValueQueueSizeThe maximum queue size for data monitored items.
The default and minimum is 1,000.
MinEventQueueSizeThe minimum queue size for event monitored items.
The default and minimum is 1,000.
MaxEventQueueSizeThe maximum queue size for event monitored items.
The default is the MinEventQueueSize. The minimum is 10,000.