3. License Management

There’s a distinction between a license (or “activation”) file or string, and a license. When you buy an RTI product, such as Connext Professional, you are licensed to use it.

Within a package, some components may have to be activated using a license file or string, while others may not. For example, when you install the Connext Professional package, the Core Libraries (which you are licensed to use) do not require a license file or string. However, tools like RTI Admin Console (which you are also licensed to use) require a license file.

Some components that do not require a license file in certain packages may require a license file in other packages. For example, the Core Libraries require a license file in the evaluation (“eval”) and LM (“lm”) packages. If you’re using the NuGet packages from nuget.org to build your C# applications or the package from pypi.org for your Python applications, the applications need to load a license file every time they run. If a component in your Connext distribution requires a license file, you will receive one from RTI.

This section describes how to manage a license file. If you have more than one license file from RTI, you can concatenate them into one file. A single license file can be used to run on any architecture and is not node-locked. You are not required to run a license server.

In the rest of this section, the term license file is used interchangeably with activation file. We also use the term file generically to refer to both an actual file and the string with the contents of the file.

3.1. Installing License File Using Launcher

The easiest way to configure your license file is using Launcher, as shown below:

Configure License

For more information, see Setting the License File in the Launcher User’s Manual.

If you do not want to use Launcher—or if you are installing Connext for C# or Python, statically linked C or C++ applications, or other scenario where <NDDSHOME> (see Paths Mentioned in Documentation) is unset—see Installing License File for C# or Python or Installing License File Using Other Methods.

3.2. Installing License File for C# or Python

If you’re using the NuGet packages from your host installation for C# or the rti.connext.activated package for Python, you don’t need a license file to run your applications.

If you’re using the NuGet packages from nuget.org for C# or the Python package from pypi.org, rti.connext, your applications need to load a license file every time they run. To obtain an evaluation license, click the Free Trial button at https://www.rti.com/.

There are several ways to specify your license file for C# or Python:

  • Copy the rti_license.dat file to the location where you run your application.

  • Set the RTI_LICENSE_FILE environment variable to the full path of your license file, including the file name.

  • Set the DomainParticipantQos to point to your license file.

See information on these methods in the next section, Installing License File Using Other Methods.

3.3. Installing License File Using Other Methods

Besides using Launcher, you can install a license file using the mechanisms below. These mechanisms apply to all the Connext components that require a license file, including the Connext Core Libraries in the LM and evaluation bundles.

For the Connext Core Libraries in the LM or evaluation bundles, for the C# NuGet packages from nuget.org, and for the Python package from pypi.org, your application’s call to create a DomainParticipant will fail, preventing communication, if it cannot find a valid license.

In all components (such as Admin Console), except for the Connext Core Libraries in regular bundles, each time the component starts, it will look for the license file in the following locations until it finds a valid license:

  1. In the location specified in the environment variable RTI_LICENSE_FILE, you may point to the full path of the license file, including the filename.

    Note

    When you run any of the scripts in the <NDDSHOME>/bin directory, this automatically sets the RTI_LICENSE_FILE environment variable (if it isn’t already set) prior to calling the executable. It looks for the license file in two places: your rti_workspace directory and the installation directory (NDDSHOME). (See Paths Mentioned in Documentation.)

  2. If you are running any of the tools/services as executables via NDDSHOME/bin/<executable script> or through Launcher (see Setting the License File in the Launcher User’s Manual):

    • In your rti_workspace/<version> directory, in a file called rti_license.dat.

    • In your rti_workspace directory, in a file called rti_license.dat.

    • In <NDDSHOME> (the Connext installation directory), in a file called rti_license.dat.

  3. If you are running your own Connext-based application:

    • In your current working directory, in a file called rti_license.dat.

    • In <NDDSHOME> (the Connext installation directory), in a file called rti_license.dat.

  4. You can also provide a license string by creating a shared library called rti_activation, which implements the activation API. See Using an Activation Library.

If you use the following, more advanced methods to store the license file, Connext will look for the license in these locations first, before the above locations. These mechanisms only activate the Connext Core Libraries in the LM or evaluation bundles:

  1. In the PropertyQosPolicy of the DomainParticipant, there may be a property called dds.license.license_string. (Only if you have an “eval” or “lm” version of Connext.) The value for this property can be set to the content of a license file. (This may be necessary if a file system is not supported on your platform.) You can set the property either in source code or in an XML file. An XML file example is shown below:

    <domain_participant_qos>
<property>
   <value>
         <element>
            <name>dds.license.license_string</name>
            <value>contents of license file</value>
         </element>
   </value>
</property>
</domain_participant_qos>

    If the content of the license file is in XML, special characters for XML need to be escaped in the license string. Special characters include: quotation marks (”) (replace with &quot;), apostrophes (’) (replace with &apos;), greater-than (>) (replace with &gt;), less-than (<) (replace with &lt;), and ampersands (&) (replace with &amp;).

  2. In the PropertyQosPolicy of the DomainParticipant, there may be a property called dds.license.license_file. (Only if you have an “eval” or “lm” version of Connext.) The value for this property can be set to the location (full path and filename) of a license file. (This may be necessary if a default license location is not feasible and environment variables are not supported.) You can set the property either in source code or in an XML file.

    Example XML to set dds.license.license_file:

    <domain_participant_qos>
   <property>
      <value>
            <element>
               <name>dds.license.license_file</name>
               <value>path to license file</value>
            </element>
      </value>
   </property>
