isa/sudo
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Fix some of the markup to be more consistent with sudo_plugin.mdoc.in.

Browse Source 
Also reword a few awkward phrases.
This commit is contained in:
Todd C. Miller
2022-09-11 19:06:25 -06:00
parent a7b200d014
commit 5bcec02442
2 changed files with 237 additions and 193 deletions
Download Patch File Download Diff File Expand all files Collapse all files

213
docs/sudo_plugin_python.man.in
View File

@@ -17,7 +17,7 @@
.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
.\"
.TH "SUDO_PLUGIN_PYTHON" "5" "June 6, 2022" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
.TH "SUDO_PLUGIN_PYTHON" "5" "September 11, 2022" "Sudo @PACKAGE_VERSION@" "File Formats Manual"
.nh
.if n .ad l
.SH "NAME"
@@ -96,9 +96,9 @@ When the plugin loads,
will create an instance of this class and call the methods.
The actual methods required depent on the type of the plugin,
but most return an
\(lqint\(rq
\fIint\fR
result code, as documented in
sudo_plugin(@mansectsu@),
sudo_plugin(@mansectform@),
that indicates whether or not the method was successful.
The Python sudo module defines the following constants to improve readability:
.RS 4n
@@ -120,12 +120,12 @@ l l.
.RE
.PP
If a function returns
\fINone\fR
\fRNone\fR
(for example, if it does not call return),
it will be considered to have returned
\fRsudo.RC.OK\fR.
If an exception is raised (other than sudo.PluginException), the backtrace will be
shown to the user and the plugin function will return
If an exception is raised (other than sudo.PluginException), the
backtrace will be shown to the user and the plugin function will return
\fRsudo.RC.ERROR\fR.
If that is not acceptable, you must catch the exception and handle it yourself.
.PP
@@ -151,7 +151,7 @@ Running the Python interpreter and bridging between C and Python is
handled by the
\fBsudo\fR
plugin
\fRpython_plugin.so\fR.
\fIpython_plugin.so\fR.
This shared object can be loaded like any other dynamic
\fBsudo\fR
plugin and should receive the path and the class name of the Python
@@ -219,7 +219,7 @@ sudo.conf(@mansectform@).
.PP
A policy plugin may have the following member functions:
.TP 6n
\fBconstructor\fR
\fIconstructor\fR
.nf
.RS 6n
__init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
@@ -235,7 +235,9 @@ as member variables in the object.
.sp
The constructor matches the
\fBopen\fR()
function in the C sudo plugin API.
function in the C
\fBsudo\fR
plugin API.
.sp
The function arguments are as follows:
.TP 6n
@@ -279,7 +281,7 @@ documentation in
sudo_plugin(@mansectform@).
.RE
.TP 6n
\fBcheck_policy\fR
\fIcheck_policy\fR
.nf
.RS 6n
check_policy(self, argv: Tuple[str, ...], env_add: Tuple[str, ...])
@@ -367,7 +369,7 @@ format.
.RE
.PD
.TP 6n
\fBinit_session\fR
\fIinit_session\fR
.nf
.RS 6n
init_session(self, user_pwd: Tuple, user_env: Tuple[str, ...])
@@ -387,8 +389,9 @@ The function arguments are as follows:
.TP 6n
\fIuser_pwd\fR
A tuple describing the user's passwd entry.
Convertible to pwd.struct_passwd or
\fINone\fR
Convertible to
\fIpwd.struct_passwd or\fR
\fRNone\fR
if the user is not present in the password database.
.sp
Example conversion:
@@ -437,7 +440,7 @@ If this is omitted, no changes will be made to
.RE
.PD
.TP 6n
\fBlist\fR
\fIlist\fR
.nf
.RS 6n
list(self, argv: Tuple[str, ...], is_verbose: int, user: str)
@@ -451,7 +454,7 @@ The function arguments are as follows:
.TP 6n
\fIargv\fR
If not set to
\fINone\fR,
\fRNone\fR,
an argument vector describing a command the user wishes to check
against the policy.
.TP 6n
@@ -461,14 +464,14 @@ Flag indicating whether to list in verbose mode or not.
\fIuser\fR
The name of a different user to list privileges for if the policy allows it.
If
\fINone\fR,
\fRNone\fR,
the plugin should list the privileges of the invoking user.
.PD 0
.PP
.RE
.PD
.TP 6n
\fBvalidate\fR
\fIvalidate\fR
.nf
.RS 6n
validate(self)
@@ -479,7 +482,7 @@ validate(self)
For policy plugins that cache authentication credentials, this function is used to validate and cache the credentials (optional).
.RE
.TP 6n
\fBinvalidate\fR
\fIinvalidate\fR
.nf
.RS 6n
invalidate(self, remove: int)
@@ -499,7 +502,7 @@ invalidating them.
.RE
.PD
.TP 6n
\fBshow_version\fR
\fIshow_version\fR
.nf
.RS 6n
show_version(self, is_verbose: int)
@@ -524,7 +527,7 @@ is run as the root user.
.RE
.PD
.TP 6n
\fBclose\fR
\fIclose\fR
.br
.nf
.RS 6n
@@ -537,7 +540,9 @@ Called when a command finishes executing.
.sp
Works the same as the
\fBclose\fR()
function in the C sudo plugin API, except that it only gets called if
function in the C
\fBsudo\fR
plugin API, except that it only gets called if
\fBsudo\fR
attempts to execute the command.
.sp
@@ -569,8 +574,10 @@ Plugin python_policy python_plugin.so \e
.RE
.fi
.PP
Be aware, however, that you cannot enable the Python policy plugin
in addition to another policy plugin, such as
Only one policy plugin can be enabled at a time so you must disable
any other policy plugin listed in
\fI@sysconfdir@/sudo.conf\fR,
such as
sudoers(@mansectform@).
.SS "I/O plugin API"
I/O plugins must be registered in
@@ -588,7 +595,7 @@ Currently only 8 python I/O plugins can be loaded at once.
.PP
An I/O plugin may have the following member functions:
.TP 6n
\fBconstructor\fR
\fIconstructor\fR
.nf
.RS 6n
__init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
@@ -604,7 +611,9 @@ as member variables in the object.
.sp
The constructor matches the
\fBopen\fR()
function in the C sudo plugin API.
function in the C
\fBsudo\fR
plugin API.
.sp
The function arguments are as follows:
.TP 6n
@@ -648,7 +657,7 @@ documentation in
sudo_plugin(@mansectform@).
.RE
.TP 6n
\fBopen\fR
\fIopen\fR
.nf
.RS 6n
open(self, argv: Tuple[str, ...],
@@ -661,13 +670,15 @@ Receives the command the user wishes to run.
.sp
Works the same as the
\fBopen\fR()
function in the C sudo plugin API except that:
function in the C
\fBsudo\fR
plugin API except that:
.sp
.RS 10n
.PD 0
.TP 3n
\fB\(bu\fR
It only gets called before the user would execute some command
It only gets called when there is a command to be executed
(and not for a version query for example).
.TP 3n
\fB\(bu\fR
@@ -708,7 +719,7 @@ If the function returns
no I/O will be sent to the plugin.
.RE
.TP 6n
\fBlog_ttyin\fR, \fBlog_ttyout\fR, \fBlog_stdin\fR, \fBlog_stdout\fR, \fBlog_stderr\fR
\fIlog_ttyin\fR, \fIlog_ttyout\fR, \fIlog_stdin\fR, \fIlog_stdout\fR, \fIlog_stderr\fR
.nf
.RS 6n
log_ttyin(self, buf: str) -> int
@@ -736,8 +747,8 @@ constants.
.sp
If
\fRsudo.RC.ERROR\fR
is returned, the running command will be terminated and all of the plugin's logging
functions will be disabled.
is returned, the running command will be terminated and all of the
plugin's logging functions will be disabled.
Other I/O logging plugins will still receive any remaining
input or output that has not yet been processed.
.sp
@@ -751,7 +762,7 @@ the command will be terminated and the data will not be written to the
terminal, though it will still be sent to any other I/O logging plugins.
.RE
.TP 6n
\fBchange_winsize\fR
\fIchange_winsize\fR
.nf
.RS 6n
change_winsize(self, line: int, cols: int) -> int
@@ -772,7 +783,7 @@ The number of columns of the terminal.
.RE
.PD
.TP 6n
\fBlog_suspend\fR
\fIlog_suspend\fR
.nf
.RS 6n
log_suspend(self, signo: int) -> int
@@ -793,7 +804,7 @@ if the command was resumed.
.RE
.PD
.TP 6n
\fBshow_version\fR
\fIshow_version\fR
.nf
.RS 6n
show_version(self, is_verbose: int)
@@ -817,7 +828,7 @@ is run as the root user.
.RE
.PD
.TP 6n
\fBclose\fR
\fIclose\fR
.br
.nf
.RS 6n
@@ -825,11 +836,13 @@ close(self, exit_status: int, error: int) -> None
.RE
.fi
.RS 6n
Called when a command execution finished.
Called when a command finishes execution.
.sp
Works the same as the
\fBclose\fR()
function in the C sudo plugin API, except that it only gets called if
function in the C
\fBsudo\fR
plugin API, except that it only gets called if
\fBsudo\fR
attempts to execute the command.
.sp
@@ -849,7 +862,7 @@ system call, otherwise 0.
.RE
.PD
.SS "I/O plugin example"
Sudo ships a Python I/O plugin example.
Sudo ships with a Python I/O plugin example.
To try it, register it by adding the following lines to
\fI@sysconfdir@/sudo.conf\fR:
.nf
@@ -874,9 +887,9 @@ Plugin python_audit python_plugin.so ModulePath=<path> ClassName=<class>
Sudo supports loading multiple audit plugins.
Currently only 8 python audit plugins can be loaded at once.
.PP
An audit plugin may have the following member functions (all of them are optional):
An audit plugin may have the following member functions (all of which are optional):
.TP 6n
\fBconstructor\fR
\fIconstructor\fR
.nf
.RS 6n
__init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
@@ -890,7 +903,9 @@ as member variables in the object.
.sp
The constructor matches the
\fBopen\fR()
function in the C sudo plugin API.
function in the C
\fBsudo\fR
plugin API.
.sp
The function arguments are as follows:
.TP 6n
@@ -926,7 +941,7 @@ format.
.RE
.PD
.TP 6n
\fBopen\fR
\fIopen\fR
.nf
.RS 6n
open(self, submit_optind: int,
@@ -949,7 +964,7 @@ The argument vector sudo was invoked with, including all command line options.
.RE
.PD
.TP 6n
\fBclose\fR
\fIclose\fR
.br
.nf
.RS 6n
@@ -964,7 +979,9 @@ The function arguments are as follows:
.TP 6n
\fIstatus_type\fR
The type of status being passed.
One of the sudo.EXIT_REASON.* constants.
One of the
\fRsudo.EXIT_REASON.*\fR
constants.
.TP 6n
\fIstatus\fR
Depending on the value of
@@ -973,11 +990,11 @@ this value is either
ignored, the command's exit status as returned by the
wait(2)
system call, the value of
\fRerrno\fR
\fIerrno\fR
set by the
execve(2)
system call, or the value of
\fRerrno\fR
\fIerrno\fR
resulting from an error in the
\fBsudo\fR
front-end.
@@ -986,7 +1003,7 @@ front-end.
.RE
.PD
.TP 6n
\fBshow_version\fR
\fIshow_version\fR
.nf
.RS 6n
show_version(self, is_verbose: int) -> int
@@ -1011,7 +1028,7 @@ is run as the root user.
.RE
.PD
.TP 6n
\fBaccept\fR
\fIaccept\fR
.nf
.RS 6n
accept(self, plugin_name: str, plugin_type: int, command_info: Tuple[str, ...],
@@ -1075,7 +1092,7 @@ The environment the command will be run with.
.RE
.PD
.TP 6n
\fBreject\fR
\fIreject\fR
.nf
.RS 6n
reject(self, plugin_name: str, plugin_type: int, audit_msg: str,
@@ -1109,7 +1126,7 @@ front-end.
audit_msg
An optional string describing the reason the command was rejected by the plugin.
If the plugin did not provide a reason, audit_msg will be
\fINone\fR
\fRNone\fR.
.TP 6n
command_info
A vector of information describing the rejected command.
@@ -1121,7 +1138,7 @@ manual for possible values.
.RE
.PD
.TP 6n
\fBerror\fR
\fIerror\fR
.br
.nf
.RS 6n
@@ -1153,7 +1170,7 @@ front-end.
audit_msg
An optional string describing the plugin error.
If the plugin did not provide a description, it will be
\fINone\fR
\fRNone\fR.
.TP 6n
command_info
A vector of information describing the command.
@@ -1165,7 +1182,7 @@ manual for possible values.
.RE
.PD
.SS "Audit plugin example"
Sudo ships a Python Audit plugin example.
Sudo ships with a Python Audit plugin example.
To try it, register it by adding the following lines to
\fI@sysconfdir@/sudo.conf\fR:
.nf
@@ -1194,7 +1211,7 @@ Currently only 8 python approval plugins can be loaded at once.
.PP
An approval plugin may have the following member functions:
.TP 6n
\fBconstructor\fR
\fIconstructor\fR
.nf
.RS 6n
__init__(self, user_env: Tuple[str, ...], settings: Tuple[str, ...],
@@ -1210,7 +1227,9 @@ as member variables in the object.
.sp
The constructor matches the
\fBopen\fR()
function in the C sudo plugin API.
function in the C
\fBsudo\fR
plugin API.
.sp
The function arguments are as follows:
.TP 6n
@@ -1254,7 +1273,7 @@ The argument vector sudo was invoked with, including all command line options.
.RE
.PD
.TP 6n
\fBshow_version\fR
\fIshow_version\fR
.nf
.RS 6n
show_version(self, is_verbose: int) -> int
@@ -1262,10 +1281,11 @@ show_version(self, is_verbose: int) -> int
.fi
.RS 6n
.sp
Display the version. (Same as for all the other plugins.)
Display the version.
(Same as for all the other plugins.)
.RE
.TP 6n
\fBcheck\fR
\fIcheck\fR
.br
.nf
.RS 6n
@@ -1306,7 +1326,7 @@ The environment the command will be run with.
.RE
.PD
.SS "Approval plugin example"
Sudo ships a Python Approval plugin example.
Sudo ships with a Python Approval plugin example.
To try it, register it by adding the following lines to
\fI@sysconfdir@/sudo.conf\fR:
.nf
@@ -1337,7 +1357,7 @@ Currently, only a single group plugin can be registered in
.PP
A group provider plugin may have the following member functions:
.TP 6n
\fBconstructor\fR
\fIconstructor\fR
.nf
.RS 6n
__init__(self, args: Tuple[str, ...], version: str)
@@ -1366,7 +1386,7 @@ The version of the Python Group Plugin API.
.RE
.PD
.TP 6n
\fBquery\fR
\fIquery\fR
.br
.nf
.RS 6n
@@ -1402,7 +1422,7 @@ is not present in the password database,
will be
\fRNULL\fR.
.SS "Group plugin example"
Sudo ships a Python group plugin example.
Sudo ships with a Python group plugin example.
To try it, register it in the
\fIsudoers\fR
file by adding the following lines:
@@ -1419,7 +1439,7 @@ The example plugin will tell
\fBsudo\fR
that the user
\fItest\fR
is part of the non-unix group
is part of the non-Unix group
\fImygroup\fR.
If you add a rule that uses this group, it will affect the
\fItest\fR
@@ -1444,16 +1464,18 @@ written in Python.
A Python plugin can interact with the user using the
\fBsudo.conv\fR()
function which displays one or more messages described by the
\fBsudo.ConvMessage\fR
\fRsudo.ConvMessage\fR
class.
This is the Python equivalent of the
\fBconversation\fR()
function in the C sudo plugin API.
function in the C
\fBsudo\fR
plugin API.
A plugin should not attempt to read directly from the standard input or
the user's tty (neither of which are guaranteed to exist).
.PP
The
\fBsudo.ConvMessage\fR
\fRsudo.ConvMessage\fR
class specifies how the user interaction should occur:
.nf
.sp
@@ -1462,7 +1484,7 @@ sudo.ConvMessage(msg_type: int, msg: str, timeout: int)
.RE
.fi
.PP
\fBsudo.ConvMessage\fR
\fRsudo.ConvMessage\fR
member variables:
.TP 6n
\fImsg_type\fR
@@ -1474,7 +1496,7 @@ constants below.
\fImsg\fR
The message to display to the user.
The caller must include a trailing newline in
\fRmsg\fR
\fImsg\fR
if one is to be displayed.
.TP 6n
\fItimeout\fR
@@ -1493,25 +1515,25 @@ To specify the message type, the following constants are available:
.PD 0
.TP 3n
\fB\(bu\fR
sudo.CONV.PROMPT_ECHO_OFF
\fRsudo.CONV.PROMPT_ECHO_OFF\fR
.TP 3n
\fB\(bu\fR
sudo.CONV.PROMPT_ECHO_ON
\fRsudo.CONV.PROMPT_ECHO_ON\fR
.TP 3n
\fB\(bu\fR
sudo.CONV.ERROR_MSG
\fRsudo.CONV.ERROR_MSG\fR
.TP 3n
\fB\(bu\fR
sudo.CONV.INFO_MSG
\fRsudo.CONV.INFO_MSG\fR
.TP 3n
\fB\(bu\fR
sudo.CONV.PROMPT_MASK
\fRsudo.CONV.PROMPT_MASK\fR
.TP 3n
\fB\(bu\fR
sudo.CONV.PROMPT_ECHO_OK
\fRsudo.CONV.PROMPT_ECHO_OK\fR
.TP 3n
\fB\(bu\fR
sudo.CONV.PREFER_TTY
\fRsudo.CONV.PREFER_TTY\fR
.RE
.PD
.PP
@@ -1534,7 +1556,7 @@ The function arguments are as follows:
.TP 6n
\fImessage(s)\fR
One of more messages (of type
\fBsudo.ConvMessage\fR),
\fRsudo.ConvMessage\fR),
each describing a conversation.
At least one message is required.
.TP 6n
@@ -1554,11 +1576,11 @@ The
\fBsudo.conv\fR()
function can raise the following exceptions:
.TP 6n
\fBsudo.SudoException\fR
\fRsudo.SudoException\fR
If the conversation fails, for example when the conversation function is not
available.
.TP 6n
\fBsudo.ConversationInterrupted\fR
\fRsudo.ConversationInterrupted\fR
If the conversation function returns an error, e.g., the timeout passed
or the user interrupted the conversation by pressing control-C.
.SS "Conversation example"
@@ -1618,7 +1640,7 @@ debug system.
\fIEnabling debugging in sudo.conf\fR
.PP
To enable debug messages, add a
\fRDebug\fR
\fIDebug\fR
line to
sudo.conf(@mansectform@)
with the program set to
@@ -1710,21 +1732,21 @@ l l l.
.PP
\fBsudo.conf name\fR \fBPython constant\fR \fBdescription\fR
.PP
crit sudo.DEBUG.CRIT only critical messages
crit \fRsudo.DEBUG.CRIT\fR only critical messages
.PP
err sudo.DEBUG.ERROR
err \fRsudo.DEBUG.ERROR\fR
.PP
warn sudo.DEBUG.WARN
warn \fRsudo.DEBUG.WARN\fR
.PP
notice sudo.DEBUG.NOTICE
notice \fRsudo.DEBUG.NOTICE\fR
.PP
diag sudo.DEBUG.DIAG
diag \fRsudo.DEBUG.DIAG\fR
.PP
info sudo.DEBUG.INFO
info \fRsudo.DEBUG.INFO\fR
.PP
trace sudo.DEBUG.TRACE
trace \fRsudo.DEBUG.TRACE\fR
.PP
debug sudo.DEBUG.DEBUG very extreme verbose debugging
debug \fRsudo.DEBUG.DEBUG\fR very extreme verbose debugging
.TE
.PP
\fIUsing the logging module\fR
@@ -1737,11 +1759,11 @@ The log handler of sudo will map each Python log level of a message to
the appropriate sudo debug level.
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
for the sudo debug system.
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 for the sudo debug system.
.SS "Debug example"
Sudo ships an example debug plugin by default.
Sudo ships with an example debug plugin.
To try it, register it by adding the following lines to
\fI@sysconfdir@/sudo.conf\fR:
.nf
@@ -1816,12 +1838,13 @@ This is how the plugin API accepts options and settings.
.SH "PLUGIN API CHANGELOG (Python)"
None yet
.SH "LIMITATIONS"
Only a maximum number of 8 python I/O plugins can be loaded at once.
A maximum of 8 python I/O plugins can be loaded at once.
If
\fI@sysconfdir@/sudo.conf\fR
contains more, those will be rejected with a warning message.
.PP
The Event API and the hook function API is currently not accessible for Python plugins.
The Event API and the hook function API is currently not accessible
for Python plugins.
.SH "SEE ALSO"
sudo.conf(@mansectform@),
sudo_plugin(@mansectform@),
@@ -1849,7 +1872,7 @@ If you believe you have found a bug in
you can submit a bug report at https://bugzilla.sudo.ws/
.SH "SECURITY CONSIDERATIONS"
All Python plugin handling is implemented inside the
\fRpython_plugin.so\fR
\fIpython_plugin.so\fR
dynamic plugin.
Therefore, if no Python plugin is registered in
sudo.conf(@mansectform@)
@@ -1875,7 +1898,7 @@ accidentally importing such file would make it possible for any user
However, during development of a plugin this might not be very convenient.
The
sudo.conf(@mansectform@)
\fRdeveloper_mode\fR
\fIdeveloper_mode\fR
option can be used to disable it.
For example:
.RS 6n