3. Configuration¶

3.1. Configuring Web Integration Service¶

This document describes how to configure Web Integration Service. To see installation instructions or walk through some simple examples, please see the appropriate section.

When you start Web Integration Service, you can specify a configuration file in XML format (it is not required). In that file, you can set properties that control the behavior of the service. Section 3.3, Section 3.4, and Section 3.5, describe how to write a configuration file.

Section 3.6 explains how to configure the Authentication and Access Control mechanisms included with Web Intergration Service.

3.2. Terms to Know¶

Before learning how to configure Web Integration Service, you should become familiar with a few key terms and concepts:

A Web Integration Service Configuration—represented by the <web_integration_service> XML tag—refers to an execution of Web Integration Service.
An Application—represented by the <application> XML tag—defines a collection of DomainParticipants and their contained entities. Applications are instantiated in the context of a Web Integration Service Configuration. That is, a Web Integration Service Configuration contains a set of applications that contain entities that are accessible for clients of the service.

3.3. How to Load the XML Configuration¶

Web Integration Service loads its XML configuration from multiple locations. This section presents the various approaches, listed in load order.

The first three locations are inherited from Connext DDS (see the RTI Connext DDS Core Libraries User’s Manual).

$NDDSHOME/resource/xml/NDDS_QOS_PROFILES.xml This file contains the Connext DDS default QoS values; it is loaded automatically if it exists. (First to be loaded.).
File in NDDS_QOS_PROFILES environment variable: The files (or XML strings) separated by semicolons referenced in this environment variable are loaded automatically.
<working directory>/USER_QOS_PROFILES.xml This file is loaded automatically if it exists.

The next locations are specific to Web Integration Service.

$NDDSHOME/resource/xml/RTI_WEB_INTEGRATION_SEVICE.xml This file contains the default Web Integration Service configuration; it is loaded if it exists. RTI_WEB_INTEGRATION_SERVICE.xml defines an empty service that clients can add applications to, as well as an example “ShapesDemo” service.
<working directory>/USER_WEB_INTEGRATION_SERVICE.xml This file is loaded automatically if it exists.
File specified using the command-line parameter -cfgFile.

You may use a combination of the above approaches.

Here is an example configuration file. You will learn the meaning of each line as you read the rest of this section.

Listing 3.1 Example Configuration File¶

<?xml version="1.0" encoding="UTF-8"?>
<dds>
    <types>
        <struct name="MyType">
            <member name="name" key="true"
                    type="string" stringMaxLength="128"/>
            <member name="count" type="long" />
        </struct>
    </types>
    <web_integration_service name="ExampleService">
        <application name="MyApplication">
            <domain_participant name="MyParticipant" domain_id="32">
                <register_type name="MyShapeType" type_ref="ShapeType" />
                <topic name="Square" register_type_ref="MyShapeType" />
                <publisher name="MyPublisher">
                    <data_writer name="MySquareWriter" topic_ref="Square" />
                </publisher>
                <subscriber>
                    <data_reader name="MySquareReader" topic_ref="Square" />
                </subscriber>
            </domain_participant>
        </application>
    </web_integration_service>
</dds>

3.4. XML Syntax and Validation¶

Web Integration Service provides DTD and XSD files that describe the format of the XML content. We recommend including a reference to one of these documents in the XML file that contains the service’s configuration—this provides helpful features in code editors such as Visual Studio® and Eclipse®, including validation and autocompletion while you are editing the XML file.

The DTD and XSD definitions of the XML elements are in $NDDSHOME/resources/schema/rti_web_integration_service.dtd and $NDDSHOME/resources/schema/rti_web_integration_service.xsd, respectively.

To include a reference to the XSD document in your XML file, use the attribute xsi:noNamespaceSchemaLocation in the <dds> tag. For example:

Listing 3.2 Including a reference to the XSD document in your XML file¶

<?xml version="1.0" encoding="UTF-8"?>
<dds xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:noNamespaceSchemaLocation="<NDDSHOME>/resource/schema/rti_web_integration_service.xsd">
  <!-- ... -->
</dds>

To include a reference to the DTD document in your XML file, use the <!DOCTYPE> tag.

For example:

Listing 3.3 Including a reference to the DTD document in your XML file¶

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE dds SYSTEM
    "<NDDSHOME>/resource/schema/rti_web_integration_service.dtd">
<dds>
  <!--...-->
</dds>

We recommend including a reference to the XSD file in the XML documents; this provides stricter validation and better autocompletion than the corresponding DTD file.

