commit 8a89202652d254bba81e5e269ff7393ac2d14736 from: Stefan Sperling date: Thu Jun 01 14:26:25 2023 UTC man page updates related to the new -e re-exec feature commit - 61379117dee1f6aa36603745f79e8a22d7f4d05a commit + 8a89202652d254bba81e5e269ff7393ac2d14736 blob - fcd7351b4d9b6e7f21569b2009b9043e99855069 blob + 26c6742dbae39cc0620e52b13304a5944146cd70 --- nsh.8 +++ nsh.8 @@ -32,7 +32,7 @@ .Nd network configuration shell .Sh SYNOPSIS .Nm nsh -.Op Fl v +.Op Fl ev .Op Fl i Ar rcfile .Op Fl c Ar config-script-file .Sh DESCRIPTION @@ -103,19 +103,27 @@ is run without arguments it loads an interactive shell The options are as follows: .Bl -tag -width Ds .It Fl v -.Nm -produce verbose output +Produce verbose output .It Fl c Ar config-script-file -.Nm -execute the command(s) in the +Execute the command(s) in the .Ar config-script-file . This is typically used to implement scripted changes to configuration. .It Fl i Ar rcfile -load the initial system configuration from the command(s) in the +Load the initial system configuration from the command(s) in the .Ar rcfile . This is typically used to clear the configuration and load a full .Nm configuration script from rcfile . +.It Fl e +Start +.Nm +in a privileged mode session. +This option is not intended to be used directly. +It is used internally by +.Nm +while restarting itself with root privileges when a non-root user runs the +.Cm enable +command. .El .Ss INTERACTIVE FEATURES When run without any command line arguments, @@ -4400,104 +4408,114 @@ see the following man pages for information .Pp !man pfctl !man pf.conf -.Sh Section 7 Adding system users to +.Sh Section 7 Allowing users to run NSH +Users can either start .Nm -on -.Ox -.Pp -.Ox -has facilities for a user to be able to login directly to +from another shell or be logged into an +.Nm +session directly if the user account's login shell is set to .Nm -without having access to a typical bourne or C shell. -Using doas (a tool similar to sudo in other POSIX systems) -one can setup doas to allow the user to launch -.Nm -as root. -there are 3 options for doing this. +as follows: +.Bd -literal -offset indent +usermod -s /usr/local/bin/nsh nshuser +.Ed .Pp -Option1 - least restrictive interactive and non-interactive +(replace 'nshuser' with the actual user name) +.Pp +If a user has knowlege of the root password they can use the nsh +.Cm enable +command to enter .Nm +privileged mode with root privileges. .Pp +If the user should not know the root password then +.Xr doas 1 +can be used to allow the user to either use the nsh +.Cm enable +command to obtain root privileges within nsh, or to launch +.Nm +as root. +.Pp To allow a user to run .Nm -interactively or non interactively -as root when logged in or logging in. -Configuring /etc/doas.conf with the line starting with 'permit' -to allow the full path to the +as root and with arbitrary arguments, configure +.Pa /etc/doas.conf +with a line starting with 'permit' to allow the full path to the .Nm -binary without any other -restrictions. -e.g. Configure the user 'stacy' so they can run -.Bd -literal -/usr/local/bin/nsh as root -or -/usr/local/bin/nsh -c /some/path/to/scriptedconfig.nshrc +binary without any other restrictions. +For example, the following allows user 'stacy' to run +.Nm +as root via +.Xr doas 1 +with arbitrary arguments: .Ed .Bd -literal -offset indent -permit nopass stacy as root cmd /usr/local/bin/nsh +permit keepenv stacy as root cmd /usr/local/bin/nsh .Ed .Pp -Option2 - allow interactive +The user stacy can now start .Nm -use only. +as follows: .Pp -Configuring /etc/doas.conf with the line starting with 'permit' -to allow the full path to the nsh binary and specify empty args -to enforce nsh be run without any arguments. .Bd -literal -offset indent -permit nopass stacy as root cmd /usr/local/bin/nsh args +doas /usr/local/bin/nsh .Ed .Pp -Option3 - allow non-interactive +If nsh arguments in +.Pa /etc/doas.conf +are restricted to the +.Fl e +option then users can use the +.Cm enable +command from within nsh to enter privileged mode. .Nm -use only. -.Pp -To allow a restricted user run a specifc configuration script only. -Configuring /etc/doas.conf with the line starting with 'permit' -to allow the full path to the +will try to run +.Xr doas 1 +automatically to obtain root privileges when privileged mode is entered, +and with a line such as the following in +.Pa /etc/doas.conf +this will succeed: +.Bd -literal -offset indent +permit keepenv stacy as root cmd /usr/local/bin/nsh args -e +.Ed +.Pp +To allow a restricted user to run a specifc .Nm -binary and specify args -to enforce nsh be run only with those specific arguments. -E.g.to allow a backupuser pull the running config only. +script only, configure /etc/doas.conf to require specific arguments to nsh +that involve the +.Fl c +option. +The following example allows a backupuser to display the running-config: .Bd -literal -offset indent -permit nopass backupuser as root cmd /usr/local/bin/nsh args -c /home/backupuser/showrunconfig.nshrc +permit nopass backupuser as root cmd /usr/local/bin/nsh args -c /etc/showrunconfig.nshrc .Ed .Pp -The /home/backup/showrunconfig.nshrc would look like this +Where the file +.Pa /etc/showrunconfig.nshrc +would not be writable by the backupuser account and would look like this: .Bd -literal -offset indent enable -show run +show running-config quit .Ed .Pp A more standards RBAC based approach would be to create a group -on the system for users with the role of manging the system via nsh. -Then simply allow all users that are members of a group to run +.Dq nshusers +on the system for users with the role of managing the system via nsh. +Then allow users that are members of a group to run .Nm -using /etc/doas.conf and referring to the groupname rather than just -a single username. +using /etc/doas.conf by referring to the groupname rather than just +a single username (the colon before the group name is required by +.Xr doas.conf 5 +syntax and signifies a group name argument): .Pp -Compile nwrapper (in the -.Nm -distribution): .Bd -literal -offset indent -cc -o nwrapper nwrapper.c -.Ed -Move nwrapper to a permanent location: -.Bd -literal -offset indent -mv nwrapper /usr/local/bin/nwrapper +permit keepenv :nshusers as root cmd /usr/local/bin/nsh args -e .Ed -Change the user's shell to nwrapper: -.Bd -literal -offset indent -usermod -s /usr/local/bin/nwrapper nshuser -.Ed -(replace 'nshuser' with the actual user name) .Pp *NB Security Warning!!! .Pp -The doas configurations outlined here are not -security measures. -They allow an administrator to grant a non root +The doas configurations outlined here grant a non-root user the ability to run .Nm with all the privileges of the @@ -4505,30 +4523,15 @@ with all the privileges of the root user. The design of .Ox -requires root privileges to change many aspects of the systems network stack. -The nwrwapper binary is a binary that hardcodes the doas request to launch +requires root privileges to administor the network stack. +A user can abuse .Nm -on -.Ox -as root. +running as root to run arbitrary commands with the +.Cm ! +shell escape syntax. +Therefore, access to running .Nm -currently does not have security countermeasure -features against malicious users. -It is therefore essential that the administrator only -grants -.Nm -user access with the same security considerations -of granting a user root access to the system. -I.e. the user can use -.Nm -running as root (facilitated by doas and nwrapper) -to carry out other shell scripts either interactively or -in a nshrc configuration file. -It gives a user the ability to configure basic system -parameters and to run editors and other commands as root. -Therefore access to -.Nm -must be restricted to trusted users only. +with root privleges must be restricted to trusted users only. .Sh Common interface types Packet Filter Logging: This interface is used to pass traffic logged by the firewall to software which can record it.