KNet for OPC (KNetOPC): Sink connector configuration reference

Overview

Like the Source connector, the KNetOPC Sink connector is configured through two separate files:

The Kafka Connect properties file (.properties for standalone mode, .json for distributed mode) — controls runtime behavior and request/response topic routing. See Connectors for the full Kafka Connect property reference.
The OPC-UA configuration file (KNetOPCSink.json) — controls OPC-UA session parameters. This page documents the OPC-UA configuration file.

The OPC-UA configuration file is referenced from the Kafka Connect properties file via one of two mutually exclusive properties:

Kafka Connect property	Description
`knet.opc.config.filename`	Path to the OPC-UA configuration file on disk. If a bare filename is provided, the connector searches in the connector package's `etc` subfolder.
`knet.opc.config.content`	The full OPC-UA configuration file encoded as a Base64 string. Use the `MASES.KNet.OPC.Configuration.Converter` tool to generate this value.

Configuration model

The Sink connector OPC-UA configuration file contains a single top-level section:

SessionConfigurationType — OPC-UA session parameters, shared with the Source connector. This is a rename of the SessionConfiguration section used in previous versions.

Unlike the Source connector, the Sink connector does not have Subscriptions, GlobalKafkaConnectParameters, or GlobalMonitoredItemParameters sections — those are Source-specific concepts. All routing configuration (request topic, reply topic, timeouts) lives in the Kafka Connect properties file.

Root properties

Property	Type	Required	Description
`ApplicationName`	string	Yes	User-defined name for the application instance. May be included in the Kafka record key.
`ApplicationVersion`	string	Yes	User-defined version for the application instance. May be included in the Kafka record key.
`SessionConfiguration`	object	Yes	OPC-UA session parameters. See SessionConfiguration.

SessionConfiguration

Describes how the Sink connector connects to the OPC-UA server. This section is identical in structure to the SessionConfigurationType section of the Source connector — see Source connector configuration for the full property reference.

Property	Type	Required	Default	Description
`EndPoint`	string	Yes	—	OPC-UA endpoint URL of the server (e.g. `opc.tcp://host:port/path`).
`ConfigFilename`	string	No	—	Path to the OPC-UA stack XML configuration file. Resolved relative to the OPC-UA configuration file location if the path is relative.
`SessionName`	string	No	internal identifier	Name assigned to the OPC-UA session.
`UserName`	string	No	—	Username for username/password authentication.
`Password`	string	No	—	Password for username/password or certificate authentication.
`Certificate`	string	No	—	Certificate for certificate-based authentication.
`AutoAccept`	boolean	No	`true`	When `true`, untrusted certificates are automatically accepted.
`AutoAcceptStatusCodes`	array of integer	No	all codes	OPC-UA `StatusCode` values accepted when `AutoAccept` is `true`.
`UseSecurity`	boolean	No	`false`	When `true`, encryption is enabled on the OPC-UA channel.
`UpdateBeforeConnect`	boolean	No	`false`	When `true`, the discovery endpoint is queried before connecting.
`CheckDomain`	boolean	No	`false`	When `true`, the server certificate domain must match the endpoint.
`OperationTimeout`	integer (ms)	No	`60000`	Timeout for all requests sent to the OPC-UA server.
`KeepAliveInterval`	integer (ms)	No	`1000`	Interval between keep-alive requests.
`SessionTimeout`	integer (ms)	No	`60000`	Session lifetime in milliseconds.
`ReconnectPeriod`	integer (ms)	No	`60000`	Reconnection interval after a disconnection.
`ReconnectPeriodExponentialBackoff`	integer (ms)	No	`15000`	Exponential back-off increment applied between reconnection attempts.
`ReverseConnectUrl`	string	No	`null` (disabled)	URL for the reverse connection manager.
`PreferredLocales`	array of string	No	`["en-US"]`	Preferred locales for the OPC-UA session.

Sink-specific properties

RetriableStatusCodes

RetriableStatusCodes is an optional array of OPC-UA StatusCode values (as unsigned integers) that the Sink connector treats as transient errors. When the OPC-UA server returns one of these codes, the connector signals to the Kafka Connect runtime that the record can be retried rather than failing permanently.