3.5. XML Tags for Configuring Web Integration Service¶

This section describes the XML tags you can use in a Web Integration Service configuration file. The following diagram and Table 3.1 describe the top-level tags allowed within the root <dds> tag.

Figure 3.1 Top-level Tags in the Configuration File

Table 3.1 Top-level Tags in the Configuration File¶
Tags within `<dds>`	Description	Multiplicity
`<qos_library>`	Specifies a QoS library and profiles. The contents of Connext DDS QoS profile file—see Chapter 17, Configuring QoS with XML, in the RTI Connext DDS Core Libraries User’s Manual.	0 or more
`<domain_library>`	Specifies a domain library. That is, a set of `<domain>` definitions.	0 or more
`<types>`	Defines types that can be used by Web Integration Service.	1 (required)
`<web_integration_service>`	Specifies a Web Integration Service configuration. See Web Integration Service (Section 3.5.1).	1 or more (required)

3.5.1. Web Integration Service¶

3.5.1.1. Web Integration Service Tag¶

A configuration file must have at least one <web_integration_service> tag; this tag is used to configure an execution of Web Integration Service. A configuration file may contain multiple <web_integration_service> tags.

When you start Web Integration Service, you can specify which <web_integration_service> tag to use to configure the service using the -cfgName command-line parameter.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<dds>
    <web_integration_service name="default"/>
    <web_integration_service name="shapesDemoTutorial">
    <!--...-->
    </web_integration_service>
</dds>

Starting Web Integration Service with the following command will use the <web_integration_service> tag with the name default.

$NDDSHOME/bin/rtiwebintegrationservice \
  -cfgFile file.xml -cfgName default

Because a configuration file may contain multiple <web_integration_service> tags, one file can be used to configure multiple Web Integration Service executions.

The following diagram and Table 3.2 describe the tags allowed within a <web_integration_service> tag.

Figure 3.2 Web Integration Service Tag Structure

Table 3.2 Web Integration Service Tag¶
Tags within `<web_integration_service>`	Description and Attributes	Multiplicity
`<application>`	Description Applications are a collection of instantiated DomainParticipants and their contained DDS entities. Attributes `name`: Application name. <web_integration_service name="ExampleService"> <application name="MyApplication"> <!-- ... --> </application> <!-- More application definitions ... --> </web_integration_service>	0 or more

3.5.1.2. Application Tag¶

An <application> provides a way to organize a set of instantiated participants belonging to the same logical application. That is, it provides a namespace that client applications can leverage to categorize their DomainParticipants within a Web Integration Service instance.

When a certain Web Integration Service configuration is instantiated using the -cfgName command-line argument, all its contained applications—along with the DDS entities associated with them—are automatically instantiated as well. This also applies to the creation of new applications via Web Integration Service’s REST API, as the creation of a new application will also trigger the instantiation of all its contained DomainParticipants and entities.

Table 3.3 Application Tag¶
Tags within `<application>`	Description and Attributes	Multiplicity
`<domain_participant>`	Description Specifies a DomainParticipant configuration. Attributes `name`: DomanParticipant name. `domain_ref` (optional): Reference (fully qualified name) to a defined `<domain>` in a domain library. `domain_id` (optional): Domain ID. If specified, overrides the ID of the domain it refers to. If no `domain_id` is specified directly or in the referenced domain, then the default `domain_id` is 0. <application name="MyApplication"> <domain_participant name="MyParticipant" domain_ref="MyDomainLibrary::MyDomain" domain_id="32"> <!-- ... --> </domain_participant> <!-- More DomainParticipant definitions ... --> </application>	0 or more

3.5.1.3. DomainParticipant Tag¶

A <domain_participant> is defined by specifying the set of Entities it contains. This is done using tags such as <publisher>, <subscriber>, <data_writer>, and <data_reader>, which specify an Entity of their corresponding type. These Entities are created within the DomainParticipant instantiated by the <application>, which is instantiated when the Web Integration Service configuration that contains it is created or when a new application is created by the REST API.

The <domain_participant> also specifies <register_type> and <topic>, which can be associated with a Domain where topics and their associated types are either already defined (see section on Domain Libraries) or are defined within the <domain_participant>.

Figure 3.3 DomainParticipant Tag Structure

