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

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