Copyright (c) 2009-2010 Todd C. Miller <Todd.Miller@courtesan.com>

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.
ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

=pod

=head1 NAME

sudoreplay - replay sudo session logs

=head1 SYNOPSIS

B<sudoreplay> [B<-d> I<directory>] [B<-f> I<filter>] [B<-m> I<max_wait>] [B<-s> I<speed_factor>] ID

B<sudoreplay> [B<-d> I<directory>] -l [search expression]

=head1 DESCRIPTION

B<sudoreplay> plays back or lists the session logs created by
B<sudo>.  When replaying, B<sudoreplay> can play the session back
in real-time, or the playback speed may be adjusted (faster or
slower) based on the command line options.  The I<ID> should be
a six character sequence of digits and upper case letters, e.g.
0100A5, which is logged by B<sudo> when a command is run with
session logging enabled.

In list mode, B<sudoreplay> can be used to find the ID of a session
based on a number of criteria such as the user, tty or command run.

In replay mode, if the standard output has not been redirected,
B<sudoreplay> will act on the following keys:

=over 8

=item ' ' (space)

Pause output; press any key to resume.

=item '<'

Reduce the playback speed by one half.

=item '>'

Double the playback speed.

=back

=head1 OPTIONS

B<sudoreplay> accepts the following command line options:

=over 12

=item -d I<directory>

Use I<directory> to for the session logs instead of the default,
F</var/log/sudo-io>.

=item -f I<filter>

By default, B<sudoreplay> will play back the command's standard
output, standard error and tty output.  The I<-f> option can be
used to select which of these to output.  The I<filter> argument
is a comma-separated list, consisting of one or more of following:
I<stdout>, I<stderr>, and I<ttyout>.

=item -l

Enable "list mode".  In this mode, B<sudoreplay> will list available
session IDs.  If a I<search expression> is specified, it will be
used to restrict the IDs that are displayed.  An expression is
composed of the following predicates:

=over 8

=item command I<command pattern>

Evaluates to true if the command run matches I<command pattern>.
On systems with POSIX regular expression support, the pattern may
be an extended regular expression.  On systems without POSIX regular
expression support, a simple substring match is performed instead.

=item cwd I<directory>

Evaluates to true if the command was run with the specified current
working directory.

=item fromdate I<date>

Evaluates to true if the command was run on or after I<date>.
See L<"Date and time format"> for a description of supported
date and time formats.

=item group I<runas_group>

Evaluates to true if the command was run with the specified
I<runas_group>.  Note that unless a I<runas_group> was explicitly
specified when B<sudo> was run this field will be empty in the log.

=item runas I<runas_user>

Evaluates to true if the command was run as the specified I<runas_user>.
Note that B<sudo> runs commands as user I<root> by default.

=item todate I<date>

Evaluates to true if the command was run on or prior to I<date>.
See L<"Date and time format"> for a description of supported
date and time formats.

=item tty I<tty>

Evaluates to true if the command was run on the specified terminal
device.  The I<tty> should be specified without the F</dev/> prefix,
e.g.  F<tty01> instead of F</dev/tty01>.

=item user I<user name>

Evaluates to true if the ID matches a command run by I<user name>.

=back

Predicates may be abbreviated to the shortest unique string (currently
all predicates may be shortened to a single character).

Predicates may be combined using I<and>, I<or> and I<!> operators
as well as C<'('> and C<')'> for grouping (note that parentheses
must generally be escaped from the shell).  The I<and> operator is
optional, adjacent predicates have an implied I<and> unless separated
by an I<or>.

=item -m I<max_wait>

Specify an upper bound on how long to wait between key presses or
output data.  By default, B<sudo_replay> will accurately reproduce
the delays between key presses or program output.  However, this
can be tedious when the session includes long pauses.  When the
I<-m> option is specified, B<sudoreplay> will limit these pauses
to at most I<max_wait> seconds.  The value may be specified as a
floating point number, .e.g. I<2.5>.

=item -s I<speed_factor>

This option causes B<sudoreplay> 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
I<speed_factor> of I<2> would make the output twice as fast whereas
a I<speed_factor> of <.5> would make the output twice as slow.

=item -V

The B<-V> (version) option causes B<sudoreplay> to print its version number
and exit.

=back

=head2 Date and time format

The time and date may be specified multiple ways, common formats include:

=over 8

=item HH:MM:SS am MM/DD/CCYY timezone

24 hour time may be used in place of am/pm.

=item 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.  Note that month and day of the week names must
be specified in English.

=item CCYY-MM-DD HH:MM:SS

ISO time format

=item DD Month CCYY HH:MM:SS

The month name may be abbreviated.

=back

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.  For example, the following
are all valid:

The following are all valid time and date specifications:

=over 8

=item now

The current time and date.

=item tomorrow

Exactly one day from now.

=item yesterday

24 hours ago.

=item 2 hours ago

2 hours ago.

=item next Friday

The first second of the next Friday.

=item this week

The current time but the first day of the coming week.

=item a fortnight ago

The current time but 14 days ago.

=item 10:01 am 9/17/2009

10:01 am, September 17, 2009.

=item 10:01 am

10:01 am on the current day.

=item 10

10:00 am on the current day.

=item 9/17/2009

00:00 am, September 17, 2009.

=item 10:01 am Sep 17, 2009

10:01 am, September 17, 2009.

=back

=head1 FILES

=over 24

=item F</var/log/sudo-io>

The default I/O log directory.

=item F</var/log/sudo-io/00/00/01/log>

Example session log info.

=item F</var/log/sudo-io/00/00/01/stdin>

Example session standard input log.

=item F</var/log/sudo-io/00/00/01/stdout>

Example session standard output log.

=item F</var/log/sudo-io/00/00/01/stderr>

Example session standard error log.

=item F</var/log/sudo-io/00/00/01/ttyin>

Example session tty input file.

=item F</var/log/sudo-io/00/00/01/ttyout>

Example session tty output file.

=item F</var/log/sudo-io/00/00/01/timing>

Example session timing file.

=back

Note that the I<stdin>, I<stdout> and I<stderr> files will be empty
unless B<sudo> was used as part of a pipeline for a particular
command.

=head1 EXAMPLES

List sessions run by user I<millert>:

 sudoreplay -l user millert

List sessions run by user I<bob> with a command containing the string vi:

 sudoreplay -l user bob command vi

List sessions run by user I<jeff> that match a regular expression:

 sudoreplay -l user jeff command '/bin/[a-z]*sh'

List sessions run by jeff or bob on the console:

 sudoreplay -l ( user jeff or user bob ) tty console

=head1 SEE ALSO

L<sudo(8)>, L<script(1)>

=head1 AUTHOR

Todd C. Miller

=head1 BUGS

If you feel you have found a bug in B<sudoreplay>, please submit a bug report
at http://www.sudo.ws/sudo/bugs/

=head1 SUPPORT

Limited free support is available via the sudo-users mailing list,
see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
search the archives.

=head1 DISCLAIMER

B<sudoreplay> is provided ``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
file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
for complete details.