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