rocm-systems/docs/install/handbook.rst

.. meta::
  :description: documentation of the installation, configuration, and use of the ROCm Data Center tool 
  :keywords: ROCm Data Center tool, RDC, ROCm, API, reference, data type, support

.. _rdc-handbook:

***************************************************
Building and testing RDC
***************************************************

RDC is open source and available under the MIT License. This section is helpful for open source developers. Third-party integrators may also find this information useful.

Prerequisites for Building RDC
==============================

.. note::
  RDC is tested on the following software versions. Earlier versions may not work.

* CMake 3.15
* g++ (5.4.0)
* AMD ROCm, which includes AMD AMDSMI Library
* gRPC and protoc

The following components are required to build the latest documentation:

* Doxygen (1.8.11)
* Latex (pdfTeX 3.14159265-2.6-1.40.16)

.. code-block:: shell
  
    $ sudo apt install libcap-dev
    $ sudo apt install -y doxygen


Build and Install RDC
=====================

To build and install, clone the RDC source code from GitHub and use CMake.

.. code-block:: shell
  
    $ git clone <GitHub for RDC>
    $ cd rdc
    $ mkdir -p build; cd build
    $ cmake -DROCM_DIR=/opt/rocm -DGRPC_ROOT="$GRPC_PROTOC_ROOT"..
    $ make
    #Install library file and header and the default location is /opt/rocm
    $ make install

 
Build Documentation
-------------------

You can generate PDF documentation after a successful build. The reference manual, refman.pdf, appears in the latex directory.

.. code-block:: shell
  
    $ make doc
    $ cd latex
    $ make


Build Unit Tests for RDC Tool
-----------------------------

.. code-block:: shell
  
    $ cd rdc/tests/rdc_tests
    $ mkdir -p build; cd build
    $ cmake -DROCM_DIR=/opt/rocm -DGRPC_ROOT="$GRPC_PROTOC_ROOT"..
    $ make

    # To run the tests
    
    $ cd build/rdctst_tests
    $ ./rdctst

 
Test
----

.. code-block:: shell
  
    # Run rdcd daemon
    $ LD_LIBRARY_PATH=$PWD/rdc_libs/  ./server/rdcd -u
    
    # In another console run the RDC command-line
    $ LD_LIBRARY_PATH=$PWD/rdc_libs/  ./rdci/rdci discovery -l -u


Authentication
==============

RDC supports encrypted communications between clients and servers.

Generate Files for Authentication
---------------------------------

The communication between the client and server can be configured to be authenticated or unauthenticated. By default, authentication is enabled.

To disable authentication, when starting the server, use the "--unauth_comm" flag (or "-u" for short). You must also use “-u” in rdci to access unauth rdcd. The /lib/systemd/system/rdc.service file can be edited to pass arguments to rdcd on starting. On the client side, when calling rdc_channel_create(), the "secure" argument must be set to False.

Scripts
-------

RDC users manage their own keys and certificates. However, some scripts generate self-signed certificates in the RDC source tree in the authentication directory for test purposes. The following flowchart depicts how to generate the root certificates using the openssl command in 01gen_root_cert.sh:

A picture containing sign, drawing Description automatically generated

.. figure:: ../data/handbook_openssl.png

    Generation of root certificates using openssl command

The section where the default responses to ``openssl`` questions can be specified is included in ``openssl.conf``. To locate the section look for the following comment line:

.. code-block:: shell
  
    # < ** REPLACE VALUES IN THIS SECTION WITH APPROPRIATE VALUES FOR YOUR ORG. **>


It is helpful to modify this section with values appropriate for your organization if you expect to call this script many times. Additionally, you must replace the dummy values and update the ``alt_names`` section for your environment.

To generate the keys and certificates using these scripts, make the following calls:

.. code-block:: shell
  
    $ 01gen_root_cert.sh
    # provide answers to posed questions
    $ 02gen_ssl_artifacts.sh
    # provide answers to posed questions


At this point, the keys and certificates are in the newly created ``CA/artifacts`` directory. 

.. important::
  You must delete this directory if you need to rerun the scripts.

To install the keys and certificates, access the artifacts directory and run the ``install.sh`` script as root, specifying the install location. By default, RDC expects this to be in ``/etc/rdc``:

.. code-block:: shell
  
    $ cd CA/artifacts
    $ sudo install_<client|server>.sh /etc/rdc


These files must be copied to and installed on all client and server machines that are expected to communicate with one another.

Known Limitation
----------------

RDC has the following authentication limitations:

The client and server are hardcoded to look for the ``openssl`` certificate and key files in ``/etc/rdc``. There is no workaround available currently.


Verify Files for Authentication
===============================

Several SSL keys and certificates must be generated and installed on clients and servers for authentication to work properly. By default, the RDC server will look in the ``/etc/rdc`` folder for the following keys and certificates: 

Client
------

.. code-block:: shell
  
    $ sudo tree /etc/rdc
    /etc/rdc
    |-- client
    |-- certs
    | |-- rdc_cacert.pem
    | |-- rdc_client_cert.pem
    |-- private
    |-- rdc_client_cert.key


.. note::
  Machines that are clients and servers consist of both directory structures. 

Server
------

.. code-block:: shell
  
    $ sudo tree /etc/rdc
    /etc/rdc
    |-- server
    |-- certs
    | |-- rdc_cacert.pem
    | |-- rdc_server_cert.pem
    |-- private
    |-- rdc_server_cert.key