Installation

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 Jan 28, 2025 is 25.1.27.

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 Linux Users section below.

The following environments are not supported. If you want to install NSCLI on them, see the section below on 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

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 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

  1. 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/25.1.27/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 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/25.1.27/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

We provide system packages for the Linux distributions below. If there is no system package available for your distro, see the next section about Installing Manually. If you have a distro you would like us to support, please reach out to us (see the 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 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

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 Bugs

Troubleshooting Wiki

NSCLI - Issues / Bugs / Known Workarounds

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 and upload the public part of the key to your profile. The next-gen bastion wiki 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. 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.

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

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

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:

  1. Go to Applications > Utilities > Keychain Access

  2. Go to Keychain Access menu > Preferences

  3. 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:

  1. Right click on ‘login’ on the left of the main window and click Delete Keychain “login”

  2. Click on Delete References & Files

  3. Next, select the ‘Local Items’ on the left side.

  4. 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.

  5. Restart.