Table 3.4 Domain Participant Tag¶
Tags within `<domain_participant>`	Description and Attributes	Multiplicity
`<register_type>`	Description Registers a type within the DomainParticipant. The type definition will be instantiated when an associated Topic is created. Attributes `name`: Name under which the type is registered with the DomanParticipants. `type_ref`: Reference (fully qualified name) to a type defined within `<types>`. This is the type that is being registered. <domain_participant name="MyParticipant"> <register_type name="MyShapeType" type_ref="ShapeType" /> <!-- ... --> </domain_participant>	0 or more
`<topic>`	Description Specifies a Topic configuration. Attributes `name`: Topic name. `register_type_ref`: Reference (name) to a `register_type` within the domain or DomainParticipant. <domain_participant name="MyParticipant"> <topic name="Square" register_type_ref="MyShapeType" /> <!-- ... --> </domain_participant>	0 or more
`<publisher>`	Description Specifies a Publisher configuration. Attributes `name`: Publisher name. <domain_participant name="MyParticipant"> <publisher name="MyPublisher"> <!-- DataWriters or PublisherQos --> </publisher> <!-- ... --> </domain_participant>	0 or more
`<subscriber>`	Description Specifies a Subscriber configuration. Attributes `name`: Subscriber name. <domain_participant name="MyParticipant"> <subscriber name="MySubscriber"> <!-- DataReaders or SubscriberQos --> </subscriber> <!-- ... --> </domain_participant>	0 or more
`<participant_qos>`	Description DomainParticipant QoS configuration. Attributes `base_name` (optional): Reference (fully qualified name) to a QoS Profile. <domain_participant base="MyParticipant"> <!-- ... --> <participant_qos base="MyQosLibrary::MyQosProfile"> <!-- You may override the referenced QosProfile by defining QoS settings here. --> </participant_qos> </domain_participant>	0 or 1

3.5.1.4. Publisher Tag¶

The <publisher> tag specifies a Publisher configuration. That is, it defines a set of DataWriters using the <data_writer> tag, as well as the Publisher’s QoS settings using the <publisher_qos> tag.

Web Integration Service does not support the use of implicit Publishers. Therefore, users must define DataWriters under an existing <publisher> tag in the configuration file.

Table 3.5 Publisher Tag¶
Tags within `<publisher>`	Description and Attributes	Multiplicity
`<data_writer>`	Description Specifies a DataWriter configuration. Attributes `name`: DataWriter name. `topic_ref`: Name of a `<topic>` associated with the `<domain_participant>`. <publisher name="MyPublisher"> <data_writer name="MySquareWriter" topic_ref="Square"> <!-- ... --> </data_writer> <!-- ... --> </publisher>	0 or more
`<publisher_qos>`	Description Publisher QoS configuration. Attributes `base_name` (optional): Reference (fully qualified name) to a QoS Profile. <publisher name="MyPublisher"> <!-- ... --> <publisher_qos base_name="MyQosLibrary::MyQosProfile"> <!-- You may override the referenced QosProfile by defining QoS settings here. --> </publisher_qos> </publisher>	0 or 1

3.5.1.5. Subscriber Tag¶

The <subscriber> tag specifies a Subscriber configuration. That is, it defines a set of DataReaders using the <data_reader> tag, as well as the Subscriber’s QoS settings using the <subscriber_qos> tag.

Web Integration Service does not support the use of implicit Subscribers. Therefore, clients need to define DataReaders under an existing <subscriber> tag in the configuration file.

Table 3.6 Subscriber Tag¶
Tags within `<subscriber>`	Description and Attributes	Multiplicity
`<data_reader>`	Description Specifies a DataReader configuration. Attributes `name`: DataReader name. `topic_ref`: Name of a `<topic>` associated with the `<domain_participant>`. <subscriber name="MySubscriber"> <data_reader name="MySquareReader" topic_ref="Square"> <!-- ... --> </data_reader> <!-- ... --> </subscriber>	0 or more
`<subscriber_qos>`	Description Subscriber QoS configuration. Attributes `base_name` (optional): Reference (fully qualified name) to a QoS Profile. <subscriber name="MySubscriber"> <!-- ... --> <subscriber_qos base_name="MyQosLibrary::MyQosProfile"> <!-- You may override the referenced QosProfile by defining QoS settings here. --> </subscriber_qos> </subscriber>	0 or 1

3.5.1.6. DataWriter Tag¶

The <data_writer> tag specifies the topic it is associated with (see Table 3.5), as well as its QoS configuration (see Table 3.7).

