Install Connext for Debian ########################## .. _section-basic-installation: Basic Installation ****************** After :ref:`configuring access to RTI's public APT repository `, use the ``rti-connext-dds-`` metapackage to install a full version of |ConnextShort|: .. code-block:: shell sudo apt-get install rti-connext-dds- The installation, under ``/opt/rti.com/rti_connext_dds-``, includes: - The **SDK** to build your distributed applications. - **Tools** that help you design, visualize, and debug your system. - **Infrastructure services** that perform dedicated functions in your system, such as recording, bridging, and persisting data. .. important:: To successfully install an RTI Debian package, an interactive terminal and user input are required. When prompted to review the RTI License Agreement, you must accept its terms. The installation process will fail if the user input cannot be gathered, or if the terms are refused. See :ref:`Non-interactive Installation` for information on how to install |ConnextShort| in unattended environments. .. _section-loading-connext: Loading Connext *************** The Debian packages include a license-managed version of |ConnextShort| that requires a valid RTI license file to be made available on the system. How to Get a License ==================== After receiving a license file (``rti_license.dat``), save it to a location on your system. Existing Customers ------------------ If you are an RTI customer, and you need an *RTI Connext* license file, contact `RTI support `_. Evaluators ---------- If you are not an RTI customer, visit https://www.rti.com/free-trial/connext to get an *RTI Connext* free trial for release 7.5.0 or higher. With the free trial you will receive a limited-time license file that contains an activation key for *RTI Connext Professional*, *RTI Security Plugins*, *RTI Real-Time WAN Transport*, and *RTI Cloud Discovery Service*. To get a free trial license for earlier releases, contact evaluations@rti.com. Configure Connext Environment ============================= The ``rtienv`` utility is used to manage the environment for |ConnextShort|. When |ConnextShort| is installed with Debian packages, you can easily configure your evironment using ``rtienv``. Use the following command to specify your license file and activate it for the current user: .. code-block:: shell # Load the default RTI Connext installation using a custom license file path eval $(rtienv -l ) Upon running the above command: - All |ConnextShort| components are automatically added to the shell's ``PATH``. - The |ConnextShort| C/C++ libraries are loaded through ``LD_LIBRARY_PATH``. - The license file is exported through ``RTI_LICENSE_FILE``. To install a license file globally for all users on the system, copy ``rti_license.dat`` into the |ConnextShort| installation directory (``/opt/rti.com/rti_connext_dds-``): .. code-block:: shell # Install license file as root sudo cp /path/to/rti_license.dat /opt/rti.com/rti_connext_dds-/rti_license.dat # Users can now load Connext without specifying a license file eval $(rtienv) The global license file is preserved between upgrades, and it is automatically deleted once you purge the package ``rti-connext-dds--common`` from your system. Customized Installation *********************** You can customize your |ConnextShort| installation by only installing packages for the components required by your system. Use the following command to see a full list of all available |ConnextShort| packages: .. code-block:: shell apt-cache search rti-connext-dds- The following table summarizes some of the most common use cases and the packages required for each: .. list-table:: :widths: 55 45 :header-rows: 1 * - Package - Use Case * - ``rti-connext-dds--lib`` - Run a C/C++/Java application using the |ConnextShort| Core APIs * - ``rti-connext-dds--lib-dbg`` - Debug a C/C++/Java application using the |ConnextShort| Core APIs * - ``rti-connext-dds--lib-dev`` - Build a C/C++/Java application using the |ConnextShort| Core APIs * - ``rti-connext-dds--rtiddsgen`` - Generate code using *RTI Code Generator* (``rtiddsgen``) * - ``rti-connext-dds--services-all`` - Install all |ConnextShort| infrastructure services * - ``rti-connext-dds--services-`` - Run one of the |ConnextShort| infrastructure services * - ``rti-connext-dds--services--dev`` - Build a C/C++/Java application using the SDK of one of the |ConnextShort| infrastructure services * - ``rti-connext-dds--services--dbg`` - Run one of the |ConnextShort| infrastructure services in debug mode * - ``rti-connext-dds--tools-all`` - Run all |ConnextShort| tools * - ``rti-connext-dds--tools-cli`` - Run one of the |ConnextShort| command-line tools * - ``rti-connext-dds--tools-`` - Run one of the |ConnextShort| GUI tools .. warning:: The following |ConnextShort| tools and services are only available on ``amd64`` systems: - *Cloud Discovery Service* - All |ConnextShort| GUI Tools Non-Interactive Installation **************************** All of the |ConnextShort| Debian packages depend on the package ``rti-connext-dds--common``. During installation, this package requires you to explictly agree to the RTI License Agreement. The installation will fail if this input cannot be requested (for example, if the package is being installed from a non-interactive terminal). The preferred way to enable unattended installation is by pre-configuring your system's ``debconf`` database to accept the RTI License Agreement before installing the package: .. code-block:: shell # Preseed debconf database echo "rti-connext-dds--common rti-connext-dds-/license/accepted select true" | sudo debconf-set-selections # Install rti-connext-dds--common sudo apt-get install rti-connext-dds--common Your selection is stored in the system database until the installed Debian package is purged (for example, by using the ``apt purge`` or ``apt remove --purge`` commands). Alternatively, you can enable an unattended installation by setting the ``RTI_LICENSE_AGREEMENT_ACCEPTED`` variable for user ``root`` to value ``accepted``. This method is less convenient because environment variables are not automatically propagated by the ``sudo`` command; therefore, the following command should only be used from a ``root`` shell: .. code-block:: shell # Switch shell to root sudo su - # Set environment variable to accept the RTI License Agreement export RTI_LICENSE_AGREEMENT_ACCEPTED=accepted # Install rti-connext-dds--common apt-get install rti-connext-dds--common Handling Multiple Versions ************************** The |ConnextShort| Debian packages allow you to install multiple versions of |ConnextShort| on the same system. Use the ``rtienv`` utility, included with all installed versions of |ConnextShort|, to easily switch between different versions. ``rtienv`` acts as a version alias; by default, it points to the most recent version of |ConnextShort| installed on the system. To load the latest |ConnextShort| version, run the following command: .. code-block:: shell # Load the most recent RTI Connext on the system eval $(rtienv) To load a specific |ConnextShort| version, use the ``rtienv`` alias for that version. For example, to make sure you are using |ConnextShort|, you would use ``rtienv-``: .. code-block:: shell # Load RTI Connext explicitly eval $(rtienv-) To modify the version used to provision the ``rtienv`` alias, use Debian's ``update-alternatives`` command: - List available |ConnextShort| versions: .. code-block:: shell update-alternatives --list rtienv - Print information about the currently selected version: .. code-block:: shell update-alternatives --display rtienv - Manually select a different version from those available: .. code-block:: shell sudo update-alternatives --config rtienv To get a list of all versions of |ConnextShort| installed on your system (ordered from oldest to newest), use the following command: .. code-block:: shell update-alternatives --list rtienv | xargs -n 1 basename | cut -d- -f2 | sort .. Usage Metrics Collection ************************ |ConnextShort| collects anonymous usage metrics in a local database inside each user's home directory. The collected data can be optionally shared with RTI to help analyze and improve the user experience. When you install the package rti-connext-dds--common, you will be asked whether you'd like for collected data to be shared. You can change your answer at any time by reconfiguring the package using the following command: .. code-block:: shell sudo dpkg-reconfigure rti-connext-dds--common Preventing Version Updates ************************** Some RTI software products, including *Connext*, do not guarantee binary compatibility between consecutive releases. To prevent your application from breaking unexpectedly, you need to configure your system to skip automatic updates of some installed packages. Use ``apt-mark hold`` to instruct ``apt`` to hold back one or more packages, even when new versions are available. For example, to hold the version of *Connext* installed by the ``rti-connext-dds`` package, you might use this command: .. code-block:: sh sudo apt-mark hold rti-connext-dds \ rti-connext-dds-host \ rti-connext-dds-target Use ``apt-mark showhold`` to display the list of packages currently being held back. To revert the hold applied by the ``apt-mark hold`` command, use ``apt-mark unhold``. For example: .. code-block:: sh sudo apt-mark unhold rti-connext-dds \ rti-connext-dds-host \ rti-connext-dds-target Support for RTI Packages ************************ .. warning:: Mixing Debian packages and RTI packages in the same |ConnextShort| installation is not recommended. APT cannot manage files installed by an RTI package, nor differentiate between files installed by an RTI or a Debian package. After installing *Connext Professional* using a Debian package, you may want to install additional |ConnextShort| components using an RTI installation package (``*.rtipkg``). While it is not recommended, RTI packages can be installed using *RTI Launcher* or the ``rtipkginstall`` CLI command. *RTI Packages* must be installed as user ``root`` because of the permissions on the |ConnextShort| installation directory. - To install an RTI package from the command line: .. code-block:: shell # Install the rtipkg file sudo /opt/rti.com/rti_connext_dds-/bin/rtipkginstall .rtipkg - To install an RTI package using *RTI Launcher*: - Start *RTI Launcher* as user root: .. code-block:: shell # Start RTI Launcher: sudo /opt/rti.com/rti_connext_dds-/bin/rtilauncher .rtipkg - From the **Configuration** tab, click **Install RTI Packages**. Add the location of your target file, then click **Install**. Installed RTI packages are recorded in the file ``/opt/rti.com/rti_connext_dds-/rti_versions.xml``. This file is marked as a *conffile* (see `Debian Policy Manual `_), which means that APT will not overwrite nor delete it if you modify it (unless |ConnextShort| is purged from the system). When mixing Debian packages and RTI packages in the same installation directory, it is important to keep in mind that APT does not know about files installed by an RTI package. For that reason: - Any file installed by a Debian package that is overwritten by an RTI package will be deleted when the Debian package is removed. - Any additional files installed by an RTI package into a Debian |ConnextShort| installation will be left on disk, even when |ConnextShort| is purged. Any such files must be deleted manually, as in the following example: .. code-block:: shell # Make sure Connext is purged from the system sudo apt purge rti-connext-dds--common # Delete left-over files sudo rm -rf /opt/rti.com/rti_connext_dds-/