granicus.if.org Git - sudo/blob - doc/sudoreplay.mdoc.in

   1 .\"
   2 .\" SPDX-License-Identifier: ISC
   3 .\"
   4 .\" Copyright (c) 2009-2019 Todd C. Miller <Todd.Miller@sudo.ws>
   5 .\"
   6 .\" Permission to use, copy, modify, and distribute this software for any
   7 .\" purpose with or without fee is hereby granted, provided that the above
   8 .\" copyright notice and this permission notice appear in all copies.
   9 .\"
  10 .\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
  11 .\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
  12 .\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
  13 .\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
  14 .\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
  15 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
  16 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
  17 .\"
  18 .Dd August 27, 2019
  19 .Dt SUDOREPLAY @mansectsu@
  20 .Os Sudo @PACKAGE_VERSION@
  21 .Sh NAME
  22 .Nm sudoreplay
  23 .Nd replay sudo session logs
  24 .Sh SYNOPSIS
  25 .Nm sudoreplay
  26 .Op Fl hnRS
  27 .Op Fl d Ar dir
  28 .Op Fl f Ar filter
  29 .Op Fl m Ar num
  30 .Op Fl s Ar num
  31 ID
  32 .Pp
  33 .Nm
  34 .Op Fl h
  35 .Op Fl d Ar dir
  36 .Fl l
  37 .Op search expression
  38 .Sh DESCRIPTION
  39 .Nm
  40 plays back or lists the output logs created by
  41 .Nm sudo .
  42 When replaying,
  43 .Nm
  44 can play the session back in real-time, or the playback speed may be
  45 adjusted (faster or slower) based on the command line options.
  46 .Pp
  47 The
  48 .Em ID
  49 should either be a six character sequence of digits and
  50 upper case letters, e.g.,
  51 .Li 0100A5 ,
  52 a pattern matching the
  53 .Em iolog_file
  54 option in the
  55 .Em sudoers
  56 file, or a path name.
  57 Path names may be relative to the
  58 .Em iolog_dir
  59 option in the
  60 .Em sudoers
  61 file (unless overridden by the
  62 .Fl d
  63 option) or fully qualified, beginning with a
  64 .Ql /
  65 character.
  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 's
  81 list mode.
  82 .Pp
  83 In list mode,
  84 .Nm
  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 input and output are connected to a terminal
  89 and the
  90 .Fl n
  91 option is not specified,
  92 .Nm
  93 will operate interactively.
  94 In interactive mode,
  95 .Nm
  96 will attempt to adjust the terminal size to match that of the session and
  97 write directly to the terminal (not all terminals support this).
  98 Additionally, it will poll the keyboard and act on the following keys:
  99 .Bl -tag -width 12n
 100 .It So Li \en Sc No or So Li \er Sc
 101 Skip to the next replay event; useful for long pauses.
 102 .It So Li \  Sc Pq space
 103 Pause output; press any key to resume.
 104 .It Ql <
 105 Reduce the playback speed by one half.
 106 .It Ql >
 107 Double the playback speed.
 108 .El
 109 .Pp
 110 The session can be interrupted via control-C.
 111 When the session has finished, the terminal is restored to its
 112 original size if it was changed during playback.
 113 .Pp
 114 The options are as follows:
 115 .Bl -tag -width Fl
 116 .It Fl d Ar dir , Fl -directory Ns = Ns Ar dir
 117 Store session logs in
 118 .Ar dir
 119 instead of the default,
 120 .Pa @iolog_dir@ .
 121 .It Fl f Ar filter , Fl -filter Ns = Ns Ar filter
 122 Select which I/O type(s) to display.
 123 By default,
 124 .Nm
 125 will display the command's standard output, standard error and tty output.
 126 The
 127 .Ar filter
 128 argument is a comma-separated list, consisting of one or more of following:
 129 .Em stdin ,
 130 .Em stdout ,
 131 .Em stderr ,
 132 .Em ttyin ,
 133 and
 134 .Em ttyout .
 135 .It Fl h , -help
 136 Display a short help message to the standard output and exit.
 137 .It Fl l , -list Op Ar search expression
 138 Enable
 139 .Dq list mode .
 140 In this mode,
 141 .Nm
 142 will list available sessions in a format similar to the
 143 .Nm sudo
 144 log file format, sorted by file name (or sequence number).
 145 If a
 146 .Ar search expression
 147 is specified, it will be used to restrict the IDs that are displayed.
 148 An expression is composed of the following predicates:
 149 .Bl -tag -width 6n
 150 .It command Ar pattern
 151 Evaluates to true if the command run matches the POSIX extended
 152 regular expression
 153 .Ar pattern .
 154 .It cwd Ar directory
 155 Evaluates to true if the command was run with the specified current
 156 working directory.
 157 .It fromdate Ar date
 158 Evaluates to true if the command was run on or after
 159 .Ar date .
 160 See
 161 .Sx Date and time format
 162 for a description of supported date and time formats.
 163 .It group Ar runas_group
 164 Evaluates to true if the command was run with the specified
 165 .Ar runas_group .
 166 Note that unless a
 167 .Ar runas_group
 168 was explicitly specified when
 169 .Nm sudo
 170 was run this field will be empty in the log.
 171 .It runas Ar runas_user
 172 Evaluates to true if the command was run as the specified
 173 .Ar runas_user .
 174 Note that
 175 .Nm sudo
 176 runs commands as user
 177 .Em root
 178 by default.
 179 .It todate Ar date
 180 Evaluates to true if the command was run on or prior to
 181 .Ar date .
 182 See
 183 .Sx Date and time format
 184 for a description of supported date and time formats.
 185 .It tty Ar tty name
 186 Evaluates to true if the command was run on the specified terminal device.
 187 The
 188 .Ar tty name
 189 should be specified without the
 190 .Pa /dev/
 191 prefix, e.g.,
 192 .Pa tty01
 193 instead of
 194 .Pa /dev/tty01 .
 195 .It user Ar user name
 196 Evaluates to true if the ID matches a command run by
 197 .Ar user name .
 198 .El
 199 .Pp
 200 Predicates may be abbreviated to the shortest unique string.
 201 .Pp
 202 Predicates may be combined using
 203 .Em and ,
 204 .Em or
 205 and
 206 .Em \&!
 207 operators as well as
 208 .Ql \&(
 209 and
 210 .Ql \&)
 211 grouping (note that parentheses must generally be escaped from the shell).
 212 The
 213 .Em and
 214 operator is optional, adjacent predicates have an implied
 215 .Em and
 216 unless separated by an
 217 .Em or .
 218 .It Fl m , -max-wait Ar max_wait
 219 Specify an upper bound on how long to wait between key presses or output data.
 220 By default,
 221 .Nm
 222 will accurately reproduce the delays between key presses or program output.
 223 However, this can be tedious when the session includes long pauses.
 224 When the
 225 .Fl m
 226 option is specified,
 227 .Nm
 228 will limit these pauses to at most
 229 .Em max_wait
 230 seconds.
 231 The value may be specified as a floating point number, e.g.,
 232 .Em 2.5 .
 233 A
 234 .Em max_wait
 235 of zero or less will eliminate the pauses entirely.
 236 .It Fl n , -non-interactive
 237 Do not prompt for user input or attempt to re-size the terminal.
 238 The session is written to the standard output, not directly to
 239 the user's terminal.
 240 .It Fl R , -no-resize
 241 Do not attempt to re-size the terminal to match the terminal size
 242 of the session.
 243 .It Fl S , -suspend-wait
 244 Wait while the command was suspended.
 245 By default,
 246 .Nm
 247 will ignore the time interval between when the command was suspended
 248 and when it was resumed.
 249 If the
 250 .Fl S
 251 option is specified,
 252 .Nm
 253 will wait instead.
 254 .It Fl s , -speed Ar speed_factor
 255 This option causes
 256 .Nm
 257 to adjust the number of seconds it will wait between key presses or
 258 program output.
 259 This can be used to slow down or speed up the display.
 260 For example, a
 261 .Ar speed_factor
 262 of
 263 .Em 2
 264 would make the output twice as fast whereas a
 265 .Ar speed_factor
 266 of
 267 .Em .5
 268 would make the output twice as slow.
 269 .It Fl V , -version
 270 Print the
 271 .Nm
 272 versions version number and exit.
 273 .El
 274 .Ss Date and time format
 275 The time and date may be specified multiple ways, common formats include:
 276 .Bl -tag -width 6n
 277 .It HH:MM:SS am MM/DD/CCYY timezone
 278 24 hour time may be used in place of am/pm.
 279 .It HH:MM:SS am Month, Day Year timezone
 280 24 hour time may be used in place of am/pm, and month and day names
 281 may be abbreviated.
 282 Note that month and day of the week names must be specified in English.
 283 .It CCYY-MM-DD HH:MM:SS
 284 ISO time format
 285 .It DD Month CCYY HH:MM:SS
 286 The month name may be abbreviated.
 287 .El
 288 .Pp
 289 Either time or date may be omitted, the am/pm and timezone are optional.
 290 If no date is specified, the current day is assumed; if no time is
 291 specified, the first second of the specified date is used.
 292 The less significant parts of both time and date may also be omitted,
 293 in which case zero is assumed.
 294 .Pp
 295 The following are all valid time and date specifications:
 296 .Bl -tag -width 6n
 297 .It now
 298 The current time and date.
 299 .It tomorrow
 300 Exactly one day from now.
 301 .It yesterday
 302 24 hours ago.
 303 .It 2 hours ago
 304 2 hours ago.
 305 .It next Friday
 306 The first second of the Friday in the next (upcoming) week.
 307 Not to be confused with
 308 .Dq this Friday
 309 which would match the Friday of the current week.
 310 .It last week
 311 The current time but 7 days ago.
 312 This is equivalent to
 313 .Dq a week ago .
 314 .It a fortnight ago
 315 The current time but 14 days ago.
 316 .It 10:01 am 9/17/2009
 317 10:01 am, September 17, 2009.
 318 .It 10:01 am
 319 10:01 am on the current day.
 320 .It 10
 321 10:00 am on the current day.
 322 .It 9/17/2009
 323 00:00 am, September 17, 2009.
 324 .It 10:01 am Sep 17, 2009
 325 10:01 am, September 17, 2009.
 326 .El
 327 .Pp
 328 Note that relative time specifications do not always work as expected.
 329 For example, the
 330 .Dq next
 331 qualifier is intended to be used in conjunction with a day such as
 332 .Dq next Monday .
 333 When used with units of weeks, months, years, etc
 334 the result will be one more than expected.
 335 For example,
 336 .Dq next week
 337 will result in a time exactly two weeks from now, which is probably
 338 not what was intended.
 339 This will be addressed in a future version of
 340 .Nm .
 341 .Ss Debugging sudoreplay
 342 .Nm
 343 versions 1.8.4 and higher support a flexible debugging framework
 344 that is configured via
 345 .Li Debug
 346 lines in the
 347 .Xr sudo.conf @mansectform@
 348 file.
 349 .Pp
 350 For more information on configuring
 351 .Xr sudo.conf @mansectform@ ,
 352 please refer to its manual.
 353 .Sh FILES
 354 .Bl -tag -width 24n
 355 .It Pa @sysconfdir@/sudo.conf
 356 Debugging framework configuration
 357 .It Pa @iolog_dir@
 358 The default I/O log directory.
 359 .It Pa @iolog_dir@/00/00/01/log
 360 Example session log info.
 361 .It Pa @iolog_dir@/00/00/01/stdin
 362 Example session standard input log.
 363 .It Pa @iolog_dir@/00/00/01/stdout
 364 Example session standard output log.
 365 .It Pa @iolog_dir@/00/00/01/stderr
 366 Example session standard error log.
 367 .It Pa @iolog_dir@/00/00/01/ttyin
 368 Example session tty input file.
 369 .It Pa @iolog_dir@/00/00/01/ttyout
 370 Example session tty output file.
 371 .It Pa @iolog_dir@/00/00/01/timing
 372 Example session timing file.
 373 .El
 374 .Pp
 375 Note that the
 376 .Em stdin ,
 377 .Em stdout
 378 and
 379 .Em stderr
 380 files will be empty unless
 381 .Nm sudo
 382 was used as part of a pipeline for a particular command.
 383 .Sh EXAMPLES
 384 List sessions run by user
 385 .Em millert :
 386 .Bd -literal -offset indent
 387 # sudoreplay -l user millert
 388 .Ed
 389 .Pp
 390 List sessions run by user
 391 .Em bob
 392 with a command containing the string vi:
 393 .Bd -literal -offset indent
 394 # sudoreplay -l user bob command vi
 395 .Ed
 396 .Pp
 397 List sessions run by user
 398 .Em jeff
 399 that match a regular expression:
 400 .Bd -literal -offset indent
 401 # sudoreplay -l user jeff command '/bin/[a-z]*sh'
 402 .Ed
 403 .Pp
 404 List sessions run by jeff or bob on the console:
 405 .Bd -literal -offset indent
 406 # sudoreplay -l ( user jeff or user bob ) tty console
 407 .Ed
 408 .Sh SEE ALSO
 409 .Xr script 1 ,
 410 .Xr sudo.conf @mansectform@ ,
 411 .Xr sudo @mansectsu@
 412 .Sh AUTHORS
 413 Many people have worked on
 414 .Nm sudo
 415 over the years; this version consists of code written primarily by:
 416 .Bd -ragged -offset indent
 417 .An Todd C. Miller
 418 .Ed
 419 .Pp
 420 See the CONTRIBUTORS file in the
 421 .Nm sudo
 422 distribution (https://www.sudo.ws/contributors.html) for an
 423 exhaustive list of people who have contributed to
 424 .Nm sudo .
 425 .Sh BUGS
 426 If you feel you have found a bug in
 427 .Nm ,
 428 please submit a bug report at https://bugzilla.sudo.ws/
 429 .Sh SUPPORT
 430 Limited free support is available via the sudo-users mailing list,
 431 see https://www.sudo.ws/mailman/listinfo/sudo-users to subscribe or
 432 search the archives.
 433 .Sh DISCLAIMER
 434 .Nm
 435 is provided
 436 .Dq AS IS
 437 and any express or implied warranties, including, but not limited
 438 to, the implied warranties of merchantability and fitness for a
 439 particular purpose are disclaimed.
 440 See the LICENSE file distributed with
 441 .Nm sudo
 442 or https://www.sudo.ws/license.html for complete details.