.. gub1581954935898
.. _configure-local-cli-access:

==========================
Configure Local CLI Access
==========================

You can access the system via a local CLI from the active controller
node's local console or by SSH-ing to the OAM floating IP Address.

.. rubric:: |context|

It is highly recommended that only 'sysadmin' and a small number of admin
level user accounts be allowed to SSH to the system. This procedure will
assume that only such an admin user is using the local CLI.

Using the **sysadmin** account and the Local CLI, you can perform all
required system maintenance, administration and troubleshooting tasks.

.. rubric:: |proc|


.. _configure-local-cli-access-steps-ewr-c33-gjb:

#.  Log in to controller-0 via the console or using SSH.

    Use the user name **sysadmin** and your <sysadmin-password>.

#.  Acquire Keystone Admin and Kubernetes Admin credentials.

    .. code-block:: none

        $ source /etc/platform/openrc
        [sysadmin@controller-0 ~(keystone_admin)]$

#.  If you plan on customizing the sysadmin's kubectl configuration on the
    |prod-long| Controller, (for example, :command:`kubectl config set-...` or
    :command:`or oidc-auth`), you should use a private KUBECONFIG file and NOT
    the system-managed KUBECONFIG file /etc/kubernetes/admin.conf, which can be
    changed and overwritten by the system.

    #.  Copy /etc/kubernetes/admin.conf to a private file under
        /home/sysadmin such as /home/sysadmin/.kube/config, and update
        /home/sysadmin/.profile to have the <KUBECONFIG> environment variable
        point to the private file.

        For example, the following commands set up a private KUBECONFIG file.

        .. code-block:: none

            # ssh sysadmin@<oamFloatingIpAddress>
            Password:
            % mkdir .kube
            % cp /etc/kubernetes/admin.conf .kube/config
            % echo "export KUBECONFIG=~/.kube/config" >> ~/.profile
            % exit


    #.  Confirm that the <KUBECONFIG> environment variable is set correctly
        and that :command:`kubectl` commands are functioning properly.

        .. code-block:: none

            # ssh sysadmin@<oamFloatingIpAddress>
            Password:
            % env | fgrep KUBE
            KUBECONFIG=/home/sysadmin/.kube/config
            % kubectl get pods

    .. rubric:: |result|

You can now access all |prod| commands.

**system commands**

StarlingX system and host management commands are executed with the
:command:`system` command.

For example:

.. code-block:: none

    ~(keystone_admin)]$ system host-list
    +----+--------------+-------------+----------------+-------------+--------------+
    | id | hostname     | personality | administrative | operational | availability |
    +----+--------------+-------------+----------------+-------------+--------------+
    | 1  | controller-0 | controller  | unlocked       | enabled     | available    |
    +----+--------------+-------------+----------------+-------------+--------------+

Use :command:`system help` for a full list of :command:`system` subcommands.

**fm commands**

StarlingX fault management commands are executed with the :command:`fm` command.

For example:

.. code-block:: none

    ~(keystone_admin)]$ fm alarm-list

    +-------+---------------+---------------------+----------+---------------+
    | Alarm | Reason Text   | Entity ID           | Severity | Time Stamp    |
    | ID    |               |                     |          |               |
    +-------+---------------+---------------------+----------+---------------+
    | 750.  | Application   | k8s_application=    | major    | 2019-08-08T20 |
    | 002   | Apply Failure | platform-integ-apps |          | :17:58.223926 |
    |       |               |                     |          |               |
    +-------+---------------+---------------------+----------+---------------+

Use :command:`fm help` for a full list of :command:`fm` subcommands.

**kubectl commands**

Kubernetes commands are executed with the :command:`kubectl` command

For example:

.. code-block:: none

    ~(keystone_admin)]$ kubectl get nodes
    NAME           STATUS   ROLES    AGE     VERSION
    controller-0   Ready    master   5d19h   v1.13.5
    ~(keystone_admin)]$ kubectl get pods
    NAME                                              READY   STATUS    RESTARTS   AGE
    dashboard-kubernetes-dashboard-7749d97f95-bzp5w   1/1     Running   0          3d18h

**Helm commands**

Helm commands are executed with the :command:`helm` command

For example:

.. code-block:: none

    % helm repo add bitnami https://charts.bitnami.com/bitnami
    % helm repo update
    % helm repo list
    % helm search repo
    % helm install wordpress bitnami/wordpress

.. _cliconfirmationsupport:

CLI Confirmation Support
------------------------

A user confirmation request can optionally be used to safeguard critical
operations performed via the CLI. When the user CLI Confirmation capability is
enabled, CLI users are prompted to explicitly confirm any potentially critical or
destructive CLI command, before proceeding with the execution of the CLI
command.

This interactive safeguard helps prevent unintentional or irreversible changes
made to the system.

The user CLI Confirmation capability is disabled by default and you must
explicitly enable it. When this feature is enabled, a CLI user when executing a
potentially critical of destructive CLI command will see a confirmation request
message such as the following:

.. code-block::

    ~(keystone_admin)$ system ca-certificate-install cert-file

    WARNING: This is a high-risk operation that may cause a service interruption or remove critical resources
    Do you want to continue? (yes/No):

This prompt has a timeout of 10 seconds before timing out and not executing the
CLI command. Therefore, you must provide the input within this time limit to
proceed with the operation.

You can also skip the confirmation message using the ``--yes`` parameter as
shown below:

.. code-block::

    ~(keystone_admin)$ system ca-certificate-install cert-file --yes

For the list of CLI commands that will ask for confirmation when the CLI
Confirmation capability is enabled, see
:ref:`confirmation-support-8f0f2784db15`.

Enable CLI Confirmation
***********************

.. rubric:: |proc|

You can enable the CLI Confirmation capability, for all the local CLI users
(users SSH'd or logged into the local console of the active controller) by
using one of the following methods:

- Before installation, specify the ``cli_confirmations`` service parameter to
  ``enabled`` in the deployment configuration file.

  .. code-block::

      serviceParameters:
        - service: platform
          section: client
          paramname:cli_confirmations
          paramvalue: ``enabled``

-  After installation, modify the ``cli_confirmations`` service parameter using
   the following commands:

   .. code-block::

       ~(keystone_admin)$ system service-parameter-modify platform client cli_confirmations=enabled
       ~(keystone_admin)$ system service-parameter-apply platform
       ~(keystone_admin)$ source /etc/profile.d/cli_env.sh

.. only:: partner

    .. include:: /_includes/confirmation-support.rest
       :start-after: confirmationmethod-begin
       :end-before: confirmationmethod-end

Disable CLI Confirmation
************************

To disable CLI Confirmation capability, run the following commands:

.. code-block::

    ~(keystone_admin)$ system service-parameter-modify platform client cli_confirmations=disabled
    ~(keystone_admin)$ system service-parameter-apply platform
    ~(keystone_admin)$ source /etc/profile.d/cli_env.sh