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 session IDs.  If a I<search expression> is specified, it will be
  92 used to restrict the IDs that are displayed.  An expression is
  93 composed of the following predicates:
  94
  95 =over 8
  96
  97 =item command I<command pattern>
  98
  99 Evaluates to true if the command run matches I<command pattern>.
 100 On systems with POSIX regular expression support, the pattern may
 101 be an extended regular expression.  On systems without POSIX regular
 102 expression support, a simple substring match is performed instead.
 103
 104 =item cwd I<directory>
 105
 106 Evaluates to true if the command was run with the specified current
 107 working directory.
 108
 109 =item fromdate I<date>
 110
 111 Evaluates to true if the command was run on or after I<date>.
 112 See L<"Date and time format"> for a description of supported
 113 date and time formats.
 114
 115 =item group I<runas_group>
 116
 117 Evaluates to true if the command was run with the specified
 118 I<runas_group>.  Note that unless a I<runas_group> was explicitly
 119 specified when B<sudo> was run this field will be empty in the log.
 120
 121 =item runas I<runas_user>
 122
 123 Evaluates to true if the command was run as the specified I<runas_user>.
 124 Note that B<sudo> runs commands as user I<root> by default.
 125
 126 =item todate I<date>
 127
 128 Evaluates to true if the command was run on or prior to I<date>.
 129 See L<"Date and time format"> for a description of supported
 130 date and time formats.
 131
 132 =item tty I<tty>
 133
 134 Evaluates to true if the command was run on the specified terminal
 135 device.  The I<tty> should be specified without the F</dev/> prefix,
 136 e.g.  F<tty01> instead of F</dev/tty01>.
 137
 138 =item user I<user name>
 139
 140 Evaluates to true if the ID matches a command run by I<user name>.
 141
 142 =back
 143
 144 Predicates may be abbreviated to the shortest unique string (currently
 145 all predicates may be shortened to a single character).
 146
 147 Predicates may be combined using I<and>, I<or> and I<!> operators
 148 as well as C<'('> and C<')'> for grouping (note that parentheses
 149 must generally be escaped from the shell).  The I<and> operator is
 150 optional, adjacent predicates have an implied I<and> unless separated
 151 by an I<or>.
 152
 153 =item -m I<max_wait>
 154
 155 Specify an upper bound on how long to wait between key presses or
 156 output data.  By default, B<sudo_replay> will accurately reproduce
 157 the delays between key presses or program output.  However, this
 158 can be tedious when the session includes long pauses.  When the
 159 I<-m> option is specified, B<sudoreplay> will limit these pauses
 160 to at most I<max_wait> seconds.  The value may be specified as a
 161 floating point number, .e.g. I<2.5>.
 162
 163 =item -s I<speed_factor>
 164
 165 This option causes B<sudoreplay> to adjust the number of seconds
 166 it will wait between key presses or program output.  This can be
 167 used to slow down or speed up the display.  For example, a
 168 I<speed_factor> of I<2> would make the output twice as fast whereas
 169 a I<speed_factor> of <.5> would make the output twice as slow.
 170
 171 =item -V
 172
 173 The B<-V> (version) option causes B<sudoreplay> to print its version number
 174 and exit.
 175
 176 =back
 177
 178 =head2 Date and time format
 179
 180 The time and date may be specified multiple ways, common formats include:
 181
 182 =over 8
 183
 184 =item HH:MM:SS am MM/DD/CCYY timezone
 185
 186 24 hour time may be used in place of am/pm.
 187
 188 =item HH:MM:SS am Month, Day Year timezone
 189
 190 24 hour time may be used in place of am/pm, and month and day names
 191 may be abbreviated.  Note that month and day of the week names must
 192 be specified in English.
 193
 194 =item CCYY-MM-DD HH:MM:SS
 195
 196 ISO time format
 197
 198 =item DD Month CCYY HH:MM:SS
 199
 200 The month name may be abbreviated.
 201
 202 =back
 203
 204 Either time or date may be omitted, the am/pm and timezone are
 205 optional.  If no date is specified, the current day is assumed; if
 206 no time is specified, the first second of the specified date is
 207 used.  The less significant parts of both time and date may also
 208 be omitted, in which case zero is assumed.  For example, the following
 209 are all valid:
 210
 211 The following are all valid time and date specifications:
 212
 213 =over 8
 214
 215 =item now
 216
 217 The current time and date.
 218
 219 =item tomorrow
 220
 221 Exactly one day from now.
 222
 223 =item yesterday
 224
 225 24 hours ago.
 226
 227 =item 2 hours ago
 228
 229 2 hours ago.
 230
 231 =item next Friday
 232
 233 The first second of the next Friday.
 234
 235 =item this week
 236
 237 The current time but the first day of the coming week.
 238
 239 =item a fortnight ago
 240
 241 The current time but 14 days ago.
 242
 243 =item 10:01 am 9/17/2009
 244
 245 10:01 am, September 17, 2009.
 246
 247 =item 10:01 am
 248
 249 10:01 am on the current day.
 250
 251 =item 10
 252
 253 10:00 am on the current day.
 254
 255 =item 9/17/2009
 256
 257 00:00 am, September 17, 2009.
 258
 259 =item 10:01 am Sep 17, 2009
 260
 261 10:01 am, September 17, 2009.
 262
 263 =back
 264
 265 =head1 FILES
 266
 267 =over 24
 268
 269 =item F</var/log/sudo-io>
 270
 271 The default I/O log directory.
 272
 273 =item F</var/log/sudo-io/00/00/01/log>
 274
 275 Example session log info.
 276
 277 =item F</var/log/sudo-io/00/00/01/stdin>
 278
 279 Example session standard input log.
 280
 281 =item F</var/log/sudo-io/00/00/01/stdout>
 282
 283 Example session standard output log.
 284
 285 =item F</var/log/sudo-io/00/00/01/stderr>
 286
 287 Example session standard error log.
 288
 289 =item F</var/log/sudo-io/00/00/01/ttyin>
 290
 291 Example session tty input file.
 292
 293 =item F</var/log/sudo-io/00/00/01/ttyout>
 294
 295 Example session tty output file.
 296
 297 =item F</var/log/sudo-io/00/00/01/timing>
 298
 299 Example session timing file.
 300
 301 =back
 302
 303 Note that the I<stdin>, I<stdout> and I<stderr> files will be empty
 304 unless B<sudo> was used as part of a pipeline for a particular
 305 command.
 306
 307 =head1 EXAMPLES
 308
 309 List sessions run by user I<millert>:
 310
 311  sudoreplay -l user millert
 312
 313 List sessions run by user I<bob> with a command containing the string vi:
 314
 315  sudoreplay -l user bob command vi
 316
 317 List sessions run by user I<jeff> that match a regular expression:
 318
 319  sudoreplay -l user jeff command '/bin/[a-z]*sh'
 320
 321 List sessions run by jeff or bob on the console:
 322
 323  sudoreplay -l ( user jeff or user bob ) tty console
 324
 325 =head1 SEE ALSO
 326
 327 L<sudo(8)>, L<script(1)>
 328
 329 =head1 AUTHOR
 330
 331 Todd C. Miller
 332
 333 =head1 BUGS
 334
 335 If you feel you have found a bug in B<sudoreplay>, please submit a bug report
 336 at http://www.sudo.ws/sudo/bugs/
 337
 338 =head1 SUPPORT
 339
 340 Limited free support is available via the sudo-users mailing list,
 341 see http://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
 342 search the archives.
 343
 344 =head1 DISCLAIMER
 345
 346 B<sudoreplay> is provided ``AS IS'' and any express or implied warranties,
 347 including, but not limited to, the implied warranties of merchantability
 348 and fitness for a particular purpose are disclaimed.  See the LICENSE
 349 file distributed with B<sudo> or http://www.sudo.ws/sudo/license.html
 350 for complete details.