This is an automated email from the ASF dual-hosted git repository.
acassis pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/nuttx.git
The following commit(s) were added to refs/heads/master by this push:
new 8e843b22e62 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.
8e843b22e62 is described below
commit 8e843b22e628ccbd0a0d12cae72030caafa3ff4b
Author: Abhishek Mishra <[email protected]>
AuthorDate: Wed Jun 17 17:15:19 2026 +0000
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=<uid> euid=<euid> gid=<gid> egid=<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 ``<sec>`` seconds.
+.. _cmdsu:
+
+``su`` Switch User Identity
+===========================
+
+**Command Syntax**::
+
+ su [<username>]
+
+**Synopsis**. Switch the NSH session to the credentials of ``<username>``.
+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 <local-path> 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::
