Configuring the CygNet OPC UA Server

After installing the CygNet OPC UA Server application, a configuration file, CygNetOpcUaServer.Config.xml, is included in the installation package, and must be configured to your system's specifications. The configuration file must be located in C:\ProgramData\Weatherford\CygNetOpcUaServer\.

The CygNet OPC UA Server will only pick up any changes to this file on startup, so the server must be restarted anytime a change is made.

See the following subsections for more information:

Default Configuration

The following table describes the default elements found in the default CygNetOpcUaServer.Config.xml file.

Element Description Required Default

<ApplicationConfiguration>

The parent element for the configuration file. Specifies the XML namespaces and schemaLocation used by the OPC UA Server. Nested within this element are extended settings specific to the CygNet OPC UA Server.

yes

xmlns:ua="http://opcfoundation.org/UA/2008/02/Types.xsd"

xmlns="http://opcfoundation.org/UA/SDK/Configuration.xsd"

schemaLocation="./Schema/ApplicationConfiguration.xsd"

<ServerConfiguration>

The parent element for general server configuration information for the application. Nested within this element are other elements that define the server settings for the CygNet OPC UA Server. See ServerConfiguration below.

yes

  

<BaseAddresses>

The parent element for the base address URL used by the CygNet OPC UA Server.

 no  

<ua:String>

Specifies the base address (URL) for accessing the CygNet OPC UA server.

yes, if
<BaseAddresses>
is included

opc.tcp://localhost:51210/CygNetOpcUaServer

"localhost" restricts client access to a client running on the server host.

To allow access from a remote client machine, modify this setting to specify the hostname and/or port, for example,

opc.tcp://opcuahost:51211/CygNetOpcUaServer

<Extensions>

The parent element for the extended settings specific to the CygNet OPC UA Server application. Nested within this element are other elements that define CygNet configuration settings, logging settings, and model builder configuration settings for the CygNet OPC UA Server application.

yes

  

<ua:XmlElement>

Contains the extended XmlElements specific to the CygNet configuration.

yes

Numerous XmlElement sets are supported.

<CygNetConfiguration>

The parent element for the custom CygNet configuration settings, including the Bridge connection information. Specifies the XML namespace used by the CygNet OPC UA Server.

yes

xmlns="https://weatherford.com/UA/cygnet/"

<CygNetBridgeBaseUrl>

Specifies the URL of the installed CygNet Bridge application.

yes

http://localhost

<CygNetBridgeUsername>

Certain operations of the CygNet OPC UA Server require that the server can log into CygNet Bridge using default credentials. CygNetBridgeUsername specifies the "default" username that will be used in those instances. The username specified will be supplied to Bridge when generating CygNet nodes, when a user subscribes to real-time and alarm notifications, and when a user authenticates with a certificate rather than a username and password. See CygNet Bridge API Access for more information.

yes

bridgeuser

<CygNetBridgePassword>

Specifies the unencrypted password used along with CygNetBridgeUsername so that the server can log into Bridge using default credentials.

yes

bridgepwd

<CygNetBridgePasswordEncrypted>

Specifies the encrypted password used along with CygNetBridgeUsername so that the server can log into Bridge using default credentials.

The CygNet OPC UA Server can use either CygNetBridgePasswordEncrypted or CygNetBridgePassword.

CygNetBridgePasswordEncrypted will replace CygNetBridgePassword once the server is started with the "-encrypt" parameter. See CygNet OPC UA Server Password Encryption for information about encrypting the CygNetBridgePassword.

no

 

<CygNetEncryptionKeyPath>

Specifies the path to the encryption key. When the encryption routine is executed to encrypt CygNetBridgePassword, the process will generate a file that decrypts CygNetBridgePasswordEncrypted internally and on an as-needed basis.

See CygNet OPC UA Server Password Encryption for information about encrypting the CygNetBridgePassword.

no

 

<CygNetModelFilePath>

Specifies the path to the CygNetModel.json file, the predefined CygNet node set binary file, which encapsulates the address space definition and is the output from the model builder script. The CygNet OPC UA Server uses the CygNetModel.json file on startup to populate its node hierarchy.

