.. fvv1597424560931
.. _configure-remote-clis-and-clients:

=====================
Configure Remote CLIs
=====================

The |prod-os| command lines can be accessed from remote computers running
Linux, MacOS, and Windows.

.. rubric:: |context|

This functionality is made available using a docker image for connecting to the
|prod-os| remotely. This docker image is pulled as required by configuration
scripts.

.. rubric:: |prereq|

You must have Docker installed on the remote systems you connect from. For more
information on installing Docker, see `https://docs.docker.com/install/
<https://docs.docker.com/install/>`__. For Windows remote workstations, Docker
is only supported on Windows 10.

For Windows remote workstations, you must run the following commands from a
Cygwin terminal. See `https://www.cygwin.com/ <https://www.cygwin.com/>`__ for
more information about the Cygwin project.

For Windows remote workstations, you must also have :command:`winpty`
installed. Download the latest release tarball for Cygwin from
`https://github.com/rprichard/winpty/releases
<https://github.com/rprichard/winpty/releases>`__. After downloading the
tarball, extract it to any location and change the Windows <PATH> variable to
include its bin folder from the extracted winpty folder.

For access to remote CLI, it is required to set the DNS in the cluster using
the :command:`system service-parameter-add openstack helm
endpoint_domain=domain_name` command and reapply OpenStack using the system
application-apply |prefix|-openstack command.

The following procedure shows how to configure the Container-backed Remote
|CLIs| for OpenStack remote access.

.. rubric:: |proc|

.. _configure-remote-clis-and-clients-steps-fvl-n4d-tkb:

#.  Copy the remote client tarball file from |dnload-loc| to the remote
    workstation, and extract its content.


    -   The tarball is available from the |prod-os| area on |dnload-loc|.

    -   You can extract the tarball's contents anywhere on your workstation system.


    .. parsed-literal::

        $ cd $HOME
        $ tar xvf |l-prefix|-remote-clients-<version>.tgz

#.  Download the user/tenant **openrc** file from the |os-prod-hor-long| to the
    remote workstation.

    .. note::

        If the |prod-os| system has HTTPS certificate enabled, use the
        following steps:

        #.  Download the certificate file (**ca-bundle.trust.crt**) from the
            /etc/pki/tls/certs/ directory on the |prod-os| system, and copy the
            file to your remote workstation to the same directory as the
            admin-openrc.sh file.

        #.  Update the admin-openrc.sh file with the following:

            .. code-block:: none

                export OS_CACERT=ca-bundle.trust.crt

    #.  Log in to |os-prod-hor| interface as the user and tenant that you want
        to configure remote access for.

        In this example, we use the 'admin' user in the 'admin' tenant.

    #.  Navigate to **Project** \> **API Access** \> **Download Openstack RCfile**.

    #.  Select **Openstack RC file**.

        The file admin-openrc.sh downloads.

        .. note::
            For a Distributed Cloud system, navigate to **Project** \> **Central Cloud Regions** \> **RegionOne** \>
            and download the **Openstack RC file**.

#.  On the remote workstation, configure the OpenStack client access.


    #.  Change to the location of the extracted tarball.

        .. parsed-literal::

            $ cd $HOME/|l-prefix|-remote-clients-<version>/

    #.  Create a working directory that will be mounted by the container
        implementing the remote |CLIs|.

        .. code-block:: none

            $ mkdir -p $HOME/remote_cli_wd

    #.  Run the :command:`configure_client.sh` script to install and configure
        the OpenStack CLIs/Clients.

        .. only:: starlingx

           ::

              $ ./configure_client.sh -t openstack -r admin-openrc.sh -w  $HOME/remote_cli_wd -a <wind-river-registry-url>/docker.io/starlingx/wr-openstackclients:<tag>

        .. only:: partner

           .. include:: /_includes/configure-remote-clis-and-clients.rest
              :start-after: remote-cli-begin
              :end-before: remote-cli-end

        If you specify repositories that require authentication, as shown
        above, you must remember to perform a :command:`docker login` to that
        repository before using remote |CLIs| for the first time.

        The options for configure_client.sh are:

        **-t**
            The type of client configuration. The options are platform (for
            |prod-long| |CLI| and clients) and OpenStack (for
            |prod-os| application |CLI| and clients).

            The default value is platform.

        **-r**
            The user/tenant RC file to use for 'openstack' |CLI| commands.

            The default value is admin-openrc.sh.

        **-o**
            The remote |CLI|/workstation RC file generated by this script.

            This RC file needs to be sourced in the shell, to setup required
            environment variables and aliases, before running any remote |CLI|
            commands.

            For the platform client setup, the default is
            remote_client_platform.sh. For the OpenStack application client
            setup, the default is remote_client_openstack.sh.

        **-w**
            The working directory that will be mounted by the container
            implementing the remote |CLIs|. When using the remote |CLIs|, any files
            passed as arguments to the remote |CLI| commands need to be in this
            directory in order for the container to access the files. The
            default value is the directory from which the
            :command:`configure_client.sh` command was run.

        **-p**
            Override the container image for the platform |CLI| and clients.

            By default, the platform |CLIs| and clients container image is pulled
            from docker.io/starlingx/stx-platformclients.

            If you specify repositories that require authentication, you must
            first perform a :command:`docker login` to that repository before
            using remote |CLIs|.

        **-a**
            Override the OpenStack application image.

            By default, the OpenStack |CLIs| and clients container image is
            pulled from docker.io/starlingx/stx-openstackclients.

        The :command:`configure-client.sh` command will generate a
        remote_client_openstack.sh RC file. This RC file needs to be sourced
        in the shell to set up required environment variables and aliases
        before any remote |CLI| commands can be run.

    #.  Copy the file remote_client_openstack.sh to $HOME/remote_cli_wd


.. rubric:: |postreq|

After configuring the |prod-os| container-backed remote |CLIs|/clients, the
remote |prod-os| |CLIs| can be used in any shell after sourcing the generated
remote |CLI|/client RC file. This RC file sets up the required environment
variables and aliases for the remote |CLI| commands.

.. note::
    Consider adding this command to your .login or shell rc file, such that
    your shells will automatically be initialized with the environment
    variables and aliases for the remote |CLI| commands.

See :ref:`Use Container-backed Remote CLIs and Clients
<config-and-management-using-container-backed-remote-clis-and-clients>` for
details.