You type _shell on a Mellanox / NVIDIA Onyx switch and the CLI answers with a licence complaint instead of a Linux prompt. That is not a broken switch and it is not a lost password — Onyx simply refuses to hand out a Restricted Commands shell until the matching entitlement is present in the licence store. On newer commercial builds the hidden _shell (and its cousins _debug, _diag, _fae) are gated behind a Restricted Commands licence, so the first thing you see is an error such as Restricted command not permitted, Command not licensed or even a plain % Unrecognized command. This guide walks through the temporary-authorisation path: how to confirm the switch really is missing the entitlement, how to install a Restricted Commands key from global configuration mode, how to get back into the Linux shell, and what to expect when the authorisation you were given is only temporary.

What the missing-licence error really means

Onyx is a Linux appliance with a purpose-built CLI bolted on top. The CLI runs in three practical permission layers: a read-only standard mode, an enable mode that lets you change configuration, and — underneath both — the operating-system shell that the CLI itself runs from. The underscore-prefixed commands are the bridge between the third and second layers. They are shipped by NVIDIA for support engineering and for workflows that the configuration CLI cannot express, such as running a bundled maintenance script, inspecting the ASIC firmware, reading kernel counters, or resetting a BIOS password that the documented interface will not touch.

Because those commands can change the appliance in ways the configuration model cannot describe, NVIDIA does not enable them by default. A switch with no Restricted Commands entitlement behaves exactly as if the command did not exist: the CLI parser rejects it before the shell is ever spawned. Nothing is wrong with the image, the boot slot or the file system — the gate is purely the licence record stored on the switch.

The same gate applies when Onyx is running in secure mode. A switch with system secure-mode enable active refuses unsigned or unlicensed shell access even when an entitlement exists, so it is worth checking both the licence table and the secure-mode state before you start changing anything.

Before you start: prerequisites

• The switch is reachable over console, SSH or the Web UI with an account that can enter configuration mode. A full administrator (or root) account on Onyx 3.x/3.10+ always works.
• You have a Restricted Commands licence key for the platform generation you are running. Keys look like LK2-RESTRICTED_CMDS_GEN2-xxxx-xxxx-xxxx-x; the GEN1/GEN2 segment matters, and a key issued for one switch family is not guaranteed to install on another.
• You know why the switch needs shell access. Every use of _shell should be documented in a change record, because you are deliberately stepping outside the supported configuration model.
• You can back the configuration out. Have a saved configuration on a server before you touch anything, so the switch can be restored if a maintenance script misbehaves. See Mellanox MLNX-OS: Back Up Switch Configuration to Server for the file-transfer steps.

Step 1 – Confirm the switch state

Log in, elevate to enable mode, and collect three facts: the software version, the installed licences, and whether secure mode is on.

switch-61d5ce login: admin
Password:

switch-61d5ce > enable
switch-61d5ce # show version
switch-61d5ce # show license
switch-61d5ce # show system secure-mode

If show license lists only the base OS or an Ethernet/feature pack and no Restricted Commands entry, the diagnosis is confirmed. If it lists an expired entry, the entry will still appear but with an expiry date in the past — the CLI treats that the same as no licence at all.

Step 2 – Enter global configuration mode

Licence operations live in global configuration mode on Onyx, exactly like every other configuration change. There is no separate licence shell.

switch-61d5ce # configure terminal
switch-61d5ce (config) #

If the prompt refuses the transition, the account you are using is not a full administrator. Change to an administrator account, or check the role table with show username — restricted-command work needs the highest privilege level the platform offers.

Step 3 – Install the Restricted Commands licence

Install the key you were issued. The command takes the key as a single argument and does not prompt for confirmation:

switch-61d5ce (config) # license install LK2-RESTRICTED_CMDS_GEN2-88A1-NEWD-BPNB-1

Two things are worth saying about that line honestly. First, the key shown above is the one used in the case this article is based on, and it is an example of the format only — a truncated or shared key from a forum post will generally fail with Invalid license key, because the trailing characters carry a checksum and the key is validated against the platform family. Use the key issued for your own chassis serial number. Second, the command must be run in configuration mode; from enable mode Onyx answers with a syntax error, which people frequently mistake for a licence problem of a different kind.

If the key is accepted, Onyx writes it into the licence store and the file system commit happens immediately. If the switch reports that the licence is already installed, you are done with this step — move on to verification, because a licence that is installed but not yet active usually means the CLI needs you to leave and re-enter the mode, or that a temporary authorisation has already expired.

Step 4 – Leave configuration mode and re-enter the shell

Leave configuration mode and try the shell again from enable mode:

switch-61d5ce (config) # exit
switch-61d5ce # _shell

When the authorisation is in place, the CLI hands the session to the Linux shell. The prompt changes from the switch-style switch-61d5ce # to a Linux prompt — a bare # or root@switch:~# depending on the release — and from that point on you are typing real Bourne shell commands rather than CLI keywords.

# uname -a
Linux switch-61d5ce 4.14.105 #1 SMP PREEMPT ... aarch64 GNU/Linux
# pwd
/opt/tms

Confirm you are actually in the shell and not still in the CLI: uname -a, hostname, id and ls / all behave like Linux. If they are rejected, the shell never started and you are still at the CLI parser.

Step 5 – Exit cleanly and record what you changed

Do not leave a shell session hanging; the CLI may hold the configuration lock while the shell is open, which blocks other administrators. Type exit once to return to the CLI. If you ran a maintenance script, capture its output to a file before you leave so the change is auditable:

