From 8e843b22e628ccbd0a0d12cae72030caafa3ff4b Mon Sep 17 00:00:00 2001 From: Abhishek Mishra Date: Wed, 17 Jun 2026 17:15:19 +0000 Subject: [PATCH] docs/nsh: document id, su, whoami, and privilege prompt markers Document NSH identity commands and how login/su update the prompt (# for effective root, $ for non-root). Cover flat-build euid semantics, related Kconfig options, and session identity behavior after login. --- Documentation/applications/nsh/commands.rst | 144 ++++++++++++++++++++ Documentation/applications/nsh/login.rst | 52 +++++++ 2 files changed, 196 insertions(+) diff --git a/Documentation/applications/nsh/commands.rst b/Documentation/applications/nsh/commands.rst index bc6abcafc23..e21c6e80044 100644 --- a/Documentation/applications/nsh/commands.rst +++ b/Documentation/applications/nsh/commands.rst @@ -740,6 +740,50 @@ supported: ifup eth0 +.. _cmdid: + +``id`` Show User and Group Identity +=================================== + +**Command Syntax**:: + + id + +**Synopsis**. Print the real and effective user and group IDs for the +current NSH session in the form:: + + uid= euid= gid= egid= + +File permission checks use the effective UID and GID. + +On flat builds where NSH retains a real UID of zero, ``id`` may report +``uid=0`` even when the session is running as a non-root user. The +``euid`` and ``egid`` fields reflect the active session identity, and +the prompt marker (``#`` or ``$``) follows ``euid``. + +This command is available only when ``CONFIG_SCHED_USER_IDENTITY`` is +enabled. It may be disabled with ``CONFIG_NSH_DISABLE_ID``. + +**Related configuration** + +=============================== ======================================= +Option Purpose +=============================== ======================================= +``CONFIG_SCHED_USER_IDENTITY`` Enable UID/GID tracking +``CONFIG_NSH_LOGIN_SETUID`` Set identity after login +``CONFIG_LIBC_PASSWD_FILE`` User database for name lookup +=============================== ======================================= + +**Example**:: + + nsh> su testuser + nsh$ id + uid=0 euid=1000 gid=0 egid=1000 + nsh$ su root + Password: + nsh# id + uid=0 euid=0 gid=0 egid=0 + .. _cmdinsmod: ``insmod`` Install an OS module @@ -1663,6 +1707,75 @@ NOTE: The ``shutdown`` command duplicates the behavior of the **Synopsis**. Pause execution (sleep) for ```` seconds. +.. _cmdsu: + +``su`` Switch User Identity +=========================== + +**Command Syntax**:: + + su [] + +**Synopsis**. Switch the NSH session to the credentials of ````. +If no user name is provided, ``su`` defaults to ``root``. + +Users with root privileges (effective UID or GID of zero) may switch to +any user without a password. Other users may switch to their own +identity without a password, or to another user after entering that +user's password (when login support is enabled). + +When the real UID is still zero, NSH changes only the effective UID and +GID so that a later ``su root`` can restore root privileges after +password verification. + +**Prompt update.** After a successful ``su``, NSH calls +``nsh_update_prompt()`` and changes the privilege marker in the prompt: + +=================== ================================================ +Marker Session +=================== ================================================ +``#`` Effective UID is zero (root) +``$`` Effective UID is non-zero (non-root) +=================== ================================================ + +For the default prompt ``nsh>``, the marker replaces the character +before ``>`` (for example ``nsh$`` or ``nsh#``). + +This command is available only when ``CONFIG_SCHED_USER_IDENTITY`` is +enabled. It may be disabled with ``CONFIG_NSH_DISABLE_SU``. User names +are looked up from the passwd database when ``CONFIG_LIBC_PASSWD_FILE`` +is enabled. Password verification requires one of the NSH login options +(``CONFIG_NSH_LOGIN_PASSWD``, ``CONFIG_NSH_LOGIN_PLATFORM``, or +``CONFIG_NSH_LOGIN_FIXED``). + +**Related configuration** + +=============================== ======================================= +Option Purpose +=============================== ======================================= +``CONFIG_SCHED_USER_IDENTITY`` Enable UID/GID identity commands +``CONFIG_LIBC_PASSWD_FILE`` Resolve user names from ``/etc/passwd`` +``CONFIG_NSH_LOGIN_SETUID`` Apply identity after login +``CONFIG_NSH_DISABLE_SU`` Disable the ``su`` command +=============================== ======================================= + +**Example**:: + + nsh> su testuser + nsh$ whoami + testuser + nsh$ su newuser + Password: + nsh$ whoami + newuser + nsh$ su root + Password: + nsh# whoami + root + nsh# su testuser + nsh$ whoami + testuser + .. _cmdtelnetd: ``telnetd`` Time Start the Telnet Daemon @@ -1933,6 +2046,37 @@ directory. unless is provided. =================== ================================================= +.. _cmdwhoami: + +``whoami`` Show Effective User Name +=================================== + +**Command Syntax**:: + + whoami + +**Synopsis**. Print the user name associated with the effective UID of +the current NSH session. If the name cannot be resolved from the passwd +database, ``whoami`` prints ``root`` when the effective UID is zero, or +the numeric UID otherwise. + +The result should match the privilege marker shown in the NSH prompt +(``#`` for root, ``$`` for non-root) when +``CONFIG_SCHED_USER_IDENTITY`` is enabled. + +This command is available only when ``CONFIG_SCHED_USER_IDENTITY`` is +enabled. It may be disabled with ``CONFIG_NSH_DISABLE_WHOAMI``. + +**Example**:: + + nsh> su testuser + nsh$ whoami + testuser + nsh$ su root + Password: + nsh# whoami + root + .. _cmdxd: ``xd`` Hexadecimal Dump of Memory diff --git a/Documentation/applications/nsh/login.rst b/Documentation/applications/nsh/login.rst index d433b874855..b499a0ff4b4 100644 --- a/Documentation/applications/nsh/login.rst +++ b/Documentation/applications/nsh/login.rst @@ -25,6 +25,58 @@ login, the user will have access to the NSH session:: NuttShell (NSH) nsh> +When ``CONFIG_NSH_LOGIN_SETUID`` is enabled (the default when +``CONFIG_SCHED_USER_IDENTITY`` is selected), NSH looks up the +authenticated user name in the passwd database and sets the session +identity after a successful login. See also ```id`` <#cmdid>`__, +```su`` <#cmdsu>`__, and ```whoami`` <#cmdwhoami>`__. + +Session Identity and Prompt +=========================== + +When ``CONFIG_SCHED_USER_IDENTITY`` is enabled, NSH tracks the calling +task's real and effective UID/GID for the shell session. File +permission checks use the **effective** identity. + +**Prompt markers.** After login or a successful ``su``, NSH updates the +command prompt to show the effective privilege level of the session: + +=================== ================================================ +Prompt marker Meaning +=================== ================================================ +``#`` Effective UID is zero (root session) +``$`` Effective UID is non-zero (non-root session) +=================== ================================================ + +The marker replaces the character before the closing ``>`` in the +default prompt (for example, ``nsh>`` becomes ``nsh#`` or ``nsh$``), or +is appended when the configured prompt does not end with ``>``. The +prompt is refreshed by ``nsh_update_prompt()`` after ``su`` and after +login when ``CONFIG_NSH_LOGIN_SETUID`` is enabled. + +**Flat builds.** NSH may retain a real UID of zero while only the +effective UID/GID are changed. In that case ``id`` can report +``uid=0 euid=1000`` after logging in as a normal user. Permission +checks and the prompt marker follow the effective identity. + +**Example**:: + + login: testuser + password: + User Logged-in! + + NuttShell (NSH) + nsh$ id + uid=0 euid=1000 gid=0 egid=1000 + nsh$ whoami + testuser + nsh$ su root + Password: + nsh# id + uid=0 euid=0 gid=0 egid=0 + nsh# whoami + root + After each failed login attempt, a delay can be set up. The purpose of this delay is to discourage attempts to crack the password by brute force. That delay is configured with::