mirror of
https://github.com/apache/nuttx.git
synced 2026-08-01 20:28:58 +00:00
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.
This commit is contained in:
Abhishek Mishra
Alan C. Assis
parent
6cda50bf81
commit
8e843b22e6
2 changed files with 196 additions and 0 deletions
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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::
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue