1. CLI¶

The Fast DDS command line interface provides a set commands and sub-commands to perform, Fast DDS related, maintenance and configuration tasks.

An executable file for Linux and Windows that runs the Fast DDS CLI application is available in the tools folder. If the tools/fastdds folder path is added to the PATH, or by sourcing the <path/to/fastdds>/install/setup.bash configuration file, Fast DDS CLI can be executed running the following commands:

Linux:
```
$ fastdds <command> [<command-args>]
```

Windows:

> fastdds.bat <command> [<command-args>]

There are three verbs whose functionality is described in the following table:

Verbs	Description
`discovery`	Launches a server for Discovery Server.
`shm`	Allows manual cleaning of garbage files that may be generated by Shared Memory Transport
`xml`	Checks if a xml profile is well formed.

1.1. discovery¶

This command provides a simple and direct way to launch a Fast DDS Discovery Server. It encompasses two main functionalities:

Discovery Server CLI Easy Mode: It launches a background daemon which will automatically handle the creation of servers. The port of each server is calculated based on the Domain ID (-d argument or ROS_DOMAIN_ID), which is the only parameter that the user must specify. If no Domain ID is provided, the default value is 0.

It is intended to be used along with the ROS2_EASY_MODE environment variable, which will manage clients connections automatically. This CLI feature allows the user to dynamically manage servers from the network: launching, stopping, restarting and even modifying their remote servers connections. For further information about this mode refer to Discovery Server Easy Mode.
Discovery Server CLI Standard Mode: It launches a server running in foreground with the specified parameters. Configurable parameters include IP address, port, transport protocol, XML profile, etc. In this mode, clients must know how to reach the server, which is accomplished by specifying an IP address, a port and a transport protocol like UDP or TCP. Servers do not need any prior knowledge of their clients, but require the listening IP address and port where they may be reached.

1.1.1. Discovery Server CLI Easy Mode¶

This mode aims to simplify the deployment and configuration of Fast DDS Discovery Servers by automatically handling the server’s connections. This mode of the CLI is meant to be used along with the ROS2_EASY_MODE environment variable, which can be used to remove multicast announcements from DDS entities and interconnect different hosts by just using the environment variable ROS2_EASY_MODE=<ip>. (Check Discovery Server Easy Mode to see a detailed explanation of this feature).

In this way, the CLI provides an auxiliary tool to obtain more advanced configuration for specific cases of use. It can be used to manage running servers, modifying their remote connections, restarting them or stopping them. Fast DDS Discovery servers are handled and monitored from a background daemon which is automatically spawned when required.

Configuration of servers launched with ROS2_EASY_MODE is available by using the following command:

fastdds discovery <command> [optional -d <domain>] [optional "<remote_server_list>"]

The following table lists the available commands for the Fast DDS Discovery Server CLI:

Command	Description
start	Start the Discovery Server daemon with the remote connections specified. (Example: start -d 1 10.0.0.1:1).
stop	Stop the Discovery Server daemon if it is executed with no arguments. If a domain is specified with the `-d` argument it will only stop the corresponding server and the daemon will remain alive.
add	Add new remote Discovery Servers to the local server. This will connect both servers and their sub-networks without modifying existing remote servers.
set	Rewrite the remote Discovery Servers connected to the local server. This will replace existing remote servers with the new connections.
list	List local active Discovery Servers created with the CLI Tool or the `ROS2_EASY_MODE=<ip>`.

Option parameters	Description
`-d --domain`	Selects the domain of the server to target for this action. It is mandatory for commands `start`, `add` and `set`.
`<remote_server>`	It is an IP-domain pair defining a remote server to connect to: `<IP:domain>`. It is mandatory with the start, add and set commands. Only valid IPv4 addresses are accepted.

Note

The command add also accepts a remote server list using the structure "<IP:domain>;<IP:domain>;...".

1.1.1.1. Examples¶