Table 3.7 *DataWriter* Tag¶
Tags within `<data_writer>`	Description and Attributes	Multiplicity
`<datawriter_qos>`	Description DataWriter QoS configuration. Attributes `base_name` (optional): Reference (fully qualified name) to a QoS Profile. <data_writer name="MySquareWriter"> <!-- ... --> <datawriter_qos base_name="MyQosLibrary::MyQosProfile"> <!-- You may override the referenced QosProfile by defining QoS settings here. --> </datawriter_qos> </data_writer>	0 or 1

3.5.1.7. DataReader Tag¶

The <data_reader> tag specifies the topic it is associated with (see Table 3.6), as well as its QoS configuration (see Table 3.8). DataReaders can also specify filter expressions that enable content filtering.

Table 3.8 *DataReader* Tag¶
Tags within `<data_reader>`	Description and Attributes	Multiplicity
`<filter>`	Description Enables the creation of the DataReader with this configuration from a ContentFilteredTopic. Attributes `name`: Name of the ContentFilteredTopic that will be associated with the same Topic referenced by the containing `<data_reader>`. `filter_kind`: Specifies which ContentFilter to use. It defaults to using the built-in SQL filter. For example: <data_reader name="MySquareReader"> <filter name="AFilter" kind="builtin.sql"> <!-- ... --> </filter> <!-- ... --> </data_reader>	0 or 1
`<datareader_qos>`	Description DataReader QoS configuration. Attributes `base_name` (optional): Reference (fully qualified name) to a QoS Profile. <data_reader name="MySquareWriter"> <!-- ... --> <datareader_qos base_name="MyQosLibrary::MyQosProfile"> <!-- You may override the referenced QosProfile by defining QoS settings here. --> </datareader_qos> </data_reader>	0 or 1

3.5.1.8. Filter Tag¶

The <filter> tag within a <data_reader> enables content filtering. It causes the corresponding DataReader to be created from a ContentFilteredTopic with the specified filter characteristics.

Tags within <filter> Description and Attributes Multiplicity

<expression>

Description: Filter expression.

<data_reader name="MySquareReader">
    <filter name="AFilter" kind="builtin.sql">
        <expression>x &lt; 10</expression>
    </filter>
</data_reader>

0 or 1

<parameter_list>

Description: List of parameters. Parameters are specified using <param> tags. The maximum number of parameters is 100.

<data_reader name="MySquareReader">
    <filter name="AFilter" kind="builtin.sql">
        <expression>x &lt; %0</expression>
    </filter>
    <parameter_list>
        <param>10</param>
        <!-- params -->
    </parameter_list>
</data_reader>

0 or 1

For example:

<?xml version="1.0" encoding="UTF-8"?>
<dds>
    <!-- ... -->
    <web_integration_service name="ExampleConfiguration">
        <application name="MyApplication">
            <domain_participant name="MyParticipant">
                <register_type name="MyShapeType" typeRef="ShapeType"/>
                <topic name="Square"  register_type_ref="MyShapeType"/>
                <publisher name="MyPublisher">
                    <data_writer name="MySquareWriter" topic_ref="Square"/>
                </publisher>
                <subscriber name="MySubscriber">
                    <data_reader name="MySquareReader" topic_ref="Square">
                        <filter name="MyFilter" kind="builtin.sql">
                            <expression>x &lt; %0</expression>
                            <parameter_list>
                                <param>10</param>
                            </parameter_list>
                        </filter>
                    </data_reader>
                </subscriber>
            </domain_participant>
        </application>
    </web_integration_service>
    <!-- ... -->
</dds>

The above configuration defines a <domain_participant> that defines a Topic Square for a MyShapeType type. The DomainParticipant contains:

A Publisher that has a DataWriter created from the Topic Square.
A Subscriber that has a DataReader created from a ContentFilteredTopic whose related Topic, Square, uses a SQL filter.

3.5.2. Types, QoS Library, and Domain Library¶

The rest of tags are part of the XML-based Application Creation API for Connext DDS.

The <types> tag is defined in Section 3.4 of the RTI Connext DDS Core Libraries User’s Manual.
The <qos_library> tag is defined in Section 17.2 of the RTI Connext DDS Core Libraries User’s Manual.
The <domain_library> tag is defined in Section 4.5.1 of the RTI Connext DDS XML-Based Application Creation Getting Started Guide.

3.6. Authentication and Access Control Mechanisms¶

Web Integration Service supports a simple access control mechanism that can be enabled to restrict access to its REST API. It is based on a set of API keys that authorize client applications to perform operations over the HTTPS protocol. When access control is enabled, client applications without an authorized API key are rejected and are not allowed to perform any operation on the running instance.

