4. Usage¶

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

How to Start Web Integration Service once it has been installed (Section 4.1).
How to Stop Web Integration Service (Section 4.2).
Web Integration Service Command-line Options (Section 4.3).

4.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 (note: you would enter this all on one line):

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

Table 4.1 describes in detail the list of command-line options.

4.2. Stopping Web Integration Service¶

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

4.3. Web Integration Service Command-Line Options¶

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

Table 4.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. It is recommended to use this parameter with a secured connection; i.e., it is important to enable HTTPS 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 3.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 3.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).
`-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 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 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 and port 443 using HTTPS. 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)
`-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 and authentication, see Section 3.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 verbosity level smaller than `n`.
`-version`	Prints the Web Integration Service version number.