Start a DS in the default domain 0 pointing to itself (no remote server):
```
fastdds discovery start -d 0 127.0.0.1:0
```
Stop all running DS and shut down Fast DDS daemon:
```
fastdds discovery stop
```
Stop DS running in domain 0:
```
fastdds discovery stop -d 0
```
Start a DS in domain 4 pointing to remote DS in domain 4 and IP 10.0.0.7:
```
fastdds discovery start -d 4 10.0.0.7:4
```
Add a new remote server to DS running in domain 4 :
```
fastdds discovery add -d 4 10.0.0.7:4
```
List all servers running locally:
```
fastdds discovery list
```
Starts a DS in domain 3 pointing to local DS in domain 6:
```
fastdds discovery start -d 3 127.0.0.1:6
```

1.1.2. Discovery Server CLI Standard Mode¶

This mode allows the user to deeply customize Discovery Servers initialization avoiding programming. However, it requires manual configuration for clients to reach the server, as they must know the server’s IP address, port and protocol. For more information on the different Fast DDS discovery mechanisms and how to configure them, please refer to Discovery.

To use this mode, execute on a shell:

fastdds discovery [optional parameters]

The following table lists the available parameters for the Fast DDS Discovery Server CLI mode:

Option	Description
`-h --help`	Produce help message with examples.
`-l --udp-address`	IPv4/IPv6 address chosen to listen the clients using UDP transport. Defaults to any (0.0.0.0/::0). Instead of an address, a DNS domain name can be specified.
`-p --udp-port`	UDP port chosen to listen the clients. Defaults to ‘11811’. Only one server can be configured using the default UDP port.
`-t --tcp-address`	IPv4/IPv6 address chosen to listen the clients using TCP transport. Instead of an address, a DNS domain name can be specified. Defaults to any (0.0.0.0).
`-q --tcp-port`	TCP port chosen to listen the clients. Defaults to ‘42100’. Only one server can be configured using the default TCP port.
`-b --backup`	Creates a BACKUP server (see Discovery Protocol)
`-x --xml-file`	XML configuration file (see XML profiles). In this case, the default configuration file is not loaded. The CLI options override XML configuration for that specific parameter. The default profile in the XML file is loaded except if a specific profile name is specified: `profile_name@xml_file`
`-i --server-id`	Unique server identifier. Its functionality its deprecated. It can be used to select a fixed GUID in the form shown below. Must be an integer in range [0, 255].

Executing the command without parameters will launch a server with default UDP values.

The output is:

#### Server started ####
  GUID prefix: <Default>|44.53.<server-id-in-hex>.5f.45.50.52.4f.53.49.4d.41
  Running on:  UDPv4:[<ip-address>]:<port>
               UDPv6:[<ip-address>]:<port>
               TCPv4:[<ip-address>]:<physical-port>-<logical-port>
               TCPv6:[<ip-address>]:<physical-port>-<logical-port>

Once the server is instantiated, the clients can be configured either programmatically or by XML (see Discovery Server Settings), or using environment variable ROS_DISCOVERY_SERVER (see ROS_DISCOVERY_SERVER)

Important

It is possible to interconnect servers (or backup servers) instantiated with Discovery Server CLI Standard Mode using environment variable ROS_DISCOVERY_SERVER (see ROS_DISCOVERY_SERVER) or a XML configuration file.

Note

The Security configuration of the discovery server should be done through XML. See example below.

1.1.2.1. Examples¶

Launch a default server listening on all available interfaces on UDP port ‘11811’. Only one server can use default values per machine.
```
fastdds discovery
```
Output:
```
#### Server started ####
  GUID prefix: <Default GUID>
  Running on:  UDPv4:[0.0.0.0]:11811
```

Launch a default server listening on localhost with UDP port 14520. Only localhost clients can reach the server defining as ROS_DISCOVERY_SERVER=127.0.0.1:14520.

fastdds discovery -l 127.0.0.1 -p 14520

Output:

#### Server started ####
  GUID prefix: <Default GUID>
  Running on:  UDPv4:[127.0.0.1]:14520

This same output can be obtained loading the following XML configuration file DiscoveryServerCLI.xml:

