############
Installation
############

.. highlight:: none

Current Version
===============

NSCLI will periodically check for updates, and notify you if an update is available. Please use the package manager
that you installed NSCLI with to handle upgrades, whether that's ``apt``, ``brew``, or ``pip``.

To see what version of NSCLI you have, you can query your package manager, or run ``nscli --version``, which will make
nscli check for updates.

The current version as of |today| is |version|.


Windows Users
=============

NSCLI is meant to run on Mac or Linux. You will need to install a Linux environment to run NSCLI. Some options for this 
include:

    - Install the Linux Subsystem for Windows (in the Windows app store, install Ubuntu.)
    - Run a Linux Virtual Machine (using VirtualBox or your virtualization software of choice)
    - Install Linux in addition to, or instead of, Windows.

Once you have set up one of these environments, see the :ref:`Linux Users<linux-users>` section below.

The following environments are not supported. If you want to install NSCLI on them, see the section below on
:ref:`Installing Manually<installing-manually>`; however, we recommend against using these:

    - Cygwin
    - Git Bash


Mac Users
=========

The below Homebrew installation steps will ONLY work for MacOS versions above 10.15 (Catalina).

If you are on MacOS 10.14 (Mojave), you will need to install NSCLI as a python package. 
Please follow installation instructions in the Troubleshooting section/wiki:
`NSCLI - Issues / Bugs / Known Workarounds <https://raxglobal.sharepoint.com/sites/OneWiki-NetworkSecurity/SitePages/NSCLI%20-%20Issues%20-%20Bugs%20-%20Known%20Workarounds.aspx>`_

Before Installing
-----------------

1. Install command line tools
    1. Run ``xcode-select --install``. This should cause a window to pop up and ask if you want to install, or 
       "get xcode". Don't click "get xcode". Just install the command line tools; you don't need full-blown xcode to 
       use nscli. This might take a while to complete. 
    2. If you see an error message like this::

          xcode-select: error: command line tools are already installed, use "Software Update" to install updates

       That's good. You can move on.

2. Install Homebrew
    1. Run ``brew -v``
    2. If you see Homebrew version info, that's good. You can move on. If you see an error message instead, then install
       Homebrew::

           /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install.sh)"

3. Tap the GTS homebrew repository
    1. **This step is optional**, but is highly recommended because it makes managing your NSCLI installation a bit easier. 
    2. Run ``brew tap``
    3. If you see ``gts/rs`` in the list, that's good and you can move on to "Installing" section
    4. Check if you can open https://github.rackspace.com/SupportTools/homebrew-rs
    5. If you can, follow the guide on getting Tap set up (Add This Tap), then SKIP to "Installing" section
    6. If you cannot, open a request in `Sailpoint <https://sailpoint.rackspace.corp/>`_ for membership in 
       the ``github-users`` group.
    7. Then, check if following page is accessible: https://one.rackspace.com/display/apple/SupportTools+Homebrew+Tap#SupportToolsHomebrewTap-SupportToolsHomebrewTap
    8. If it is, you can use "SupportTools Homebrew Tap" section to add tap, then SKIP to "Installing" section.
    9. If not, see if there are any updated installation instructions @ wiki:
`NSCLI - Issues / Bugs / Known Workarounds <https://raxglobal.sharepoint.com/sites/OneWiki-NetworkSecurity/SitePages/NSCLI%20-%20Issues%20-%20Bugs%20-%20Known%20Workarounds.aspx>`_
    10. Contact NSIA team for any further assistance.  

Installing
----------

Install NSCLI with Homebrew:

If you have tapped ``gts/rs`` (see previous section if unsure), then::

    brew update && brew install nscli
    
If not, then:

    1. Get the full URL of "brew formula" for the latest version of NSCLI from http or https://intra.mirror.rackspace.com.
       
        As of this writing, that URL is:
            \https://intra.mirror.rackspace.com/netsec.devops/nscli/Formula/|version|/nscli.rb

    2. Run following command, with URL replaced with actual url from the previous step:

        ``brew update && curl -L URL > nscli.rb && brew install --formula nscli.rb`` 


After Installing
----------------

1. If you previously had nscli installed outside of homebrew, and this is your first time installing via homebrew, run
   this command to to pave over your old nscli installation::

       brew unlink nscli; brew link nscli --overwrite
       nscli reset

2. See the section below about :ref:`SSH Keys<ssh-keys>`.

Upgrading
---------

Upgrade NSCLI with Homebrew:

