From 9f5615e5b10ff58cd8ceac6f16f6c8c0c7303add Mon Sep 17 00:00:00 2001 From: "Todd C. Miller" Date: Wed, 16 Feb 2022 16:38:44 -0700 Subject: [PATCH] Avoid using "note that" and "note: " in documentation. --- INSTALL.md | 52 ++++++++++---------- README.LDAP.md | 15 +++--- docs/TROUBLESHOOTING.md | 11 ++--- docs/UPGRADE.md | 17 ++++--- docs/sudo.conf.man.in | 4 +- docs/sudo.conf.mdoc.in | 4 +- docs/sudo.man.in | 25 +++++----- docs/sudo.mdoc.in | 25 +++++----- docs/sudo_logsrv.proto.man.in | 6 +-- docs/sudo_logsrv.proto.mdoc.in | 6 +-- docs/sudo_logsrvd.conf.man.in | 20 ++++---- docs/sudo_logsrvd.conf.mdoc.in | 20 ++++---- docs/sudo_plugin.man.in | 55 +++++++++++---------- docs/sudo_plugin.mdoc.in | 55 +++++++++++---------- docs/sudo_plugin_python.man.in | 4 +- docs/sudo_plugin_python.mdoc.in | 4 +- docs/sudoers.ldap.man.in | 33 +++++++------ docs/sudoers.ldap.mdoc.in | 33 +++++++------ docs/sudoers.man.in | 85 ++++++++++++++++----------------- docs/sudoers.mdoc.in | 85 ++++++++++++++++----------------- docs/sudoreplay.man.in | 18 +++---- docs/sudoreplay.mdoc.in | 18 +++---- docs/visudo.man.in | 8 ++-- docs/visudo.mdoc.in | 8 ++-- examples/sudo_logsrvd.conf.in | 12 ++--- 25 files changed, 295 insertions(+), 328 deletions(-) diff --git a/INSTALL.md b/INSTALL.md index d707c33d4..c17c68fbe 100644 --- a/INSTALL.md +++ b/INSTALL.md @@ -49,11 +49,11 @@ for a list of packages required to build sudo. you may file a bug report at https://bugzilla.sudo.ws/ or an issue at https://github.com/sudo-project/sudo/issues/ (not both). -5. Type `make install` (as root) to install sudo, visudo, the - man pages, and a skeleton sudoers file. Note that the install - will not overwrite an existing sudoers file. You can also - install various pieces the package via the install-binaries, - install-doc, and install-sudoers make targets. +5. Type `make install` (as root) to install sudo, visudo, the man + pages, and a skeleton sudoers file. The install will not overwrite + an existing sudoers file. You can also install various pieces of + the package via the install-binaries, install-doc, and install-sudoers + make targets. 6. Edit the sudoers file with `visudo` as necessary for your site. You will probably want to refer the example sudoers @@ -349,7 +349,7 @@ Defaults are listed in brackets after the description. Disable natural language support. By default, sudo will use the gettext() family of functions, if available, to implement messages in the invoking user's native language. - Note that translations do not exist for all languages. + Translations do not exist for all languages. --with-ldap[=DIR] Enable LDAP support. If specified, DIR is the base directory @@ -524,9 +524,9 @@ Defaults are listed in brackets after the description. for BSD/OS and OpenBSD systems that support it. It is not possible to mix BSD authentication with other authentication methods (and there really should be no need - to do so). Note that only the newer BSD authentication API - is supported. If you don't have /usr/include/bsd_auth.h - then you cannot use this. + to do so). Only the newer BSD authentication API is + supported. If you don't have /usr/include/bsd_auth.h then + you cannot use this. --with-DCE Enable DCE support for systems without PAM. Known to work on @@ -570,7 +570,7 @@ Defaults are listed in brackets after the description. Enable PAM support. This is on by default for Darwin, FreeBSD, Linux, NetBSD, Solaris, and HP-UX (version 11 and higher). - NOTE: on RedHat Linux and Fedora you **must** have an `/etc/pam.d/sudo` + On RedHat Linux and Fedora you **must** have an `/etc/pam.d/sudo` file installed. You may either use the example pam.conf file included with sudo or use `/etc/pam.d/su` as a reference. The pam.conf file included with sudo may or may not work with other Linux distributions. @@ -798,10 +798,10 @@ Defaults are listed in brackets after the description. file. Ie: instead of myhost you would use myhost.mydomain.edu. You may still use the short form if you wish (and even mix the two). Beware that turning FQDN on requires sudo to make DNS lookups which may make - sudo unusable if your DNS is totally hosed. Also note that you must - use the host's official name as DNS knows it. That is, you may not use - a host alias (CNAME entry) due to performance issues and the fact that - there is no way to get all aliases from DNS. + sudo unusable if your DNS is totally hosed. You must use the host's + official name as DNS knows it. That is, you may not use a host alias + (CNAME entry) due to performance issues and the fact that there is no + way to get all aliases from DNS. Sudoers option: fqdn --with-goodpri=PRIORITY @@ -940,7 +940,7 @@ Defaults are listed in brackets after the description. users to have a reasonable PATH environment variable you may want to use this. Another use is if you want to have the "root path" be separate from the "user path." You will need to customize the - path for your site. NOTE: this is not applied to users in the group + path for your site. This is not applied to users in the group specified by --with-exemptgroup. If you do not specify a path, "/bin:/usr/ucb:/usr/bin:/usr/sbin:/sbin:/usr/etc:/etc" is used. Sudoers option: secure_path @@ -955,22 +955,20 @@ Defaults are listed in brackets after the description. Sudoers options: !mailerpath or !mailto --with-sudoers-mode=MODE - File mode for the sudoers file (octal). Note that if you - wish to NFS-mount the sudoers file this must be group - readable. This value may overridden at run-time in the - sudo.conf file. The default mode is 0440. + File mode for the sudoers file (octal). If you wish to + NFS-mount the sudoers file this must be group readable. + This value may overridden at run-time in the sudo.conf file. + The default mode is 0440. --with-sudoers-uid=UID - User id that "owns" the sudoers file. Note that this is - the numeric id, **not** the symbolic name. This value may - overridden at run-time in the sudo.conf file. The default - is 0. + User id that "owns" the sudoers file. This is the numeric + id, **not** the symbolic name. This value may overridden + at run-time in the sudo.conf file. The default is 0. --with-sudoers-gid=GID - Group id that "owns" the sudoers file. Note that this is - the numeric id, **not** the symbolic name. This value may - overridden at run-time in the sudo.conf file. The default - is 0. + Group id that "owns" the sudoers file. This is the numeric + id, **not** the symbolic name. This value may overridden + at run-time in the sudo.conf file. The default is 0. --with-timeout=NUMBER Number of minutes that can elapse before sudo will ask for a passwd diff --git a/README.LDAP.md b/README.LDAP.md index 1e511b076..7d3e97f6a 100644 --- a/README.LDAP.md +++ b/README.LDAP.md @@ -191,13 +191,14 @@ for a list of supported ldap.conf parameters and an example ldap.conf Make sure you sudoers_base matches the location you specified when you imported the sudoers ldif data. -After configuring /etc/ldap.conf, you must add a line in /etc/nsswitch.conf -to tell sudo to look in LDAP for sudoers. See the "Configuring nsswitch.conf" -section in the sudoers.ldap manual for details. Note that sudo will use -/etc/nsswitch.conf even if the underlying operating system does not support it. -To disable nsswitch support, run configure with the `--with-nsswitch=no` option. -This will cause sudo to consult LDAP first and /etc/sudoers second, unless the -ignore_sudoers_file flag is set in the global LDAP options. +After configuring /etc/ldap.conf, you must add a line in the +/etc/nsswitch.conf file to tell sudo to look in LDAP for sudoers. +See the "Configuring nsswitch.conf" section in the sudoers.ldap +manual for details. Sudo will use /etc/nsswitch.conf even if the +underlying operating system does not support it. To disable nsswitch +support, run configure with the `--with-nsswitch=no` option. This +will cause sudo to consult LDAP first and /etc/sudoers second, +unless the ignore_sudoers_file flag is set in the global LDAP options. ## Debugging your LDAP configuration diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index acc863d92..8b3e30483 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -91,7 +91,7 @@ It just says "Sorry, try again." three times and exits. > log files, you need to create the file before syslogd will log > to it (e.g.: touch /var/log/sudo). -> Note: the facility (e.g. 'auth.debug') must be separated from +> The facility (e.g. 'auth.debug') must be separated from > the destination (e.g. '/var/log/auth' or '@loghost') by tabs, > *not* spaces. This is a common error. @@ -104,8 +104,8 @@ It just says "Sorry, try again." three times and exits. > look ups was detected. For instance, for SVR4-style shadow > passwords, `HAVE_GETSPNAM` should be defined (you can search for > the string 'shadow passwords' in config.h with your editor). -> Note that there is no define for 4.4BSD-based shadow passwords -> since that just uses the standard getpw* routines. +> There is no define needed for 4.4BSD-based shadow passwords +> which just use the standard getpw* routines. #### Can sudo use the ssh agent instead of asking for the user's password? @@ -203,9 +203,8 @@ It just says "Sorry, try again." three times and exits. > config.cache to make re-running configure speedy. However, > if you are building sudo for a different platform the results > in config.cache will be wrong so you need to remove the config.cache file. -> You can do this via `rm config.cache` or `make realclean`. -> Note that `make realclean` will also remove any object files -> and configure temp files that are laying around as well. +> You can do this via `rm config.cache`, or `make realclean` to also +> remove any object files and configure temp files that are present. #### When I run 'visudo' it says "sudoers file busy, try again later." diff --git a/docs/UPGRADE.md b/docs/UPGRADE.md index a39097daa..d61eea551 100644 --- a/docs/UPGRADE.md +++ b/docs/UPGRADE.md @@ -130,9 +130,9 @@ Notes on upgrading from an older release cvtsudoers -f json -o output_file sudoers_file - Note that unlike "visudo -x", "cvtsudoers" reads from the - standard input by default. Also, the base DN may be specified - on the command line, if desired, using the -b option. + Unlike "visudo -x", "cvtsudoers" reads from the standard input + by default. Also, the base DN may be specified on the command + line, if desired, using the -b option. * Upgrading from a version prior to 1.8.20: @@ -429,9 +429,9 @@ Notes on upgrading from an older release to preserve the old value of MAIL. - NOTE: preserving HOME has security implications since many programs - use it when searching for configuration files. Adding HOME to env_keep - may enable a user to run unrestricted commands via sudo. + Preserving HOME has security implications since many programs + use it when searching for configuration files. Adding HOME to + env_keep may enable a user to run unrestricted commands via sudo. The default syslog facility has changed from "local2" to "authpriv" (or "auth" if the operating system doesn't have "authpriv"). @@ -501,9 +501,8 @@ Notes on upgrading from an older release when env_reset was set (which is now on by default). Starting with sudo 1.6.9, environment variables listed in env_check are also preserved in the env_reset case, provided that they do not - contain a '/' or '%' character. Note that it is not necessary - to also list a variable in env_keep--having it in env_check is - sufficient. + contain a '/' or '%' character. It is not necessary to also + list a variable in env_keep--having it in env_check is sufficient. The default lists of variables to be preserved and/or checked are displayed when sudo is run by root with the -V flag. diff --git a/docs/sudo.conf.man.in b/docs/sudo.conf.man.in index 7e7059df0..c9758e99d 100644 --- a/docs/sudo.conf.man.in +++ b/docs/sudo.conf.man.in @@ -66,8 +66,8 @@ the line, are ignored. Long lines can be continued with a backslash (\(oq\e\(cq) as the last character on the line. -Note that leading white space is removed from the beginning of lines -even when the continuation character is used. +Leading white space is removed from the beginning of lines +even when a continuation character is used. .PP Non-comment lines that don't begin with \fRPlugin\fR, diff --git a/docs/sudo.conf.mdoc.in b/docs/sudo.conf.mdoc.in index 9453bc5b0..722fbd625 100644 --- a/docs/sudo.conf.mdoc.in +++ b/docs/sudo.conf.mdoc.in @@ -63,8 +63,8 @@ the line, are ignored. Long lines can be continued with a backslash .Pq Ql \e as the last character on the line. -Note that leading white space is removed from the beginning of lines -even when the continuation character is used. +Leading white space is removed from the beginning of lines +even when a continuation character is used. .Pp Non-comment lines that don't begin with .Li Plugin , diff --git a/docs/sudo.man.in b/docs/sudo.man.in index 8d636bb26..15a07c0ac 100644 --- a/docs/sudo.man.in +++ b/docs/sudo.man.in @@ -242,8 +242,8 @@ This option has no effect if an askpass program is used. .TP 12n \fB\-b\fR, \fB\--background\fR Run the given command in the background. -Note that it is not possible to use shell job control to manipulate -background processes started by +It is not possible to use shell job control to manipulate background +processes started by \fBsudo\fR. Most interactive commands will fail to work properly in background mode. @@ -375,7 +375,7 @@ not be edited unless that user is root (version 1.8.16 and higher). Users are never allowed to edit device special files. .sp If the specified file does not exist, it will be created. -Note that unlike most commands run by +Unlike most commands run by \fIsudo\fR, the editor is run with the invoking user's environment unmodified. If the temporary file becomes empty after editing, the user will @@ -433,7 +433,7 @@ Display a short help message to the standard output and exit. Run the command on the specified \fIhost\fR if the security policy plugin supports remote commands. -Note that the +The \fIsudoers\fR plugin does not currently support running remote commands. This may also be used in conjunction with the @@ -466,7 +466,7 @@ attempts to change to that user's home directory before running the shell. The command is run with an environment similar to the one a user would receive at log in. -Note that most shells behave differently when a command is specified +Most shells behave differently when a command is specified as compared to an interactive session; consult the shell's manual for details. The @@ -643,7 +643,7 @@ with a backslash except for alphanumerics, underscores, hyphens, and dollar signs. If no command is specified, an interactive shell is executed. -Note that most shells behave differently when a command is specified +Most shells behave differently when a command is specified as compared to an interactive session; consult the shell's manual for details. .if \n(SL \{\ @@ -888,7 +888,7 @@ command has an associated timeout, or the or \fIpam_setcred\fR options are enabled. -Note that +Both \fIpam_session\fR and \fIpam_setcred\fR @@ -1066,9 +1066,9 @@ that reside in a directory that is writable by the user. If the user can modify or replace the command there is no way to limit what additional commands they can run. .PP -Note that +By default, \fBsudo\fR -will normally only log the command it explicitly runs. +will only log the command it explicitly runs. If a user runs a command such as \fRsudo su\fR or @@ -1243,8 +1243,7 @@ is not set. \fBsudo\fR front-end configuration .SH "EXAMPLES" -Note: the following examples assume a properly configured security -policy. +The following examples assume a properly configured security policy. .PP To get a file listing of an unreadable directory: .nf @@ -1299,9 +1298,9 @@ $ sudo shutdown -r +15 "quick reboot" .fi .PP To make a usage listing of the directories in the /home partition. -Note that this runs the commands in a sub-shell to make the +The commands are run in a sub-shell to allow the \fRcd\fR -and file redirection work. +command and file redirection to work. .nf .sp .RS 4n diff --git a/docs/sudo.mdoc.in b/docs/sudo.mdoc.in index 40a55b738..3b1914aa2 100644 --- a/docs/sudo.mdoc.in +++ b/docs/sudo.mdoc.in @@ -238,8 +238,8 @@ Ring the bell as part of the password prompt when a terminal is present. This option has no effect if an askpass program is used. .It Fl b , -background Run the given command in the background. -Note that it is not possible to use shell job control to manipulate -background processes started by +It is not possible to use shell job control to manipulate background +processes started by .Nm . Most interactive commands will fail to work properly in background mode. @@ -358,7 +358,7 @@ not be edited unless that user is root (version 1.8.16 and higher). Users are never allowed to edit device special files. .Pp If the specified file does not exist, it will be created. -Note that unlike most commands run by +Unlike most commands run by .Em sudo , the editor is run with the invoking user's environment unmodified. If the temporary file becomes empty after editing, the user will @@ -411,7 +411,7 @@ Display a short help message to the standard output and exit. Run the command on the specified .Ar host if the security policy plugin supports remote commands. -Note that the +The .Em sudoers plugin does not currently support running remote commands. This may also be used in conjunction with the @@ -443,7 +443,7 @@ attempts to change to that user's home directory before running the shell. The command is run with an environment similar to the one a user would receive at log in. -Note that most shells behave differently when a command is specified +Most shells behave differently when a command is specified as compared to an interactive session; consult the shell's manual for details. The @@ -601,7 +601,7 @@ with a backslash except for alphanumerics, underscores, hyphens, and dollar signs. If no command is specified, an interactive shell is executed. -Note that most shells behave differently when a command is specified +Most shells behave differently when a command is specified as compared to an interactive session; consult the shell's manual for details. .if \n(SL \{\ @@ -829,7 +829,7 @@ command has an associated timeout, or the or .Em pam_setcred options are enabled. -Note that +Both .Em pam_session and .Em pam_setcred @@ -1007,9 +1007,9 @@ that reside in a directory that is writable by the user. If the user can modify or replace the command there is no way to limit what additional commands they can run. .Pp -Note that +By default, .Nm -will normally only log the command it explicitly runs. +will only log the command it explicitly runs. If a user runs a command such as .Li sudo su or @@ -1168,8 +1168,7 @@ is not set. front-end configuration .El .Sh EXAMPLES -Note: the following examples assume a properly configured security -policy. +The following examples assume a properly configured security policy. .Pp To get a file listing of an unreadable directory: .Bd -literal -offset 4n @@ -1206,9 +1205,9 @@ $ sudo shutdown -r +15 "quick reboot" .Ed .Pp To make a usage listing of the directories in the /home partition. -Note that this runs the commands in a sub-shell to make the +The commands are run in a sub-shell to allow the .Li cd -and file redirection work. +command and file redirection to work. .Bd -literal -offset 4n $ sudo sh -c "cd /home ; du -s * | sort -rn > USAGE" .Ed diff --git a/docs/sudo_logsrv.proto.man.in b/docs/sudo_logsrv.proto.man.in index 9d662e52c..5e0e1a91e 100644 --- a/docs/sudo_logsrv.proto.man.in +++ b/docs/sudo_logsrv.proto.man.in @@ -732,11 +732,9 @@ ttyname string the terminal the command was submitted from The server must accept other variables not listed above but may ignore them. .SH "EXAMPLES" -The Protocol Buffers description of the log server protocol is included -in full below. -Note that this uses the newer +The Protocol Buffers description of the log server protocol, using \(lqproto3\(rq -syntax. +syntax, is included in full below. .nf .sp .RS 0n diff --git a/docs/sudo_logsrv.proto.mdoc.in b/docs/sudo_logsrv.proto.mdoc.in index 9e64a8afb..af9239c29 100644 --- a/docs/sudo_logsrv.proto.mdoc.in +++ b/docs/sudo_logsrv.proto.mdoc.in @@ -652,11 +652,9 @@ entries are recognized, but not required: The server must accept other variables not listed above but may ignore them. .Sh EXAMPLES -The Protocol Buffers description of the log server protocol is included -in full below. -Note that this uses the newer +The Protocol Buffers description of the log server protocol, using .Dq proto3 -syntax. +syntax, is included in full below. .Bd -literal syntax = "proto3"; diff --git a/docs/sudo_logsrvd.conf.man.in b/docs/sudo_logsrvd.conf.man.in index 0c8be9070..84b5b03e8 100644 --- a/docs/sudo_logsrvd.conf.man.in +++ b/docs/sudo_logsrvd.conf.man.in @@ -46,7 +46,7 @@ are also ignored. Long lines can be continued with a backslash (\(oq\e\(cq) as the last character on the line. -Note that leading white space is removed from the beginning of lines +Leading white space is removed from the beginning of lines even when the continuation character is used. .PP The @@ -137,7 +137,7 @@ Supported values are or a path name beginning with the \(oq/\(cq character. -Note that a value of +A value of \fIstderr\fR is only effective when used in conjunction with the \fB\-n\fR @@ -512,9 +512,9 @@ iolog_file = path The path name, relative to \fIiolog_dir\fR, in which to store I/O logs. -Note that +It is possible for \fIiolog_file\fR -may contain directory components. +to contain directory components. The default value is \fR%{seq}\fR. .sp @@ -870,9 +870,8 @@ Sudo log server configuration file #tls_key = /etc/ssl/sudo/private/logsrvd_key.pem # TLS cipher list (see "CIPHER LIST FORMAT" in the openssl-ciphers manual). -# NOTE that this setting is only effective if the negotiated protocol -# is TLS version 1.2. -# The default cipher list is HIGH:!aNULL. +# This setting is only effective if the negotiated protocol is TLS version +# 1.2. The default cipher list is HIGH:!aNULL. #tls_ciphers_v12 = HIGH:!aNULL # TLS cipher list if the negotiated protocol is TLS version 1.3. @@ -942,9 +941,8 @@ Sudo log server configuration file #tls_key = /etc/ssl/sudo/private/logsrvd_key.pem # TLS cipher list (see "CIPHER LIST FORMAT" in the openssl-ciphers manual). -# NOTE that this setting is only effective if the negotiated protocol -# is TLS version 1.2. -# The default is to use the value in the [server] section. +# this setting is only effective if the negotiated protocol is TLS version +# 1.2. The default is to use the value in the [server] section. #tls_ciphers_v12 = HIGH:!aNULL # TLS cipher list if the negotiated protocol is TLS version 1.3. @@ -961,7 +959,7 @@ Sudo log server configuration file #iolog_dir = @iolog_dir@ # The path name, relative to iolog_dir, in which to store I/O logs. -# Note that iolog_file may contain directory components. +# It is possible for iolog_file to contain directory components. #iolog_file = %{seq} # If set, I/O logs will be compressed using zlib. Enabling compression can diff --git a/docs/sudo_logsrvd.conf.mdoc.in b/docs/sudo_logsrvd.conf.mdoc.in index 2c406b757..ba017e1a5 100644 --- a/docs/sudo_logsrvd.conf.mdoc.in +++ b/docs/sudo_logsrvd.conf.mdoc.in @@ -45,7 +45,7 @@ are also ignored. Long lines can be continued with a backslash .Pq Ql \e as the last character on the line. -Note that leading white space is removed from the beginning of lines +Leading white space is removed from the beginning of lines even when the continuation character is used. .Pp The @@ -123,7 +123,7 @@ Supported values are or a path name beginning with the .Ql / character. -Note that a value of +A value of .Em stderr is only effective when used in conjunction with the .Fl n @@ -449,9 +449,9 @@ should be used. The path name, relative to .Em iolog_dir , in which to store I/O logs. -Note that +It is possible for .Em iolog_file -may contain directory components. +to contain directory components. The default value is .Li %{seq} . .Pp @@ -796,9 +796,8 @@ Sudo log server configuration file #tls_key = /etc/ssl/sudo/private/logsrvd_key.pem # TLS cipher list (see "CIPHER LIST FORMAT" in the openssl-ciphers manual). -# NOTE that this setting is only effective if the negotiated protocol -# is TLS version 1.2. -# The default cipher list is HIGH:!aNULL. +# This setting is only effective if the negotiated protocol is TLS version +# 1.2. The default cipher list is HIGH:!aNULL. #tls_ciphers_v12 = HIGH:!aNULL # TLS cipher list if the negotiated protocol is TLS version 1.3. @@ -868,9 +867,8 @@ Sudo log server configuration file #tls_key = /etc/ssl/sudo/private/logsrvd_key.pem # TLS cipher list (see "CIPHER LIST FORMAT" in the openssl-ciphers manual). -# NOTE that this setting is only effective if the negotiated protocol -# is TLS version 1.2. -# The default is to use the value in the [server] section. +# this setting is only effective if the negotiated protocol is TLS version +# 1.2. The default is to use the value in the [server] section. #tls_ciphers_v12 = HIGH:!aNULL # TLS cipher list if the negotiated protocol is TLS version 1.3. @@ -887,7 +885,7 @@ Sudo log server configuration file #iolog_dir = @iolog_dir@ # The path name, relative to iolog_dir, in which to store I/O logs. -# Note that iolog_file may contain directory components. +# It is possible for iolog_file to contain directory components. #iolog_file = %{seq} # If set, I/O logs will be compressed using zlib. Enabling compression can diff --git a/docs/sudo_plugin.man.in b/docs/sudo_plugin.man.in index 90856acb2..8fee422f8 100644 --- a/docs/sudo_plugin.man.in +++ b/docs/sudo_plugin.man.in @@ -688,7 +688,7 @@ will be the \fRNULL\fR pointer. .sp -NOTE: the +The \fIplugin_options\fR parameter is only available starting with API version 1.2. @@ -716,7 +716,7 @@ must remain valid until the plugin's \fBclose\fR() function is called. .sp -NOTE: the +The \fIerrstr\fR parameter is only available starting with API version 1.15. @@ -874,8 +874,7 @@ in the user's environment, such as \fREDITOR\fR, and include it in \fIargv_out\fR -(note that environment -variables may include command line options). +(environment variables may include command line options). The files to be edited should be copied from \fIargv\fR into @@ -1518,7 +1517,7 @@ must remain valid until the plugin's \fBclose\fR() function is called. .sp -NOTE: the +The \fIerrstr\fR parameter is only available starting with API version 1.15. @@ -1606,7 +1605,7 @@ must remain valid until the plugin's \fBclose\fR() function is called. .sp -NOTE: the +The \fIerrstr\fR parameter is only available starting with API version 1.15. @@ -1676,7 +1675,7 @@ must remain valid until the plugin's \fBclose\fR() function is called. .sp -NOTE: the +The \fIerrstr\fR parameter is only available starting with API version 1.15. @@ -1779,7 +1778,7 @@ pointer stored in The expected use case is to merge the contents of the PAM environment (if any) with the contents of \fIuser_env_out\fR. -NOTE: the +The \fIuser_env_out\fR parameter is only available starting with API version 1.2. @@ -1843,7 +1842,7 @@ See the section below for more information about hooks. .sp -NOTE: the +The \fBregister_hooks\fR() function is only available starting with API version 1.2. @@ -1896,7 +1895,7 @@ See the section below for more information about hooks. .sp -NOTE: the +The \fBderegister_hooks\fR() function is only available starting with API version 1.2. @@ -1934,7 +1933,7 @@ See the section below for more information about events. .sp -NOTE: the +The \fBevent_alloc\fR() function is only available starting with API version 1.15. @@ -1961,7 +1960,7 @@ must remain valid until the plugin's \fBclose\fR() function is called. .sp -NOTE: the +The \fIerrstr\fR parameter is only available starting with API version 1.15. @@ -2043,7 +2042,7 @@ will open a pipe to capture the I/O for logging before passing it on. .PP The log_ttyin function receives the raw user input from the terminal -device (note that this will include input even when echo is disabled, +device (this will include input even when echo is disabled, such as when a password is read). The log_ttyout function receives output from the pseudo-terminal that is suitable for replaying the user's session at a later time. @@ -2307,7 +2306,7 @@ will be the \fRNULL\fR pointer. .sp -NOTE: the +The \fIplugin_options\fR parameter is only available starting with API version 1.2. @@ -2335,7 +2334,7 @@ must remain valid until the plugin's \fBclose\fR() function is called. .sp -NOTE: the +The \fIerrstr\fR parameter is only available starting with API version 1.15. @@ -2465,7 +2464,7 @@ must remain valid until the plugin's \fBclose\fR() function is called. .sp -NOTE: the +The \fIerrstr\fR parameter is only available starting with API version 1.15. @@ -2524,7 +2523,7 @@ must remain valid until the plugin's \fBclose\fR() function is called. .sp -NOTE: the +The \fIerrstr\fR parameter is only available starting with API version 1.15. @@ -2586,7 +2585,7 @@ must remain valid until the plugin's \fBclose\fR() function is called. .sp -NOTE: the +The \fIerrstr\fR parameter is only available starting with API version 1.15. @@ -2648,7 +2647,7 @@ must remain valid until the plugin's \fBclose\fR() function is called. .sp -NOTE: the +The \fIerrstr\fR parameter is only available starting with API version 1.15. @@ -2710,7 +2709,7 @@ must remain valid until the plugin's \fBclose\fR() function is called. .sp -NOTE: the +The \fIerrstr\fR parameter is only available starting with API version 1.15. @@ -2781,7 +2780,7 @@ must remain valid until the plugin's \fBclose\fR() function is called. .sp -NOTE: the +The \fIerrstr\fR parameter is only available starting with API version 1.15. @@ -2837,7 +2836,7 @@ must remain valid until the plugin's \fBclose\fR() function is called. .sp -NOTE: the +The \fIerrstr\fR parameter is only available starting with API version 1.15. @@ -2875,7 +2874,7 @@ See the section below for more information about events. .sp -NOTE: the +The \fBevent_alloc\fR() function is only available starting with API version 1.15. @@ -3565,7 +3564,7 @@ See the section below for more information about events. .sp -NOTE: the +The \fBevent_alloc\fR() function is only available starting with API version 1.17. @@ -4222,8 +4221,8 @@ unchanged. .RE .PD .PP -Note that it is very easy to create an infinite loop when hooking -C library functions. +Care must be taken when hooking C library functions, +it is very easy to create an infinite loop. For example, a getenv(3) hook that calls the @@ -4600,7 +4599,7 @@ that the remote host will accept and run a program on the remote host that would setup the execution environment accordingly. .PP -Note that remote +Remote \fBsudoedit\fR functionality must be handled by the policy plugin, not \fBsudo\fR @@ -4724,7 +4723,7 @@ will return a value of \-1. The intended use is to allow the plugin to release resources, such as locks, that should not be held indefinitely while suspended and then reacquire them when the process is resumed. -Note that the functions are not actually invoked from within a signal handler. +The functions are not actually invoked from within a signal handler. .PP The \fImsg_type\fR diff --git a/docs/sudo_plugin.mdoc.in b/docs/sudo_plugin.mdoc.in index dc098c33c..e4432b839 100644 --- a/docs/sudo_plugin.mdoc.in +++ b/docs/sudo_plugin.mdoc.in @@ -609,7 +609,7 @@ will be the .Dv NULL pointer. .Pp -NOTE: the +The .Em plugin_options parameter is only available starting with API version 1.2. @@ -636,7 +636,7 @@ must remain valid until the plugin's .Fn close function is called. .Pp -NOTE: the +The .Fa errstr parameter is only available starting with API version 1.15. @@ -775,8 +775,7 @@ in the user's environment, such as .Li EDITOR , and include it in .Em argv_out -(note that environment -variables may include command line options). +(environment variables may include command line options). The files to be edited should be copied from .Em argv into @@ -1359,7 +1358,7 @@ must remain valid until the plugin's .Fn close function is called. .Pp -NOTE: the +The .Fa errstr parameter is only available starting with API version 1.15. @@ -1436,7 +1435,7 @@ must remain valid until the plugin's .Fn close function is called. .Pp -NOTE: the +The .Fa errstr parameter is only available starting with API version 1.15. @@ -1499,7 +1498,7 @@ must remain valid until the plugin's .Fn close function is called. .Pp -NOTE: the +The .Fa errstr parameter is only available starting with API version 1.15. @@ -1590,7 +1589,7 @@ pointer stored in The expected use case is to merge the contents of the PAM environment (if any) with the contents of .Em user_env_out . -NOTE: the +The .Em user_env_out parameter is only available starting with API version 1.2. @@ -1649,7 +1648,7 @@ See the section below for more information about hooks. .Pp -NOTE: the +The .Fn register_hooks function is only available starting with API version 1.2. @@ -1697,7 +1696,7 @@ See the section below for more information about hooks. .Pp -NOTE: the +The .Fn deregister_hooks function is only available starting with API version 1.2. @@ -1730,7 +1729,7 @@ See the section below for more information about events. .Pp -NOTE: the +The .Fn event_alloc function is only available starting with API version 1.15. @@ -1755,7 +1754,7 @@ must remain valid until the plugin's .Fn close function is called. .Pp -NOTE: the +The .Fa errstr parameter is only available starting with API version 1.15. @@ -1833,7 +1832,7 @@ will open a pipe to capture the I/O for logging before passing it on. .Pp The log_ttyin function receives the raw user input from the terminal -device (note that this will include input even when echo is disabled, +device (this will include input even when echo is disabled, such as when a password is read). The log_ttyout function receives output from the pseudo-terminal that is suitable for replaying the user's session at a later time. @@ -2083,7 +2082,7 @@ will be the .Dv NULL pointer. .Pp -NOTE: the +The .Em plugin_options parameter is only available starting with API version 1.2. @@ -2110,7 +2109,7 @@ must remain valid until the plugin's .Fn close function is called. .Pp -NOTE: the +The .Fa errstr parameter is only available starting with API version 1.15. @@ -2216,7 +2215,7 @@ must remain valid until the plugin's .Fn close function is called. .Pp -NOTE: the +The .Fa errstr parameter is only available starting with API version 1.15. @@ -2266,7 +2265,7 @@ must remain valid until the plugin's .Fn close function is called. .Pp -NOTE: the +The .Fa errstr parameter is only available starting with API version 1.15. @@ -2319,7 +2318,7 @@ must remain valid until the plugin's .Fn close function is called. .Pp -NOTE: the +The .Fa errstr parameter is only available starting with API version 1.15. @@ -2372,7 +2371,7 @@ must remain valid until the plugin's .Fn close function is called. .Pp -NOTE: the +The .Fa errstr parameter is only available starting with API version 1.15. @@ -2425,7 +2424,7 @@ must remain valid until the plugin's .Fn close function is called. .Pp -NOTE: the +The .Fa errstr parameter is only available starting with API version 1.15. @@ -2484,7 +2483,7 @@ must remain valid until the plugin's .Fn close function is called. .Pp -NOTE: the +The .Fa errstr parameter is only available starting with API version 1.15. @@ -2531,7 +2530,7 @@ must remain valid until the plugin's .Fn close function is called. .Pp -NOTE: the +The .Fa errstr parameter is only available starting with API version 1.15. @@ -2565,7 +2564,7 @@ See the section below for more information about events. .Pp -NOTE: the +The .Fn event_alloc function is only available starting with API version 1.15. @@ -3181,7 +3180,7 @@ See the section below for more information about events. .Pp -NOTE: the +The .Fn event_alloc function is only available starting with API version 1.17. @@ -3749,8 +3748,8 @@ unchanged. .El .El .Pp -Note that it is very easy to create an infinite loop when hooking -C library functions. +Care must be taken when hooking C library functions, +it is very easy to create an infinite loop. For example, a .Xr getenv 3 hook that calls the @@ -4060,7 +4059,7 @@ that the remote host will accept and run a program on the remote host that would setup the execution environment accordingly. .Pp -Note that remote +Remote .Nm sudoedit functionality must be handled by the policy plugin, not .Nm sudo @@ -4178,7 +4177,7 @@ will return a value of \-1. The intended use is to allow the plugin to release resources, such as locks, that should not be held indefinitely while suspended and then reacquire them when the process is resumed. -Note that the functions are not actually invoked from within a signal handler. +The functions are not actually invoked from within a signal handler. .Pp The .Em msg_type diff --git a/docs/sudo_plugin_python.man.in b/docs/sudo_plugin_python.man.in index cea0d2e7d..e2cf4d814 100644 --- a/docs/sudo_plugin_python.man.in +++ b/docs/sudo_plugin_python.man.in @@ -1724,7 +1724,7 @@ logger will get forwarded to sudo log system, as it would call sudo.debug. .PP The log handler of sudo will map each Python log level of a message to the appropriate sudo debug level. -Note however, that sudo debug system will only get the messages not filtered +The sudo debug system will only receive messages that are not filtered out by the Python loggers. For example, the log level of the python logger will be an additional filter for the log messages, and is usually very different from what level is set in sudo.conf @@ -1790,7 +1790,7 @@ The function arguments are as follows: .TP 6n \fIoptions_dict\fR A dictionary where both the key and the value are strings. -Note that the key should not contain an equal sign +The key should not contain an equal sign (\(oq\&=\(cq), otherwise the resulting string will have a different meaning. However, this is not currently enforced. diff --git a/docs/sudo_plugin_python.mdoc.in b/docs/sudo_plugin_python.mdoc.in index 03b82ab27..9665a4914 100644 --- a/docs/sudo_plugin_python.mdoc.in +++ b/docs/sudo_plugin_python.mdoc.in @@ -1387,7 +1387,7 @@ logger will get forwarded to sudo log system, as it would call sudo.debug. .Pp The log handler of sudo will map each Python log level of a message to the appropriate sudo debug level. -Note however, that sudo debug system will only get the messages not filtered +The sudo debug system will only receive messages that are not filtered out by the Python loggers. For example, the log level of the python logger will be an additional filter for the log messages, and is usually very different from what level is set in sudo.conf @@ -1443,7 +1443,7 @@ The function arguments are as follows: .Bl -tag -width 4n .It Fa options_dict A dictionary where both the key and the value are strings. -Note that the key should not contain an equal sign +The key should not contain an equal sign .Pq Sq \&= , otherwise the resulting string will have a different meaning. However, this is not currently enforced. diff --git a/docs/sudoers.ldap.man.in b/docs/sudoers.ldap.man.in index f2298b51e..259e29e93 100644 --- a/docs/sudoers.ldap.man.in +++ b/docs/sudoers.ldap.man.in @@ -168,9 +168,9 @@ with the option (or as \fBsudoedit\fR). It may take command line arguments just as a normal command does. -Note that +Unlike other commands, \(lq\fRsudoedit\fR\(rq -is a command built into +is a built into \fBsudo\fR itself and must be specified in without a leading path. .sp @@ -288,7 +288,7 @@ will be valid. If multiple \fRsudoNotBefore\fR entries are present, the earliest is used. -Note that timestamps must be in Coordinated Universal Time (UTC), +Timestamps must be in Coordinated Universal Time (UTC), not the local timezone. The minute and seconds portions are optional, but some LDAP servers require that they be present (contrary to the RFC). @@ -311,7 +311,7 @@ will no longer be valid. If multiple \fRsudoNotAfter\fR entries are present, the last one is used. -Note that timestamps must be in Coordinated Universal Time (UTC), +Timestamps must be in Coordinated Universal Time (UTC), not the local timezone. The minute and seconds portions are optional, but some LDAP servers require that they be present (contrary to the RFC). @@ -671,10 +671,10 @@ file for LDAP-specific configuration. Typically, this file is shared between different LDAP-aware clients. As such, most of the settings are not \fBsudo\fR-specific. -Note that -\fBsudo\fR -parses +The \fI@ldap_conf@\fR +file is parsed by +\fBsudo\fR itself and may support options that differ from those described in the system's ldap.conf(@mansectform@) @@ -686,8 +686,7 @@ may be overridden via the plugin argument in sudo.conf(@mansectform@). .PP -Also note that on systems using the OpenLDAP libraries, default -values specified in +On systems using the OpenLDAP libraries, default values specified in \fI/etc/openldap/ldap.conf\fR or the user's \fI.ldaprc\fR @@ -1089,7 +1088,7 @@ will be unable to connect to it. If \fBTLS_CHECKPEER\fR is disabled, no check is made. -Note that disabling the check creates an opportunity for man-in-the-middle +Disabling this check creates an opportunity for man-in-the-middle attacks since the server's identity will not be authenticated. If possible, the CA's certificate should be installed locally so it can be verified. @@ -1300,7 +1299,7 @@ search order. Sudo looks for a line beginning with \fRsudoers\fR: and uses this to determine the search order. -Note that by default, +By default, \fBsudo\fR does not stop searching after the first match and later matches take precedence over earlier ones (unless @@ -1375,10 +1374,10 @@ sudoers: files .RE .fi .PP -Note that +The \fI@nsswitch_conf@\fR -is supported even when the underlying operating system does not use -an nsswitch.conf file, except on AIX (see below). +file is supported even when the underlying operating system does not +support it, except on AIX (see below). .SS "Configuring netsvc.conf" On AIX systems, the \fI@netsvc_conf@\fR @@ -1420,7 +1419,7 @@ sudoers = ldap = auth, files .RE .fi .PP -Note that in the above example, the +In the above example, the \fRauth\fR qualifier only affects user lookups; both LDAP and \fIsudoers\fR @@ -1455,7 +1454,7 @@ instead of \fRldap\fR for the sudoers entry in \fI@nsswitch_conf@\fR. -Note that the +The \fI@ldap_conf@\fR file is not used by the SSSD \fBsudo\fR @@ -1703,7 +1702,7 @@ distribution (https://www.sudo.ws/about/contributors/) for an exhaustive list of people who have contributed to \fBsudo\fR. .SH "CAVEATS" -Note that there are differences in the way that LDAP-based +There are differences in the way that LDAP-based \fIsudoers\fR is parsed compared to file-based \fIsudoers\fR. diff --git a/docs/sudoers.ldap.mdoc.in b/docs/sudoers.ldap.mdoc.in index 5496a3b64..e967f06c3 100644 --- a/docs/sudoers.ldap.mdoc.in +++ b/docs/sudoers.ldap.mdoc.in @@ -161,9 +161,9 @@ with the option (or as .Nm sudoedit ) . It may take command line arguments just as a normal command does. -Note that +Unlike other commands, .Dq Li sudoedit -is a command built into +is a built into .Nm sudo itself and must be specified in without a leading path. .Pp @@ -272,7 +272,7 @@ will be valid. If multiple .Li sudoNotBefore entries are present, the earliest is used. -Note that timestamps must be in Coordinated Universal Time (UTC), +Timestamps must be in Coordinated Universal Time (UTC), not the local timezone. The minute and seconds portions are optional, but some LDAP servers require that they be present (contrary to the RFC). @@ -294,7 +294,7 @@ will no longer be valid. If multiple .Li sudoNotAfter entries are present, the last one is used. -Note that timestamps must be in Coordinated Universal Time (UTC), +Timestamps must be in Coordinated Universal Time (UTC), not the local timezone. The minute and seconds portions are optional, but some LDAP servers require that they be present (contrary to the RFC). @@ -634,10 +634,10 @@ file for LDAP-specific configuration. Typically, this file is shared between different LDAP-aware clients. As such, most of the settings are not .Nm sudo Ns -specific. -Note that -.Nm sudo -parses +The .Pa @ldap_conf@ +file is parsed by +.Nm sudo itself and may support options that differ from those described in the system's .Xr ldap.conf @mansectform@ @@ -649,8 +649,7 @@ may be overridden via the plugin argument in .Xr sudo.conf @mansectform@ . .Pp -Also note that on systems using the OpenLDAP libraries, default -values specified in +On systems using the OpenLDAP libraries, default values specified in .Pa /etc/openldap/ldap.conf or the user's .Pa .ldaprc @@ -1010,7 +1009,7 @@ will be unable to connect to it. If .Sy TLS_CHECKPEER is disabled, no check is made. -Note that disabling the check creates an opportunity for man-in-the-middle +Disabling this check creates an opportunity for man-in-the-middle attacks since the server's identity will not be authenticated. If possible, the CA's certificate should be installed locally so it can be verified. @@ -1197,7 +1196,7 @@ search order. Sudo looks for a line beginning with .Li sudoers : and uses this to determine the search order. -Note that by default, +By default, .Nm sudo does not stop searching after the first match and later matches take precedence over earlier ones (unless @@ -1256,10 +1255,10 @@ default is assumed: sudoers: files .Ed .Pp -Note that +The .Pa @nsswitch_conf@ -is supported even when the underlying operating system does not use -an nsswitch.conf file, except on AIX (see below). +file is supported even when the underlying operating system does not +support it, except on AIX (see below). .Ss Configuring netsvc.conf On AIX systems, the .Pa @netsvc_conf@ @@ -1292,7 +1291,7 @@ if the user is not present in LDAP, use: sudoers = ldap = auth, files .Ed .Pp -Note that in the above example, the +In the above example, the .Li auth qualifier only affects user lookups; both LDAP and .Em sudoers @@ -1324,7 +1323,7 @@ instead of .Li ldap for the sudoers entry in .Pa @nsswitch_conf@ . -Note that the +The .Pa @ldap_conf@ file is not used by the SSSD .Nm sudo @@ -1565,7 +1564,7 @@ distribution (https://www.sudo.ws/about/contributors/) for an exhaustive list of people who have contributed to .Nm sudo . .Sh CAVEATS -Note that there are differences in the way that LDAP-based +There are differences in the way that LDAP-based .Em sudoers is parsed compared to file-based .Em sudoers . diff --git a/docs/sudoers.man.in b/docs/sudoers.man.in index 39ced2a72..cfe76db10 100644 --- a/docs/sudoers.man.in +++ b/docs/sudoers.man.in @@ -208,7 +208,7 @@ Defaults entry (described later) and defaults to \fR@mailto@\fR. .PP -Note that no mail will be sent if an unauthorized user tries to run +No mail will be sent if an unauthorized user tries to run \fBsudo\fR with the \fB\-l\fR @@ -471,7 +471,7 @@ is displayed when is run by root with the \fB\-V\fR option. -Note that the list of environment variables to remove +The list of environment variables to remove varies based on the operating system \fBsudo\fR is running on. @@ -508,9 +508,9 @@ match a pattern in the \fIenv_delete\fR list. .PP -Note that the dynamic linker on most operating systems will remove -variables that can control dynamic linking from the environment of -set-user-ID executables, including +The dynamic linker on most operating systems will remove variables +that can control dynamic linking from the environment of set-user-ID +executables, including \fBsudo\fR. Depending on the operating system this may include @@ -896,7 +896,7 @@ See \fIGROUP PROVIDER PLUGINS\fR for more information. .PP -Note that quotes around group names are optional. +Quotes around group names are optional. Unquoted strings must use a backslash (\(oq\e\(cq) to escape spaces and special characters. @@ -931,13 +931,12 @@ of \fRUser_Alias\fRes it can contain \fRRunas_Alias\fRes. -Note that -user names and groups are matched as strings. +User names and groups are matched as strings. In other words, two users (groups) with the same user (group) ID are considered to be distinct. If you wish to match all user names with the same user-ID (e.g., root and toor), you can use a user-ID instead of a name (#0 in the example given). -Note that the user-ID or group-ID specified in a +The user-ID or group-ID specified in a \fRRunas_Member\fR need not be listed in the password or group database. .nf @@ -983,7 +982,6 @@ command on your machine returns the fully qualified host name, you'll need to use the \fIfqdn\fR flag for wildcards to be useful. -Note that \fBsudo\fR only inspects actual network interfaces; this means that IP address 127.0.0.1 (localhost) will never match. @@ -1101,9 +1099,9 @@ with the option (or as \fBsudoedit\fR). It may take command line arguments just as a normal command does. -Note that +Unlike other commands, \(lq\fRsudoedit\fR\(rq -is a command built into +is built into \fBsudo\fR itself and must be specified in the \fIsudoers\fR @@ -1180,7 +1178,7 @@ values at run-time via one or more lines. These may affect all users on any host, all users on a specific host, a specific user, a specific command, or commands being run as a specific user. -Note that per-command entries may not include command line arguments. +Per-command entries may not include command line arguments. If you need to specify arguments, define a \fRCmnd_Alias\fR and reference @@ -1438,7 +1436,7 @@ dgb boulder = (operator : operator) /bin/ls, (root) /bin/kill,\e .RE .fi .PP -Note that while the group portion of the +While the group portion of the \fRRunas_Spec\fR permits the user to run as command with that group, it does not force the user @@ -1468,8 +1466,7 @@ tcm boulder = (:dialer) /usr/bin/tip, /usr/bin/cu,\e .RE .fi .PP -Note that in this example only the group will be set, the command -still runs as user +In this example only the group will be set, the command still runs as user \fBtcm\fR. E.g.\& .nf @@ -1517,7 +1514,7 @@ subsequent in the \fRCmnd_Spec_List\fR, inherit that option unless it is overridden by another option. -Note that the option names are reserved words in +Option names are reserved words in \fIsudoers\fR. This means that none of the valid option names (see below) can be used when declaring an alias. @@ -1933,7 +1930,7 @@ options. These tags override the value of the \fIsetenv\fR flag on a per-command basis. -Note that if +If \fRSETENV\fR has been set for a command, the user may disable the \fIenv_reset\fR @@ -2031,7 +2028,7 @@ This is used to escape special characters such as: and \(oq]\&\(cq. .PP -\fBNote that these are not regular expressions.\fR +\fBThese are not regular expressions.\fR Unlike a regular expression there is no way to match one or more characters within a range. .PP @@ -2056,7 +2053,7 @@ For example: .PP Would match any file name beginning with a letter. .PP -Note that a forward slash +A forward slash (\(oq/\(cq) will \fInot\fR @@ -2355,7 +2352,7 @@ file that contained the \fR@includedir\fR directive. .PP -Note that unlike files included via +Unlike files included via \fR@include\fR, \fBvisudo\fR will not edit the files in a @@ -2395,7 +2392,7 @@ Attempting to define an named \fBALL\fR will result in a syntax error. -Note that using +Using \fBALL\fR can be dangerous since in a command context, it allows the user to run \fIany\fR @@ -2658,7 +2655,6 @@ will use the value of the or \fREDITOR\fR environment variables before falling back on the default editor list. -Note that \fBvisudo\fR is typically run as root so this flag may allow a user with \fBvisudo\fR @@ -2873,7 +2869,7 @@ to make DNS lookups which renders \fBsudo\fR unusable if DNS stops working (for example if the machine is disconnected from the network). -Also note that just like with the hosts file, you must use the +Just like with the hosts file, you must use the \(lqcanonical\(rq name as DNS knows it. That is, you may not use a host alias @@ -3251,7 +3247,7 @@ must look up any group name listed in the file and use the group-ID instead of the group name when determining whether the user is a member of the group. .sp -Note that if +If \fImatch_group_by_gid\fR is enabled, group database lookups performed by \fBsudoers\fR @@ -3548,7 +3544,7 @@ When is set, \fBsudo\fR will provide visual feedback when the user presses a key. -Note that this does have a security impact as an onlooker may be able to +This does have a security impact as an onlooker may be able to determine the length of the password being entered. This flag is \fIoff\fR @@ -3695,9 +3691,9 @@ However, since some programs (including the RCS revision control system) use to determine the real identity of the user, it may be desirable to change this behavior. This can be done by negating the set_logname option. -Note that +The \fIset_logname\fR -will have no effect +option will have no effect if the \fIenv_reset\fR option has not been disabled and the @@ -3846,7 +3842,7 @@ option (defaults to \fRroot\fR) instead of the password of the invoking user when running a command or editing a file. -Note that this flag precludes the use of a user-ID not listed in the passwd +This flag precludes the use of a user-ID not listed in the passwd database as an argument to the \fB\-u\fR option. @@ -4284,7 +4280,6 @@ options are enabled or when the or \fRLOG_OUTPUT\fR tags are present for a command. -Note that \fIiolog_file\fR may contain directory components. The default is @@ -4611,7 +4606,7 @@ This defaults to sudoers_locale Locale to use when parsing the sudoers file, logging commands, and sending email. -Note that changing the locale may affect how sudoers is interpreted. +Changing the locale may affect how sudoers is interpreted. Defaults to \(lq\fRC\fR\(rq. .TP 18n @@ -4778,7 +4773,6 @@ The default value is This avoids a time of check versus time of use race condition when the command is located in a directory writable by the invoking user. .sp -Note that \fIfdexec\fR will change the first element of the argument vector for scripts ($0 in the shell) due to the way the kernel runs script interpreters. @@ -5337,8 +5331,8 @@ The global list of environment variables to remove is displayed when is run by root with the \fB\-V\fR option. -Note that many operating systems will remove potentially dangerous -variables from the environment of any set-user-ID process (such as +Many operating systems will remove potentially dangerous variables +from the environment of any set-user-ID process (such as \fBsudo\fR). .TP 18n env_keep @@ -6045,8 +6039,7 @@ a pipe or file. .TP 10n \fIttyout\fR Output from the pseudo-terminal (what the command writes to the screen). -Note that terminal-specific post-processing is performed before the -data is logged. +Terminal-specific post-processing is performed before the data is logged. This means that, for example, line feeds are usually converted to line feed/carriage return pairs and tabs may be expanded to spaces. .TP 10n @@ -6075,9 +6068,9 @@ The output portion of an I/O log file can be viewed with the sudoreplay(@mansectsu@) utility, which can also be used to list or search the available logs. .PP -Note that user input may contain sensitive information such as -passwords (even if they are not echoed to the screen), which will -be stored in the log file unencrypted. +User input may contain sensitive information such as passwords (even +if they are not echoed to the screen), which will be stored in the +log file unencrypted. In most cases, logging the command output via \fIlog_output\fR or @@ -6137,8 +6130,8 @@ First, we allow a few environment variables to pass and then define our .sp .RS 0n # Run X applications through sudo; HOME is used to find the -# .Xauthority file. Note that other programs use HOME to find -# configuration files and this may lead to privilege escalation! +# .Xauthority file. Other programs use HOME to locate configuration +# files and this may lead to privilege escalation! Defaults env_keep += "DISPLAY HOME" # User alias specification @@ -6215,7 +6208,7 @@ Lastly, we disable shell escapes for the commands in the PAGERS and \fI/usr/bin/less\fR) \&. -Note that this will not effectively constrain users with +This will not effectively constrain users with \fBsudo\fR \fBALL\fR privileges. @@ -6327,7 +6320,7 @@ Here, those are commands related to backups, killing processes, the printing system, shutting down the system, and any commands in the directory \fI/usr/oper/bin/\fR. -Note that one command in the +One command in the \fRDUMPS\fR Cmnd_Alias includes a sha224 digest, \fI/home/operator/bin/start_backups\fR. @@ -6386,7 +6379,9 @@ words. This example assumes that passwd(1) does not take multiple user names on the command line. -Note that on GNU systems, options to +On systems with GNU +getopt(3), +options to passwd(1) may be specified after the user argument. As a result, this rule will also allow: @@ -6927,7 +6922,7 @@ you can always just try it out and check whether shell escapes work when is enabled. .RE .PP -Note that restricting shell escapes is not a panacea. +Restricting shell escapes is not a panacea. Programs running as root are still capable of many potentially hazardous operations (such as changing or overwriting files) that could lead to unintended privilege escalation. diff --git a/docs/sudoers.mdoc.in b/docs/sudoers.mdoc.in index e00de1545..b8286b8f3 100644 --- a/docs/sudoers.mdoc.in +++ b/docs/sudoers.mdoc.in @@ -196,7 +196,7 @@ Defaults entry (described later) and defaults to .Li @mailto@ . .Pp -Note that no mail will be sent if an unauthorized user tries to run +No mail will be sent if an unauthorized user tries to run .Nm sudo with the .Fl l @@ -457,7 +457,7 @@ is displayed when is run by root with the .Fl V option. -Note that the list of environment variables to remove +The list of environment variables to remove varies based on the operating system .Nm sudo is running on. @@ -494,9 +494,9 @@ match a pattern in the .Em env_delete list. .Pp -Note that the dynamic linker on most operating systems will remove -variables that can control dynamic linking from the environment of -set-user-ID executables, including +The dynamic linker on most operating systems will remove variables +that can control dynamic linking from the environment of set-user-ID +executables, including .Nm sudo . Depending on the operating system this may include @@ -864,7 +864,7 @@ See .Sx "GROUP PROVIDER PLUGINS" for more information. .Pp -Note that quotes around group names are optional. +Quotes around group names are optional. Unquoted strings must use a backslash .Pq Ql \e to escape spaces and special characters. @@ -896,13 +896,12 @@ of .Li User_Alias Ns es it can contain .Li Runas_Alias Ns es . -Note that -user names and groups are matched as strings. +User names and groups are matched as strings. In other words, two users (groups) with the same user (group) ID are considered to be distinct. If you wish to match all user names with the same user-ID (e.g., root and toor), you can use a user-ID instead of a name (#0 in the example given). -Note that the user-ID or group-ID specified in a +The user-ID or group-ID specified in a .Li Runas_Member need not be listed in the password or group database. .Bd -literal @@ -945,7 +944,6 @@ command on your machine returns the fully qualified host name, you'll need to use the .Em fqdn flag for wildcards to be useful. -Note that .Nm sudo only inspects actual network interfaces; this means that IP address 127.0.0.1 (localhost) will never match. @@ -1060,9 +1058,9 @@ with the option (or as .Nm sudoedit ) . It may take command line arguments just as a normal command does. -Note that +Unlike other commands, .Dq Li sudoedit -is a command built into +is built into .Nm sudo itself and must be specified in the .Em sudoers @@ -1133,7 +1131,7 @@ values at run-time via one or more lines. These may affect all users on any host, all users on a specific host, a specific user, a specific command, or commands being run as a specific user. -Note that per-command entries may not include command line arguments. +Per-command entries may not include command line arguments. If you need to specify arguments, define a .Li Cmnd_Alias and reference @@ -1374,7 +1372,7 @@ dgb boulder = (operator : operator) /bin/ls, (root) /bin/kill,\e /usr/bin/lprm .Ed .Pp -Note that while the group portion of the +While the group portion of the .Li Runas_Spec permits the user to run as command with that group, it does not force the user @@ -1398,8 +1396,7 @@ tcm boulder = (:dialer) /usr/bin/tip, /usr/bin/cu,\e /usr/local/bin/minicom .Ed .Pp -Note that in this example only the group will be set, the command -still runs as user +In this example only the group will be set, the command still runs as user .Sy tcm . E.g.\& .Bd -literal @@ -1441,7 +1438,7 @@ subsequent in the .Li Cmnd_Spec_List , inherit that option unless it is overridden by another option. -Note that the option names are reserved words in +Option names are reserved words in .Em sudoers . This means that none of the valid option names (see below) can be used when declaring an alias. @@ -1830,7 +1827,7 @@ options. These tags override the value of the .Em setenv flag on a per-command basis. -Note that if +If .Li SETENV has been set for a command, the user may disable the .Em env_reset @@ -1921,7 +1918,7 @@ and .El .Pp .Bf -symbolic -Note that these are not regular expressions. +These are not regular expressions. .Ef Unlike a regular expression there is no way to match one or more characters within a range. @@ -1944,7 +1941,7 @@ For example: .Pp Would match any file name beginning with a letter. .Pp -Note that a forward slash +A forward slash .Pq Ql / will .Em not @@ -2221,7 +2218,7 @@ file that contained the .Li @includedir directive. .Pp -Note that unlike files included via +Unlike files included via .Li @include , .Nm visudo will not edit the files in a @@ -2261,7 +2258,7 @@ Attempting to define an named .Sy ALL will result in a syntax error. -Note that using +Using .Sy ALL can be dangerous since in a command context, it allows the user to run .Em any @@ -2508,7 +2505,6 @@ will use the value of the or .Ev EDITOR environment variables before falling back on the default editor list. -Note that .Nm visudo is typically run as root so this flag may allow a user with .Nm visudo @@ -2716,7 +2712,7 @@ to make DNS lookups which renders .Nm sudo unusable if DNS stops working (for example if the machine is disconnected from the network). -Also note that just like with the hosts file, you must use the +Just like with the hosts file, you must use the .Dq canonical name as DNS knows it. That is, you may not use a host alias @@ -3069,7 +3065,7 @@ must look up any group name listed in the file and use the group-ID instead of the group name when determining whether the user is a member of the group. .Pp -Note that if +If .Em match_group_by_gid is enabled, group database lookups performed by .Nm @@ -3351,7 +3347,7 @@ When is set, .Nm sudo will provide visual feedback when the user presses a key. -Note that this does have a security impact as an onlooker may be able to +This does have a security impact as an onlooker may be able to determine the length of the password being entered. This flag is .Em off @@ -3488,9 +3484,9 @@ However, since some programs (including the RCS revision control system) use to determine the real identity of the user, it may be desirable to change this behavior. This can be done by negating the set_logname option. -Note that +The .Em set_logname -will have no effect +option will have no effect if the .Em env_reset option has not been disabled and the @@ -3630,7 +3626,7 @@ option (defaults to .Li root ) instead of the password of the invoking user when running a command or editing a file. -Note that this flag precludes the use of a user-ID not listed in the passwd +This flag precludes the use of a user-ID not listed in the passwd database as an argument to the .Fl u option. @@ -4040,7 +4036,6 @@ options are enabled or when the or .Li LOG_OUTPUT tags are present for a command. -Note that .Em iolog_file may contain directory components. The default is @@ -4338,7 +4333,7 @@ This defaults to .It sudoers_locale Locale to use when parsing the sudoers file, logging commands, and sending email. -Note that changing the locale may affect how sudoers is interpreted. +Changing the locale may affect how sudoers is interpreted. Defaults to .Dq Li C . .It timestamp_type @@ -4490,7 +4485,6 @@ The default value is This avoids a time of check versus time of use race condition when the command is located in a directory writable by the invoking user. .Pp -Note that .Em fdexec will change the first element of the argument vector for scripts ($0 in the shell) due to the way the kernel runs script interpreters. @@ -4984,8 +4978,8 @@ The global list of environment variables to remove is displayed when is run by root with the .Fl V option. -Note that many operating systems will remove potentially dangerous -variables from the environment of any set-user-ID process (such as +Many operating systems will remove potentially dangerous variables +from the environment of any set-user-ID process (such as .Nm sudo ) . .It env_keep Environment variables to be preserved in the user's environment when the @@ -5620,8 +5614,7 @@ The standard input when no terminal is present, or input redirected from a pipe or file. .It Pa ttyout Output from the pseudo-terminal (what the command writes to the screen). -Note that terminal-specific post-processing is performed before the -data is logged. +Terminal-specific post-processing is performed before the data is logged. This means that, for example, line feeds are usually converted to line feed/carriage return pairs and tabs may be expanded to spaces. .It Pa stdout @@ -5649,9 +5642,9 @@ The output portion of an I/O log file can be viewed with the .Xr sudoreplay @mansectsu@ utility, which can also be used to list or search the available logs. .Pp -Note that user input may contain sensitive information such as -passwords (even if they are not echoed to the screen), which will -be stored in the log file unencrypted. +User input may contain sensitive information such as passwords (even +if they are not echoed to the screen), which will be stored in the +log file unencrypted. In most cases, logging the command output via .Em log_output or @@ -5703,8 +5696,8 @@ First, we allow a few environment variables to pass and then define our .Em aliases : .Bd -literal # Run X applications through sudo; HOME is used to find the -# .Xauthority file. Note that other programs use HOME to find -# configuration files and this may lead to privilege escalation! +# .Xauthority file. Other programs use HOME to locate configuration +# files and this may lead to privilege escalation! Defaults env_keep += "DISPLAY HOME" # User alias specification @@ -5781,7 +5774,7 @@ Lastly, we disable shell escapes for the commands in the PAGERS and .Pa /usr/bin/less .Pc . -Note that this will not effectively constrain users with +This will not effectively constrain users with .Nm sudo .Sy ALL privileges. @@ -5874,7 +5867,7 @@ Here, those are commands related to backups, killing processes, the printing system, shutting down the system, and any commands in the directory .Pa /usr/oper/bin/ . -Note that one command in the +One command in the .Li DUMPS Cmnd_Alias includes a sha224 digest, .Pa /home/operator/bin/start_backups . @@ -5927,7 +5920,9 @@ words. This example assumes that .Xr passwd 1 does not take multiple user names on the command line. -Note that on GNU systems, options to +On systems with GNU +.Xr getopt 3 , +options to .Xr passwd 1 may be specified after the user argument. As a result, this rule will also allow: @@ -6405,7 +6400,7 @@ you can always just try it out and check whether shell escapes work when is enabled. .El .Pp -Note that restricting shell escapes is not a panacea. +Restricting shell escapes is not a panacea. Programs running as root are still capable of many potentially hazardous operations (such as changing or overwriting files) that could lead to unintended privilege escalation. diff --git a/docs/sudoreplay.man.in b/docs/sudoreplay.man.in index a60ddcdab..9b1b4c5a0 100644 --- a/docs/sudoreplay.man.in +++ b/docs/sudoreplay.man.in @@ -153,7 +153,7 @@ similar to \(lqtail -f\(rq. An I/O log file is considered to be complete when the write bits have been cleared on the session's timing file. -Note that versions of +Versions of \fBsudo\fR prior to 1.9.1 do not clear the write bits upon completion. .TP 12n @@ -196,7 +196,7 @@ for a description of supported date and time formats. group \fIrunas_group\fR Evaluates to true if the command was run with the specified \fIrunas_group\fR. -Note that unless a +Unless a \fIrunas_group\fR was explicitly specified when \fBsudo\fR @@ -209,11 +209,11 @@ Evaluates to true if the command was run on the specified runas \fIrunas_user\fR Evaluates to true if the command was run as the specified \fIrunas_user\fR. -Note that +By default, \fBsudo\fR -runs commands as user +runs commands as the \fIroot\fR -by default. +user. .TP 8n todate \fIdate\fR Evaluates to true if the command was run on or prior to @@ -248,7 +248,7 @@ operators as well as \(oq\&(\(cq and \(oq\&)\(cq -grouping (note that parentheses must generally be escaped from the shell). +grouping (parentheses must generally be escaped from the shell). The \fIand\fR operator is optional, adjacent predicates have an implied @@ -326,7 +326,7 @@ HH:MM:SS am MM/DD/CCYY timezone HH:MM:SS am Month, Day Year timezone 24 hour time may be used in place of am/pm, and month and day names may be abbreviated. -Note that month and day of the week names must be specified in English. +Month and day of the week names must be specified in English. .TP 8n CCYY-MM-DD HH:MM:SS ISO time format @@ -383,7 +383,7 @@ The current time but 14 days ago. 10:01 am Sep 17, 2009 10:01 am, September 17, 2009. .PP -Note that relative time specifications do not always work as expected. +Relative time specifications do not always work as expected. For example, the \(lqnext\(rq qualifier is intended to be used in conjunction with a day such as @@ -440,7 +440,7 @@ Example session tty output file. \fI@iolog_dir@/00/00/01/timing\fR Example session timing file. .PP -Note that the +The \fIstdin\fR, \fIstdout\fR and diff --git a/docs/sudoreplay.mdoc.in b/docs/sudoreplay.mdoc.in index 1dc0a5fcf..b9e8086fe 100644 --- a/docs/sudoreplay.mdoc.in +++ b/docs/sudoreplay.mdoc.in @@ -147,7 +147,7 @@ similar to .Dq tail -f . An I/O log file is considered to be complete when the write bits have been cleared on the session's timing file. -Note that versions of +Versions of .Nm sudo prior to 1.9.1 do not clear the write bits upon completion. .It Fl h , -help @@ -181,7 +181,7 @@ for a description of supported date and time formats. .It group Ar runas_group Evaluates to true if the command was run with the specified .Ar runas_group . -Note that unless a +Unless a .Ar runas_group was explicitly specified when .Nm sudo @@ -192,11 +192,11 @@ Evaluates to true if the command was run on the specified .It runas Ar runas_user Evaluates to true if the command was run as the specified .Ar runas_user . -Note that +By default, .Nm sudo -runs commands as user +runs commands as the .Em root -by default. +user. .It todate Ar date Evaluates to true if the command was run on or prior to .Ar date . @@ -229,7 +229,7 @@ operators as well as .Ql \&( and .Ql \&) -grouping (note that parentheses must generally be escaped from the shell). +grouping (parentheses must generally be escaped from the shell). The .Em and operator is optional, adjacent predicates have an implied @@ -300,7 +300,7 @@ The time and date may be specified multiple ways, common formats include: .It HH:MM:SS am Month, Day Year timezone 24 hour time may be used in place of am/pm, and month and day names may be abbreviated. -Note that month and day of the week names must be specified in English. +Month and day of the week names must be specified in English. .It CCYY-MM-DD HH:MM:SS ISO time format .It DD Month CCYY HH:MM:SS @@ -346,7 +346,7 @@ The current time but 14 days ago. 10:01 am, September 17, 2009. .El .Pp -Note that relative time specifications do not always work as expected. +Relative time specifications do not always work as expected. For example, the .Dq next qualifier is intended to be used in conjunction with a day such as @@ -395,7 +395,7 @@ Example session tty output file. Example session timing file. .El .Pp -Note that the +The .Em stdin , .Em stdout and diff --git a/docs/visudo.man.in b/docs/visudo.man.in index 48fa0d870..5b53e6c17 100644 --- a/docs/visudo.man.in +++ b/docs/visudo.man.in @@ -98,7 +98,6 @@ or \fREDITOR\fR environment variable if possible, or the first editor in the list that exists and is executable. -Note that \fBsudo\fR does not preserve the \fRSUDO_EDITOR\fR, @@ -127,7 +126,6 @@ will use the value of the or \fREDITOR\fR environment variables before falling back on the default editor list. -Note that \fBvisudo\fR is typically run as root so this option may allow a user with \fBvisudo\fR @@ -254,9 +252,9 @@ If an alias is referenced but not actually defined or if there is a cycle in an alias, \fBvisudo\fR will consider this a syntax error. -Note that it is not possible to differentiate between an -alias and a host name or user name that consists solely of uppercase -letters, digits, and the underscore +It is not possible to differentiate between an alias and a host +name or user name that consists solely of uppercase letters, digits, +and the underscore (\(oq_\(cq) character. .TP 12n diff --git a/docs/visudo.mdoc.in b/docs/visudo.mdoc.in index d283733d8..d9baddde3 100644 --- a/docs/visudo.mdoc.in +++ b/docs/visudo.mdoc.in @@ -96,7 +96,6 @@ or .Ev EDITOR environment variable if possible, or the first editor in the list that exists and is executable. -Note that .Nm sudo does not preserve the .Ev SUDO_EDITOR , @@ -124,7 +123,6 @@ will use the value of the or .Ev EDITOR environment variables before falling back on the default editor list. -Note that .Nm visudo is typically run as root so this option may allow a user with .Nm visudo @@ -246,9 +244,9 @@ If an alias is referenced but not actually defined or if there is a cycle in an alias, .Nm will consider this a syntax error. -Note that it is not possible to differentiate between an -alias and a host name or user name that consists solely of uppercase -letters, digits, and the underscore +It is not possible to differentiate between an alias and a host +name or user name that consists solely of uppercase letters, digits, +and the underscore .Pq Ql _ character. .It Fl V , -version diff --git a/examples/sudo_logsrvd.conf.in b/examples/sudo_logsrvd.conf.in index beb2400a9..86fda9002 100644 --- a/examples/sudo_logsrvd.conf.in +++ b/examples/sudo_logsrvd.conf.in @@ -57,9 +57,8 @@ #tls_key = /etc/ssl/sudo/private/logsrvd_key.pem # TLS cipher list (see "CIPHER LIST FORMAT" in the openssl-ciphers manual). -# NOTE that this setting is only effective if the negotiated protocol -# is TLS version 1.2. -# The default cipher list is HIGH:!aNULL. +# This setting is only effective if the negotiated protocol is TLS version +# 1.2. The default cipher list is HIGH:!aNULL. #tls_ciphers_v12 = HIGH:!aNULL # TLS cipher list if the negotiated protocol is TLS version 1.3. @@ -129,9 +128,8 @@ #tls_key = /etc/ssl/sudo/private/logsrvd_key.pem # TLS cipher list (see "CIPHER LIST FORMAT" in the openssl-ciphers manual). -# NOTE that this setting is only effective if the negotiated protocol -# is TLS version 1.2. -# The default is to use the value in the [server] section. +# this setting is only effective if the negotiated protocol is TLS version +# 1.2. The default is to use the value in the [server] section. #tls_ciphers_v12 = HIGH:!aNULL # TLS cipher list if the negotiated protocol is TLS version 1.3. @@ -148,7 +146,7 @@ #iolog_dir = @iolog_dir@ # The path name, relative to iolog_dir, in which to store I/O logs. -# Note that iolog_file may contain directory components. +# It is possible for iolog_file to contain directory components. #iolog_file = %{seq} # If set, I/O logs will be compressed using zlib. Enabling compression can