<participant profile_name="participant_profile_discovery_server_cli" is_default_profile="true">
    <rtps>
        <builtin>
            <discovery_config>
                <discoveryProtocol>SERVER</discoveryProtocol>
            </discovery_config>
            <metatrafficUnicastLocatorList>
                <locator>
                    <udpv4>
                        <address>localhost</address>
                        <port>14520</port>
                    </udpv4>
                </locator>
            </metatrafficUnicastLocatorList>
        </builtin>
    </rtps>
</participant>

<participant profile_name="second_participant_profile_discovery_server_cli">
    <rtps>
        <builtin>
            <discovery_config>
                <discoveryProtocol>SERVER</discoveryProtocol>
            </discovery_config>
            <metatrafficUnicastLocatorList>
                <locator>
                    <udpv4>
                        <address>192.168.36.34</address>
                        <port>8783</port>
                    </udpv4>
                </locator>
                <locator>
                    <udpv4>
                        <address>172.20.96.1</address>
                        <port>51083</port>
                    </udpv4>
                </locator>
            </metatrafficUnicastLocatorList>
        </builtin>
    </rtps>
</participant>

<participant profile_name="secure_discovery_server_cli">
    <rtps>
        <builtin>
            <discovery_config>
                <discoveryProtocol>SERVER</discoveryProtocol>
            </discovery_config>
            <metatrafficUnicastLocatorList>
                <locator>
                    <udpv4>
                        <address>0.0.0.0</address>
                        <port>11811</port>
                    </udpv4>
                </locator>
            </metatrafficUnicastLocatorList>
        </builtin>
        <propertiesPolicy>
            <properties>
                <!-- Activate Auth:PKI-DH plugin -->
                <property>
                    <name>dds.sec.auth.plugin</name>
                    <value>builtin.PKI-DH</value>
                </property>

                <!-- Configure Auth:PKI-DH plugin -->
                <property>
                    <name>dds.sec.auth.builtin.PKI-DH.identity_ca</name>
                    <value>file://maincacert.pem</value>
                </property>
                <property>
                    <name>dds.sec.auth.builtin.PKI-DH.identity_certificate</name>
                    <value>file://appcert.pem</value>
                </property>
                <property>
                    <name>dds.sec.auth.builtin.PKI-DH.private_key</name>
                    <value>file://appkey.pem</value>
                </property>

                <!-- Activate Access:Permissions plugin -->
                <property>
                    <name>dds.sec.access.plugin</name>
                    <value>builtin.Access-Permissions</value>
                </property>

                <!-- Configure Access:Permissions plugin -->
                <property>
                    <name>dds.sec.access.builtin.Access-Permissions.permissions_ca</name>
                    <value>file://maincacet.pem</value>
                </property>
                <property>
                    <name>dds.sec.access.builtin.Access-Permissions.governance</name>
                    <value>file://governance.smime</value>
                </property>
                <property>
                    <name>dds.sec.access.builtin.Access-Permissions.permissions</name>
                    <value>file://permissions.smime</value>
                </property>

                <!-- Activate Crypto:AES-GCM-GMAC plugin -->
                <property>
                    <name>dds.sec.crypto.plugin</name>
                    <value>builtin.AES-GCM-GMAC</value>
                </property>
            </properties>
        </propertiesPolicy>
    </rtps>
</participant>

fastdds discovery -x [PATH_TO_FILE]/DiscoveryServerCLI.xml

Launch a default server listening on all available interfaces on TCP port ‘42100’. Only one server can use default values per machine.
```
fastdds discovery -t
```
Output:
```
#### Server started ####
  GUID prefix: <Default GUID>
  Running on:  TCPv4:[0.0.0.0]:42100
```

Launch a default server with GUID corresponding to id 1 (see Deprecated_CLI) listening on IPv6 address 2a02:ec80:600:ed1a::3 with UDP port 14520.

fastdds discovery -i 1 -l 2a02:ec80:600:ed1a::3 -p 14520

Output:

#### Server started ####
  GUID prefix: 44.53.01.5f.45.50.52.4f.53.49.4d.41
  Running on:  UDPv6:[2a02:ec80:600:ed1a::3]:14520

