Edge Control OPC UA Server Application#
The purpose of the OPCSVR application is to provide an OPC UA server for testing. A configuration file is used to define the server launch parameters. This document will describe those configuration parameters.
The server uses the open62541 library API interface for all communications. Security can be enabled by specifying the necessary certificate and public/private keys information in the configuration. This private keys may be stored either in a file. HW-based TPM storage is a future enhancement.
A configuration file is used to define the server runtime parameters defined in a YAML file. This file will describe the configuration parameters for the server.
A configuration files uses the YAML format. All parameters are case-sensitive and proper formatting and indentation is critical.
Further details of YAML formatting is outside the scope of this document. You can find guides on the Internet that provide details on YAML file formatting.
Note: Any unknown parameters in a configuration file will be ignored.
Application Command-line Parameters#
The OPCSVR application takes a single command-line parameter, the name of the configuration file to load.
Example:
./opcsvr config.yaml
Server Configuration Parameters#
This is an example of the contents of a YAML configuration file.
app-settings:
log-level: "debug" # options: error, warning, info, debug (default), trace, verbose
thread-core-affinity: 3 # default 0 (range: 0 to {# of cores - 1})
thread-sched-priority: 49 # default 50 (range: 0 to 99, but strongly suggest a value in middle of range)
server:
port: 4841 # default 4840
iterate-interval-us: 10000 # default 50000
security-type: 1 # options: 0 = none (default), 1 = certificate file, 2 = sealed certificate file
tpm-slot: 1 # required for security-type 2
tpm-user-pin: 123456 # required for security-type 2
tpm-key-label: "opcua_key" # required for security-type 2
server-app-uri: "urn:open62541.server.application" # required for security-type 1 or 2
server-certificate: "../security/server-certificate.der" # required for security-type 1 or 2
server-private-key: "../security/server-private-key.der" # required for security-type 1 or 2
client-certificates: # required for security-type 1 or 2
-
certificate: "../security/uaexpert.der"
-
certificate: "../security/client-certificate.der"
log-level#
This parameter will set the level of logging messages output to the console. The allowed values are error, warning, info, debug (default), trace, and verbose.
Example: This example sets the log level to debug.
log-level: "debug"
thread-core-affinity#
This parameter will set the core affinity of the real-time thread. The permitted values are 0 to 1 less than the number of CPU cores. The default is core 0.
Example: This example sets the core affinity to 3.
thread-core-affinity: 3
thread-sched-priority#
This parameter will set the priority of the real-time thread. The permitted values are 0 to 99, however it is strongly recommended to select a value that is in the middle of this range. The default priority is 50.
Example: This example sets the priority value to 49.
thread-sched-priority: 49
port#
The server will launch on the port specified. If the parameter is not specified, the server will launch on the default port, 4840.
Example: This example sets the priority value to 4841.
port: 4841
iterate-interval-us#
This parameter will set the interval at which the server will iterate to update node values. This value is in microseconds. On some systems, if the iteration interval is too low, the system will become unresponsive as it cannot process fast enough. The default is 50 milliseconds.
Example: This example sets the iteration interval to 10 milliseconds.
iterate-interval-us: 10000
security-type#
This parameter is optional and defines whether the server should allow connections anonymously or use sign and encrypt security. The allowed values are:
0=anonymous
1=certificate
2=sealed certificate
Example: This example sets the security type to use certificates.
security-type: 1
tpm-slot#
This parameter must be defined when security-type is set to 2. It defines the slot number used by the TPM to encrypt and decrypt the server private key.
Example:
tpm-slot: 1
tpm-user-pin#
This parameter must be defined when security-type is set to 2. It defines the user pin used by the TPM to authorize encryption and decryption of the server private key.
Example:
tpm-user-pin: 123456
tpm-key-label#
This parameter must be defined when security-type is set to 2. It defines the label used to find the AES key in the TPM. The TEP AES key is used to encrypt and decrypt the server private key.
Example:
tpm-key-label: "opcua_key"
server-app-uri#
This parameter must be defined when security-type is set to 1 or 2. It is the URI specified in the server certificate. The server application URI is needed for OPC UA sign and encrypt security.
Example:
server-app-uri: "urn:open62541.server.application"
server-certificate#
This parameter must be defined when security-type is set to 1 or 2. It indicates the location where the server certificate is stored in the file
system. The server certificate is needed for OPC UA sign and encrypt security.
Example:
server-certificate: "../security/server-certificate.der"
server-private-key#
This parameter must be defined when security-type is set to 1 or 2. It indicates the location where the server private key is stored in the file
system. The server private key is needed for OPC UA sign and encrypt security. The server private key can contain the actual key in binary format or the key after it has been encrypted by the TPM.
Example:
server-private-key: "../security/server-private-key.der"
client-certificates/certificates#
These parameters must be defined when security-type is set to 1 or 2. It indicates the location where the client certificates are stored in the file system. The client certificate is needed for OPC UA sign and encrypt security. These certificates will be added to the server’s trust list.
Example:
client-certificates:
-
certificate: "../security/uaexpert.der"
-
certificate: "../security/client-certificate.der"
Note: This parameters, when present, MUST be the last item in the server section, otherwise parsing errors will occur.
PubSub Publisher Configuration Parameters#
This example shows all parameters available in a YAML configuration file for a PubSub publisher.
pubsub-publishers:
-
cycle-time-us: 1000000
transport-profile: "http://opcfoundation.org/UA-Profile/Transport/pubsub-eth-uadp"
network-interface: "lo"
network-address-url: "opc.eth://ff-ff-ff-ff-ff-ff"
publisher-id: 100
writer-group-id: 200
dataset-writer-id: 300
security-type: 1 # options: 0=NONE (default), 1=AES128_FILE, 2=AES128_SEALED_FILE, 3=AES256_FILE, 4=AES256_SEALED_FILE, 5=AES128_TPM, 6=AES256_TPM
keys-file: "../security/pubsub128.key" # required for security-type 1, 2, 3 or 4
tpm-slot: 1 # required for security-type 2, 4, 5 or 6
tpm-user-pin: 123456 # required for security-type 2, 4, 5 or 6
tpm-sealing-key-label: "opcua_key" # required for security-type 2 or 4
tpm-aes-key-label: "enc_key" # required for security-type 5 or 6
tpm-hmac-key-label: "sign_key" # required for security-type 5 or 6
nodes:
-
node-id: "ns=0;i=2258" # UA_NS0ID_SERVER_SERVERSTATUS_CURRENTTIME
cycle-time-us (publisher)#
This mandatory parameter indicates the interval, in microseconds, of the Publisher. The value of this parameter should be between 1 and 4,294,967,295.
Example:
cycle-time-us: 1000000
transport-profile (publisher)#
This mandatory parameter must be one of the following values:
http://opcfoundation.org/UA-Profile/Transport/pubsub-udp-uadp: User Datagram Protocol (UDP) is a Transport Layer protocol. Unlike TCP, it is unreliable and connectionless protocol.
http://opcfoundation.org/UA-Profile/Transport/pubsub-eth-uadp: Ethernet (ETH) is a Transport Layer protocol that uses TCP.
Example:
transport-profile: http://opcfoundation.org/UA-Profile/Transport/pubsub-eth-uadp
network-interface (publisher)#
This mandatory parameter represents the name of network interface card (NIC). Use lo for testing with the loopback interface.
Example:
network-interface: lo
network-url (publisher)#
This mandatory parameter should be set to the network URL of the target PubSub subscriber.
It typically takes the form of opc.eth:// followed by the MAC address of the subscriber’s NIC, for example, opc.eth://xx-xx-xx-xx-xx-xx. Multicast over Ethernet or loopback can specify the value, opc.eth://ff-ff-ff-ff-ff-ff, while multicast over UDP can specify the value, opc.udp://224.0.0.22:4840.
Example:
network-url: "opc.eth://ff-ff-ff-ff-ff-ff"
publisher-id (publisher)#
This mandatory parameter along with writer-group-id and dataset-writer-id form a set of unique identifiers for one PubSub publisher and subscriber pair. Subscribers will only receive data from Publishers that have matching values. This value should be an integer between 1 and 65534.
Example:
publisher-id: 100
writer-group-id (publisher)#
This mandatory parameter along with publisher-id and dataset-writer-id form a set of unique identifiers for one PubSub publisher and subscriber pair. Subscribers will only receive data from Publishers that have matching values. This value should be an integer between 1 and 65534.
Example:
writer-group-id: 200
dataset-writer-id (publisher)#
This mandatory parameter along with write-group-id and publisher-id form a set of unique identifiers for one PubSub publisher and subscriber pair. Subscribers will only receive data from Publishers that have matching values. This value should be an integer between 1 and 65534.
Example:
dataset-writer-id: 300
security-type (publisher)#
This parameter is optional and defines whether PubSub should encrypt communications. The allowed values are:
0=none
1=AES128 keys file
2=sealed AES128 keys file
3=AES256 keys file
6=sealed AES256 keys file
5=TPM AES128 and HMAC keys
6=TPM AES256 & HMAC keys
Example: This example sets the security type to use an unsealed AES128 keys file.
security-type: 1
tpm-keys-file (publisher)#
This parameter must be defined when security-type is set to 1, 2, 3, or 4. It defines the local file containing the AES and HMAC keys.
Example:
tpm-keys-file: "../security/pubsub128.key"
tpm-slot (publisher)#
This parameter must be defined when security-type is set to 2, 4, 5, or 6. It defines the slot number containing the TPM keys.
Example:
tpm-slot: 1
tpm-user-pin (publisher)#
This parameter must be defined when security-type is set to 2, 4, 5, or 6. It defines the user pin used to access the TPM keys.
Example:
tpm-user-pin: 123456
tpm-sealing-key-label (publisher)#
This parameter must be defined when security-type is set to 2 or 4. It defines the label used to find the AES key in the TPM for unsealing the local encrypted keys file.
Example:
tpm-sealing-key-label: "opcua_key"
tpm-aes-key-label (publisher)#
This parameter must be defined when security-type is set to 5 or 6. It defines the label used to find the AES key in the TPM for PubSub encryption.
Example:
tpm-aes-key-label: "enc_key"
tpm-hmac-key-label (publisher)#
This parameter must be defined when security-type is set to 5 or 6. It defines the label used to find the HMAC key in the TPM for PubSub encryption.
Example:
tpm-aes-key-label: "enc_key"
nodes/node-id (publisher)#
These mandatory parameters define the OPC UA variable nodes that need to be published.
Example:
nodes:
-
node-id: "ns=0;i=2258" # UA_NS0ID_SERVER_SERVERSTATUS_CURRENTTIME
PubSub Subscriber Configuration Parameters#
This example shows all parameters available in a YAML configuration file for a PubSub subscriber.
pubsub-subscribers:
-
cycle-time-us: 1000000
transport-profile: "http://opcfoundation.org/UA-Profile/Transport/pubsub-eth-uadp"
network-interface: "lo"
network-address-url: "opc.eth://ff-ff-ff-ff-ff-ff"
publisher-id: 100
writer-group-id: 200
dataset-writer-id: 300
security-type: 1 # options: 0=NONE (default), 1=AES128_FILE, 2=AES128_SEALED_FILE, 3=AES256_FILE, 4=AES256_SEALED_FILE, 5=AES128_TPM, 6=AES256_TPM
keys-file: "../security/pubsub128.key" # required for security-type 1, 2, 3 or 4
tpm-slot: 1 # required for security-type 2, 4, 5 or 6
tpm-user-pin: 123456 # required for security-type 2, 4, 5 or 6
tpm-sealing-key-label: "opcua_key" # required for security-type 2 or 4
tpm-aes-key-label: "enc_key" # required for security-type 5 or 6
tpm-hmac-key-label: "sign_key" # required for security-type 5 or 6
nodes:
-
node-id: "ns=1;s=MyDateTime"
cycle-time-us (subscriber)#
This mandatory parameter indicates the interval, in microseconds, of the Publisher. The value of this parameter should be between 1 and 4,294,967,295.
Example:
cycle-time-us: 1000000
transport-profile (subscriber)#
This mandatory parameter must be one of the following values:
http://opcfoundation.org/UA-Profile/Transport/pubsub-udp-uadp: UDP is a Transport Layer protocol. Unlike TCP, it is unreliable and connectionless protocol.
http://opcfoundation.org/UA-Profile/Transport/pubsub-eth-uadp: Ethernet (ETH) is a Transport Layer protocol that uses TCP.
Example:
transport-profile: http://opcfoundation.org/UA-Profile/Transport/pubsub-eth-uadp
network-interface (subscriber)#
This mandatory parameter represents the name of network interface card (NIC). Use lo for testing with the loopback interface.
Example:
network-interface: lo
network-url (subscriber)#
This mandatory parameter should be set to the network URL of the target PubSub subscriber. It typically takes the form of opc.eth:// followed by the MAC address of the subscriber’s NIC, for example, opc.eth://xx-xx-xx-xx-xx-xx. Multicast over Ethernet or loopback can specify the value, opc.eth://ff-ff-ff-ff-ff-ff, while multicast over UDP can specify the value, opc.udp://224.0.0.22:4840.
Example:
network-url: "opc.eth://ff-ff-ff-ff-ff-ff"
publisher-id (subscriber)#
This mandatory parameter along with writer-group-id and dataset-writer-id form a set of unique identifiers for one PubSub publisher and subscriber pair. Subscribers will only receive data from Publishers that have matching values. This value should be an integer between 1 and 65534.
Example:
publisher-id: 100
writer-group-id (subscriber)#
This mandatory parameter along with publisher-id and dataset-writer-id, together form a set of unique identifiers for one PubSub publisher and subscriber pair. Subscribers will only receive data from Publishers that have matching values. This value should be an integer between 1 and 65534.
Example:
writer-group-id: 200
dataset-writer-id (subscriber)#
This mandatory parameter along with write-group-id and publisher-id form a set of unique identifiers for one PubSub publisher and subscriber pair. Subscribers will only receive data from Publishers that have matching values. This value should be an integer between 1 and 65534.
Example:
dataset-writer-id: 300
security-type (subscriber)#
This parameter is optional and defines whether PubSub should encrypt communications. The allowed values are:
0=none
1=AES128 keys file
2=sealed AES128 keys file
3=AES256 keys file
6=sealed AES256 keys file
5=TPM AES128 and HMAC keys
6=TPM AES256 & HMAC keys
Example: This example sets the security type to use an unsealed AES128 keys file.
security-type: 1
tpm-keys-file (subscriber)#
This parameter must be defined when security-type is set to 1, 2, 3, or 4. It defines the local file containing the AES and HMAC keys.
Example:
tpm-keys-file: "../security/pubsub128.key"
tpm-slot (subscriber)#
This parameter must be defined when security-type is set to 2, 4, 5, or 6. It defines the slot number containing the TPM keys.
Example:
tpm-slot: 1
tpm-user-pin (subscriber)#
This parameter must be defined when security-type is set to 2, 4, 5, or 6. It defines the user pin used to access the TPM keys.
Example:
tpm-user-pin: 123456
tpm-sealing-key-label (subscriber)#
This parameter must be defined when security-type is set to 2 or 4. It defines the label used to find the AES key in the TPM for unsealing the local encrypted keys file.
Example:
tpm-sealing-key-label: "opcua_key"
tpm-aes-key-label (subscriber)#
This parameter must be defined when security-type is set to 5 or 6. It defines the label used to find the AES key in the TPM for PubSub encryption.
Example:
tpm-aes-key-label: "enc_key"
tpm-hmac-key-label (subscriber)#
This parameter must be defined when security-type is set to 5 or 6. It defines the label used to find the HMAC key in the TPM for PubSub encryption.
Example:
tpm-aes-key-label: "enc_key"
nodes/node-id (subscriber)#
This mandatory parameter defines the OPC UA variable nodes to which the incoming published data should be written. The specified variable nodes must exactly match those defined in the corresponding Publisher.
Example:
nodes:
-
node-id: "ns=1;s=MyDateTime"
OPCSVR - Test Configuration Files#
The following sample test configuration files can be found in the /opt/ec-protocol-bridge/config/ folder:
opcsvr.yaml: anonymous accessopcsvr-secure.yaml: secure accessopcsvr-secure-enc-file.yaml: secure access using sealed private key file
Advanced Server Configuration Parameters#
This section is intended for those who are very familiar with OPC UA. By design, these parameters provide more flexibility in defining nodes, but at the expense of not being user-friendly. Those unfamiliar with OPC UA, its namespace zero definitions, node references, and node attributes should avoid using these configuration parameters. Describe the details of each of these parameter is not within the scope of this document, since it requires specific OPC UA domain knowledge.
Proceed further only if you are familiar with OPC UA.
These advanced parameters permit the creation of dynamic object and variable nodes in an OPC UA server. Object nodes may be created using the object-node-id parameter. Variable nodes may be created using the variable-node-id parameter. Each may have other associated attribute such as parent-node-id, and so on.
The following example is self-explanatory, with recognizable parameter names and formats that should be understandable to those familiar with OPC UA node definition.
This example shows all the advanced parameters available in a YAML- configuration file for defining nodes.
add-nodes:
-
object-node-id: "ns=1;s=MyObject" # required for object nodes
-
object-node-id: "ns=1;s=MyFolder" # required for object nodes
objtype-node-id: "ns=0;i=61" # Folder, default: "ns=0;i=58" #BaseObjectType
parent-node-id: "ns=1;s=MyObject" # default "ns=0;i=85" #ObjectsFolder
-
object-node-id: "ns=1;s=MySubFolder" # required for object nodes
objtype-node-id: "ns=0;i=61" # Folder, default: "ns=0;i=58" #BaseObjectType
parent-node-id: "ns=1;s=MyFolder" # default "ns=0;i=85" #ObjectsFolder
-
variable-node-id: "ns=1;s=MyFloat" # required for variable nodes
datatype-node-id: "ns=0;i=10" # Float, default: "ns=0;i=24" #BaseDataType
vartype-node-id: "ns=0;i=68" # Property, default: "ns=0;i=63" #BaseDataVariableType
parent-node-id: "ns=1;s=MySubFolder" # default: "ns=0;i=85" #ObjectsFolder
default-value: 12.34 # default: <none>, available only for the common scalar datatypes show below
-
object-node-id: "ns=1;s=MyPubSubGrp" # required for object nodes
objtype-node-id: "ns=0;i=14232" # default: "ns=0;i=58" #BaseObjectType
include-optional: y # default: n
-
variable-node-id: "ns=1;s=strvar" # required for variable nodes
description: "A string" # default: ""
display-name: "MyString" # default is to use identifier value
datatype-node-id: "ns=0;i=12" # examples of common base datatypes:
# 1 = boolean
# 2 = signed byte (a.k.a. int8)
# 3 = byte (a.k.a. uint8)
# 4 = int16
# 5 = uint16
# 6 = int32
# 7 = uint32
# 8 = int64
# 9 = uint64
# 10 = float
# 11 = double
# 12 = string
# 13 = datetime
access-level: 3 # bit mask: default = 3 (read & write)
# 1 = READ
# 2 = WRITE
# 4 = HISTORYREAD
# 8 = HISTORYWRITE
# 16 = SEMANTICCHANGE
# 32 = STATUSWRITE
# 64 = TIMESTAMPWRITE
write-mask: 0 # bit mask; default = 0 (none)
# 1 = ACCESSLEVEL
# 2 = ARRRAYDIMENSIONS
# 4 = BROWSENAME
# 8 = CONTAINSNOLOOPS
# 16 = DATATYPE
# 32 = DESCRIPTION
# 64 = DISPLAYNAME
# 128 = EVENTNOTIFIER
# 256 = EXECUTABLE
# 512 = HISTORIZING
# 1024 = INVERSENAME
# 2048 = ISABSTRACT
# 4096 = MINIMUMSAMPLINGINTERVAL
# 8192 = NODECLASS
# 16384 = NODEID
# 32768 = SYMMETRIC
# 65536 = USERACCESSLEVEL
# 131072 = USEREXECUTABLE
# 262144 = USERWRITEMASK
# 524288 = VALUERANK
# 1048576 = WRITEMASK
# 2097152 = VALUEFORVARIABLETYPE
parent-node-id: "ns=0;i=85" # default: "ns=0;i=85" #ObjectsFolder
default-value: "Hello!" # default: <none>, available only for the common scalar datatypes show above