git.gag.com Git - debian/sudo/blob - doc/sudoreplay.pod

   1 Copyright (c) 2009-2011 Todd C. Miller <Todd.Miller@courtesan.com>
   2
   3 Permission to use, copy, modify, and distribute this software for any
   4 purpose with or without fee is hereby granted, provided that the above
   5 copyright notice and this permission notice appear in all copies.
   6
   7 THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
   8 WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
   9 MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  10 ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  11 WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  12 ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  13 OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  14 ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
  15
  16 =pod
  17
  18 =head1 NAME
  19
  20 sudoreplay - replay sudo session logs
  21
  22 =head1 SYNOPSIS
  23
  24 B<sudoreplay> [B<-h>] [B<-d> I<directory>] [B<-f> I<filter>] [B<-m> I<max_wait>] [B<-s> I<speed_factor>] ID
  25
  26 B<sudoreplay> [B<-h>] [B<-d> I<directory>] -l [search expression]
  27
  28 =head1 DESCRIPTION
  29
  30 B<sudoreplay> plays back or lists the output logs created by B<sudo>.
  31 When replaying, B<sudoreplay> can play the session back in real-time,
  32 or the playback speed may be adjusted (faster or slower) based on
  33 the command line options.
  34
  35 The I<ID> should either be a six character sequence of digits and
  36 upper case letters, e.g. C<0100A5>, or a pattern matching the
  37 I<iolog_file> option in the I<sudoers> file.  When a command is run
  38 via B<sudo> with I<log_output> enabled in the I<sudoers> file, a
  39 C<TSID=ID> string is logged via syslog or to the B<sudo> log file.
  40 The I<ID> may also be determined using B<sudoreplay>'s list mode.
  41
  42 In list mode, B<sudoreplay> can be used to find the ID of a session
  43 based on a number of criteria such as the user, tty or command run.
  44
  45 In replay mode, if the standard output has not been redirected,
  46 B<sudoreplay> will act on the following keys:
  47
  48 =over 8
  49
  50 =item ' ' (space)
  51
  52 Pause output; press any key to resume.
  53
  54 =item '<'
  55
  56 Reduce the playback speed by one half.
  57
  58 =item '>'
  59
  60 Double the playback speed.
  61
  62 =back
  63
  64 =head1 OPTIONS
  65
  66 B<sudoreplay> accepts the following command line options:
  67
  68 =over 12
  69
  70 =item -d I<directory>
  71
  72 Use I<directory> to for the session logs instead of the default,
  73 F</var/log/sudo-io>.
  74
  75 =item -f I<filter>
  76
  77 By default, B<sudoreplay> will play back the command's standard
  78 output, standard error and tty output.  The I<-f> option can be
  79 used to select which of these to output.  The I<filter> argument
  80 is a comma-separated list, consisting of one or more of following:
  81 I<stdout>, I<stderr>, and I<ttyout>.
  82
  83 =item -h
  84
  85 The B<-h> (I<help>) option causes B<sudoreplay> to print a short
  86 help message to the standard output and exit.
  87
  88 =item -l [I<search expression>]
  89
  90 Enable "list mode".  In this mode, B<sudoreplay> will list available
  91 sessions in a format similar to the B<sudo> log file format, sorted
  92 by file name (or sequence number).  If a I<search expression> is
  93 specified, it will be used to restrict the IDs that are displayed.
  94 An expression is composed of the following predicates:
  95
  96 =over 8
  97
  98 =item command I<command pattern>
  99
 100 Evaluates to true if the command run matches I<command pattern>.
 101 On systems with POSIX regular expression support, the pattern may
 102 be an extended regular expression.  On systems without POSIX regular
 103 expression support, a simple substring match is performed instead.
 104
 105 =item cwd I<directory>
 106
 107 Evaluates to true if the command was run with the specified current
 108 working directory.
 109
 110 =item fromdate I<date>
 111
 112 Evaluates to true if the command was run on or after I<date>.
 113 See L<"Date and time format"> for a description of supported
 114 date and time formats.
 115
 116 =item group I<runas_group>
 117
 118 Evaluates to true if the command was run with the specified
 119 I<runas_group>.  Note that unless a I<runas_group> was explicitly
 120 specified when B<sudo> was run this field will be empty in the log.
 121
 122 =item runas I<runas_user>
 123
 124 Evaluates to true if the command was run as the specified I<runas_user>.
 125 Note that B<sudo> runs commands as user I<root> by default.
 126
 127 =item todate I<date>
 128
 129 Evaluates to true if the command was run on or prior to I<date>.
 130 See L<"Date and time format"> for a description of supported
 131 date and time formats.
 132
 133 =item tty I<tty>
 134
 135 Evaluates to true if the command was run on the specified terminal
 136 device.  The I<tty> should be specified without the F</dev/> prefix,
 137 e.g.  F<tty01> instead of F</dev/tty01>.
 138
 139 =item user I<user name>
 140
 141 Evaluates to true if the ID matches a command run by I<user name>.
 142
 143 =back
 144
 145 Predicates may be abbreviated to the shortest unique string (currently
 146 all predicates may be shortened to a single character).
 147
 148 Predicates may be combined using I<and>, I<or> and I<!> operators
 149 as well as C<'('> and C<')'> for grouping (note that parentheses
 150 must generally be escaped from the shell).  The I<and> operator is
 151 optional, adjacent predicates have an implied I<and> unless separated
 152 by an I<or>.
 153
 154 =item -m I<max_wait>
 155
 156 Specify an upper bound on how long to wait between key presses or
 157 output data.  By default, B<sudo_replay> will accurately reproduce
 158 the delays between key presses or program output.  However, this
 159 can be tedious when the session includes long pauses.  When the
 160 I<-m> option is specified, B<sudoreplay> will limit these pauses
 161 to at most I<max_wait> seconds.  The value may be specified as a
 162 floating point number, .e.g. I<2.5>.
 163
 164 =item -s I<speed_factor>
 165
 166 This option causes B<sudoreplay> to adjust the number of seconds
 167 it will wait between key presses or program output.  This can be
 168 used to slow down or speed up the display.  For example, a
 169 I<speed_factor> of I<2> would make the output twice as fast whereas
 170 a I<speed_factor> of <.5> would make the output twice as slow.
 171
 172 =item -V
 173
 174 The B<-V> (version) option causes B<sudoreplay> to print its version number
 175 and exit.
 176
 177 =back
 178
 179 =head2 Date and time format
 180
 181 The time and date may be specified multiple ways, common formats include:
 182
 183 =over 8
 184
 185 =item HH:MM:SS am MM/DD/CCYY timezone
 186
 187 24 hour time may be used in place of am/pm.
 188
 189 =item HH:MM:SS am Month, Day Year timezone
 190
 191 24 hour time may be used in place of am/pm, and month and day names
 192 may be abbreviated.  Note that month and day of the week names must
 193 be specified in English.
 194
 195 =item CCYY-MM-DD HH:MM:SS
 196
 197 ISO time format
 198
 199 =item DD Month CCYY HH:MM:SS
 200
 201 The month name may be abbreviated.
 202
 203 =back
 204
 205 Either time or date may be omitted, the am/pm and timezone are
 206 optional.  If no date is specified, the current day is assumed; if
 207 no time is specified, the first second of the specified date is
 208 used.  The less significant parts of both time and date may also
 209 be omitted, in which case zero is assumed.  For example, the following
 210 are all valid:
 211
 212 The following are all valid time and date specifications:
 213
 214 =over 8
 215
 216 =item now
 217
 218 The current time and date.
 219
 220 =item tomorrow
 221
 222 Exactly one day from now.
 223
 224 =item yesterday
 225
 226 24 hours ago.
 227
 228 =item 2 hours ago
 229
 230 2 hours ago.
 231
 232 =item next Friday
 233
 234 The first second of the next Friday.
 235
 236 =item this week
 237
 238 The current time but the first day of the coming week.
 239
 240 =item a fortnight ago
 241
 242 The current time but 14 days ago.
 243
 244 =item 10:01 am 9/17/2009
 245
 246 10:01 am, September 17, 2009.
 247
 248 =item 10:01 am
 249
 250 10:01 am on the current day.
 251
 252 =item 10
 253
 254 10:00 am on the current day.
 255
 256 =item 9/17/2009
 257
 258 00:00 am, September 17, 2009.
 259
 260 =item 10:01 am Sep 17, 2009
 261
 262 10:01 am, September 17, 2009.
 263
 264 =back
 265
 266 =head1 FILES
 267
 268 =over 24
 269
 270 =item F</var/log/sudo-io>
 271
 272 The default I/O log directory.
 273
 274 =item F</var/log/sudo-io/00/00/01/log>
 275
 276 Example session log info.
 277
 278 =item F</var/log/sudo-io/00/00/01/stdin>
 279
 280 Example session standard input log.
 281
 282 =item F</var/log/sudo-io/00/00/01/stdout>
 283
 284 Example session standard output log.
 285
 286 =item F</var/log/sudo-io/00/00/01/stderr>
 287
 288 Example session standard error log.
 289
 290 =item F</var/log/sudo-io/00/00/01/ttyin>
 291
 292 Example session tty input file.
 293
 294 =item F</var/log/sudo-io/00/00/01/ttyout>
 295
 296 Example session tty output file.
 297
 298 =item F</var/log/sudo-io/00/00/01/timing>
 299
 300 Example session timing file.
 301
 302 =back
 303
 304 Note that the I<stdin>, I<stdout> and I<stderr> files will be empty
 305 unless B<sudo> was used as part of a pipeline for a particular
 306 command.
 307
 308 =head1 EXAMPLES
 309
 310 List sessions run by user I<millert>:
 311
 312  sudoreplay -l user millert
 313
 314 List sessions run by user I<bob> with a command containing the string vi:
 315
 316  sudoreplay -l user bob command vi
 317
 318 List sessions run by user I<jeff> that match a regular expression:
 319
 320  sudoreplay -l user jeff command '/bin/[a-z]*sh'
 321
 322 List sessions run by jeff or bob on the console:
 323
 324  sudoreplay -l ( user jeff or user bob ) tty console
 325
 326 =head1 SEE ALSO
 327
 328 L<sudo(8)>, L<script(1)>
 329
 330 =head1 AUTHOR
 331
 332 Todd C. Miller
 333
 334 =head1 BUGS
 335
 336 If you feel you have found a bug in B<sudoreplay>, please submit a bug report
 337 at http://www.sudo.ws/sudo/bugs/
 338
 339 =head1 SUPPORT
 340
 341 Limited free support is available via the sudo-users mailing list,
 342 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
 343 search the archives.
 344
 345 =head1 DISCLAIMER
 346
 347 B<sudoreplay> is provided ``AS IS'' and any express or implied warranties,
 348 including, but not limited to, the implied warranties of merchantability
 349 and fitness for a particular purpose are disclaimed.  See the LICENSE
 350 file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
 351 for complete details.