Launch a default server listening on WiFi (192.168.36.34) and Ethernet (172.20.96.1) local interfaces with UDP ports 8783 and 51083 respectively (addresses and ports are made up for the example).
```
fastdds discovery -l 192.168.36.34 -p 8783 -l 172.20.96.1 -p 51083
```
Output:
```
#### Server started ####
  GUID prefix: <Default GUID>
  Running on:  UDPv4:[192.168.36.34]:8783
               UDPv4:[172.20.96.1]:51083
```
Using the same XML configuration file from the second example, the same output can be obtained loading a specific profile: second_participant_profile_discovery_server_cli.
```
fastdds discovery -x second_participant_profile_discovery_server_cli@[PATH_TO_FILE]/DiscoveryServerCLI.xml
```
Launch a default server listening on 172.30.144.1 with UDP port 12345 and provided with a backup file. If the server crashes it will automatically restore its previous state when re-enacted.
```
fastdds discovery -l 172.30.144.1 -p 12345 -b
```
Output:
```
#### Backup Server started ####
  GUID prefix: <Default GUID>
  Running on:  UDPv4:[172.30.144.1]:12345
```

Launch a secure server listening on all available interfaces on UDP port ‘11811’.

fastdds discovery -x secure_discovery_server_cli@[PATH_TO_FILE]/DiscoveryServerCLI.xml

Output:

#### Server started ####
  GUID prefix: <Default GUID>
  Running on:  UDPv4:[0.0.0.0]:11811

Launch a server reading specific profile_name configuration from XML file.

fastdds discovery -x profile_name@[PATH_TO_FILE]/config.xml

Output:

#### Server started ####
  GUID prefix: <Default GUID>
  Running on:  UDPv4:[127.0.0.1]:56542

Launch a server listening on localhost on default TCP port ‘42100’.

fastdds discovery -t 127.0.0.1

Output:

#### Server started ####
  GUID prefix: <Default GUID>
  Running on:  TCPv4:[127.0.0.1]:42100-42100

Launch a server listening on localhost and WiFi (192.163.6.34). Two TCP ports need to be specified because transports cannot share ports.

fastdds discovery -t 127.0.0.1 -q 42100 -t 192.163.6.34 -q 42101

Output:

#### Server started ####
  GUID prefix: <Default GUID>
  Running on:  TCPv4:[127.0.0.1]:42100-42100
               TCPv4:[192.163.6.34]:42101-42101

Note

When using Discovery Server over TCP, the first port shown in the output refers to the TCP Physical port and the second one to the TCP Logical port (see TCP Transport).

Note

A server can be instantiated just by passing the port arguments -p and -q. Fast DDS CLI will use the default values of the IP addresses, that is, 0.0.0.0 for both UDP and TCP.

1.2. shm¶

Provides maintenance tasks related with Shared Memory Transport. Shared Memory transport creates Segments, blocks of memory accessible from different processes. Zombie files are memory blocks that were reserved by shared memory and are no longer in use which take up valuable memory resources. This tool finds and frees those memory allocations.

It is also possible to clean Data Sharing segments when the --force option is used. However, this option should be used with caution, as it will remove all Data Sharing segments, including the ones that are being used by active applications.

fastdds shm [<shm-command>]

Sub-command	Description
`clean`	Cleans SHM zombie files.

Option	Description
`-h --help`	Produce help message.
`-f --force`	Force the deletion of data sharing segments.

Warning

Running this command with the --force option will remove all Data Sharing segments, including the ones that are being used by active applications. Use this option only when there are no running Fast DDS applications, as it might raise errors if the segments are still in use.

1.3. xml¶

Checks if a given xml profile is well formed, by matching it against a XSD schema. If the given input to the command is a path to a folder instead of a path to a file,all xml files contained in the folder will be validated.

This validation consists in checking the lack of parameters, values bounds, expected values data types and main profile structure. For further information see Creating an XML profiles file.

fastdds xml [<xml-command>]

Sub-command	Description
`validate`	Checks a xml profile by matching it against a XSD schema.

Option	Description
`-h --help`	Produce help message.
`-d --debug`	Print debug information (disabled by default)
`-x --xsd_file`	XSD schema for validation (not required, Fast DDS schema is used by default)

Example

fastdds xml validate my_profile.xml