prepare to upload
[debian/sudo] / sudoreplay.man.in
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 .\" Automatically generated by Pod::Man 2.22 (Pod::Simple 3.07)
17 .\"
18 .\" Standard preamble:
19 .\" ========================================================================
20 .de Sp \" Vertical space (when we can't use .PP)
21 .if t .sp .5v
22 .if n .sp
23 ..
24 .de Vb \" Begin verbatim text
25 .ft CW
26 .nf
27 .ne \\$1
28 ..
29 .de Ve \" End verbatim text
30 .ft R
31 .fi
32 ..
33 .\" Set up some character translations and predefined strings.  \*(-- will
34 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
35 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
36 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
37 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
38 .\" nothing in troff, for use with C<>.
39 .tr \(*W-
40 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
41 .ie n \{\
42 .    ds -- \(*W-
43 .    ds PI pi
44 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
45 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
46 .    ds L" ""
47 .    ds R" ""
48 .    ds C` 
49 .    ds C' 
50 'br\}
51 .el\{\
52 .    ds -- \|\(em\|
53 .    ds PI \(*p
54 .    ds L" ``
55 .    ds R" ''
56 'br\}
57 .\"
58 .\" Escape single quotes in literal strings from groff's Unicode transform.
59 .ie \n(.g .ds Aq \(aq
60 .el       .ds Aq '
61 .\"
62 .\" If the F register is turned on, we'll generate index entries on stderr for
63 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
64 .\" entries marked with X<> in POD.  Of course, you'll have to process the
65 .\" output yourself in some meaningful fashion.
66 .ie \nF \{\
67 .    de IX
68 .    tm Index:\\$1\t\\n%\t"\\$2"
69 ..
70 .    nr % 0
71 .    rr F
72 .\}
73 .el \{\
74 .    de IX
75 ..
76 .\}
77 .\"
78 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
79 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
80 .    \" fudge factors for nroff and troff
81 .if n \{\
82 .    ds #H 0
83 .    ds #V .8m
84 .    ds #F .3m
85 .    ds #[ \f1
86 .    ds #] \fP
87 .\}
88 .if t \{\
89 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
90 .    ds #V .6m
91 .    ds #F 0
92 .    ds #[ \&
93 .    ds #] \&
94 .\}
95 .    \" simple accents for nroff and troff
96 .if n \{\
97 .    ds ' \&
98 .    ds ` \&
99 .    ds ^ \&
100 .    ds , \&
101 .    ds ~ ~
102 .    ds /
103 .\}
104 .if t \{\
105 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
106 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
107 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
108 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
109 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
110 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
111 .\}
112 .    \" troff and (daisy-wheel) nroff accents
113 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
114 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
115 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
116 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
117 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
118 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
119 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
120 .ds ae a\h'-(\w'a'u*4/10)'e
121 .ds Ae A\h'-(\w'A'u*4/10)'E
122 .    \" corrections for vroff
123 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
124 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
125 .    \" for low resolution devices (crt and lpr)
126 .if \n(.H>23 .if \n(.V>19 \
127 \{\
128 .    ds : e
129 .    ds 8 ss
130 .    ds o a
131 .    ds d- d\h'-1'\(ga
132 .    ds D- D\h'-1'\(hy
133 .    ds th \o'bp'
134 .    ds Th \o'LP'
135 .    ds ae ae
136 .    ds Ae AE
137 .\}
138 .rm #[ #] #H #V #F C
139 .\" ========================================================================
140 .\"
141 .IX Title "SUDOREPLAY @mansectsu@"
142 .TH SUDOREPLAY @mansectsu@ "July 12, 2010" "1.7.4" "MAINTENANCE COMMANDS"
143 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
144 .\" way too many mistakes in technical documents.
145 .if n .ad l
146 .nh
147 .SH "NAME"
148 sudoreplay \- replay sudo session logs
149 .SH "SYNOPSIS"
150 .IX Header "SYNOPSIS"
151 \&\fBsudoreplay\fR [\fB\-d\fR \fIdirectory\fR] [\fB\-f\fR \fIfilter\fR] [\fB\-m\fR \fImax_wait\fR] [\fB\-s\fR \fIspeed_factor\fR] \s-1ID\s0
152 .PP
153 \&\fBsudoreplay\fR [\fB\-d\fR \fIdirectory\fR] \-l [search expression]
154 .SH "DESCRIPTION"
155 .IX Header "DESCRIPTION"
156 \&\fBsudoreplay\fR plays back or lists the session logs created by
157 \&\fBsudo\fR.  When replaying, \fBsudoreplay\fR can play the session back
158 in real-time, or the playback speed may be adjusted (faster or
159 slower) based on the command line options.  The \fI\s-1ID\s0\fR should be
160 a six character sequence of digits and upper case letters, e.g.
161 0100A5, which is logged by \fBsudo\fR when a command is run with
162 session logging enabled.
163 .PP
164 In list mode, \fBsudoreplay\fR can be used to find the \s-1ID\s0 of a session
165 based on a number of criteria such as the user, tty or command run.
166 .PP
167 In replay mode, if the standard output has not been redirected,
168 \&\fBsudoreplay\fR will act on the following keys:
169 .IP "' ' (space)" 8
170 .IX Item "' ' (space)"
171 Pause output; press any key to resume.
172 .IP "'<'" 8
173 Reduce the playback speed by one half.
174 .IP "'>'" 8
175 Double the playback speed.
176 .SH "OPTIONS"
177 .IX Header "OPTIONS"
178 \&\fBsudoreplay\fR accepts the following command line options:
179 .IP "\-d \fIdirectory\fR" 12
180 .IX Item "-d directory"
181 Use \fIdirectory\fR to for the session logs instead of the default,
182 \&\fI/var/log/sudo\-io\fR.
183 .IP "\-f \fIfilter\fR" 12
184 .IX Item "-f filter"
185 By default, \fBsudoreplay\fR will play back the command's standard
186 output, standard error and tty output.  The \fI\-f\fR option can be
187 used to select which of these to output.  The \fIfilter\fR argument
188 is a comma-separated list, consisting of one or more of following:
189 \&\fIstdout\fR, \fIstderr\fR, and \fIttyout\fR.
190 .IP "\-l" 12
191 .IX Item "-l"
192 Enable \*(L"list mode\*(R".  In this mode, \fBsudoreplay\fR will list available
193 session IDs.  If a \fIsearch expression\fR is specified, it will be
194 used to restrict the IDs that are displayed.  An expression is
195 composed of the following predicates:
196 .RS 12
197 .IP "command \fIcommand pattern\fR" 8
198 .IX Item "command command pattern"
199 Evaluates to true if the command run matches \fIcommand pattern\fR.
200 On systems with \s-1POSIX\s0 regular expression support, the pattern may
201 be an extended regular expression.  On systems without \s-1POSIX\s0 regular
202 expression support, a simple substring match is performed instead.
203 .IP "cwd \fIdirectory\fR" 8
204 .IX Item "cwd directory"
205 Evaluates to true if the command was run with the specified current
206 working directory.
207 .IP "fromdate \fIdate\fR" 8
208 .IX Item "fromdate date"
209 Evaluates to true if the command was run on or after \fIdate\fR.
210 See \*(L"Date and time format\*(R" for a description of supported
211 date and time formats.
212 .IP "group \fIrunas_group\fR" 8
213 .IX Item "group runas_group"
214 Evaluates to true if the command was run with the specified
215 \&\fIrunas_group\fR.  Note that unless a \fIrunas_group\fR was explicitly
216 specified when \fBsudo\fR was run this field will be empty in the log.
217 .IP "runas \fIrunas_user\fR" 8
218 .IX Item "runas runas_user"
219 Evaluates to true if the command was run as the specified \fIrunas_user\fR.
220 Note that \fBsudo\fR runs commands as user \fIroot\fR by default.
221 .IP "todate \fIdate\fR" 8
222 .IX Item "todate date"
223 Evaluates to true if the command was run on or prior to \fIdate\fR.
224 See \*(L"Date and time format\*(R" for a description of supported
225 date and time formats.
226 .IP "tty \fItty\fR" 8
227 .IX Item "tty tty"
228 Evaluates to true if the command was run on the specified terminal
229 device.  The \fItty\fR should be specified without the \fI/dev/\fR prefix,
230 e.g.  \fItty01\fR instead of \fI/dev/tty01\fR.
231 .IP "user \fIuser name\fR" 8
232 .IX Item "user user name"
233 Evaluates to true if the \s-1ID\s0 matches a command run by \fIuser name\fR.
234 .RE
235 .RS 12
236 .Sp
237 Predicates may be abbreviated to the shortest unique string (currently
238 all predicates may be shortened to a single character).
239 .Sp
240 Predicates may be combined using \fIand\fR, \fIor\fR and \fI!\fR operators
241 as well as \f(CW\*(Aq(\*(Aq\fR and \f(CW\*(Aq)\*(Aq\fR for grouping (note that parentheses
242 must generally be escaped from the shell).  The \fIand\fR operator is
243 optional, adjacent predicates have an implied \fIand\fR unless separated
244 by an \fIor\fR.
245 .RE
246 .IP "\-m \fImax_wait\fR" 12
247 .IX Item "-m max_wait"
248 Specify an upper bound on how long to wait between key presses or
249 output data.  By default, \fBsudo_replay\fR will accurately reproduce
250 the delays between key presses or program output.  However, this
251 can be tedious when the session includes long pauses.  When the
252 \&\fI\-m\fR option is specified, \fBsudoreplay\fR will limit these pauses
253 to at most \fImax_wait\fR seconds.  The value may be specified as a
254 floating point number, .e.g. \fI2.5\fR.
255 .IP "\-s \fIspeed_factor\fR" 12
256 .IX Item "-s speed_factor"
257 This option causes \fBsudoreplay\fR to adjust the number of seconds
258 it will wait between key presses or program output.  This can be
259 used to slow down or speed up the display.  For example, a
260 \&\fIspeed_factor\fR of \fI2\fR would make the output twice as fast whereas
261 a \fIspeed_factor\fR of <.5> would make the output twice as slow.
262 .IP "\-V" 12
263 .IX Item "-V"
264 The \fB\-V\fR (version) option causes \fBsudoreplay\fR to print its version number
265 and exit.
266 .SS "Date and time format"
267 .IX Subsection "Date and time format"
268 The time and date may be specified multiple ways, common formats include:
269 .IP "\s-1HH:MM:SS\s0 am \s-1MM/DD/CCYY\s0 timezone" 8
270 .IX Item "HH:MM:SS am MM/DD/CCYY timezone"
271 24 hour time may be used in place of am/pm.
272 .IP "\s-1HH:MM:SS\s0 am Month, Day Year timezone" 8
273 .IX Item "HH:MM:SS am Month, Day Year timezone"
274 24 hour time may be used in place of am/pm, and month and day names
275 may be abbreviated.  Note that month and day of the week names must
276 be specified in English.
277 .IP "CCYY-MM-DD \s-1HH:MM:SS\s0" 8
278 .IX Item "CCYY-MM-DD HH:MM:SS"
279 \&\s-1ISO\s0 time format
280 .IP "\s-1DD\s0 Month \s-1CCYY\s0 \s-1HH:MM:SS\s0" 8
281 .IX Item "DD Month CCYY HH:MM:SS"
282 The month name may be abbreviated.
283 .PP
284 Either time or date may be omitted, the am/pm and timezone are
285 optional.  If no date is specified, the current day is assumed; if
286 no time is specified, the first second of the specified date is
287 used.  The less significant parts of both time and date may also
288 be omitted, in which case zero is assumed.  For example, the following
289 are all valid:
290 .PP
291 The following are all valid time and date specifications:
292 .IP "now" 8
293 .IX Item "now"
294 The current time and date.
295 .IP "tomorrow" 8
296 .IX Item "tomorrow"
297 Exactly one day from now.
298 .IP "yesterday" 8
299 .IX Item "yesterday"
300 24 hours ago.
301 .IP "2 hours ago" 8
302 .IX Item "2 hours ago"
303 2 hours ago.
304 .IP "next Friday" 8
305 .IX Item "next Friday"
306 The first second of the next Friday.
307 .IP "this week" 8
308 .IX Item "this week"
309 The current time but the first day of the coming week.
310 .IP "a fortnight ago" 8
311 .IX Item "a fortnight ago"
312 The current time but 14 days ago.
313 .IP "10:01 am 9/17/2009" 8
314 .IX Item "10:01 am 9/17/2009"
315 10:01 am, September 17, 2009.
316 .IP "10:01 am" 8
317 .IX Item "10:01 am"
318 10:01 am on the current day.
319 .IP "10" 8
320 .IX Item "10"
321 10:00 am on the current day.
322 .IP "9/17/2009" 8
323 .IX Item "9/17/2009"
324 00:00 am, September 17, 2009.
325 .IP "10:01 am Sep 17, 2009" 8
326 .IX Item "10:01 am Sep 17, 2009"
327 10:01 am, September 17, 2009.
328 .SH "FILES"
329 .IX Header "FILES"
330 .IP "\fI/var/log/sudo\-io\fR" 24
331 .IX Item "/var/log/sudo-io"
332 The default I/O log directory.
333 .IP "\fI/var/log/sudo\-io/00/00/01/log\fR" 24
334 .IX Item "/var/log/sudo-io/00/00/01/log"
335 Example session log info.
336 .IP "\fI/var/log/sudo\-io/00/00/01/stdin\fR" 24
337 .IX Item "/var/log/sudo-io/00/00/01/stdin"
338 Example session standard input log.
339 .IP "\fI/var/log/sudo\-io/00/00/01/stdout\fR" 24
340 .IX Item "/var/log/sudo-io/00/00/01/stdout"
341 Example session standard output log.
342 .IP "\fI/var/log/sudo\-io/00/00/01/stderr\fR" 24
343 .IX Item "/var/log/sudo-io/00/00/01/stderr"
344 Example session standard error log.
345 .IP "\fI/var/log/sudo\-io/00/00/01/ttyin\fR" 24
346 .IX Item "/var/log/sudo-io/00/00/01/ttyin"
347 Example session tty input file.
348 .IP "\fI/var/log/sudo\-io/00/00/01/ttyout\fR" 24
349 .IX Item "/var/log/sudo-io/00/00/01/ttyout"
350 Example session tty output file.
351 .IP "\fI/var/log/sudo\-io/00/00/01/timing\fR" 24
352 .IX Item "/var/log/sudo-io/00/00/01/timing"
353 Example session timing file.
354 .PP
355 Note that the \fIstdin\fR, \fIstdout\fR and \fIstderr\fR files will be empty
356 unless \fBsudo\fR was used as part of a pipeline for a particular
357 command.
358 .SH "EXAMPLES"
359 .IX Header "EXAMPLES"
360 List sessions run by user \fImillert\fR:
361 .PP
362 .Vb 1
363 \& sudoreplay \-l user millert
364 .Ve
365 .PP
366 List sessions run by user \fIbob\fR with a command containing the string vi:
367 .PP
368 .Vb 1
369 \& sudoreplay \-l user bob command vi
370 .Ve
371 .PP
372 List sessions run by user \fIjeff\fR that match a regular expression:
373 .PP
374 .Vb 1
375 \& sudoreplay \-l user jeff command \*(Aq/bin/[a\-z]*sh\*(Aq
376 .Ve
377 .PP
378 List sessions run by jeff or bob on the console:
379 .PP
380 .Vb 1
381 \& sudoreplay \-l ( user jeff or user bob ) tty console
382 .Ve
383 .SH "SEE ALSO"
384 .IX Header "SEE ALSO"
385 \&\fIsudo\fR\|(@mansectsu@), \fIscript\fR\|(1)
386 .SH "AUTHOR"
387 .IX Header "AUTHOR"
388 Todd C. Miller
389 .SH "BUGS"
390 .IX Header "BUGS"
391 If you feel you have found a bug in \fBsudoreplay\fR, please submit a bug report
392 at http://www.sudo.ws/sudo/bugs/
393 .SH "SUPPORT"
394 .IX Header "SUPPORT"
395 Limited free support is available via the sudo-users mailing list,
396 see http://www.sudo.ws/mailman/listinfo/sudo\-users to subscribe or
397 search the archives.
398 .SH "DISCLAIMER"
399 .IX Header "DISCLAIMER"
400 \&\fBsudoreplay\fR is provided ``\s-1AS\s0 \s-1IS\s0'' and any express or implied warranties,
401 including, but not limited to, the implied warranties of merchantability
402 and fitness for a particular purpose are disclaimed.  See the \s-1LICENSE\s0
403 file distributed with \fBsudo\fR or http://www.sudo.ws/sudo/license.html
404 for complete details.