# /opt/tms/bin/<your-script> 2>&1 | tee /tmp/$(date +%F)-maintenance.log
# exit
switch-61d5ce #

Then save the configuration if the script altered anything the CLI tracks, and verify with the same three commands from Step 1 that the licence is now listed:

switch-61d5ce # show license
switch-61d5ce # write memory

Temporary authorisation: what it does and does not give you

Most people who hit this error do not have a permanent entitlement — they have a temporary authorisation issued by support or by a distributor for a specific escalation. That changes the operational meaning of the whole exercise, so it is worth being precise about it.

• A temporary key is still a licence install. Nothing about the procedure above changes; the switch does not have a separate "trial mode". You install the key, the shell unlocks, and the key records an expiry date.
• The entitlement is time-bounded, not session-bounded. Once installed, the shell stays available for the lifetime encoded in the key, across CLI logouts and across reboots, until the expiry date passes.
• At expiry, shell access disappears again. The next _shell returns to the missing-licence error. Nothing else on the switch degrades — forwarding, routing, management and monitoring are all untouched, because the Restricted Commands entitlement governs only the engineering commands.
• Check the remaining time before you schedule work. show license prints the entry name, the switch serial or platform it is bound to, and the expiry date where one exists. If you are planning a maintenance window the following week, verify the expiry date is beyond it.
• A temporary key is bound to a chassis. It will not unlock a second switch, even an identical model, and it cannot be re-installed somewhere else after it expires.

What to do when you cannot get a licence at all

If the chassis is end-of-life, out of support, or a lab unit without an entitlement, do not spend the day hunting for a key that will not install. Consider these instead:

• Ask whether the task has a supported equivalent. A large share of "I need shell access" cases on Onyx are really about reading counters or running diagnostics that the CLI exposes. The command filters and log tooling covered in MLNX-OS CLI Troubleshooting: Filters, watch and Log Commands answer most of them without leaving the configuration model.
• Check whether secure mode is the real blocker. On a secure-mode switch, an installed entitlement may still not open a shell. Confirm with show system secure-mode before concluding that the key is wrong.
• Get the key through the normal entitlement path. Restricted Commands keys are issued against a support contract or a feature entitlement record tied to the serial number; the same key covers every switch in the same generation that has the entitlement.
• Reinstall instead of hacking. If the goal is recovery rather than diagnosis — a lost BIOS password, a switch that will not boot — a clean ONIE and Onyx reinstall is often faster and always cleaner than a shell workaround. The full flow is in ONIE and ONYX (MLNX-OS) Install Guide for Mellanox Switches.

Troubleshooting

• _shell still refused after installing the key. Leave configuration mode first — the CLI caches the licence table per mode in some releases. If it still fails, reload the switch; the licence store is re-read at boot.
• Invalid license key. The key is truncated, belongs to a different generation, or was copied with a trailing space. Re-copy it directly from the entitlement record.
• Licence listed but expired. Temporary authorisations expire silently. Request a fresh key; there is no grace period.
• Shell opens and closes immediately. A policy or profile script is failing. Check /var/log/ inside the shell before it exits, or run a single command non-interactively.
• Shell works, commands are missing. Onyx images are deliberately stripped. BusyBox applets such as awk, grep and vi are usually present; full packages are not, and installing extra software is unsupported.
• Licence vanished after a firmware upgrade. Some upgrade paths rewrite the licence store. Confirm with show license after every major upgrade and reinstall the key if needed.

Security notes worth keeping in mind

Restricted Commands access is a privileged capability, and treating it as ordinary configuration work is how switches end up in an unsupported state. Log every session: the CLI records licence installs and shell entries in the system log, and those entries are the audit trail that matters during an incident review. Never run an unknown script from a forum or a paste bin inside the shell — it runs as the appliance's own user, with write access to the running configuration and the boot slots. If a support engineer asks for shell output, pipe it to a file and pull the file off with SCP rather than pasting screenfuls of output into a ticket. And if the switch is in production, close the shell session when you are done; an idle shell holds doors open that the configuration CLI would have closed.

Verification checklist

• show license lists a Restricted Commands entry with no expiry, or with an expiry date beyond your change window.
• show system secure-mode reports the state you expect for the platform.
• _shell from enable mode produces a Linux prompt, and uname -a answers.
• The maintenance script's output is saved, and the configuration is written if it changed.
• The shell session is closed and the CLI prompt is back.

FAQ

Does installing a Restricted Commands licence void support? No. The shell is a documented, licensable capability. Running unsupported scripts inside it is what puts you outside the supported configuration, not the shell itself.

Can I uninstall the licence afterwards? Yes. From configuration mode, no license <key> or the platform's license delete form removes it, after which _shell is gated again.

Why does the same key work on one switch and not another? Because the string embeds a platform/generation segment and a checksum. Two GEN2 switches with the same entitlement can share a key; a GEN1 chassis cannot use it.

Is there a password I can type instead? No. There is no hidden password path — the gate is the licence store, not authentication.

Related reading

If you are new to the platform, start with Mellanox Switch Getting Started: First-Time Setup and CLI Basics and Mellanox Switch CLI: Getting Started with MLNX-OS Commands, which cover the mode hierarchy that this procedure relies on. For saving and reloading configurations around a licence change, see MLNX-OS Configuration Management: Save, Load, Reset. And for the Cisco equivalent of a licence-gated privileged mode, compare with Catalyst 9000 Smart Licensing Troubleshooting: SLP and CSSM.