no

%CommonApplicationData%\Weatherford\CygNetOpcUaServer\
CygNetModel.json

Note: The %CommonApplicationData% token will be resolved by the server at runtime.

<ua:XmlElement>

Contains the extended XmlElements specific to the logging configuration.

no

Numerous XmlElement sets are supported.

<LoggingConfiguration>

The parent element for the custom CygNet logging configuration settings. Specifies the XML namespace used by the OPC UA Server.

no

xmlns="https://weatherford.com/UA/cygnet/"

<FilePath>

The path to the log file(s) generated by the server.

no

%CommonApplicationData%\Weatherford\CygNetOpcUaServer\
Logs\CygNetOpcUaServer.log

Note: The %CommonApplicationData% token will be resolved by the server at runtime.

<FileSizeLimitBytes>

The maximum size, in bytes, that the log file can grow to before the server creates a new log file (in addition to the original one, not in place of it).

no

52428800

<RetainedFileCountLimit>

The maximum number of log files that will be written to before the server begins to overwrite the earliest ones.

no

5

<MinimumLevel>

The minimum level of logging detail that will be logged to the log file. The options are:

  • Fatal — To see only messages related to a fatal termination of the server, use Fatal.
  • Error — To see everything prior, as well as any non-fatal errors, use Error.
  • Warning — To see everything prior, as well as warnings, use Warning.
  • Information — To see everything prior, as well as useful but non-critical information about the operation of the server, use Information. This is the default setting.
  • Debug — To see everything prior, as well as diagnostic messages to help identify the source of problems, use Debug.
  • Verbose — To see every possible message about the server, use Verbose.

no

Information

<ua:XmlElement>

Contains the extended XmlElements specific to the model builder configuration.

yes

Numerous XmlElement sets are supported.

<ModelBuilderConfiguration>

The parent element for the custom model builder configuration settings. The model builder is a mechanism for generating the address space for the CygNet system, which is run when you first set up the CygNet OPC UA Server, and when you make changes to CygNet that you want exposed in OPC UA (such as adding or removing points or facilities, changes to metadata, etc.). Specifies the XML namespace used by the server. See Maintaining the CygNet OPC UA Address Space for more information.

Specifies the XML namespace used by the OPC UA Server.

yes

xmlns="https://weatherford.com/UA/cygnet/"

<CygNetServices>

Specifies a comma-separated list of CygNet current value services (CVS) in the format [DOMAIN]SITE.SERVICE that will be used to generate the CygNetModel.json file when the GenerateCygNetModel.ps1 script is run.

yes

[00000]CYGNET.UIS,[00000]CYGNET.HSS

<DisplayNameProperties>

The parent element for configuring the display names of each nodes in the address space. Contains three child elements for each configurable node property: <Cvs>, <Facility>, and <Point>.

Note: The entire DisplayNameProperties element and any or all of the three child elements may be left out of the configuration file. If missing, the default values for the child elements will be:

  • Cvs — DomainSiteService
  • Facility — Description
  • Point — Description

no

 

<Cvs>

Specifies the display name to be used for the Current Value Service (CVS) node. Possible values for the <Cvs> element are:

  • DomainSiteService
  • SiteService
  • Description

Note: The <Cvs> element is not required. If missing, the default value for the element will be DomainSiteService.

Also see the note about blank attributes below this table.

no

DomainSiteService

<Facility>

Specifies the display name to be used for the Facility node. Possible values for the <Facility> element are:

  • FacilityId
  • FacilityDescription
  • Description
  • FacilityInfoAttribute0
  • FacilityInfoAttribute1
  • FacilityTextAttribute00 — FacilityTextAttribute39
  • FacilityTableAttribute00 — FacilityTableAttribute59
  • FacilityTableAttribute00Description — FacilityTableAttribute59Description
  • FacilityTag

Note: The <Facility> element is not required. If missing, the default value for the element will be Description.

Also see the note about blank attributes below this table.

no

Description

<Point>

