===============================================================================
Versa FlexVNF — Shell Lockout with 2FA Feature Documentation
===============================================================================
OVERVIEW
--------
The Shell Lockout feature restricts direct Linux shell (bash) access on Versa FlexVNF appliances by protecting it with Time-based One-Time Password (TOTP) two-factor authentication. When enabled, all users are placed into the Versa CLI by default, and shell access requires a one-time password generated by Versa support.
This feature is available in VOS 22.1.4 and later releases.
ENABLING SHELL LOCKOUT
----------------------
Only the "admin" user can enable or disable this feature.
Command:
request system shell lockout secret <secret> [shell-timeout <seconds>]
[bypass-console <enable|disable>] [bypass-user <username>]
Parameters:
secret (Required) A unique secret key for this device. This same secret is required later to disable the lockout. Maximum 63 characters. Spaces and '#' are not allowed.
shell-timeout (Optional) Absolute timeout in seconds after which the shell session is automatically terminated. This is NOT an idle/inactivity timer — the session ends after this duration regardless of activity. Default: 60 seconds.
bypass-console (Optional) When set to "enable", users logging in via the physical console bypass the 2FA prompt and get direct shell access. Default: enabled.
bypass-user (Optional) A specific username that is allowed to access the shell without 2FA authentication. This is useful for designated maintenance accounts or external AAA (e.g., TACACS+) users who need direct shell access. Username must be 2-32 characters. [Only available from 22.1.4 Feb 2026 hotfix release]
Example:
admin@Device-cli> request system shell lockout secret MyS3cretKey shell-timeout 120 bypass-console enable bypass-user flexadmin
Once enabled:
- All user login shells are changed from bash to Versa CLI.
- Accessing the shell via the "shell" command from CLI requires a TOTP code.
- The bypass-user (if configured) can access the shell without 2FA.
- Console users skip 2FA if bypass-console is enabled.
ACCESSING THE SHELL (WITH 2FA)
------------------------------
When a user types "shell" from the CLI, the following prompt is displayed:
Local Time: Tue Dec 21 16:03:40 2021 (IST)
UTC Time: Tue Dec 21 10:33:40 2021 UTC
Versa Device: MNQTKMDFGA2WKLJVMU4DCLJRGFSWGLJZGYZTALJVGI2TIMBQ...
Enter OTP:
The "Versa Device" key is a base32-encoded identifier derived from the appliance serial number and the configured secret. To obtain the OTP:
1. Provide the "Versa Device" key to Versa Networks TAC.
2. The Versa TAC Engineer runs the OTP generator tool on a time-synchronized machine using the device key.
3. The generated OTP is valid for approximately 90 seconds (current 30-second window plus adjacent windows).
4. Enter the OTP at the prompt to gain shell access.
The shell session will be automatically ended after the configured shell-timeout duration.
DISABLING SHELL LOCKOUT
-----------------------
To restore normal shell access for all users:
admin@Device-cli> request system shell enable secret <secret>
The secret must match the one provided when lockout was enabled. On success, all user shells are restored to bash.
EXTERNAL AAA (TACACS+/RADIUS) INTEGRATION
------------------------------------------
When shell lockout is enabled with a bypass-user configured:
- If the bypass-user authenticates via an external AAA server (e.g., TACACS+) and has the Versa_Admin_Login=shell AVP attribute set, the user lands directly on the bash shell without 2FA.
- Other external AAA users without bypass privileges land on the CLI and must use the standard 2FA flow to access the shell.
IMPORTANT NOTES
---------------
- Only the "admin" user can enable or disable shell lockout.
- The secret is stored in encrypted form on the device.
- The shell-timeout is an absolute timer, not an inactivity timer. Plan maintenance tasks accordingly.
- Time synchronization (NTP) between the VOS device and the OTP generator machine is critical for successful OTP validation.
- The bypass-console setting is intended for emergency physical access scenarios. Disable it in high-security environments.
- This feature persists across device reboots.
- Recommended to have console access bypassed to have out-of-band access for servicing/maintenance.
==============================================================================