 |
High Performance OPC UA Server SDK
1.5.0.296
|
|
High Performance OPC UA Server SDK
1.5.0.296
|
This section contains instructions for migrating existing applications to a new SDK release.
The appconfig struct as well as the according settings.conf parameters have been extended for this version and may require updates of existing configuration files depending on the enabled features.
With V1.5.0 support for GDS Push model has been introduced and this required improving the handling of store:// prefix in settings.conf. The file:// prefix is not affected by this change and works as before.
In V1.4.x the SDK was searching for the correct certificate based on the certificate metadata if the SHA1 ID was missing in the certificate configuration. This heuristic was never 100% reliable, but avoided changing the settings.conf every time when the certificate was changed (e.g. initial self-signed generation).
With V1.5.0 it is now required to enter the correct SHA1 e.g. store://51A16B6E182F584ABAF30D5A8A2E4C41B0F4EE3F. In this case it is 100% guaranteed that the correct certificate gets loaded. An invalid SHA1 ID will cause a configuration error on startup.
The empty configuration using store:// is still used and working for the initial configuration. This will tell the SDK that a new certificate needs to be generated. The SDK will update the configuation automatically if the new parameter certificate_conf_filename was set.
Because we don't want to overwrite the settings.conf and loose all comments and formatting, we moved the certificate configuration into a separate new file (e.g. certificates.conf), which gets included by settings.conf using the newly introduced 'include' support. This way the SDK can overwrite the certificates.conf with updated information whenever a new certificate is created. This works for both SDK-generated self-signed certificates and certificates downloaded by GDS Push.
The new parameter and include statement is found in the general section:
The !include directive performs the include operation. The parameter certificate_conf_filename tells the SDK where to save updated certificate configurations.
For the new UA FileType functionality new settings habe been added in the [server] section:
The [server] section now allows to configure the server capabilities. You should configure this to match your server's capabilities.
A new section for GDS configuration has been added.
When building with GDS support you should also add the "GDS" capability to the [server] section.
GDS functionality depends on UA FileType, so you need to configure this as well.
The sections [ns0_config] and [ns1_config] now allow to configure additional memory pool resources. This was hard coded in the server provider in previous versions.
By default, the server will only allocate as much as is necessary to load the ns0.bin file for NS0. NS1 is configured to be able to create diagnostic objects. If you need to create additional nodes or references in these namespaces at runtime use these settings to adjust the memory pools to your needs.
To configure the new (optional) pubsub functionality another new section was introduced. At the moment this contains only the filename of the pubsub configuration file, which contains all publisher ans subscriber settings. This configuration can be changed online using UaExpert. This functionality also require UA FileType support.
The 1.4.0 required to introduce some breaking changes that can be easily fixed by following these instructions.
Applications that use hardcoded appconfig structures need to change the following settings. If you are using configuration files skip this section and read the next section about settings files.
To make client security configuration possible independent of server endpoints the certificate configuration has been moved from the server's endpoint settings into the separate certificate_config structure. Both client and server configuration refer to this certificate configuration by using a certificate index.
To fix this, move existing certificate configurations from g_appconfig.endpoint to g_appconfig.certificates.
Certificate entries now have a new field key_usage which allow to set either server_auth, client_auth, or client_and_server_auth.
You need to add this new field to each configured certificate.
Monitored items which are monitoring objects for alarms & conditions typically use a much larger queue size then for monitoring data. For this reason a separate configuration option was necessary to allow a different maximum queue size for event monitoring items.
To fix this add the new setting g_appconfig.subscription.max_monitoreditem_event_queue_size.
A new mechanism for registering method callbacks was introduced, which allows a better way of finding method callbacks, based on ObjectId and MethodId combinations. This mechanism allows registering methods simply on ObjectTypes and when calling methods on instances of this type, the according method is still found by following the MethodDelarationId. Still it is possible to override the method callbacks for certain instances if necessary. Inheritance is also supported by this new mechanism.
The method registration table requires the new setting g_appconfig.server.num_methods, which is the maximum number of callbacks that can be registered using uaserver_call_table_register.
See Lesson 3: Creating Methods for more information on registering methods at the method call table.
Applications that load the configuration from a settings file need to update their configurations files.
To make client security configuration possible independent from server endpoints the certificate configuration has been moved from the server's endpoint settings into the separate [certificates] section. Both client and server configuration refer to this certificate configuration by using a certificate index.
To fix this, move existing certificate entries from the [endpoint] section to a new [certificates] section.
Certificate entries now have a new field key_usage which allow to set either server_auth, client_auth, or client_and_server_auth. If this field is missing it will default to client_and_server_auth.
Example:
Monitored items which are monitoring objects for alarms & conditions typically use a much larger queue size then for monitoring data. For this reason a separate configuration option was necessary to allow a different maximum queue size for event monitoring items.
To fix this, add the new setting max_monitoreditem_event_queue_size to the [subscription] section.
Example:
A new mechanism for registering method callbacks was introduced, which allows a better way of finding method callbacks, based on ObjectId and MethodId combinations. This mechanism allows to register methods simply on ObjectTypes and when calling methods on instances of this type, the according method is still found by following the MethodDelarationId. Still, it is possible to override the method callbacks for certain instances if necessary. Inheritance is also supported by this new mechanism.
The method registration table requires the new setting g_appconfig.server.num_methods, which is the maximum number of callbacks that can be registered using uaserver_call_table_register.
To fix this, add the new setting num_methods to the [server] section.
Example:
See Lesson 3: Creating Methods for more information on registering methods at the method call table.
This is only relevant when you have implemented your own data sampling at provider interface level and don't use the default provider implementation.
The provider interface contained three callbacks for managing monitored items, that should be sampled at the underlying data source: add_item, remove_item, and modify_item. A new callback set_item_mode must now be implemented, which allows to disable sampling without removing the items. This callback is called when a UA client changes the ua_monitoringmode.
If you override the default implementation of the three existing callbacks, you now also need to implement the new set_item_mode callback. The SDK will detect inconsistent configurations and will stop the server to avoid crashes.
Users of the default provider implementation don't need any changes, as the default provider implementation has been updated accordingly.
The example groups configuration file, that is used by our example servers has been updated and now contains new default groups as defined in the OPC specification.
When building the server with UASERVER_SUPPORT_DIAGNOSTICS=ON, which will enable server diagnostic via the OPC UA information model, the security relevant nodes will get assigned to the SecurityAdmin group. This means only users of this group will be able to read this information.
You need to ensure that this group exists in your groups configuration as well, if using user authorization. The group is found by its name so this works also with custom authorization backends as long as this group does exist.