Specifies the display name to be used for the Point node. Possible values for the <Point> element are:

  • Description
  • Tag
  • TagLong
  • TagFull
  • PointId
  • PointIdLong
  • UDC
  • UDCDescription
  • LongDescription
  • SystemDescription
  • PointDataTypeDescription
  • AlarmCategoryDescription
  • Comment
  • Indexed1
  • Indexed2
  • Indexed3
  • TableDriven1
  • TableDriven2
  • TableDriven3
  • TableDriven1Description
  • TableDriven2Description
  • TableDriven3Description
  • GeneralData1
  • GeneralData2
  • GeneralData3
  • ExternalId

Note: The <Point> element is not required. If missing, the default value for the element will be Description.

Also see the note about blank attributes below this table.

no

Description

Blank Display Name Attributes

Note that there is another kind of "default" for the <Cvs>, <Facility>, and <Point> elements. If the value resolved by the CygNet service is blank for whatever attribute is chosen (for example, if you choose Description for Facility, but a facility’s description is blank), then the following defaults will be used:

This is because none of these attributes above can ever be blank in a CygNet system, so this guarantees that nodes will never have a blank display name.

Back to top

Server Configuration

The <ServerConfiguration> section of the CygNetOpcUaServer.Config.xml defines general server information for the CygNet OPC UA Server application. This section appears in the default CygNetOpcUaServer.Config.xml file, but can be supplemented with the following elements to override default server settings.

When subscribing to large numbers of points, it is recommended to use a single Subscription for multiple MonitoredItems. We recommend between 5,000 and 10,000 MonitoredItems per subscription. If you run into issues with a large number of Subscriptions or MonitoredItems, you can increase one or more of the following parameters by adding these elements to your CygNet OPC UA Server configuration file. See Troubleshooting the CygNet OPC UA Server for more information about Subscriptions and MonitoredItems.

To configure server settings

  1. Open the CygNetOpcUaServer.Config.xml in a text or xml editor.
  2. Copy the three elements between the <ServerConfiguration> parent elements and paste into the <ServerConfiguration> section of the CygNetOpcUaServer.Config.xml. The elements are described in the table below.
  3. Edit the elements as necessary.
  4. Restart the CygNet OPC UA Server.

ServerConfiguration XML

Add the following XML to your CygNetOpcUaServer.Config.xml to set the maximum message queue size, notifications per publish, and subscription count for the server.

<ServerConfiguration>

<MaxMessageQueueSize>10000</MaxMessageQueueSize>

<MaxNotificationsPerPublish>1000</MaxNotificationsPerPublish>

<MaxSubscriptionCount>100</MaxSubscriptionCount>

</ServerConfiguration>

ServerConfiguration Elements

The following table describes the <ServerConfiguration> elements that can be added to the CygNetOpcUaServer.Config.xml file.

Element Description Required Default

<ServerConfiguration>

The parent element for general server configuration information for the application. Nested within this element are other elements that define the server settings for the CygNet OPC UA Server.

yes

  

<MaxMessageQueueSize>

The maximum number of messages in the internal queue in the CygNet OPC UA Server. If this limit is reached, the server will drop messages, and they won’t be delivered to the client.

This will be logged in the log file with a message such as, "WARNING: QUEUE OVERFLOW. Dropping <X> Messages. Increase MaxMessageQueueSize. SubId=<id>, MaxMessageQueueSize=10000"

no

10,000

<MaxNotificationsPerPublish>

The maximum number of notifications in each publish from the CygNet OPC UA Server. Things that can affect this are the total number of notifications being processed by the server, and the Publishing Interval specified by the client when creating the Subscription.

no

1,000

<MaxSubscriptionCount>

The maximum allowed number of subscriptions.

no

100

Back to top

Security Configuration

The <SecurityConfiguration> section of the CygNetOpcUaServer.Config.xml defines certificate information for the CygNet OPC UA Server application. This section does not appear in the default CygNetOpcUaServer.Config.xml file, but can be added to override default certificate locations.