If you have tapped ``gts/rs`` (see previous section "3. Tap the GTS homebrew repository" if unsure), then::

    brew update && brew upgrade nscli

If not, then:

    1. Get the full URL of "brew formula" for the latest version of NSCLI from Mirror
       As of this writing, that URL is \https://intra.mirror.rackspace.com/netsec.devops/nscli/Formula/|version|/nscli.rb
    2. Run following command, with URL replaced with actual url from the previous step: 
       ``brew update && curl -L URL > nscli.rb && brew upgrade --formula nscli.rb`` 

Uninstalling
------------

To uninstall nscli, run ``brew uninstall nscli``. After uninstalling, the following items will remain and can be
purged manually if desired:

1. Configuration files under ``~/Library/Application Support/nscli``
2. Cached data under ``~/Library/Caches/nscli``
3. Logs under ``~/Library/Logs/nscli``
4. Cached credentials stored in the system keychain. These can be found in the Keychain Access app, and all names 
   begin with "com.rackspace.nscli"


.. _linux-users:

Linux Users
===========

We provide system packages for the Linux distributions below. If there is no system package available for your distro, 
see the next section about :ref:`Installing Manually<installing-manually>`. If you have a distro you would like us to support, please
reach out to us (see the :doc:`Contact` section). Contributions in this department are very much welcome.

======  =======  ========
Supported OS Flavors
-------------------------
Distro  Version  Codename
======  =======  ========
Debian  10       Buster
Ubuntu  20.04    Focal
Ubuntu  22.04    Jammy
======  =======  ========


Debian and Ubuntu Users
-----------------------

Before Installing
^^^^^^^^^^^^^^^^^

1. [Ubuntu Users] Upgrade to a supported version
    1. Run ``cat /etc/os-release``. If your Ubuntu version is listed in the table above, skip to the next step. If it is not, you
       will need to upgrade. To upgrade, first back up any essential files. Then run ``sudo do-release-upgrade`` and 
       grab a cup of tea because this will take a while. Alternatively, you might want to delete your OS and install
       a more recent version, as that can be faster than upgrading, especially if you don't need to preserve your files.
2. [Everyone] Add Artifactory as a trusted source::

    sudo apt-get update && sudo apt-get -y install gnupg2 curl ca-certificates apt-transport-https man
    sudo sh -c "printf 'deb https://artifacts.rackspace.net/artifactory/nscli-debian-local %s main\n' $(awk 'BEGIN { FS="=" } /CODENAME/ {print $2;exit;}' /etc/os-release) > /etc/apt/sources.list.d/nscli.list"
    curl -fsSL https://artifacts.rackspace.net/artifactory/api/gpg/key/public | sudo apt-key add -

    ! If you see following message after running above command :
    ! Warning: apt-key is deprecated. Manage keyring files in trusted.gpg.d instead (see apt-key(8))
    ! Then, run following command as well to ensure compatibility across newer OS versions

    curl -fsSL https://artifacts.rackspace.net/artifactory/api/gpg/key/public | gpg --dearmor > rax-artifactory-key.gpg
    sudo mv rax-artifactory-key.gpg /etc/apt/trusted.gpg.d/

Installing
^^^^^^^^^^

::

    sudo apt-get update && sudo apt-get install nscli

After Installing
^^^^^^^^^^^^^^^^

1. If you are installing nscli with ``apt`` for the first time, and you previously had an earlier version 
   installed, run the following commands to un-link the old version::

       sudo rm -rf /usr/local/bin/nscli /usr/local/share/man/man1/nscli.1.gz /usr/local/share/man/man5/nscli_settings.5.gz

   After that, close your terminal window and open a new one.

2. See the section below about :ref:`SSH Keys<ssh-keys>`.

Uninstalling
^^^^^^^^^^^^

To uninstall nscli, run ``sudo dpkg -P nscli``. After uninstalling, the following items will remain and can be purged 
manually if desired:

1. Configuration files under ``~/.config/nscli``  or in ``$XDG_CONFIG_HOME``, if defined
2. Cached data under ``~/.cache/nscli`` or in ``$XDG_CACHE_HOME``, if defined
3. Logs under ``~/.cache/nscli/log`` or in ``$XDG_CACHE_HOME`` if defined
4. Cached credentials stored via the Python ``keyring`` library. If you have a Gnome keyring or another secret storage
   method using dbus available, ``keyring`` likely stored your passwords there. If not, it fell back to storing them
   under ``python_keyring/keyring_pass.cfg`` in the directory ``~/.local/share`` or ``$XDG_DATA_HOME``, if defined. Note 
   that, because this location is not relative to nscli's installation path, it could be shared by other Python scripts.

