diff options
Diffstat (limited to 'docs/sudoreplay.mdoc.in')
| -rw-r--r-- | docs/sudoreplay.mdoc.in | 477 |
1 files changed, 477 insertions, 0 deletions
diff --git a/docs/sudoreplay.mdoc.in b/docs/sudoreplay.mdoc.in new file mode 100644 index 0000000..005cf1f --- /dev/null +++ b/docs/sudoreplay.mdoc.in @@ -0,0 +1,477 @@ +.\" +.\" SPDX-License-Identifier: ISC +.\" +.\" Copyright (c) 2009-2023 Todd C. Miller <Todd.Miller@sudo.ws> +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.Dd January 16, 2023 +.Dt SUDOREPLAY @mansectsu@ +.Os Sudo @PACKAGE_VERSION@ +.Sh NAME +.Nm sudoreplay +.Nd replay sudo session logs +.Sh SYNOPSIS +.Nm sudoreplay +.Op Fl FhnRS +.Op Fl d Ar dir +.Op Fl f Ar filter +.Op Fl m Ar num +.Op Fl s Ar num +.No ID Ns Op Ar @offset +.Pp +.Nm +.Op Fl h +.Op Fl d Ar dir +.Fl l +.Op search expression +.Sh DESCRIPTION +.Nm +plays back or lists the output logs created by +.Nm sudo . +When replaying, +.Nm +can play the session back in real-time, or the playback speed may be +adjusted (faster or slower) based on the command line options. +.Pp +The +.Em ID +should either be a six character sequence of digits and +upper case letters, e.g., +.Dq 0100A5 +or a path name. +The +.Em ID +may include an optional +.Ar @offset +suffix which may be used to start replaying at a specific time offset. +The +.Ar @offset +is specified as a number in seconds since the start of the session +with an optional decimal fraction. +.Pp +Path names may be relative to the I/O log directory +.Pa @iolog_dir@ +(unless overridden by the +.Fl d +option) or fully qualified, beginning with a +.Ql / +character. +When a command is run via +.Nm sudo +with +.Em log_output +enabled in the +.Em sudoers +file, a +.Dq TSID=ID +string is logged via +.Xr syslog 3 +or to the +.Nm sudo +log file. +The +.Em ID +may also be determined using +.Nm sudoreplay Ns 's +list mode. +.Pp +In list mode, +.Nm +can be used to find the ID of a session based on a number of criteria +such as the user, tty, or command run. +.Pp +In replay mode, if the standard input and output are connected to a terminal +and the +.Fl n +option is not specified, +.Nm +will operate interactively. +In interactive mode, +.Nm +will attempt to adjust the terminal size to match that of the session and +write directly to the terminal (not all terminals support this). +Additionally, it will poll the keyboard and act on the following keys: +.Bl -tag -width 12n +.It So Li \en Sc No or So Li \er Sc +Skip to the next replay event; useful for long pauses. +.It So Li \ Sc Pq space +Pause output; press any key to resume. +.It Ql < +Reduce the playback speed by one half. +.It Ql > +Double the playback speed. +.El +.Pp +The session can be interrupted via control-C. +When the session has finished, the terminal is restored to its +original size if it was changed during playback. +.Pp +The options are as follows: +.Bl -tag -width Ds +.It Fl d Ar dir , Fl -directory Ns = Ns Ar dir +Store session logs in +.Ar dir +instead of the default, +.Pa @iolog_dir@ . +.It Fl f Ar filter , Fl -filter Ns = Ns Ar filter +Select which I/O type(s) to display. +By default, +.Nm +will display the command's standard output, standard error, and tty output. +The +.Ar filter +argument is a comma-separated list, consisting of one or more of following: +.Em stdin , +.Em stdout , +.Em stderr , +.Em ttyin , +and +.Em ttyout . +.It Fl F , -follow +Enable +.Dq follow mode . +When replaying a session, +.Nm +will ignore end-of-file and keep replaying until the log is complete. +This can be used to replay a session that is still in progress, +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. +Versions of +.Nm sudo +prior to 1.9.1 do not clear the write bits upon completion. +.It Fl h , -help +Display a short help message to the standard output and exit. +.It Fl l , -list Op Ar search expression +Enable +.Dq list mode . +In this mode, +.Nm +will list available sessions in a format similar to the +.Nm sudo +log file format, sorted by file name (or sequence number). +Any control characters present in the log data are formatted in octal +with a leading +.Ql # +character. +For example, a horizontal tab is displayed as +.Ql #011 +and an embedded carriage return is displayed as +.Ql #015 . +Space characters in the command name and arguments are also formatted in octal. +.Pp +If a +.Ar search expression +is specified, it will be used to restrict the IDs that are displayed. +An expression is composed of the following predicates: +.Bl -tag -width 6n +.It command Ar pattern +Evaluates to true if the command run matches the POSIX extended +regular expression +.Ar pattern . +.It cwd Ar directory +Evaluates to true if the command was run with the specified current +working directory. +.It fromdate Ar date +Evaluates to true if the command was run on or after +.Ar date . +See +.Sx Date and time format +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 . +Unless a +.Ar runas_group +was explicitly specified when +.Nm sudo +was run this field will be empty in the log. +.It host Ar hostname +Evaluates to true if the command was run on the specified +.Ar hostname . +.It runas Ar runas_user +Evaluates to true if the command was run as the specified +.Ar runas_user . +By default, +.Nm sudo +runs commands as the +.Sy root +user. +.It todate Ar date +Evaluates to true if the command was run on or prior to +.Ar date . +See +.Sx Date and time format +for a description of supported date and time formats. +.It tty Ar tty name +Evaluates to true if the command was run on the specified terminal device. +The +.Ar tty name +should be specified without the +.Pa /dev/ +prefix, e.g., +.Pa tty01 +instead of +.Pa /dev/tty01 . +.It user Ar user name +Evaluates to true if the ID matches a command run by +.Ar user name . +.El +.Pp +Predicates may be abbreviated to the shortest unique string. +.Pp +Predicates may be combined using +.Em and , +.Em or , +and +.Em \&! +operators as well as +.Ql \&( +and +.Ql \&) +grouping (parentheses must generally be escaped from the shell). +The +.Em and +operator is optional, adjacent predicates have an implied +.Em and +unless separated by an +.Em or . +.It Fl m , -max-wait Ar max_wait +Specify an upper bound on how long to wait between key presses or output data. +By default, +.Nm +will accurately reproduce the delays between key presses or program output. +However, this can be tedious when the session includes long pauses. +When the +.Fl m +option is specified, +.Nm +will limit these pauses to at most +.Em max_wait +seconds. +The value may be specified as a floating point number, e.g., +.Em 2.5 . +A +.Em max_wait +of zero or less will eliminate the pauses entirely. +.It Fl n , -non-interactive +Do not prompt for user input or attempt to re-size the terminal. +The session is written to the standard output, not directly to +the user's terminal. +.It Fl R , -no-resize +Do not attempt to re-size the terminal to match the terminal size +of the session. +.It Fl S , -suspend-wait +Wait while the command was suspended. +By default, +.Nm +will ignore the time interval between when the command was suspended +and when it was resumed. +If the +.Fl S +option is specified, +.Nm +will wait instead. +.It Fl s , -speed Ar speed_factor +This option causes +.Nm +to adjust the number of seconds it will wait between key presses or +program output. +This can be used to slow down or speed up the display. +For example, a +.Ar speed_factor +of +.Em 2 +would make the output twice as fast whereas a +.Ar speed_factor +of +.Em .5 +would make the output twice as slow. +.It Fl V , -version +Print the +.Nm +versions version number and exit. +.El +.Ss Date and time format +The time and date may be specified multiple ways, common formats include: +.Bl -tag -width 6n +.It HH:MM:SS am MM/DD/CCYY timezone +24 hour time may be used in place of am/pm. +.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. +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 +The month name may be abbreviated. +.El +.Pp +Either time or date may be omitted, the am/pm and timezone are optional. +If no date is specified, the current day is assumed; if no time is +specified, the first second of the specified date is used. +The less significant parts of both time and date may also be omitted, +in which case zero is assumed. +.Pp +The following are all valid time and date specifications: +.Bl -tag -width 6n +.It now +The current time and date. +.It tomorrow +Exactly one day from now. +.It yesterday +24 hours ago. +.It 2 hours ago +2 hours ago. +.It next Friday +The first second of the Friday in the next (upcoming) week. +Not to be confused with +.Dq this Friday +which would match the Friday of the current week. +.It last week +The current time but 7 days ago. +This is equivalent to +.Dq a week ago . +.It a fortnight ago +The current time but 14 days ago. +.It 10:01 am 9/17/2009 +10:01 am, September 17, 2009. +.It 10:01 am +10:01 am on the current day. +.It 10 +10:00 am on the current day. +.It 9/17/2009 +00:00 am, September 17, 2009. +.It 10:01 am Sep 17, 2009 +10:01 am, September 17, 2009. +.El +.Pp +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 +.Dq next Monday . +When used with units of weeks, months, years, etc +the result will be one more than expected. +For example, +.Dq next week +will result in a time exactly two weeks from now, which is probably +not what was intended. +This will be addressed in a future version of +.Nm . +.Ss Debugging sudoreplay +.Nm +versions 1.8.4 and higher support a flexible debugging framework +that is configured via +.Em Debug +lines in the +.Xr sudo.conf @mansectform@ +file. +.Pp +For more information on configuring +.Xr sudo.conf @mansectform@ , +refer to its manual. +.Sh FILES +.Bl -tag -width 24n +.It Pa @sysconfdir@/sudo.conf +Debugging framework configuration +.It Pa @iolog_dir@ +The default I/O log directory. +.It Pa @iolog_dir@/00/00/01/log +Example session log info. +.It Pa @iolog_dir@/00/00/01/log.json +Example session log info (JSON format). +.It Pa @iolog_dir@/00/00/01/stdin +Example session standard input log. +.It Pa @iolog_dir@/00/00/01/stdout +Example session standard output log. +.It Pa @iolog_dir@/00/00/01/stderr +Example session standard error log. +.It Pa @iolog_dir@/00/00/01/ttyin +Example session tty input file. +.It Pa @iolog_dir@/00/00/01/ttyout +Example session tty output file. +.It Pa @iolog_dir@/00/00/01/timing +Example session timing file. +.El +.Pp +The +.Em stdin , +.Em stdout +and +.Em stderr +files will be empty unless +.Nm sudo +was used as part of a pipeline for a particular command. +.Sh EXAMPLES +List sessions run by user +.Em millert : +.Bd -literal -offset 4n +# sudoreplay -l user millert +.Ed +.Pp +List sessions run by user +.Em bob +with a command containing the string vi: +.Bd -literal -offset 4n +# sudoreplay -l user bob command vi +.Ed +.Pp +List sessions run by user +.Em jeff +that match a regular expression: +.Bd -literal -offset 4n +# sudoreplay -l user jeff command '/bin/[a-z]*sh' +.Ed +.Pp +List sessions run by jeff or bob on the console: +.Bd -literal -offset 4n +# sudoreplay -l ( user jeff or user bob ) tty console +.Ed +.Sh SEE ALSO +.Xr script 1 , +.Xr sudo.conf @mansectform@ , +.Xr sudo @mansectsu@ +.Sh AUTHORS +Many people have worked on +.Nm sudo +over the years; this version consists of code written primarily by: +.Bd -ragged -offset indent +.An Todd C. Miller +.Ed +.Pp +See the CONTRIBUTORS.md file in the +.Nm sudo +distribution (https://www.sudo.ws/about/contributors/) for an +exhaustive list of people who have contributed to +.Nm sudo . +.Sh BUGS +If you believe you have found a bug in +.Nm , +you can submit a bug report at https://bugzilla.sudo.ws/ +.Sh SUPPORT +Limited free support is available via the sudo-users mailing list, +see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or +search the archives. +.Sh DISCLAIMER +.Nm +is provided +.Dq AS IS +and any express or implied warranties, including, but not limited +to, the implied warranties of merchantability and fitness for a +particular purpose are disclaimed. +See the LICENSE.md file distributed with +.Nm sudo +or https://www.sudo.ws/about/license/ for complete details. |