5. Usage¶

This chapter explains how to run Cloud Discovery Service either from the distributed command-line executable or as a library within your application.

5.1. Command-Line Executable¶

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

rticlouddiscoveryservice [options]

This section explains how to run Cloud Discovery Service from a command-line tool. In particular, it describes:

Starting Cloud Discovery Service (Section 5.1.1).
Stopping Cloud Discovery Service (Section 5.1.2).
Command-line Options (Section 5.1.3).

5.1.1. Starting Cloud Discovery Service¶

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

rticlouddiscoveryservice [options]

To start Cloud Discovery Service with a default configuration, enter:

$NDDSHOME/bin/rticlouddiscoveryservice

This command will run Cloud Discovery Service indefinitely until you stop it. See Section 5.1.2.

Note

Cloud Discovery Service is pre-loaded with a builtin configuration that has default settings. See Section 6.3.

Table 5.1 describes the command-line parameters.

5.1.2. Stopping Cloud Discovery Service¶

To stop Cloud Discovery Service, press Ctrl-c. Cloud Discovery Service will perform a clean shutdown.

5.1.3. Command-Line Options¶

The following table describes all the command-line parameters available in Cloud Discovery Service. To list the available commands, run rticlouddiscoveryservice -h.

Table 5.1 Cloud Discovery Service Command-line Options¶
Parameter	Description
`-allowDomain <string>`	Subset of domain IDs where Cloud Discovery Service operates. Use this argument in order to indicate which domain IDs Cloud Discovery Service should process announcements for. Remaining ones will be automatically ignored. Default: `DOMAIN_LIST_ALL` (forward all domains)
`-appName <string>`	Assigns a name to the execution of the Cloud Discovery Service. Remote commands and status information will refer to the instances using this name. Default: (same as configuration name).
`-cfgFile <string>`	Path to the configuration file. Default: (unspecified)
`-cfgName <string>`	Name of the Cloud Discovery Service configuration to be loaded. It must match a `<cloud_discovery_service>` tag in the configuration file. Default: rti.cds.builtin.config.default.
`-denyDomain <string>`	Subset of domain IDs ignored by Cloud Discovery Service. Use this argument in order to indicate which domain IDs Cloud Discovery Service shouldn’t process announcements from. Default: Empty string (no domain IDs are ignored) Overrides: `domain_list/allow_domain_id` or `-allowDomain`
`-heapSnapshotDir <dir>`	Output directory where the heap monitoring snapshots are dumped. The filename format is RTI_heap_<appName>_<processId>_<index>. Used only if heap monitoring is enabled. Default: current working directory
`-heapSnapshotPeriod <sec>`	Period at which heap monitoring snapshots are dumped. Enables heap monitoring if > 0. Default: 0 (disabled)
`-help`	Prints this help and exits.
`-ignoreXsdValidation`	Loads the configuration even if the XSD validation fails.
`-listConfig`	Prints the available configurations and exits.
`-logFormat <format>`	A mask to configure the format of the log messages for both the service and DDS. It allows the following values: `DEFAULT` - Print message, method name, and activity context `VERBOSE` - DEFAULT + module, thread ID and spreads the message over two lines. `TIMESTAMPED` - VERBOSE + timestamped `MINIMAL` - Print only message number and method name `MAXIMAL` - Print all available fields Default: DEFAULT
`-maxObjectsPerThread <int>`	Maximum number of thread-specific objects that can be created. Default: 2048
`-remoteAdministrationDomainId <int>`	Enables remote administration and sets the domain ID for communication. Overrides: `administration/domain_id`
`-remoteMonitoringDomainId <int>`	Enables remote monitoring and sets the domain ID for status publication. Overrides: `monitoring/domain_id`
`-stopAfter <int>`	Number of seconds the Cloud Discovery Service runs before it stops. Default: (infinite).
`-transport <string>`	A comma separated list of transport resources, where each resource is specified in the form: `[alias:]receive_port` Default: udpv4:7400 Overrides: `transport`
`-licenseFile <string>`	Specifies the license file path to be used. See How to use a License File with RTI Services. Default: Empty string
`-D<name>=<value>`	Defines a user variable that can be used as an alternative replacement for XML environment variables, specified in the form $(<name>). Note that definitions in the environment takes precedence over these definitions. This option can be specified multiple times.
`-verbosity <service_level>[:<dds_level>]`	Controls what type of messages are logged. <service_level> is the verbosity level for the service logs and <dds_level> is the verbosity level for the DDS logs. Both can take any of the following values: `SILENT` `ERROR` `WARN` `LOCAL` `REMOTE` `ALL` Default: `ERROR:ERROR`
`-version`	Prints the Cloud Discovery Service version and exits.

All the command-line options are optional; if specified, they override the values of their corresponding settings in the loaded XML configuration. See Section 6 for the set of XML elements that can be overriden with command-line options.

5.2. Cloud Discovery Service as a Library¶

Cloud Discovery Service can be deployed as a library linked into your application on selected architectures (see Section 14). This allows you to create, configure, and start Cloud Discovery Service instances from your application.

To build your application, add the dependency with the Cloud Discovery Service library under <NDDSHOME>/lib/<ARCHITECTURE>, where <ARCHITECTURE> is a valid and installed target architecture.

Here is an example of using Cloud Discovery Service as a library with the Service API:

struct RTI_CDS_Property property =
        RTI_CDS_Property_INITIALIZER;
struct RTI_CDS_Service *service = NULL;

/* Initialize property */
property.cfg_file     = "my_cds_service_cfg.xml";
property.service_name = "my_cds_service";
...

service = RTI_CDS_Service_new(&property);
if(service == NULL) {
    /* Log error */
    ...
}

if(!RTI_CDS_Service_start(service)) {
    /* Log error */
    ...
}

while(keep_running) {
    sleep();
    ...
}
...

RTI_CDS_Service_delete(service);

using namespace rti::cds;

CloudDiscoveryService service(
        ServiceProperty()
                .cfg_file("my_cds_service_cfg.xml")
                .service_name("my_cds_service"));

service.start();

5.3. Operating System Daemon¶

See generic instructions in How to Run as an Operating System Daemon.