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

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