3. Usage

This chapter explains how to run Web Integration Service once it has been installed. In particular, it describes:

3.1. Starting Web Integration Service

Web Integration Service runs as a separate application. The script to run the executable is in <NDDSHOME>/bin.

To start Web Integration Service, enter:

$NDDSHOME/bin/rtiwebintegrationservice [options] -cfgName <cfgName>

For example:

$NDDSHOME/bin/rtiwebintegrationservice -cfgFile example.xml -cfgName example

Table 3.1 describes the command-line options.

3.2. Stopping Web Integration Service

To stop Web Integration Service, press Ctrl-c. Web Integration Service will perform a clean shutdown.

3.3. Command-Line Parameters

The following table describes the command-line parameters for Web Integration Service. They are all optional, except for -cfgName.

Table 3.1 RTI Web Integration Service Command-line Options

Option

Description

-accessLogFile <file>

Path to the web server’s access log.
Default: NULL (nothing gets logged).

-aclFile <file>

Access Control List file. This parameter loads an Access Control List file, which enables access control in all the HTTP requests and WebSocket (WS) connections. It is recommended to use this parameter with a secured connection; i.e., it is important to enable HTTPS and Secure WebSocket (WSS) in every single -listeningPort and provide an -sslCertificate.
Default: Do not load an ACL file and therefore do not check for any kind of access key in HTTP requests.

-cfgFile <file>

Specifies a configuration file to be loaded. See How to Load the XML Configuration in Section 4.3.

-cfgName <name>

Required.
Specifies a configuration name. Web Integration Service will look for a matching <web_integration_service> tag in the configuration file specified via the -cfgFile parameter and in the default configuration files listed in Section 4.3.

-createAPIKey <description>

Adds a new API key to an Access Control List file along with a description of the purpose of the API key to be generated.
This command must be used in combination with the -aclFile argument to specify the file in which to add the API key. If the file does not exist, Web Integration Service will automatically create it for you.
Once the key is added to the ACL file, Web Integration Service exits.

-deleteAPIKey <key>

Deletes an API key from an Access Control List file.
This command must be used in combination with the -aclFile argument to specify the file from which the API key will be deleted.
Once the key is deleted from the ACL file, Web Integration Service exits.

-documentRoot <dir>

Directory that will be served by Web Integration Service’s web server on http[s]://<hostname>:<listeningPort>.
Default: Documentation directory.

-enableKeepAlive <yes|no>

Allows clients to reuse TCP connections for subsequent HTTP requests, which improves performance. It is important to add the correct Content-Length HTTP header for each request. Otherwise, the client will timeout.
Default: No.

-enableResourceCaching

Caches WaitSet, Sample Buffer, and DynamicData ojects in the thread-specific storage of the worker threads that handle HTTP requests. You can limit the allocated resources by reducing the number of worker threads via the -numThreads command-line argument.
Default: Disabled (i.e., resources are created on demand).

-enableWebSockets

Allows clients to read/write data through WebSocket.
Default: Disabled (i.e., WebSocket connections will be rejected).

-keepAliveTimeout <timeInMs>

Idle timeout, in milliseconds, between two requests in a keep-alive connection. If -enableKeepAlive is set to “no,” the value of -keepAliveTimeout is ignored.
Default: 500.

-heapSnapshotDir <dir>

When heap monitoring is enabled, this parameter specifies the directory where the heap snapshots are to be dumped. Note that the given directory must exist.
Default: Current working directory.

-heapSnapshotPeriod <timeInS>

Enables heap monitoring and generates a heap snapshot file every <timeInS> seconds. The snapshot filename format is: RTI_heap_<processId>_<index>.log.
Default: Heap monitoring is disabled.

-help

Displays help information.

-listAPIKeys

Lists all the API keys available in an Access Control List file.
This command must be used in combination with the -aclFile argument to specify the file from which API keys should be listed.

-listeningPorts <listOfPorts>

Comma-separated list of ports to listen on. To enable HTTPS/WSS on a specific port, append “s” to the port number. For example, if you specify "8080,443s", Web Integration Service will listen on port 8080 using HTTP/WS and port 443 using HTTPS/WSS.
If any of the ports has SSL enabled, -listeningPorts must be used in combination with -sslCertificate to indicate the path to the certificate file that will be used.
Default: 8080 (HTTP/WS)

-maxObjectsPerThread <n>

Maximum number of thread-specific objects that can be created.
Default: 2048

-numThreads <n>

Number of worker threads for the web server. The web server handles each incoming connection in a separate thread. Therefore, the value of this option is effectively the number of connections that can be handled.
Default: 50

-sslCertificate <file>

Path to the SSL certificate file. This option is only required when one of the -listeningPorts has enabled SSL. The file must be in PEM format and must contain both the private key and the certificate.
For more information on how to configure HTTPS/WSS and authentication, see Section 4.6.
Default: NULL.

-verbosity <n>

Controls what type of messages are logged:

0. Silent
1. Exceptions (Connext DDS and Web Integration Service)
2. Warnings (Web Integration Service)
3. Information (Web Integration Service)
4. Warnings (Connext DDS and Web Integration Service)
5. Tracing (Web Integration Service)
6. Tracing (Connext DDS and Web Integration Service)

Each verbosity level, n, includes all the levels less than n.
Default: 1 (Exceptions)

-version

Prints the Web Integration Service version number.