4. Configuration
4.1. Configuring Web Integration Service
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 4.3 discusses how the file is loaded.
Section 4.4 explains its syntax and validation.
Section 4.5 describes how to write a configuration file.
Section 4.6 explains how to configure the Authentication and Access Control mechanisms included with Web Integration Service.
4.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.
4.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 specified in the
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. It 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.
<?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>
4.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/resource/schema/rti_web_integration_service.dtd
and
$NDDSHOME/resource/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:
<?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:
<?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.
4.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 4.1
describe the top-level tags allowed within the root <dds>
tag.
Tags within |
Description |
Multiplicity |
---|---|---|
|
Specifies a QoS library and profiles. The contents of the Connext DDS QoS profile file—see the “Configuring QoS with XML” chapter in the RTI Connext DDS Core Libraries User’s Manual. |
0..* |
|
Specifies a domain library. That is, a set of |
0..* |
|
Required. Defines types that can be used by Web Integration Service. See Section 4.5.2. |
1..* |
|
Required. Specifies a Web Integration Service configuration. See Section 4.5.1. |
1..* |
4.5.1. Web Integration Service
4.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 option.
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 4.2 describe
the tags allowed within a <web_integration_service>
tag.
Tags within |
Description and Attributes |
Multiplicity |
---|---|---|
|
<web_integration_service name="ExampleService">
<application name="MyApplication">
<!-- ... -->
</application>
<!-- More application definitions ... -->
</web_integration_service>
|
0..* |
4.5.1.2. Application Tag
An <application>
provides a way to organize a set of instantiated
participants that belong 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 option, all of 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.
Tags within |
Description and Attributes |
Multiplicity |
---|---|---|
|
<application name="MyApplication">
<domain_participant name="MyParticipant"
domain_ref="MyDomainLibrary::MyDomain"
domain_id="32">
<!-- ... -->
</domain_participant>
<!-- More DomainParticipant definitions ... -->
</application>
|
0..* |
4.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>
.
Tags within |
Description and Attributes |
Multiplicity |
---|---|---|
|
<domain_participant name="MyParticipant">
<register_type name="MyShapeType" type_ref="ShapeType" />
<!-- ... -->
</domain_participant>
|
0..* |
|
<domain_participant name="MyParticipant">
<topic name="Square" register_type_ref="MyShapeType" />
<!-- ... -->
</domain_participant>
|
0..* |
|
<domain_participant name="MyParticipant">
<publisher name="MyPublisher">
<!-- DataWriters or PublisherQos -->
</publisher>
<!-- ... -->
</domain_participant>
|
0..* |
|
<domain_participant name="MyParticipant">
<subscriber name="MySubscriber">
<!-- DataReaders or SubscriberQos -->
</subscriber>
<!-- ... -->
</domain_participant>
|
0..* |
|
<domain_participant base="MyParticipant">
<!-- ... -->
<domain_participant_qos base="MyQosLibrary::MyQosProfile">
<!-- You may override the referenced QosProfile by
defining QoS settings here. -->
</domain_participant_qos>
</domain_participant>
|
0..1 |
4.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, you must define DataWriters under an existing
<publisher>
tag in the configuration file.
Tags within |
Description and Attributes |
Multiplicity |
---|---|---|
|
<publisher name="MyPublisher">
<data_writer name="MySquareWriter" topic_ref="Square">
<!-- ... -->
</data_writer>
<!-- ... -->
</publisher>
|
0..* |
|
<publisher name="MyPublisher">
<!-- ... -->
<publisher_qos base_name="MyQosLibrary::MyQosProfile">
<!-- You may override the referenced QosProfile by
defining QoS settings here. -->
</publisher_qos>
</publisher>
|
0..1 |
4.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.
Tags within |
Description and Attributes |
Multiplicity |
---|---|---|
|
<subscriber name="MySubscriber">
<data_reader name="MySquareReader" topic_ref="Square">
<!-- ... -->
</data_reader>
<!-- ... -->
</subscriber>
|
0..* |
|
<subscriber name="MySubscriber">
<!-- ... -->
<subscriber_qos base_name="MyQosLibrary::MyQosProfile">
<!-- You may override the referenced QosProfile by
defining QoS settings here. -->
</subscriber_qos>
</subscriber>
|
0..1 |
4.5.1.6. DataWriter Tag
The <data_writer>
tag specifies the topic it is associated with
(see Table 4.5), as well as its QoS configuration (see
Table 4.7).
Tags within |
Description and Attributes |
Multiplicity |
---|---|---|
|
<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..1 |
4.5.1.7. DataReader Tag
The <data_reader>
tag specifies the topic it is associated with
(see Table 4.6), as well as its QoS configuration
(see Table 4.8). DataReaders can also specify filter
expressions that enable content filtering.
Tags within |
Description and Attributes |
Multiplicity |
---|---|---|
|
<data_reader name="MySquareReader">
<content_filter name="AFilter" kind="builtin.sql">
<!-- ... -->
</content_filter>
<!-- ... -->
</data_reader>
|
0..1 |
|
<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..1 |
4.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 |
Description and Attributes |
Multiplicity |
---|---|---|
|
<data_reader name="MySquareReader">
<content_filter name="AFilter" kind="builtin.sql">
<expression>x < 10</expression>
</content_filter>
</data_reader>
|
0..1 |
|
<data_reader name="MySquareReader">
<content_filter name="AFilter" kind="builtin.sql">
<expression>x < %0</expression>
</content_filter>
<expression_parameters>
<element>10</element>
<!-- params -->
</expression_parameters>
</data_reader>
|
0..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">
<content_filter name="MyFilter" kind="builtin.sql">
<expression>x < %0</expression>
<expression_parameters>
<element>10</element>
</expression_parameters>
</content_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.
4.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 the section “Creating User Data Types with Extensible Markup Language (XML)” in the RTI Connext DDS Core Libraries User’s Manual.The
<qos_library>
tag is defined in the “QoS Libraries” section of the RTI Connext DDS Core Libraries User’s Manual.The
<domain_library>
tag is defined in the “Domain Library” section of the RTI Connext DDS XML-Based Application Creation Getting Started Guide.
4.6. Authentication and Access Control Mechanisms
Web Integration Service supports a simple access-control mechanism which can be enabled to restrict access to its REST API and WebSocket API. It is based on a set of API keys that authorize client applications to perform operations over the HTTPS and Secure WebSocket protocols. 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/WSS to secure the transmission of API keys and data. While HTTPS/WSS 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 or WebSocket, as malicious applications could extract the API key, which should be considered a secret.
Section 4.6.1 explains how to enable HTTPS/WSS in Web Integration Service. Section 4.6.2 describes the Access Control List file. Section 4.6.3 illustrates how to manage the Access Control List file. Section 4.6.4 explains how to configure client applications to use the generated API keys.
4.6.1. Enabling HTTPS/WSS
To secure the transmission of API keys and the data exchanged between client applications and Web Integration Service, information must be exchanged via HTTPS/WSS. To enable HTTPS/WSS, you must install OpenSSL on your system. You can see how to install it in Section 2.
To enable HTTPS/WSS, 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/WSS must be used on every port it follows. In contrast, ports specified
without a trailing “s
” will use HTTP/WS.
Unlike other popular web servers, Web Integration Service’s web server requires you 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 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
4.6.2. The Access Control List File
To enable access control, you 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 and WebSocket connections 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 with -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.
4.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.
4.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.
4.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
4.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
4.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 and WebSocket Connection.
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 and Section 6.1 provides a complete overview of the HTTP headers and the WebSocket HELLO message involved in operations supported by Web Integration Service’s REST API and WebSocket API.