####
Bugs
####

Report a Bug
============

Before you report a bug, please make sure you are using the latest nscli version. Check for available upgrades with
``nscli -v``. If you are having trouble upgrading from one version of NSCLI to another, please try uninstalling 
NSCLI and performing a clean install. See :doc:`Installation` for instructions.

Please visit `our github <https://github.rackspace.com/NSI/nscli/issues>`_ to submit an issue about NSCLI, or see the
:doc:`Contact` section for other ways to get in touch.

Also try reviewing our NSCLI troubleshooting wiki page for additional tips.
`NSCLI - Issues / Bugs / Known Workarounds <https://raxglobal.sharepoint.com/sites/OneWiki-NetworkSecurity/SitePages/NSCLI%20-%20Issues%20-%20Bugs%20-%20Known%20Workarounds.aspx>`_

Known Bugs
==========

RSA Tokens
----------

Moving to, or set up, of the RSA App on your phone requires an additional step to support NSCLI.
You are required to set up an additional PIN that is used in place of a token during RSA prompts in NSCLI.
Please follow these instructions for set up. `Instructions <https://one.rackspace.com/pages/viewpage.action?pageId=733173229#RSA-MultiFactorAuthentication-AuthenticatetoRadiusClients,API,orotherdevicesthatpointtotheonpremiseRSAserverswithaCloudToken>`_

nscli maint port-migrate
------------------------

1. (Bug) If switch has a directly connected Aggr and a chained switch to other Aggr, not directly connected, second aggr 
   may be missed
2. (BUG) Fix finding mlag/vpc if necessary 'mlag <po #>' and 'vpc <po #>' - only applies to devices with port-channels

Reset
-----

NSCLI maintains a cache of credentials and other information. ``nscli reset`` will delete these things, and is often
enough to fix what looks like buggy behavior. ``nscli reset`` is often a good first step in troubleshooting any nscli
problems.

Settings
--------

There is an nscli :doc:`settings file <SettingsFile>` that contains usernames and preferences. Sometimes bug-like 
behavior is caused by missing or incorrect data in the settings file. To see the location of the file, run 
``nscli --version``. If the file is deleted, nscli will replace it with a fresh, blank copy on the next run.

Unicode
-------

Internally, Python stores text as unicode code points. When it's time to print some output, Python takes cues from the 
output device on what types of encodings it will accept. If nscli is running in a terminal, and that terminal wants 
ascii output, then nscli will try to oblige. The problem is that many unicode characters can't be properly represented 
in ascii, so if Python tries to decode one of these characters as ascii, you'll see a crash with a message about a 
"UnicodeDecodeError". Unicode characters are ubiquitous at Rackspace (and in the world). We have them in account names, 
customer contact names, device management guidelines, etc., so failing to support/encode/display unicode is not an 
option.

If nscli warns that stdout or stderr lack unicode support, you will need to configure your environment to permit Python 
to print unicode to the terminal. The easiest way to do this is to set your locale environment variable properly. Run
``locale -a`` to see which locales are supported on your system. Then edit your shell profile so that this variable will
be set whenever you start a new session. For example::

    printf '\nLC_CTYPE=en_US.UTF-8; export LC_CTYPE\n' >> ~/.bash_profile

If nscli does not give a warning regarding unicode, but its unicode output is using the wrong symbols (commonly a 
diamond or square around a question mark), then nscli is successfully writing unicode to the terminal, but the terminal 
application itself cannot display the given code point. This problem is outside of nscli's control, and might be solved 
by upgrading, replacing, or configuring the terminal application. Some users have had success with choosing a different 
font.

Illegal instruction: 4
----------------------

Mac users who encounter this error message should upgrade their OS to at least version 10.13. Details available at 
https://github.rackspace.com/NSI/nscli/issues/1037

Unable to connect to agent
--------------------------

If ``nscli ssh`` or another nscli command that involves SSHing crashes, and the error output includes
``Unable to connect to agent``, first see the ssh-key documentation in the nscli 
`Installation article <https://pages.github.rackspace.com/nsi/nscli/Installation.html#ssh-keys>`_.

If you have configured your ssh keys/agent properly, but you are still seeing this crash, and you are running Ubuntu 18,
see this workaround: https://github.com/Microsoft/WSL/issues/3183#issuecomment-411138426

Reaching Into NSCLI
-------------------

In rare cases, it may be useful to reach into the internals of NSCLI's virtual environment and take some action, for
example, upgrading one of NSCLI's Python dependencies to apply a critical patch. NSCLI's python interpreter is shown
in the output of ``nscli -v``, therefore its pip executable can be invoked like this:
``"$(nscli -v 2>&1 | awk '/python interpreter/ {print $4}')" -m pip``

Again, it should not normally be necessary to interact with this at all, but for example, if one needed to upgrade
NSCLI's NSPYLIB dependency, it could be done like this::

    "$(nscli -v 2>&1 | awk '/python interpreter/ {print $4}')" -m pip install --upgrade nspylib

Binding to AD
-------------

The error message ``Unable to determine user's division.`` indicates that NSCLI was not able to get the information it
needs from Active Directory via the Identity API. This could mean that your SSO username or identity token are wrong
in NSCLI, which are problems that an ``nscli reset`` will fix. It could also mean that api.identity.rackspace.corp is
not reachable from your system, which could indicate a service outage or a local networking problem.

PTY Allocation Failed
---------------------

The ``PTY allocation request failed on channel 0`` error message happens because the user is not a member 
of the Balabit_Support_gateway LDAP group (or the corresponding group for non-support balabits). Despite this, the 
balabit still allows the users to complete authentication; it only fails later in the process when trying to allocate a 
pseudo-terminal.

ModuleNotFoundError: No module named 'distutils.util'
-----------------------------------------------------

The ``ModuleNotFoundError: No module named 'distutils.util'`` error message happens on Linux because the python3 distutils package is not installed. To install the module run:
``sudo apt-get install python3-distutils``

nscli maint port-audit
------------------------

port-audit attempts to gather a device's switch information from CTK to see which DC it is in in case of a DC migration.
This information is no longer being populated for new switches and the script will now fall back to using the device's
DC instead. If a device is going through a migration to a new DC, the results may be unreliable or just wrong.