Property	Type	Required	Default	Description
`RetriableStatusCodes`	array of uint	No	`[0x80EE0000]`	List of OPC-UA status codes that trigger a retry. The default value `0x80EE0000` corresponds to `BadServerTooBusy`. All other OPC-UA status codes are available in the OPC-UA specification.
`LogEventAtInfoLevel`	boolean	No	`false`	When `true`, each OPC-UA operation executed by the connector is logged at `Info` level. Leave at `false` in production to reduce logging overhead.

Example

{
  "ApplicationName": "MyApp",
  "ApplicationVersion": "1.0.0",
  "SessionConfiguration": {
    "ConfigFilename": "KNetOPC.Config.xml",
    "EndPoint": "opc.tcp://172.31.48.1:62640/masesgroup/ServerSimulator",
    "SessionName": "MyApp",
    "ReconnectPeriod": 5000,
    "ReconnectPeriodExponentialBackoff": 1000,
    "OperationTimeout": 10000
  }
}

JSON schema

{
  "title": "Root KNet for OPC Sink Connector Configuration",
  "description": "The configuration used from Sink Connector of KNet for OPC.",
  "definitions": {
    "SessionConfigurationType": {
      "title": "Session Configuration",
      "description": "It is a mandatory section which describes how to connect to the OPC-UA Server.",
      "type": "object",
      "properties": {
        "ConfigFilename": {
          "title": "OPC-UA Configuration file",
          "description": "The file containing the information used from the OPC-UA Stack for the connection to an OPC-UA server (see https://opcfoundation.org/about/opc-technologies/opc-ua/). If the file location is relative to this file location the connector automatically discover it, otherwise the location shall be an absolute path.",
          "type": [
            "string",
            "null"
          ]
        },
        "EndPoint": {
          "title": "Remote OPC-UA Endpoint",
          "description": "The URL where the remote OPC-UA server is exposing (see https://opcfoundation.org/about/opc-technologies/opc-ua/).",
          "type": "string"
        },
        "AutoAccept": {
          "title": "AutoAccept",
          "description": "If set to true automatically accepts certificates; otherwise AutoAcceptStatusCodes is checked.",
          "type": "boolean"
        },
        "AutoAcceptStatusCodes": {
          "title": "AutoAccept StatusCode",
          "description": "The list of StatusCode used to valid a certificate if AutoAccept is set to true; The values are BadCertificatePolicyCheckFailed (The certificate does not meet the requirements of the security policy.) = 0x81140000; BadCertificateTimeInvalid (The certificate has expired or is not yet valid.) = 0x80140000; BadCertificateIssuerTimeInvalid (An issuer certificate has expired or is not yet valid.) = 0x80150000; BadCertificateHostNameInvalid (The HostName used to connect to a server does not match a HostName in the certificate.) = 0x80160000; BadCertificateUriInvalid (The URI specified in the ApplicationDescription does not match the URI in the certificate.) = 0x80170000; BadCertificateUseNotAllowed (The certificate may not be used for the requested operation.) = 0x80180000; BadCertificateIssuerUseNotAllowed (The issuer certificate may not be used for the requested operation.) = 0x80190000; BadCertificateUntrusted (The certificate is not trusted.) = 0x801A0000; BadCertificateRevocationUnknown (It was not possible to determine if the certificate has been revoked.) = 0x801B0000; BadCertificateIssuerRevocationUnknown (It was not possible to determine if the issuer certificate has been revoked.) = 0x801C0000; BadCertificateRevoked (The certificate has been revoked.) = 0x801D0000; BadCertificateIssuerRevoked (The issuer certificate has been revoked.) = 0x801E0000; BadCertificateChainIncomplete (The certificate chain is incomplete.) = 0x810D0000. By default all values are added to the list.",
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "integer"
          }
        },
        "UseSecurity": {
          "title": "Use Security for OPC-UA Endpoint",
          "description": "Set the value to true to enable the usage of encryption on OPC-UA channels.",
          "type": "boolean"
        },
        "UpdateBeforeConnect": {
          "title": "Update configuration before connect to an OPC-UA channel",
          "description": "If set to true the discovery endpoint is used to update the endpoint description before connecting (see https://opcfoundation.org/about/opc-technologies/opc-ua/).",
          "type": "boolean"
        },
        "CheckDomain": {
          "title": "Check Domain on OPC-UA certificate",
          "description": "If set to true then the domain in the certificate must match the endpoint used (see https://opcfoundation.org/about/opc-technologies/opc-ua/).",
          "type": "boolean"
        },
        "SessionName": {
          "title": "Session Name assigned",
          "description": "The name to assign to the session.",
          "type": [
            "string",
            "null"
          ]
        },
        "UserName": {
          "title": "User Name",
          "description": "The username to be used when the connection authentication needs a username/password identity.",
          "type": [
            "string",
            "null"
          ]
        },
        "Certificate": {
          "title": "Certificate",
          "description": "The certificate to be used when the connection authentication needs a certificate identity.",
          "type": [
            "string",
            "null"
          ]
        },
        "Password": {
          "title": "Password",
          "description": "The password to be used when the connection authentication needs a username/password or certificate identity.",
          "type": [
            "string",
            "null"
          ]
        },
        "OperationTimeout": {
          "title": "Operation Timeout",
          "description": "The timeout in milliseconds associated to all requests made to the OPC-UA server (see https://opcfoundation.org/about/opc-technologies/opc-ua/).",
          "type": "integer"
        },
        "KeepAliveInterval": {
          "title": "KeepAlive Interval",
          "description": "The interval, in milliseconds, between each keepalive request made on the OPC-UA server (see https://opcfoundation.org/about/opc-technologies/opc-ua/).",
          "type": "integer"
        },
        "SessionTimeout": {
          "title": "Session Timeout",
          "description": "The timeout period, in milliseconds, for the session (see https://opcfoundation.org/about/opc-technologies/opc-ua/).",
          "type": "integer"
        },
        "ReverseConnectUrl": {
          "title": "Reverse Connect Url",
          "description": "The Url used from the reverse connection manager. Default is null which disables the feature.",
          "type": [
            "string",
            "null"
          ]
        },
        "ReconnectPeriod": {
          "title": "Reconnect Period",
          "description": "The interval, in milliseconds, the connector tries to reconnect after a disconnection before declares the OPC-UA server no more reachable and informs the Apache Kafka Connect infrastructure.",
          "type": "integer"
        },
        "ReconnectPeriodExponentialBackoff": {
          "title": "Reconnect Period Exponential Backoff",
          "description": "The reconnect period exponential backoff to be used in milliseconds.",
          "type": "integer"
        },
        "PreferredLocales": {
          "title": "Preferred Locales",
          "description": "The preferred locales (see https://opcfoundation.org/about/opc-technologies/opc-ua/).",
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": [
              "string",
              "null"
            ]
          }
        }
      },
      "required": [
        "EndPoint"
      ]
    }
  },
  "type": "object",
  "properties": {
    "RetriableStatusCodes": {
      "title": "Retriable StatusCode",
      "description": "The list of StatusCode used to inform Connect it can retry the execution; The default value is BadServerTooBusy (The Server does not have the resources to process the request at this time.) = 0x80EE0000; All other values are available in OPC-UA specification.",
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "integer"
      }
    },
    "LogEventAtInfoLevel": {
      "title": "Log Event at Info Level",
      "description": "Use Info level to write the requested operations in the logs, default is false to reduce the application stress.",
      "type": "boolean"
    },
    "ApplicationName": {
      "title": "Application Name",
      "description": "The user defined name associated to the application where the connector is in use; can be used to describe the published data and can be added to the record key.",
      "type": "string"
    },
    "ApplicationVersion": {
      "title": "Application Version",
      "description": "The user defined version associated to the application where the connector is in use; can be used to describe the published data and can be added to the record key.",
      "type": "string"
    },
    "SessionConfiguration": {
      "$ref": "#/definitions/SessionConfigurationType"
    }
  },
  "required": [
    "ApplicationName",
    "ApplicationVersion",
    "SessionConfiguration"
  ]
}

Table of Contents