From: Todd C. Miller Date: Sat, 16 Jan 2016 23:47:42 +0000 (-0700) Subject: Add "I/O LOG FILES" section to the manual and move many of the X-Git-Tag: SUDO_1_8_16^2~65 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=7f8a29dfc040c2a30967e12ba426c84bacc139a1;p=sudo Add "I/O LOG FILES" section to the manual and move many of the details from the log_input and log_output descriptions to it. --- diff --git a/doc/sudoers.cat b/doc/sudoers.cat index 8ad5beaa0..4eda3319f 100644 --- a/doc/sudoers.cat +++ b/doc/sudoers.cat @@ -60,7 +60,7 @@ DDEESSCCRRIIPPTTIIOONN For more information on configuring sudo.conf(4), please refer to its manual. - AAuutthheennttiiccaattiioonn aanndd llooggggiinngg + UUsseerr AAuutthheennttiiccaattiioonn The ssuuddooeerrss security policy requires that most users authenticate themselves before they can use ssuuddoo. A password is not required if the invoking user is root, if the target user is the same as the invoking @@ -99,15 +99,19 @@ DDEESSCCRRIIPPTTIIOONN record for each tty, which means that a user's login sessions are authenticated separately. The _t_t_y___t_i_c_k_e_t_s option can be disabled to force the use of a single time stamp for all of a user's sessions. + + LLooggggiinngg ssuuddooeerrss can log both successful and unsuccessful attempts (as well as errors) to syslog(3), a log file, or both. By default, ssuuddooeerrss will log via syslog(3) but this is changeable via the _s_y_s_l_o_g and _l_o_g_f_i_l_e Defaults - settings. + settings. See _L_O_G _F_O_R_M_A_T for a description of the log file format. - _s_u_d_o_e_r_s also supports logging a command's input and output streams. I/O - logging is not on by default but can be enabled using the _l_o_g___i_n_p_u_t and - _l_o_g___o_u_t_p_u_t Defaults flags as well as the LOG_INPUT and LOG_OUTPUT command - tags. + ssuuddooeerrss is also capable of running a command in a pseudo-tty and logging + all input and/or output. The standard input, standard output and + standard error can be logged even when not associated with a terminal. + I/O logging is not on by default but can be enabled using the _l_o_g___i_n_p_u_t + and _l_o_g___o_u_t_p_u_t options as well as the LOG_INPUT and LOG_OUTPUT command + tags. See _I_/_O _L_O_G _F_I_L_E_S for details on how I/O log files are stored. CCoommmmaanndd eennvviirroonnmmeenntt Since environment variables can influence program behavior, ssuuddooeerrss @@ -1044,50 +1048,13 @@ SSUUDDOOEERRSS OOPPTTIIOONNSS connected to the user's tty, due to I/O redirection or because the command is part of a pipeline, that input is also captured and stored in a separate log file. + For more information, see the _I_/_O _L_O_G _F_I_L_E_S section. This flag is _o_f_f by default. - Input is logged to the directory specified by the - _i_o_l_o_g___d_i_r option (_/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o by default) using a - unique session ID that is included in the normal ssuuddoo - log line, prefixed with ``TSID=''. The _i_o_l_o_g___f_i_l_e - option may be used to control the format of the session - ID. Input from the user's tty is logged to the _t_t_y_i_n - file. Input from a pipe or file is logged to the _s_t_d_i_n - file. These files are in gzip (compressed) format - unless the _c_o_m_p_r_e_s_s___i_o option has been disabled. Due - to buffering, the I/O log data will not be complete - until the ssuuddoo command has completed. - - 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. In most cases, logging the command output - via _l_o_g___o_u_t_p_u_t is all that is required. - log_output If set, ssuuddoo will run the command in a pseudo-tty and log all output that is sent to the screen, similar to - the script(1) command. If the standard output or - standard error is not connected to the user's tty, due - to I/O redirection or because the command is part of a - pipeline, that output is also captured and stored in - separate log files. This flag is _o_f_f by default. - - Output is logged to the directory specified by the - _i_o_l_o_g___d_i_r option (_/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o by default) using a - unique session ID that is included in the normal ssuuddoo - log line, prefixed with ``TSID=''. The _i_o_l_o_g___f_i_l_e - option may be used to control the format of the session - ID. Output from the pseudo-tty is logged to the _t_t_y_o_u_t - file. Output to a pipe or redirected to a file is - logged to the either the _s_t_d_o_u_t or _s_t_d_e_r_r files. These - files are in gzip (compressed) format unless the - _c_o_m_p_r_e_s_s___i_o option has been disabled. Due to - buffering, the I/O log data will not be complete until - the ssuuddoo command has completed. - - Output logs may be viewed with the sudoreplay(1m) - utility, which can also be used to list or search the - available logs. + the script(1) command. For more information, see the + _I_/_O _L_O_G _F_I_L_E_S section. This flag is _o_f_f by default. log_year If set, the four-digit year will be logged in the (non- syslog) ssuuddoo log file. This flag is _o_f_f by default. @@ -1841,8 +1808,8 @@ GGRROOUUPP PPRROOVVIIDDEERR PPLLUUGGIINNSS The group provider plugin API is described in detail in sudo_plugin(1m). LLOOGG FFOORRMMAATT - ssuuddooeerrss can log events using either syslog(3) or a simple log file. In - each case the log format is almost identical. + ssuuddooeerrss can log events using either syslog(3) or a simple log file. The + log format is almost identical in both cases. AAcccceepptteedd ccoommmmaanndd lloogg eennttrriieess Commands that sudo runs are logged using the following format (split into @@ -2021,6 +1988,56 @@ LLOOGG FFOORRMMAATT _l_o_g_l_i_n_e_l_e_n option is set to 0 (or negated with a `!'), word wrap will be disabled. +II//OO LLOOGG FFIILLEESS + When I/O logging is enabled, ssuuddoo will run the command in a pseudo-tty + and log all user input and/or output. I/O is logged to the directory + specified by the _i_o_l_o_g___d_i_r option (_/_v_a_r_/_l_o_g_/_s_u_d_o_-_i_o by default) using a + unique session ID that is included in the ssuuddoo log line, prefixed with + ``TSID=''. The _i_o_l_o_g___f_i_l_e option may be used to control the format of + the session ID. + + Each I/O log is stored in a separate directory that contains the + following files: + + _l_o_g a text file containing the time the command was run, the name + of the user who ran ssuuddoo, the name of the target user, the name + of the target group (optional), the terminal that ssuuddoo was run + from, the number of rows and columns of the terminal, the + working directory the command was run from and the path name of + the command itself (with arguments if present) + + _t_i_m_i_n_g a log of the amount of time between, and the number of bytes + in, each I/O log entry (used for session playback) + + _t_t_y_i_n input from the user's tty (what the user types) + + _s_t_d_i_n input from a pipe or file + + _t_t_y_o_u_t output from the pseudo-tty (what the command writes to the + screen) + + _s_t_d_o_u_t standard output to a pipe or redirected to a file + + _s_t_d_e_r_r standard error to a pipe or redirected to a file + + All files other than _l_o_g are compressed in gzip format unless the + _c_o_m_p_r_e_s_s___i_o option has been disabled. Due to buffering, the I/O log data + will not be complete until the ssuuddoo command has completed. The output + portion of an I/O log file can be viewed with the sudoreplay(1m) utility, + which can also be used to list or search the available logs. + + 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. In most cases, logging the command output via + _l_o_g___o_u_t_p_u_t or LOG_OUTPUT is all that is required. + + Since each session's I/O logs are stored in a separate directory, + traditional log rotation utilities cannot be used to limit the number of + I/O logs. The simplest way to limit the number of I/O is by setting the + _m_a_x_s_e_q option to the maximum number of logs you wish to store. Once the + I/O log sequence number reaches _m_a_x_s_e_q, it will be reset to zero and + ssuuddooeerrss will truncate and re-use any existing I/O logs. + FFIILLEESS _/_e_t_c_/_s_u_d_o_._c_o_n_f Sudo front end configuration @@ -2507,4 +2524,4 @@ DDIISSCCLLAAIIMMEERR file distributed with ssuuddoo or https://www.sudo.ws/license.html for complete details. -Sudo 1.8.16 January 12, 2016 Sudo 1.8.16 +Sudo 1.8.16 January 16, 2016 Sudo 1.8.16 diff --git a/doc/sudoers.man.in b/doc/sudoers.man.in index 145a7430a..2ff876ed8 100644 --- a/doc/sudoers.man.in +++ b/doc/sudoers.man.in @@ -21,7 +21,7 @@ .\" Agency (DARPA) and Air Force Research Laboratory, Air Force .\" Materiel Command, USAF, under agreement number F39502-99-1-0512. .\" -.TH "SUDOERS" "5" "January 12, 2016" "Sudo @PACKAGE_VERSION@" "File Formats Manual" +.TH "SUDOERS" "5" "January 16, 2016" "Sudo @PACKAGE_VERSION@" "File Formats Manual" .nh .if n .ad l .SH "NAME" @@ -136,7 +136,7 @@ It should be specified as an octal value. For more information on configuring sudo.conf(@mansectform@), please refer to its manual. -.SS "Authentication and logging" +.SS "User Authentication" The \fBsudoers\fR security policy requires that most users authenticate @@ -235,6 +235,7 @@ The \fItty_tickets\fR option can be disabled to force the use of a single time stamp for all of a user's sessions. +.SS "Logging" \fBsudoers\fR can log both successful and unsuccessful attempts (as well as errors) to @@ -249,20 +250,28 @@ but this is changeable via the and \fIlogfile\fR Defaults settings. +See +\fILOG FORMAT\fR +for a description of the log file format. .PP -\fIsudoers\fR -also supports logging a command's input and output -streams. +\fBsudoers\fR +is also capable of running a command in a pseudo-tty and logging all +input and/or output. +The standard input, standard output and standard error can be logged +even when not associated with a terminal. I/O logging is not on by default but can be enabled using the \fIlog_input\fR and \fIlog_output\fR -Defaults flags as well as the +options as well as the \fRLOG_INPUT\fR and \fRLOG_OUTPUT\fR command tags. +See +\fII/O LOG FILES\fR +for details on how I/O log files are stored. .SS "Command environment" Since environment variables can influence program behavior, \fBsudoers\fR @@ -2220,41 +2229,12 @@ will run the command in a pseudo-tty and log all user input. If the standard input is not connected to the user's tty, due to I/O redirection or because the command is part of a pipeline, that input is also captured and stored in a separate log file. +For more information, see the +\fII/O LOG FILES\fR +section. This flag is \fIoff\fR by default. -.sp -Input is logged to the directory specified by the -\fIiolog_dir\fR -option -(\fI@iolog_dir@\fR -by default) -using a unique session ID that is included in the normal -\fBsudo\fR -log line, prefixed with -\(Lq\fRTSID=\fR\(Rq. -The -\fIiolog_file\fR -option may be used to control the format of the session ID. -Input from the user's tty is logged to the -\fIttyin\fR -file. -Input from a pipe or file is logged to the -\fIstdin\fR -file. -These files are in gzip (compressed) format unless the -\fIcompress_io\fR -option has been disabled. -Due to buffering, the I/O log data will not be complete until the -\fBsudo\fR -command has completed. -.sp -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. -In most cases, logging the command output via -\fIlog_output\fR -is all that is required. .TP 18n log_output If set, @@ -2263,44 +2243,12 @@ will run the command in a pseudo-tty and log all output that is sent to the screen, similar to the script(1) command. -If the standard output or standard error is not connected to the -user's tty, due to I/O redirection or because the command is part -of a pipeline, that output is also captured and stored in separate -log files. +For more information, see the +\fII/O LOG FILES\fR +section. This flag is \fIoff\fR by default. -.sp -Output is logged to the directory specified by the -\fIiolog_dir\fR -option -(\fI@iolog_dir@\fR -by default) -using a unique session ID that is included in the normal -\fBsudo\fR -log line, prefixed with -\(Lq\fRTSID=\fR\(Rq. -The -\fIiolog_file\fR -option may be used to control the format of the session ID. -Output from the pseudo-tty is logged to the -\fIttyout\fR -file. -Output to a pipe or redirected to a file is logged to the either the -\fIstdout\fR -or -\fIstderr\fR -files. -These files are in gzip (compressed) format unless the -\fIcompress_io\fR -option has been disabled. -Due to buffering, the I/O log data will not be complete until the -\fBsudo\fR -command has completed. -.sp -Output logs may be viewed with the -sudoreplay(@mansectsu@) -utility, which can also be used to list or search the available logs. .TP 18n log_year If set, the four-digit year will be logged in the (non-syslog) @@ -3774,7 +3722,7 @@ sudo_plugin(@mansectsu@). can log events using either syslog(3) or a simple log file. -In each case the log format is almost identical. +The log format is almost identical in both cases. .SS "Accepted command log entries" Commands that sudo runs are logged using the following format (split into multiple lines for readability): @@ -4117,6 +4065,88 @@ If the option is set to 0 (or negated with a \(oq\&!\(cq), word wrap will be disabled. +.SH "I/O LOG FILES" +When I/O logging is enabled, +\fBsudo\fR +will run the command in a pseudo-tty and log all user input and/or output. +I/O is logged to the directory specified by the +\fIiolog_dir\fR +option +(\fI@iolog_dir@\fR +by default) +using a unique session ID that is included in the +\fBsudo\fR +log line, prefixed with +\(Lq\fRTSID=\fR\(Rq. +The +\fIiolog_file\fR +option may be used to control the format of the session ID. +.PP +Each I/O log is stored in a separate directory that contains the +following files: +.TP 10n +\fIlog\fR +a text file containing the time the command was run, the name of the user +who ran +\fBsudo\fR, +the name of the target user, the name of the target group (optional), +the terminal that +\fBsudo\fR +was run from, the number of rows and columns of the terminal, +the working directory the command was run from and the path name of +the command itself (with arguments if present) +.TP 10n +\fItiming\fR +a log of the amount of time between, and the number of bytes in, each +I/O log entry (used for session playback) +.TP 10n +\fIttyin\fR +input from the user's tty (what the user types) +.TP 10n +\fIstdin\fR +input from a pipe or file +.TP 10n +\fIttyout\fR +output from the pseudo-tty (what the command writes to the screen) +.TP 10n +\fIstdout\fR +standard output to a pipe or redirected to a file +.TP 10n +\fIstderr\fR +standard error to a pipe or redirected to a file +.PP +All files other than +\fIlog\fR +are compressed in gzip format unless the +\fIcompress_io\fR +option has been disabled. +Due to buffering, the I/O log data will not be complete until the +\fBsudo\fR +command has completed. +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. +In most cases, logging the command output via +\fIlog_output\fR +or +\fRLOG_OUTPUT\fR +is all that is required. +.PP +Since each session's I/O logs are stored in a separate directory, +traditional log rotation utilities cannot be used to limit the +number of I/O logs. +The simplest way to limit the number of I/O is by setting the +\fImaxseq\fR +option to the maximum number of logs you wish to store. +Once the I/O log sequence number reaches +\fImaxseq\fR, +it will be reset to zero and +\fBsudoers\fR +will truncate and re-use any existing I/O logs. .SH "FILES" .TP 26n \fI@sysconfdir@/sudo.conf\fR diff --git a/doc/sudoers.mdoc.in b/doc/sudoers.mdoc.in index 98c076556..c30556325 100644 --- a/doc/sudoers.mdoc.in +++ b/doc/sudoers.mdoc.in @@ -19,7 +19,7 @@ .\" Agency (DARPA) and Air Force Research Laboratory, Air Force .\" Materiel Command, USAF, under agreement number F39502-99-1-0512. .\" -.Dd January 12, 2016 +.Dd January 16, 2016 .Dt SUDOERS @mansectform@ .Os Sudo @PACKAGE_VERSION@ .Sh NAME @@ -124,7 +124,7 @@ It should be specified as an octal value. For more information on configuring .Xr sudo.conf @mansectform@ , please refer to its manual. -.Ss Authentication and logging +.Ss User Authentication The .Nm sudoers security policy requires that most users authenticate @@ -224,6 +224,7 @@ The .Em tty_tickets option can be disabled to force the use of a single time stamp for all of a user's sessions. +.Ss Logging .Nm sudoers can log both successful and unsuccessful attempts (as well as errors) to @@ -238,20 +239,28 @@ but this is changeable via the and .Em logfile Defaults settings. +See +.Sx "LOG FORMAT" +for a description of the log file format. .Pp -.Em sudoers -also supports logging a command's input and output -streams. +.Nm sudoers +is also capable of running a command in a pseudo-tty and logging all +input and/or output. +The standard input, standard output and standard error can be logged +even when not associated with a terminal. I/O logging is not on by default but can be enabled using the .Em log_input and .Em log_output -Defaults flags as well as the +options as well as the .Li LOG_INPUT and .Li LOG_OUTPUT command tags. +See +.Sx "I/O LOG FILES" +for details on how I/O log files are stored. .Ss Command environment Since environment variables can influence program behavior, .Nm sudoers @@ -2079,43 +2088,12 @@ will run the command in a pseudo-tty and log all user input. If the standard input is not connected to the user's tty, due to I/O redirection or because the command is part of a pipeline, that input is also captured and stored in a separate log file. +For more information, see the +.Sx "I/O LOG FILES" +section. This flag is .Em off by default. -.Pp -Input is logged to the directory specified by the -.Em iolog_dir -option -.Po -.Pa @iolog_dir@ -by default -.Pc -using a unique session ID that is included in the normal -.Nm sudo -log line, prefixed with -.Dq Li TSID= . -The -.Em iolog_file -option may be used to control the format of the session ID. -Input from the user's tty is logged to the -.Pa ttyin -file. -Input from a pipe or file is logged to the -.Pa stdin -file. -These files are in gzip (compressed) format unless the -.Em compress_io -option has been disabled. -Due to buffering, the I/O log data will not be complete until the -.Nm sudo -command has completed. -.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. -In most cases, logging the command output via -.Em log_output -is all that is required. .It log_output If set, .Nm sudo @@ -2123,46 +2101,12 @@ will run the command in a pseudo-tty and log all output that is sent to the screen, similar to the .Xr script 1 command. -If the standard output or standard error is not connected to the -user's tty, due to I/O redirection or because the command is part -of a pipeline, that output is also captured and stored in separate -log files. +For more information, see the +.Sx "I/O LOG FILES" +section. This flag is .Em off by default. -.Pp -Output is logged to the directory specified by the -.Em iolog_dir -option -.Po -.Pa @iolog_dir@ -by default -.Pc -using a unique session ID that is included in the normal -.Nm sudo -log line, prefixed with -.Dq Li TSID= . -The -.Em iolog_file -option may be used to control the format of the session ID. -Output from the pseudo-tty is logged to the -.Pa ttyout -file. -Output to a pipe or redirected to a file is logged to the either the -.Pa stdout -or -.Pa stderr -files. -These files are in gzip (compressed) format unless the -.Em compress_io -option has been disabled. -Due to buffering, the I/O log data will not be complete until the -.Nm sudo -command has completed. -.Pp -Output logs may be viewed with the -.Xr sudoreplay @mansectsu@ -utility, which can also be used to list or search the available logs. .It log_year If set, the four-digit year will be logged in the (non-syslog) .Nm sudo @@ -3512,7 +3456,7 @@ The group provider plugin API is described in detail in can log events using either .Xr syslog 3 or a simple log file. -In each case the log format is almost identical. +The log format is almost identical in both cases. .Ss Accepted command log entries Commands that sudo runs are logged using the following format (split into multiple lines for readability): @@ -3827,6 +3771,85 @@ option is set to 0 (or negated with a .Ql \&! ) , word wrap will be disabled. .El +.Sh I/O LOG FILES +When I/O logging is enabled, +.Nm sudo +will run the command in a pseudo-tty and log all user input and/or output. +I/O is logged to the directory specified by the +.Em iolog_dir +option +.Po +.Pa @iolog_dir@ +by default +.Pc +using a unique session ID that is included in the +.Nm sudo +log line, prefixed with +.Dq Li TSID= . +The +.Em iolog_file +option may be used to control the format of the session ID. +.Pp +Each I/O log is stored in a separate directory that contains the +following files: +.Bl -tag -width 8n +.It Pa log +a text file containing the time the command was run, the name of the user +who ran +.Nm sudo , +the name of the target user, the name of the target group (optional), +the terminal that +.Nm sudo +was run from, the number of rows and columns of the terminal, +the working directory the command was run from and the path name of +the command itself (with arguments if present) +.It Pa timing +a log of the amount of time between, and the number of bytes in, each +I/O log entry (used for session playback) +.It Pa ttyin +input from the user's tty (what the user types) +.It Pa stdin +input from a pipe or file +.It Pa ttyout +output from the pseudo-tty (what the command writes to the screen) +.It Pa stdout +standard output to a pipe or redirected to a file +.It Pa stderr +standard error to a pipe or redirected to a file +.El +.Pp +All files other than +.Pa log +are compressed in gzip format unless the +.Em compress_io +option has been disabled. +Due to buffering, the I/O log data will not be complete until the +.Nm sudo +command has completed. +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. +In most cases, logging the command output via +.Em log_output +or +.Li LOG_OUTPUT +is all that is required. +.Pp +Since each session's I/O logs are stored in a separate directory, +traditional log rotation utilities cannot be used to limit the +number of I/O logs. +The simplest way to limit the number of I/O is by setting the +.Em maxseq +option to the maximum number of logs you wish to store. +Once the I/O log sequence number reaches +.Em maxseq , +it will be reset to zero and +.Nm +will truncate and re-use any existing I/O logs. .Sh FILES .Bl -tag -width 24n .It Pa @sysconfdir@/sudo.conf