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