To override the default certificate locations

  1. Open the CygNetOpcUaServer.Config.xml in a text or xml editor.
  2. Copy the following xml and paste into the CygNetOpcUaServer.Config.xml as a child of <ApplicationConfiguration> element (a sibling of <Extensions> element). The <SecurityConfiguration> elements are described in the table below.
  3. Edit the elements as necessary.
  4. Restart the CygNet OPC UA Server.

SecurityConfiguration XML

Add the following XML block to your CygNetOpcUaServer.Config.xml to override the certificate locations.

Copy

CygNetOpcUaServer.Config.xml

<SecurityConfiguration>
    <!-- Where the application instance certificate is stored (MachineDefault) -->
    <ApplicationCertificate>
        <StoreType>X509Store</StoreType>
        <StorePath>CurrentUser\My</StorePath>
        <SubjectName>CN=CygNet OPC UA Server, C=US, S=Arizona, O=OPC Foundation, DC=localhost</SubjectName>
    </ApplicationCertificate>
     
    <!-- Where the issuer certificate is stored (certificate authorities) -->
    <TrustedIssuerCertificates>
        <StoreType>Directory</StoreType>
        <StorePath>%CommonApplicationData%/Weatherford/CygNetOpcUaServer/Certificates/Issuer</StorePath>
    </TrustedIssuerCertificates>
     
    <!-- Where the trust list is stored (UA Applications) -->
    <TrustedPeerCertificates>
        <StoreType>Directory</StoreType>
        <StorePath>%CommonApplicationData%/Weatherford/CygNetOpcUaServer/Certificates/Trusted</StorePath>
    </TrustedPeerCertificates>
     
    <!-- The directory used to store invalid certificates for later review by the administrator. -->
    <RejectedCertificateStore>
        <StoreType>Directory</StoreType>
        <StorePath>%CommonApplicationData%/Weatherford/CygNetOpcUaServer/Certificates/Rejected</StorePath>
    </RejectedCertificateStore>
</SecurityConfiguration>

SecurityConfiguration Elements

The following table describes the <SecurityConfiguration> elements that can be added to the CygNetOpcUaServer.Config.xml file.

Element Description Required Default

<SecurityConfiguration>

The parent element for the security configuration for the application. Nested within this element are other elements that define the certificate settings for the CygNet OPC UA Server.

no

  

<ApplicationCertificate>

Contains the application certificate storage details.

The <ApplicationCertficate> element identifies the CygNet OPC UA Server application itself. A certificate will be generated by the application the first time it is run.

Alternatively, you can provide a certificate from a Certificate Authority (CA), and use the <ApplicationCertficate> element to specify where it resides.

 no  

<StoreType>

The type of application certificate.

 no

X509Store

<StorePath>

The path to the application certificate for the current user.

 no

CurrentUser\My

<SubjectName>

The subject name to use for the application certificate.

 no

CN=CygNet OPC UA Server, C=US, S=Arizona, O=OPC Foundation, DC=localhost

<TrustedIssuerCertificates>

Contains a list of issuer certificates that can be trusted by the server.

 no  

<StoreType>

The storage type for the trusted issuer certificate.

 no

Directory

<StorePath>

The directory where the trusted issuer certificate is stored.

 no

%CommonApplicationData%/Weatherford/CygNetOpcUaServer/Certificates/Issuer>

<TrustedPeerCertificates>

Contains a list of peer certificates that can be trusted by the server.

 no  

<StoreType>

The storage type for the trusted peer certificate.

 no

Directory

<StorePath>

The directory where the trusted peer certificate is stored.

 no

%CommonApplicationData%/Weatherford/CygNetOpcUaServer/Certificates/Trusted

<RejectedCertificateStore>

Contains a list of rejected certificates. Invalid certificates will be copied to the specified location and should be reviewed by the system administrator at some later time.

 no  

<StoreType>

The storage type for the rejected certificate.

 no

Directory

<StorePath>

The directory where the rejected certificates are stored.

 no

%CommonApplicationData%/Weatherford/CygNetOpcUaServer/Certificates/Rejected

Back to top