From 03ba6426e7d53a15dbec038f6aac8e2fc8d9a82b Mon Sep 17 00:00:00 2001 From: "Todd C. Miller" Date: Thu, 11 Jul 2019 13:42:12 -0600 Subject: [PATCH] Expand the description of the I/O log files. --- doc/sudoers.man.in | 74 +++++++++++++++++++++++++++++++++++++-------- doc/sudoers.mdoc.in | 63 ++++++++++++++++++++++++++++++-------- 2 files changed, 111 insertions(+), 26 deletions(-) diff --git a/doc/sudoers.man.in b/doc/sudoers.man.in index 326f596a3..4e421d3d7 100644 --- a/doc/sudoers.man.in +++ b/doc/sudoers.man.in @@ -25,7 +25,7 @@ .nr BA @BAMAN@ .nr LC @LCMAN@ .nr PS @PSMAN@ -.TH "SUDOERS" "@mansectform@" "June 21, 2019" "Sudo @PACKAGE_VERSION@" "File Formats Manual" +.TH "SUDOERS" "@mansectform@" "July 11, 2019" "Sudo @PACKAGE_VERSION@" "File Formats Manual" .nh .if n .ad l .SH "NAME" @@ -4829,34 +4829,82 @@ 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 +A text file containing information about the command. +The first line consists of the following colon-delimited fields: +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) +was run from, and the number of rows and columns of the terminal. +The second and third lines contain 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) +Timing information used to replay the session. +Each line consists of the I/O log entry type and amount of time +since the last entry, followed by type-specific data. +The I/O log entry types and their corresponding type-specific data are: +.PP +.RS 10n +.PD 0 +.TP 6n +0 +standard input, number of bytes in the entry +.TP 6n +1 +standard output, number of bytes in the entry +.TP 6n +2 +standard error, number of bytes in the entry +.TP 6n +3 +terminal input, number of bytes in the entry +.TP 6n +4 +terminal output, number of bytes in the entry +.TP 6n +5 +window change, new number rows and columns +.TP 6n +6 +bug compatibility for +\fBsudo\fR +1.8.7 terminal output +.TP 6n +7 +command suspend or resume, signal number received +.PP +.RE +.PD .TP 10n \fIttyin\fR -input from the user's tty (what the user types) +Input from the user's tty, exactly as the user typed it. +No post-processing is performed. +For manual viewing, you may wish to convert carriage return characters +in the log to line feeds. +For example: +\(oqgunzip -c ttyin | tr \&"\er\&" \&"\en\&"\(cq .TP 10n \fIstdin\fR -input from a pipe or file +The standard input when no terminal is present, or input redirected from +a pipe or file. .TP 10n \fIttyout\fR -output from the pseudo-terminal (what the command writes to the screen) +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. +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 \fIstdout\fR -standard output to a pipe or redirected to a file +The standard output when no terminal is present, or output redirected to +a pipe or file. .TP 10n \fIstderr\fR -standard error to a pipe or redirected to a file +The standard error redirected to a pipe or file. .PP All files other than \fIlog\fR @@ -4864,7 +4912,7 @@ are compressed in gzip format unless the \fIcompress_io\fR flag has been disabled. Due to buffering, it is not normally possible to display the I/O logs in -real-time as the program is executing +real-time as the program is executing. The I/O log data will not be complete until the program run by \fBsudo\fR has exited or has been terminated by a signal. diff --git a/doc/sudoers.mdoc.in b/doc/sudoers.mdoc.in index c7d6a1420..bfda1a208 100644 --- a/doc/sudoers.mdoc.in +++ b/doc/sudoers.mdoc.in @@ -24,7 +24,7 @@ .nr BA @BAMAN@ .nr LC @LCMAN@ .nr PS @PSMAN@ -.Dd June 21, 2019 +.Dd July 11, 2019 .Dt SUDOERS @mansectform@ .Os Sudo @PACKAGE_VERSION@ .Sh NAME @@ -4503,28 +4503,65 @@ 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 +A text file containing information about the command. +The first line consists of the following colon-delimited fields: +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) +was run from, and the number of rows and columns of the terminal. +The second and third lines contain 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) +Timing information used to replay the session. +Each line consists of the I/O log entry type and amount of time +since the last entry, followed by type-specific data. +The I/O log entry types and their corresponding type-specific data are: +.Pp +.Bl -tag -width 4n -compact +.It 0 +standard input, number of bytes in the entry +.It 1 +standard output, number of bytes in the entry +.It 2 +standard error, number of bytes in the entry +.It 3 +terminal input, number of bytes in the entry +.It 4 +terminal output, number of bytes in the entry +.It 5 +window change, new number rows and columns +.It 6 +bug compatibility for +.Nm sudo +1.8.7 terminal output +.It 7 +command suspend or resume, signal number received +.El .It Pa ttyin -input from the user's tty (what the user types) +Input from the user's tty, exactly as the user typed it. +No post-processing is performed. +For manual viewing, you may wish to convert carriage return characters +in the log to line feeds. +For example: +.Ql gunzip -c ttyin | tr \&"\er\&" \&"\en\&" .It Pa stdin -input from a pipe or file +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) +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. +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 -standard output to a pipe or redirected to a file +The standard output when no terminal is present, or output redirected to +a pipe or file. .It Pa stderr -standard error to a pipe or redirected to a file +The standard error redirected to a pipe or file. .El .Pp All files other than @@ -4533,7 +4570,7 @@ are compressed in gzip format unless the .Em compress_io flag has been disabled. Due to buffering, it is not normally possible to display the I/O logs in -real-time as the program is executing +real-time as the program is executing. The I/O log data will not be complete until the program run by .Nm sudo has exited or has been terminated by a signal. -- 2.40.0