Upgrading
^^^^^^^^^

::

    sudo apt-get -y update && sudo apt-get install nscli


.. _installing-manually:

Installing Manually
===================

We recommend installing from a system package if it is available for your OS, but nscli is also available as a Python 
package on Artifactory. Installing from the Python package will likely require some additional configuration on your 
system, which is not documented here. It is assumed that users who install nscli from the Python package are familiar 
with configuring Python and/or virtual environments. This command would be the minimum to get nscli installed in this 
way::

    pip install nscli --index-url https://artifacts.rackspace.net/artifactory/api/pypi/pypi/simple -c https://pages.github.rackspace.com/nsi/nscli/constraints.txt

Troubleshooting
===============

See :doc:`Bugs`

Troubleshooting Wiki
--------------------

`NSCLI - Issues / Bugs / Known Workarounds <https://raxglobal.sharepoint.com/sites/OneWiki-NetworkSecurity/SitePages/NSCLI%20-%20Issues%20-%20Bugs%20-%20Known%20Workarounds.aspx>`_


.. _ssh-keys:

SSH Keys
========

One of NSCLI's main functions is to handle SSH for you. This lets you run ``nscli ssh <device number>`` and not have to 
think about the specific IP addresses and proxies involved. In order for NSCLI to do this, your system needs to be set 
up to allow SSH to work. NSCLI can identify some common misconfigurations and will offer to correct them for you, but 
here are a couple of important things that it can't do on its own:

Upload your Public Key to Identity Services
-------------------------------------------

If you don't have an ssh key, nscli will help you create one. Once you have it, you'll need to log into the
`Identity Portal <https://identity.rackspace.corp/ManageSSHKeys>`_ and upload the public part of the key to your 
profile. The next-gen bastion 
`wiki <https://one.rackspace.com/display/rackertools/Next+Gen+Bastions#NextGenBastions-BasicKeyBasedAuthentication>`_
has more information on this procedure.

Run ssh-agent
-------------

``ssh-agent`` needs to be running, since that is the program that holds onto your SSH keys while you proxy through the
`Balabit SCBs <https://one.rackspace.com/display/rackertools/Next+Gen+Bastions#NextGenBastions-BasicKeyBasedAuthentication>`_.
For Mac (and many Linux) users, this is already happening for you and you don't have to set anything up.

To verify ``ssh-agent`` is running, run ``ssh-add -l``. If you see SSH keys, or "The agent has no identities," then it
is running. If you see "Could not open a connection to your authentication agent," or another error message, then it is
not running.

To start ``ssh-agent``, run ``eval $(ssh-agent -s)``. Note that this modifies your current shell, so if you close your
terminal or switch to a new tab, you might have to run this again. You can automate this process by adding the command
to the end of the special file ``~/.profile`` (``~/.bash_profile`` for Mac users), which gets executed every time you
start a new shell. For advanced configuration ideas, see `this discussion <https://stackoverflow.com/a/18915067>`_.


Nucleus
=======

Nucleus is a browser plugin that can integrate with nscli. Although Nucleus is deprecated at this point, some users 
still have success in getting it to work. Please refer to the 
`instructions on Nucleus for nscli <https://raxglobal.sharepoint.com/sites/OneWiki-NetworkSecurity/SitePages/nscli%20Nucleus%20Integration%20Linux%20or%20MAC.aspx>`_   


Corrupt Mac Keychain
====================

We have taken measures to try and minimize keychain corruption, but from time to time you may receive error messages 
where nscli is unable to read or write to your keyring on Mac. We have created a wiki to help troubleshoot this with
screen shots here: `Fix corrupted Mac keychain <https://raxglobal.sharepoint.com/sites/OneWiki-NetworkSecurity/SitePages/Fix%20corrupted%20Mac%20keychain.aspx>`_

Here are the steps in short form:

1. Restart. Always start with this step.

If you continue to have issues proceed with the next steps:

2. Go to Applications > Utilities > Keychain Access
3. Go to Keychain Access menu > Preferences
4. Click on Reset My Default Keychains. If you don't get any errors, restart.

If you get an auth error or the problem persists after restart, continue to manually delete:

5. Right click on 'login' on the left of the main window and click Delete Keychain "login"
6. Click on Delete References & Files
7. Next, select the 'Local Items' on the left side.
8. You will not be able to delete the whole keychain as you did with 'login' so individually select each item in the 
   main window and delete them all.
9. Restart.