</domain_participant_qos>

As Connext attempts to locate and read your license file, you may (depending on the terms of the license) see a printed message with details about your license.

If you have any problems with your license file, please email support@rti.com.

3.4. Adding or Removing License Management

If you are using a package type that requires a license file and your license file changes—for example, you receive a new license for a longer term than your original license—you do not need to reinstall Connext.

However, if you switch from an evaluation (“eval”) or LM (“lm”) distribution of Connext to a regular distribution, or vice versa, RTI recommends that you first uninstall your original distribution before installing your new distribution. Doing so will prevent you from inadvertently using a mixture of libraries from multiple installations.

3.5. Using an Activation Library

Providing a license string by copying a license file into the filesystem where the Connext applications run may not be feasible. For example, you may have your own license server from which you want to obtain all the licenses required by your applications, including the Connext licenses.

To help support these use cases, Connext allows you to provide a license string by implementing the C activation API in a shared library called rti_activation (e.g., librti_activation.so, rti_activation.dll). This activation mechanism is available on all platforms but VxWorks.

The C activation API is provided in the header file ndds/dl_driver/dl_driver_activation_user.h.

You must implement the following three APIs:

/**
* @brief Get the activation string.
*
* @pre buffer can be NULL if *size is 0.
* @pre size cannot be NULL.
* @pre exception cannot be NULL.
*
* @param buffer Out. Buffer where the activation string will be copied.
* @param size In/Out. In: Size of the buffer. Out: Size of the activation
* string. The size includes the null terminator.
* @param user_data In. User data returned by RTI_ActivationLibrary_initialize().
* @param exception Out. Exception object. If there is no error, code will be
* set to RTI_ACTIVATION_LIBRARY_EXCEPTION_OK. If there is an error, code
* will be set to any of the predefined errors
* (RTI_ACTIVATION_LIBRARY_EXCEPTION_ERROR or
* RTI_ACTIVATION_LIBRARY_EXCEPTION_INSUFFICIENT_SPACE) or a user-defined
* error code. The exception message will contain a description of the error.
*
* If the input buffer is not big enough to hold the activation string, the
* function will return RTI_ACTIVATION_LIBRARY_EXCEPTION_INSUFFICIENT_SPACE
* and *size will be set to the required size of the activation string.
*
* This function can be called in parallel by multiple threads.
*
* @return 0 if there is an error, 1 otherwise.
*/
DLDRIVERDllExport
int RTI_ActivationLibrary_get_activation_string(
      char *buffer,
      unsigned int *size,
      void *user_data,
      struct RTI_ActivationLibraryException *exception);

/**
* @brief Initialize the activation library.
*
* This function will be called once after loading the activation shared
* library.
*
* @param user_data Out. User data. The library can initialize *user_data to
* NULL or to a pointer to a library-defined object.
* @param error_contact_info Out. Who-to-contact message. The library can use
* this message to change the displayed who-to-contact message in case of an
* exception.
* @param exception Out. Exception object. If there is no error, code will be
* set to RTI_ACTIVATION_LIBRARY_EXCEPTION_OK. If there is an error, code
* will be set to any of the predefined errors or a user-defined error code.
*
* @return 0 if there is an error, 1 otherwise.
*/
DLDRIVERDllExport
int RTI_ActivationLibrary_initialize(
      void **user_data,
      char error_contact_info[RTI_ACTIVATION_LIBRARY_CONTACT_INFO_MESSAGE_MAX_SIZE],
      struct RTI_ActivationLibraryException *exception);

/**
* @brief Finalize the activation library.
*
* This function will be called once after unloading the activation shared
* library.
*
* @param user_data In. User data.
* @param exception Out. Exception object. If there is no error, code will be
* set to RTI_ACTIVATION_LIBRARY_EXCEPTION_OK. If there is an error, code
* will be set to any of the predefined errors or a user-defined error code.
*
* @return 0 if there is an error, 1 otherwise.
*/
DLDRIVERDllExport
int RTI_ActivationLibrary_finalize(
      void *user_data,
      struct RTI_ActivationLibraryException *exception);

The loading of the rti_activation library will be done transparently by Connext if available in the environment, but only as the last mechanism for activation. If any other mechanism is provided (such as a valid license file), this library will not have any effect.

Once loaded, the RTI_ActivationLibrary_initialize API will only be called once per process. This provides an opportunity to initialize some state required to obtain the activation string. This state is returned in the userData output parameter.

The RTI_ActivationLibrary_get_activation_string API may be called one or more times per process whenever a valid activation string is needed. For example, for the Connext Core Libraries distributed with the LM or evaluation bundles, the API is called every time a DomainParticipant is created.

Optionally, before your application finishes, you might want to unload the Activation Library as part of your cleanup process. For this purpose, Connext provides the NDDS_LM_unload_activation_library() API, which will internally both call RTI_ActivationLibrary_finalize and unload the rti_activation shared library. This function is available for the C, Traditional C++, and Modern C++ APIs:

C:

DDS_Boolean NDDS_LM_unload_activation_library();

Traditional C++:

class NDDSLM {
   static DDS_Boolean unload_activation_library();
};

Modern C++:

namespace rti { namespace util { namespace activation {
   bool unload_activation_library();
};