To enable Access Control, we recommend that you enable HTTPS to secure the transmission of API keys and data. While HTTPS can be enabled for all kinds of applications—even when access control is not a requirement—API keys should never be exchanged over simple HTTP as malicious applications could extract the API key, which should be considered a secret.

Section 3.6.1 explains how to enable HTTPS in Web Integration Service, Section 3.6.2 describes the Access Control List file, Section 3.6.3 illustrates how to manage the Access Control List file, and Section 3.6.4 explains how to configure client applications to use the generated API keys.

3.6.1. Enabling HTTPS¶

To secure the transmission of API keys and the data exchanged between client applications and Web Integration Service, information must be exchanged via HTTPS.

To enable HTTPS, all the ports specified in the -listeningPorts command-line option must add a trailing “s” to the port number and provide an SSL certificate (which must include the private key). For example:

$NDDSHOME/bin/rtiwebintegrationservice -listeningPorts 8080s \
    -sslCertificate ~/.certificates/server.pem

The trailing “s” (that is, using 8080s instead of 8080) indicates that HTTPS must be used on every port it follows. In contrast, ports specified without a trailing “s” will use HTTP.

Unlike other popular web servers, Web Integration Service’s web server requires users to combine both the actual certificate and the RSA private key section in the same file.

Note

For example, Apache uses the SSLCertificateFile and SSLCertificateKeyFile parameters to configure certificates and keys. Nginx uses also two different parameters: ssl_certificate and ssl_certificate_key.

Assuming the original certificate is stored in a file called server.crt and the private key is in a file called server.key, these certificates need to be combined in a common PEM file (which in this example we call server.pem) as follows:

$ cat server.crt > server.pem
$ cat server.key >> server.pem

In some cases, certificate authorities provide two different certificates, one for the domain and one for a certificate from the appropriate certificate authority (e.g., DigiCert). In that case, all certificates and keys can be combined as follows:

$ cat star_dot_example_dot_com.crt > server.pem
$ cat DigiCertCA.crt >> server.pem
$ cat star_dot_example_dot_com.key  >> server.pem

3.6.2. The Access Control List file¶

To enable access control, users need to provide an Access Control List (ACL) file when starting the service. The -aclFile command-line option specifies the path to the ACL file and configures the service to reject HTTP requests from clients that do not provide a valid API key (i.e., an API key included in the Access Control List file the service was started with).

If the file specified in -aclFile does not exist, Web Integration Service will create an empty file that can be populated later on with the -createAPIKey and -deleteAPIKey command-line options.

The Access Control List is a Sqlite3 database with a single table that contains all the API keys, a message describing each API key, and the date when they were added to the file.

3.6.3. Creating, Deleting, and Listing API keys¶

The rtiwebintegrationservice executable can be used to dynamically create, delete, and list API keys. If the file that is being updated is in use by any Web Integration Service instance, the service will be automatically notified of the changes in it. Then it will reload the list of valid API keys accordingly.

3.6.3.1. Creating API Keys¶

To add a new API key to an ACL file, use the -createAPIKey and -aclFile command-line options as follows:

$NDDSHOME/bin/rtiwebintegrationservice \
    -createAPIKey "API Key for ShapesDemo client" \
    -aclFile ~/.acl/acl_file.db

If the ACL file does not exist, it will automatically be created. Note that a message identifying the API key must be passed to the -createAPIKey argument.

3.6.3.2. Deleting API Keys¶

To delete an API key from an ACL file, use the -deleteAPIKey and -aclFile command-line options as follows:

$NDDSHOME/bin/rtiwebintegrationservice \
    -deleteAPIKey "r5x/ERs9wGkIufffeRfWSFH1li/60BUoJmJ0ETua" \
    -aclFile ~/.acl/acl_file.db

3.6.3.3. Listing API Keys¶

To list the API keys in an ACL file, use the -listAPIKeys and -aclFile command-line options as follows:

$NDDSHOME/bin/rtiwebintegrationservice \
    -aclFile ~/.acl/acl_file.db \
    -listAPIKeys

3.6.4. Using API Keys in Client Applications¶

Client applications communicating with access-control-limited instances of Web Integration Service must include a valid API key in the OMG-DDS-API-Key header field of every HTTP request. The API key must remain secret. Therefore, clients should only share it through a secure connection and should not expose it to users of the client application.

Section 5.1 provides a complete overview of the HTTP headers involved in operations supported by Web Integration Service’s REST API.