.. _configure: Configuration ============= As of today, configuration of the *ogamma* Modbus OPC UA Server is done by editing of the configuration file. Location of the file is ``data/config.json``. Intially file does not exist, and is created automatically at application start up. Changing configuration settings. --------------------------------- Configuration settings are defined in JSON format, and can be modified in 3 different ways: 1. Editing the file in place. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Configuration file ``data/config.json`` can be edited using text editor. The application monitors changes in the configuration file, and changes will be applied without restart. Existing connections will be closed and clients need to reconnect after configuration changes though. 2. Over OPC UA interface. ^^^^^^^^^^^^^^^^^^^^^^^^^ Two methods are defined in the OPC UA server address space to facilitate editign of the server configuration: ``Server/Get Configuration`` to receive the current settings from the server, and ``Server/ Set Configuration`` to replace the configuration file. To get the current configuration form the server, connect to it using OPC UA client and call method ``Get Configuration``: .. thumbnail:: images/GetConfiguration.png To apply new configuration, connect to the server using OPC UA client and call method ``Set Configuration``. In case of success, the server should restart and apply changes automatically. .. thumbnail:: images/SetConfiguration.png 3. Using environment variables ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ A few environment variables can be used to change some configuration options. Note that these settings have priority over settings defined in the configuration file. They are not applied when the configuration is modified over OPC UA interface. * ``OMOUAS_PORT`` - type: integer, defines OPC UA Server port number. * ``OMOUAS_HOST`` - type: string, defines host name used in discovery and endpoint URLs returned by the server, as well as in the application instance certificate. * ``OMOUAS_ACCEPT_ANY_CERTIFICATE`` - type: boolean, if set to value ``true``, any client certificates will be accepted to open secured connection. In production environment must be set to ``false``. * ``OMOUAS_ENABLE_NONE_SECURE_ENDPOINT`` - type: boolean, if set to value ``true``, none-secure endpoint can be used to create session. When set to false (default value), none-secure endpoint can be used only to call discovery services (FindServers and GetEndpoints). Description of configuration settings. --------------------------------------- Default configuration file ^^^^^^^^^^^^^^^^^^^^^^^^^^ When the application starts very first time, it creates default configuration file at location ``data/config.json`` (relative to the working directory). The content of the file is quoted in the code block below. .. include:: config.json :code: json Desctiption of configuration settings. ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ * ``id``, ``idh``, ``td`` - these nodes used internally and must be kept unchanged. * ``server`` - settings related to the general OPC UA Server properties. * ``port`` - TCP port on which the server listens to accept connections from OPC UA clients. Default value os 4840. * ``hostName``- host name of the machine where the application runs. It is used as part of discovery and endpoint URLs, as well as in the application instance certificate. If set to empty value, then the application will determine host name by making systems call. * ``endpointUrlPath`` - the postfix part in the OPC UA endpoint URL (the portion following after port number). Default value is empty. * ``acceptAnyCertificate`` - when set to ``true``, any OPC UA client certificate will be accepted in secured connections. Default value is ``false``. * ``enableNoneSecureEndpoint`` - when set to ``true``, connections in none-secure mode are allowed. Default value is ``false``. * ``receiveBufferSize`` - size of the receiving buffer, default value is ``1048576`` (in bytes). In most cases no need to change this value. * ``sendBufferSize`` - size of the sending buffer, default value is ``1048576`` (in bytes). In most cases no need to change this value. * ``modbus / devices`` - arry of settings defining what Modbus devices to connect to to, and what registers to expose. For each array element of object type there will be created corresponding node in the OPC UA Server's address space under ``Objects / DeviceSet``. Each node can have the following below sub-nodes: * ``unitId`` - Modbus device's unit id. Must be unique for each device node. * ``name`` - display name of the device. * ``browseName`` - used as ``BrowseName`` attribute of the Modbus device node * ``description`` - used as ``Description`` attribute of the Modbus device node. * ``type`` - defines what protocol to use to connect to the Modbus device. Can be ``TCP`` for TCP connections or ``RTU`` for serial connections (RS-232 or RS-485). The rest of options depends on the value of the ``type`` option. When ``type`` is set to value ``TCP``, following below options are used: * ``hostName`` - IP address of the Modbus device. Default value: ``127.0.0.1``. Note: only IPV4 addresses are supported, no host names can be used in the version 1.0. * ``port`` - port number used to connect to the Modbus device. Default value is ``502``. When option ``type`` is set to ``RTU``, the following below options are used (their name start with ``serial`` prefix): * ``serialDeviceName`` - name of serial device. In Windows machines, it is defined as ``COM1``, ``COM2``, and so on. In Linux systems often defiend as ``/dev/ttyS0``. * ``serailBaudRate``, ``serialDataBits``, ``serailParity``, ``serailStopBits`` define the rest of serial communicaiton options. The next object nodes are used to group variables representing Modbus registers. They can be of 4 different type, and have similar structure: * ``name`` - display name of the OPC UA node. * ``brosweName`` - attribute ``BrowseName`` of the OPC UA node. * ``variables`` - array of variables representing Modbus registers. * ``inputCoils`` - defines Modbus input coils represented in the OPC UA server address space. * ``outputCoils`` - defines Modbus output coils represented in the OPC UA server address space. * ``inputRegisters`` - defines Modbus input registers represented in the OPC UA server address space. * ``holdingRegisters`` - defines Modbus holding (output) registers represented in the OPC UA server address space. The ``variables`` node is JSON array consisting of elements defined as objects with the following below fields: * ``name`` - used as display name and as well as browse name of the OPC UA Variable node. As part, it can have the placeholder ``[index]``, which will be replaced by value of the ``index`` virtual variable. the ``index`` virtual valiable by defualt is set to 1, and is incremented by 1 for the next variable. This way, it is possible to define the field ``name`` as like ``Room [index] temperature``. It will be defined as ``Room 1 temperature`` at runtime, the next variable name will be ``Room 2 temperature``, and so on. To limit number of variables generated this way, another option, ``number`` is used. Its default value is 1, which means, only one variable OPC UA variable wil be created in the address space. If it is set to value greater than 1, then that number of OPC UA variables will be created in the OPC UA server address space. When option ``number`` exists``, it is expected that the field ``name`` has placeholder ``[index]`` or ``[offset]``, so they have unique names. Note that sometimes you might need to define index values with specific width, for example, to make sure that they are ordered properly, like ``Register 001``, ``Register 002``, and so on. For this, it is possible to define option ``indexFormat`` with value like ``{:03d}``. Here ``3`` means width of the index number, and ``0`` means padding symbol. For more detials about syntax for this option refer to this web page: https://fmt.dev/latest/syntax.html * ``dataType`` - this field defines data type of the OPC UA variable node. Can have the following values: * ``Boolean`` - boolean type; * ``Int16`` - signed 16-bit integer * ``UInt16`` - unsigned 16-bit integer * ``Int32`` - signed 32-bit integer * ``UInt32`` - unsigned 32-bit integer * ``Int64`` - signed 64-bit integer * ``UInt64`` - unsigned 64-bit integer * ``Float`` - 32 bit float point number * ``Double`` - 64 bit float point number * ``String`` - String type. In this case additional field ``length`` must be defined, defining string length. * ``ByteString`` - ByteString type. In this case additional field ``length`` must be defined, defining string length. * ``offset`` - defines offset of the register, starting from 0. If omitted, for the very first variable value 0 is used. For the next variables, next available Modbus register offset will be used. ?If registers are following without gaps, it is possible to omit it completely. Value of this field can also be used to substitute placeholder ``[offset]`` in the ``name`` field. * ``index`` - value of this option is used to substitute placeholder ``[index]`` in the ``name`` option as described above. * ``arrayLength`` - must be set to -1 in version 1.0. In the future versions will be used as array length for array type variables. * ``swapBytes`` - optional, can be used for input and holding registers to indicate that order if bytes must be swapped. * ``swapWords`` - optional, can be used for input and holding register with data types occupying 2 or more registers to indicate that order if words must be swapped. Configuring trust to OPC UA Client certificates ------------------------------------------------- By default, the *ogamma* Modbus OPC UA Server is confured to allow only secured connections, and to not accept client certificates if they are not in the list of trusted certificates (the option ``acceptAnyCertificate`` is set to ``false`` and option ``enableNoneSecureEndpoint`` is set to ``false``). In such configuration, clients can open OPC UA Sessions only in secured mode. When a client tries to connect in secured mode, initially connection will not be accepted, because client certificate is not trusted. The client's certificate will be stored in the folder ``data/pki/rejected/certs``. To allow connections in secured mode, this stored certificate can be copied to the folder where trusted certificates are stored: ``data/pki/trusted/certs``. Alternatively, you can obtain the client certificate by other means and store it there. The certificate format must be ``der``. If the client certificate is signed by a CA certificate, then one certificate from the certificates chain must be saved in the folder ``data/pki/trusted/certs``. The CA certificates which are not in the trusted certificates folder, must be stored in the folder of known issuers, that is ``data/pki/issuer/certs``. And additionally, any CA certificate from the chain must have certificate revocation list file stored in folder ``data/pki/crls``. .. note:: In Windows machines, after storing or removing a file in one of the PKI folders ``data/pki/trusted/certs``, ``data/pki/issuer/certs`` or ``data/pki/crls``, the application restarts the OPC UA Server object to apply changes, so existing client connections will be closed. In Linux machines no such restart is done, so changes are applied in new connections. Restarting OPC UA Server object and stopping the application ------------------------------------------------------------- To stop the application, termination signal can be sent at the operating system level, as well as ``Ctrl+C`` keys combination works too. The application also can be stopped by creating a file ``data/omouas-exit.txt``. Note that the file will be deleted before exiting, to prevent inifinite start/exit loops. Restarting of the internal OPC UA Server object can be done by creating a file ``data/omouas-restart.txt``. Note that the file will be deleted to prevent infinite restarts. Another way to restart is by calling method ``Server/Restart`` over OPC UA connection.