From 872e1688366445579b72cbb35c625dba736a0e6c Mon Sep 17 00:00:00 2001 From: "Todd C. Miller" Date: Thu, 17 Jan 2013 15:13:32 -0500 Subject: [PATCH] Document signal handler behavior in plugin API 1.3 --- doc/sudo_plugin.cat | 30 +++++++++++++++++++++ doc/sudo_plugin.man.in | 59 +++++++++++++++++++++++++++++++++++++++++ doc/sudo_plugin.mdoc.in | 51 +++++++++++++++++++++++++++++++++++ 3 files changed, 140 insertions(+) diff --git a/doc/sudo_plugin.cat b/doc/sudo_plugin.cat index e433be588..ae265109b 100644 --- a/doc/sudo_plugin.cat +++ b/doc/sudo_plugin.cat @@ -1069,6 +1069,29 @@ DDEESSCCRRIIPPTTIIOONN Same as for the _P_o_l_i_c_y _p_l_u_g_i_n _A_P_I. + SSiiggnnaall hhaannddlleerrss + The ssuuddoo front end installs default signal handlers to trap common + signals while the plugin functions are run. The following signals are + trapped by default before the command is executed: + + oo SIGALRM + oo SIGHUP + oo SIGINT + oo SIGQUIT + oo SIGTERM + oo SIGTSTP + oo SIGUSR1 + oo SIGUSR2 + + If a fatal signal is received before the command is executed, ssuuddoo will + call the plugin's cclloossee() function with an exit status of 128 plus the + value of the signal that was received. This allows for consistent + logging of commands killed by a signal for plugins that log such + information in their cclloossee() function. + + A plugin may temporarily install its own signal handlers but must restore + the original handler before the plugin function returns. + HHooookk ffuunnccttiioonn AAPPII Beginning with plugin API version 1.2, it is possible to install hooks for certain functions called by the ssuuddoo front end. @@ -1388,6 +1411,13 @@ PPLLUUGGIINN AAPPII CCHHAANNGGEELLOOGG used to merge in environment variables stored in the PAM handle before a command is run. + Version 1.3 + Support for the _e_x_e_c___b_a_c_k_g_r_o_u_n_d entry has been added to the + command_info list. + + The ssuuddoo front end now installs default signal handlers to trap + common signals while the plugin functions are run. + SSEEEE AALLSSOO sudoers(4), sudo(1m) diff --git a/doc/sudo_plugin.man.in b/doc/sudo_plugin.man.in index 6a07c2b2a..b800da414 100644 --- a/doc/sudo_plugin.man.in +++ b/doc/sudo_plugin.man.in @@ -1971,6 +1971,53 @@ section for a description of .PP Same as for the \fIPolicy plugin API\fR. +.SS "Signal handlers" +The +\fBsudo\fR +front end installs default signal handlers to trap common signals +while the plugin functions are run. +The following signals are trapped by default before the command is +executed: +.TP 4n +\fBo\fR +\fRSIGALRM\fR +.PD 0 +.TP 4n +\fBo\fR +\fRSIGHUP\fR +.TP 4n +\fBo\fR +\fRSIGINT\fR +.TP 4n +\fBo\fR +\fRSIGQUIT\fR +.TP 4n +\fBo\fR +\fRSIGTERM\fR +.TP 4n +\fBo\fR +\fRSIGTSTP\fR +.TP 4n +\fBo\fR +\fRSIGUSR1\fR +.TP 4n +\fBo\fR +\fRSIGUSR2\fR +.PD +.PP +If a fatal signal is received before the command is executed, +\fBsudo\fR +will call the plugin's +\fBclose\fR() +function with an exit status of 128 plus the value of the signal +that was received. +This allows for consistent logging of commands killed by a signal +for plugins that log such information in their +\fBclose\fR() +function. +.PP +A plugin may temporarily install its own signal handlers but must +restore the original handler before the plugin function returns. .SS "Hook function API" Beginning with plugin API version 1.2, it is possible to install hooks for certain functions called by the @@ -2532,6 +2579,18 @@ Policy plugin function is now passed a pointer to the user environment which can be updated as needed. This can be used to merge in environment variables stored in the PAM handle before a command is run. +.TP 6n +Version 1.3 +Support for the +\fIexec_background\fR +entry has been added to the +\fRcommand_info\fR +list. +.sp +The +\fBsudo\fR +front end now installs default signal handlers to trap common signals +while the plugin functions are run. .SH "SEE ALSO" sudoers(@mansectform@), sudo(@mansectsu@) diff --git a/doc/sudo_plugin.mdoc.in b/doc/sudo_plugin.mdoc.in index e677bc400..946d69d04 100644 --- a/doc/sudo_plugin.mdoc.in +++ b/doc/sudo_plugin.mdoc.in @@ -1718,6 +1718,46 @@ section for a description of .Pp Same as for the .Sx Policy plugin API . +.Ss Signal handlers +The +.Nm sudo +front end installs default signal handlers to trap common signals +while the plugin functions are run. +The following signals are trapped by default before the command is +executed: +.Pp +.Bl -bullet -compact +.It +.Dv SIGALRM +.It +.Dv SIGHUP +.It +.Dv SIGINT +.It +.Dv SIGQUIT +.It +.Dv SIGTERM +.It +.Dv SIGTSTP +.It +.Dv SIGUSR1 +.It +.Dv SIGUSR2 +.El +.Pp +If a fatal signal is received before the command is executed, +.Nm sudo +will call the plugin's +.Fn close +function with an exit status of 128 plus the value of the signal +that was received. +This allows for consistent logging of commands killed by a signal +for plugins that log such information in their +.Fn close +function. +.Pp +A plugin may temporarily install its own signal handlers but must +restore the original handler before the plugin function returns. .Ss Hook function API Beginning with plugin API version 1.2, it is possible to install hooks for certain functions called by the @@ -2195,6 +2235,17 @@ Policy plugin function is now passed a pointer to the user environment which can be updated as needed. This can be used to merge in environment variables stored in the PAM handle before a command is run. +.It Version 1.3 +Support for the +.Em exec_background +entry has been added to the +.Li command_info +list. +.Pp +The +.Nm sudo +front end now installs default signal handlers to trap common signals +while the plugin functions are run. .El .Sh SEE ALSO .Xr sudoers @mansectform@ ,