1 '\" te
2 .\" Copyright (c) 2007 Sun Microsystems, Inc. All Rights Reserved.
3 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
4 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
5 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
6 .TH LOGADM 1M "May 23, 2007"
7 .SH NAME
8 logadm \- manage endlessly growing log files
9 .SH SYNOPSIS
10 .LP
11 .nf
12 \fBlogadm\fR
13 .fi
14
15 .LP
16 .nf
17 \fBlogadm\fR [\fB-\fIoptions\fR\fR] \fIlogname\fR...
18 .fi
19
20 .SH DESCRIPTION
21 .sp
22 .LP
23 \fBlogadm\fR is a general log rotation tool that is suitable for running from
24 \fBcron\fR(1M).
25 .sp
26 .LP
27 Without arguments, \fBlogadm\fR reads the \fB/etc/logadm.conf\fR file, and for
28 every entry found in that file checks the corresponding log file to see if it
29 should be rotated. Typically this check is done each morning by an entry in the
30 root's \fBcrontab\fR.
31 .sp
32 .LP
33 If the \fIlogname\fR argument is specified, \fBlogadm\fR renames the
34 corresponding log file by adding a suffix so that the most recent log file ends
35 with \fB\&.0\fR (that is, \fIlogfile\fR\fB\&.0\fR), the next most recent ends
36 with \fB\&.1\fR (that is, \fIlogfile\fR\fB\&.1\fR), and so forth. By default,
37 ten versions of old log files are kept (that is, \fIlogfile\fR\fB\&.0\fR
38 through \fIlogfile\fR\fB\&.9\fR). At the point when what would be the eleventh
39 file is logged, \fBlogadm\fR automatically deletes the oldest version to keep
40 the count of files at ten.
41 .sp
42 .LP
43 \fBlogadm\fR takes a number of \fIoptions\fR. You can specify these options on
44 the command line or in the \fB/etc/logadm.conf\fR file. The \fBlogadm\fR
45 command searches \fB/etc/logadm.conf\fR for lines of the form \fIlogname\fR
46 \fIoptions\fR
47 .sp
48 .ne 2
49 .na
50 \fB\fIlogname\fR\fR
51 .ad
52 .sp .6
53 .RS 4n
54 Identifies an entry in \fB/etc/logadm.conf\fR. This can be a name or the
55 pathname of the log file. If you specify a log file, rather than a name, for
56 this field, it must be a fully qualified pathname.
57 .RE
58
59 .sp
60 .ne 2
61 .na
62 \fB\fIoptions\fR\fR
63 .ad
64 .sp .6
65 .RS 4n
66 Identifies command line options exactly as they would be entered on the command
67 line. This allows commonly used log rotation policies to be stored in the
68 \fB/etc/logadm.conf\fR file. See \fBEXAMPLES\fR.
69 .sp
70 If \fIoptions\fR are specified both in \fB/etc/logadm.conf\fR and on the
71 command line, those in the \fB/etc/logadm.conf\fR file are applied first.
72 Therefore, the command line options override those in \fB/etc/logadm.conf\fR.
73 .sp
74 Log file names specified in \fB/etc/logadm.conf\fR may contain filename
75 substitution characters such as \fB*\fR and \fB?\fR, that are supported by
76 \fBcsh\fR(1).
77 .RE
78
79 .sp
80 .LP
81 Two options control when a log file is rotated. They are: \fB-s\fR size
82 \fB-p\fR period.
83 .sp
84 .LP
85 When using more than one of these options at a time, there is an implied
86 \fBand\fR between them. This means that all conditions must be met before the
87 log is rotated.
88 .sp
89 .LP
90 If neither of these two options are specified, the default conditions for
91 rotating a log file are: \fB\fR\fB-s\fR \fB1b\fR \fB-p\fR \fB1w\fR, which means
92 the log file is only rotated if the size is non-zero and if at least 1 week has
93 passed since the last time it was rotated.
94 .sp
95 .LP
96 By specifying \fB\fR\fB-p\fR \fBnever\fR as a rotation condition, any other
97 rotation conditions are ignored and \fBlogadm\fR moves on to the expiration of
98 old log files. By specifying \fB\fR\fB-p\fR \fBnow\fR as a rotation condition,
99 a log rotation is forced.
100 .sp
101 .LP
102 Unless specified by the \fB-o\fR, \fB-g\fR, or \fB-m\fR options, \fBlogadm\fR
103 replaces the log file (after renaming it) by creating an empty file whose
104 owner, group ID, and permissions match the original file.
105 .sp
106 .LP
107 Three options control when old log files are expired: \fB-A\fR age \fB-C\fR
108 count \fB-S\fR size. These options expire the oldest log files until a
109 particular condition or conditions are met. For example, the combination
110 \fB\fR\fB-C\fR \fB5\fR and the \fB\fR\fB-S\fR \fB10m\fR options expires old log
111 files until there are no more than 5 of the \fBand\fR their combined disk usage
112 is no more than 10 megabytes. If none of these options are specified, the
113 default expiration is \fB\fR\fB-C\fR \fB10\fR which keeps ten old log files. If
114 no files are to be expired, use \fB\fR\fB-C\fR \fB0\fR to prevent expiration by
115 default.
116 .SH OPTIONS
117 .sp
118 .LP
119 The following options are supported:
120 .sp
121 .ne 2
122 .na
123 \fB\fB-a\fR \fIpost_command\fR\fR
124 .ad
125 .sp .6
126 .RS 4n
127 Execute the \fIpost_command\fR after renaming the log file. \fIpost_command\fR
128 is passed to \fBsh\fR \fB-c\fR.
129 .sp
130 Specify \fIpost_command\fR as a valid shell command. Use quotes to protect
131 spaces or shell metacharacters in \fIpost_command\fR.
132 .sp
133 This option can be used to restart a daemon that is writing to the file. When
134 rotating multiple logs with one \fBlogadm\fR command, \fIpost_command\fR is
135 executed only once after all the logs are rotated, not once per rotated log.
136 .RE
137
138 .sp
139 .ne 2
140 .na
141 \fB\fB-A\fR \fIage\fR\fR
142 .ad
143 .sp .6
144 .RS 4n
145 Delete any versions that have not been modified for the amount of time
146 specified by \fIage\fR.
147 .sp
148 Specify \fIage\fR as a number followed by an \fBh\fR (hours), \fBd\fR (days),
149 \fBw\fR(weeks), \fBm\fR (months), or \fBy\fR (years).
150 .RE
151
152 .sp
153 .ne 2
154 .na
155 \fB\fB-b\fR \fIpre_command\fR\fR
156 .ad
157 .sp .6
158 .RS 4n
159 Execute \fIpre_command\fR before renaming the log file. \fIpre_command\fR is
160 passed to \fBsh\fR \fB-c\fR.
161 .sp
162 Specify \fIpre_command\fR as a valid shell command. Use quotes to protect
163 spaces or shell metacharacters in the \fIpre_command\fR.
164 .sp
165 This option can be used to stop a daemon that is writing to the file. When
166 rotating multiple logs with one \fBlogadm\fR command, \fIpre_command\fR is
167 executed only once before all the logs are rotated, not once per rotated log.
168 .RE
169
170 .sp
171 .ne 2
172 .na
173 \fB\fB-c\fR\fR
174 .ad
175 .sp .6
176 .RS 4n
177 Rotate the log file by copying it and truncating the original logfile to zero
178 length, rather than renaming the file.
179 .RE
180
181 .sp
182 .ne 2
183 .na
184 \fB\fB-C\fR \fIcount\fR\fR
185 .ad
186 .sp .6
187 .RS 4n
188 Delete the oldest versions until there are not more than \fIcount\fR files
189 left.
190 .sp
191 If no expire options (\fB-A\fR, \fB-C\fR, or \fB-S\fR) are specified,
192 \fB\fR\fB-C\fR \fB10\fR is the default. To prevent the default expire rule from
193 being added automatically, specify \fB\fR\fB-C\fR \fB0\fR .
194 .RE
195
196 .sp
197 .ne 2
198 .na
199 \fB\fB-e\fR \fImail_addr\fR\fR
200 .ad
201 .sp .6
202 .RS 4n
203 Send error messages by email to \fImail_addr\fR.
204 .sp
205 As \fBlogadm\fR is typically run from \fBcron\fR(1M), error messages are
206 captured by \fBcron\fR and mailed to the owner of the \fBcrontab\fR.
207 .sp
208 This option is useful if you want the mail regarding error messages to go to
209 another address instead. If no errors are encountered, no mail message is
210 generated.
211 .RE
212
213 .sp
214 .ne 2
215 .na
216 \fB\fB-E\fR \fIcmd\fR\fR
217 .ad
218 .sp .6
219 .RS 4n
220 Execute \fIcmd\fR to expire the file, rather than deleting the old log file to
221 expire it.
222 .sp
223 \fIcmd\fR is passed it to \fBsh\fR \fB-c\fR. The file is considered expired
224 after \fIcmd\fR completes. If the old log file is not removed or renamed by the
225 \fIcmd\fR, \fBlogadm\fR considers it for expiration the next time that it runs
226 on the specified log file. If present, the keyword \fB$file\fR is expanded in
227 the specified \fIcmd\fRto the name of the file being expired.
228 .sp
229 This option is useful for tasks such as mailing old log files to
230 administrators, or copying old log files to long term storage.
231 .RE
232
233 .sp
234 .ne 2
235 .na
236 \fB\fB-f\fR \fIconf_file\fR\fR
237 .ad
238 .sp .6
239 .RS 4n
240 Use \fIconf_file\fR instead of \fB/etc/logadm.conf\fR.
241 .sp
242 This option allows non-root users to keep their own \fBlogadm\fR configuration
243 files.
244 .RE
245
246 .sp
247 .ne 2
248 .na
249 \fB\fB-g\fR \fIgroup\fR\fR
250 .ad
251 .sp .6
252 .RS 4n
253 Create a new empty file with the \fBID\fR specified by \fIgroup\fR, instead of
254 preserving the group \fBID\fR of the log file.
255 .sp
256 Specify \fIgroup\fR by name or by numeric group \fBID\fR, as accepted by
257 \fBchgrp\fR(1).
258 .sp
259 This option requires the ability to change file group ownership using the
260 \fBchgrp\fR(1) command.
261 .RE
262
263 .sp
264 .ne 2
265 .na
266 \fB\fB-h\fR\fR
267 .ad
268 .sp .6
269 .RS 4n
270 Print a help message that describes \fBlogadm\fR's options.
271 .RE
272
273 .sp
274 .ne 2
275 .na
276 \fB\fB-l\fR\fR
277 .ad
278 .sp .6
279 .RS 4n
280 Use local time rather than the Coordinated Universal Time (UTC) when naming
281 rotated log files (see the discussion of percent sequences in the templates
282 supplied with the \fB-t\fR option).
283 .RE
284
285 .sp
286 .ne 2
287 .na
288 \fB\fB-m\fR \fImode\fR\fR
289 .ad
290 .sp .6
291 .RS 4n
292 Create a new empty file with the mode specified by \fImode\fR, instead of
293 preserving the mode of the log file.
294 .sp
295 Specify \fImode\fR in any form that is accepted by the \fBchmod\fR(1) command.
296 .RE
297
298 .sp
299 .ne 2
300 .na
301 \fB\fB-M\fR \fIcmd\fR\fR
302 .ad
303 .sp .6
304 .RS 4n
305 Use \fIcmd\fR to rename the log file. If the keyword \fB$file\fR is specified,
306 it is expanded to the name of the log file. Similarly, the keyword \fB$nfile\fR
307 is expanded to the new name of the log file. The \fB$nfile\fR keyword is only
308 available with commands provided with the \fB-M\fR option. After the command
309 completes, the log file is replaced by the rotate file. The default \fIcmd\fR
310 is "\fB/bin/mv\fR \fB$file\fR\fB\fR\fB$nfile\fR".
311 .RE
312
313 .sp
314 .ne 2
315 .na
316 \fB\fB-n\fR \fI\fR\fR
317 .ad
318 .sp .6
319 .RS 4n
320 Print the actions that the \fBlogadm\fR command will perform without actually
321 performing them.
322 .sp
323 This option is useful for checking arguments before making any changes to the
324 system.
325 .sp
326 It is important to remember, however, that since log rotating actions are only
327 printed with this option, \fBlogadm\fR might not find files that need expiring,
328 but if run without the \fB-n\fR \fBlogadm\fR might create a file that needs
329 expiring by performing the log rotating actions. Therefore, if you see no files
330 being expired with the \fB-n\fR option, files still might be expired without
331 it.
332 .RE
333
334 .sp
335 .ne 2
336 .na
337 \fB\fB-N\fR\fR
338 .ad
339 .sp .6
340 .RS 4n
341 Prevent an error message if the specified logfile does not exist. Normally,
342 \fBlogadm\fR produces an error message if the log file is not found. With
343 \fB-N\fR, if the log file doesn't exist \fBlogadm\fR moves on to the expire
344 rules (if any) and then to the next log file (if any), without creating the
345 empty replacement log file.
346 .RE
347
348 .sp
349 .ne 2
350 .na
351 \fB\fB-o\fR \fIowner\fR\fR
352 .ad
353 .sp .6
354 .RS 4n
355 Create the new empty file with \fIowner\fR, instead of preserving the owner of
356 the log file.
357 .sp
358 Specify \fIowner\fR in any form that is accepted by the \fBchown\fR(1) command.
359 .RE
360
361 .sp
362 .ne 2
363 .na
364 \fB\fB-p\fR \fIperiod\fR\fR
365 .ad
366 .sp .6
367 .RS 4n
368 Rotate a log file after the specified time period (\fIperiod\fR).
369 .sp
370 Specify \fIperiod\fR as a number followed by \fBd\fR for days, \fBh\fR for
371 hours, \fBw\fR for weeks, \fBm\fR for months (30 days) or \fBy\fR for years.
372 There are also two special values for period: \fBnow\fR and \fBnever\fR.
373 "\fB\fR\fB-p\fR \fBnow\fR" forces log rotation. "\fB\fR\fB-p\fR \fBnever\fR"
374 forces no log rotation.
375 .RE
376
377 .sp
378 .ne 2
379 .na
380 \fB\fB-P\fR \fItimestamp\fR\fR
381 .ad
382 .sp .6
383 .RS 4n
384 Used by \fBlogadm\fR to record the last time the log was rotated in
385 \fB/etc/logadm.conf\fR.
386 .sp
387 This option uses \fItimestamp\fR to determine if the log rotation period has
388 passed. The format of \fItimestamp\fR matches the format generated by
389 \fBctime\fR(3C), with quotes around it to protect embedded spaces.
390 \fItimestamp\fR is always recorded in the Coordinated Universal Time (UTC)
391 timezone.
392 .RE
393
394 .sp
395 .ne 2
396 .na
397 \fB\fB-r\fR\fR
398 .ad
399 .sp .6
400 .RS 4n
401 Remove any entries corresponding to the specified \fIlogname\fR from the
402 \fB/etc/logadm.conf\fR.
403 .RE
404
405 .sp
406 .ne 2
407 .na
408 \fB\fB-R\fR \fIcmd\fR\fR
409 .ad
410 .sp .6
411 .RS 4n
412 Run the \fIcmd\fR when an old log file is created by a log rotation. If the
413 keyword \fB$file\fR is embedded in the specified command, it is expanded to the
414 name of the old log file just created by log rotation.
415 .sp
416 This option is useful for processing log file contents after rotating the log.
417 \fIcmd\fR is executed by passing it to \fBsh\fR \fB-c\fR. When rotating
418 multiple logs with one logadm command, the command supplied with \fB-R\fR is
419 executed once every time a log is rotated. This is useful for post-processing a
420 log file (that is, sorting it, removing uninteresting lines, etc.). The
421 \fB-a\fR option is a better choice for restarting daemons after log rotation.
422 .RE
423
424 .sp
425 .ne 2
426 .na
427 \fB\fB-s\fR \fIsize\fR\fR
428 .ad
429 .sp .6
430 .RS 4n
431 Rotate the log file only if its size is greater than or equal to \fIsize\fR.
432 .sp
433 Specify \fIsize\fR as a number followed by the letter \fBb\fR for bytes,
434 \fBk\fR for kilobytes, \fBm\fR for megabytes, or \fBg\fR for gigabytes.
435 .RE
436
437 .sp
438 .ne 2
439 .na
440 \fB\fB-S\fR \fIsize\fR\fR
441 .ad
442 .sp .6
443 .RS 4n
444 Delete the oldest versions until the total disk space used by the old log files
445 is less than the specified size.
446 .sp
447 Specify \fIsize\fR as a number followed by the letter \fBb\fR for bytes,
448 \fBk\fR for kilobytes, \fBm\fR for megabytes, or \fBg\fR for gigabytes.
449 .RE
450
451 .sp
452 .ne 2
453 .na
454 \fB\fB-t\fR \fItemplate\fR\fR
455 .ad
456 .sp .6
457 .RS 4n
458 Specify the template to use when renaming log files.
459 .sp
460 \fItemplate\fR can be a simple name, such as \fB/var/adm/oldfile\fR, or it can
461 contain special keywords which are expanded by \fBlogadm\fR and are in the form
462 \fB$\fR\fIword\fR. Allowed sequences are:
463 .sp
464 .ne 2
465 .na
466 \fB$\fIbasename\fR\fR
467 .ad
468 .sp .6
469 .RS 4n
470 The log file name, without the directory name
471 .RE
472
473 .sp
474 .ne 2
475 .na
476 \fB$\fIdirname\fR\fR
477 .ad
478 .sp .6
479 .RS 4n
480 The directory of the file to be rotated
481 .RE
482
483 .sp
484 .ne 2
485 .na
486 \fB$\fIdomain\fR\fR
487 .ad
488 .sp .6
489 .RS 4n
490 Expands to the output of \fBdomainname\fR
491 .RE
492
493 .sp
494 .ne 2
495 .na
496 \fB$\fIfile\fR\fR
497 .ad
498 .sp .6
499 .RS 4n
500 The full path name of the file to be rotated
501 .RE
502
503 .sp
504 .ne 2
505 .na
506 \fB$\fIisa\fR\fR
507 .ad
508 .sp .6
509 .RS 4n
510 Expands to the output of \fBuname\fR \fB-p\fR
511 .RE
512
513 .sp
514 .ne 2
515 .na
516 \fB$\fImachine\fR\fR
517 .ad
518 .sp .6
519 .RS 4n
520 Expands to the output of \fBuname\fR \fB-m\fR
521 .RE
522
523 .sp
524 .ne 2
525 .na
526 \fB$\fIn\fR\fR
527 .ad
528 .sp .6
529 .RS 4n
530 The version number, \fB0\fR is most recent, \fB1\fR is next most recent, and so
531 forth
532 .RE
533
534 .sp
535 .ne 2
536 .na
537 \fB$\fIN\fR\fR
538 .ad
539 .sp .6
540 .RS 4n
541 The same as $\fIn\fR, but starts at \fB1\fR instead of zero
542 .RE
543
544 .sp
545 .ne 2
546 .na
547 \fB$\fInodename\fR\fR
548 .ad
549 .sp .6
550 .RS 4n
551 Expands to the output of \fBuname\fR \fB-n\fR
552 .RE
553
554 .sp
555 .ne 2
556 .na
557 \fB$\fIplatform\fR\fR
558 .ad
559 .sp .6
560 .RS 4n
561 Expands to the output of \fBuname\fR \fB-i\fR
562 .RE
563
564 .sp
565 .ne 2
566 .na
567 \fB$\fIrelease\fR\fR
568 .ad
569 .sp .6
570 .RS 4n
571 Expands to the output of \fBuname\fR \fB-r\fR
572 .RE
573
574 .sp
575 .ne 2
576 .na
577 \fB$\fIsecs\fR\fR
578 .ad
579 .sp .6
580 .RS 4n
581 The number of seconds since \fB00:00:00 UTC, January 1,1970\fR
582 .RE
583
584 .sp
585 .ne 2
586 .na
587 \fB$\fIzonename\fR\fR
588 .ad
589 .sp .6
590 .RS 4n
591 Expands to the output of \fBzonename\fR(1).
592 .RE
593
594 To actually have the dollar sign character in the file name, use \fB$$\fR. Any
595 percent sequences allowed by \fBstrftime\fR(3C) are also allowed, for example,
596 \fB%d\fR expands to the day of the month. To actually have a percent sign
597 character in the file name, use \fB%%\fR. Both dollar-sign keywords and percent
598 sequences can appear anywhere in the template. If the template results in a
599 pathname with non-existent directories, they are created as necessary when
600 rotating the log file.
601 .sp
602 If no \fB-t\fR option is specified, the default template is \fB$file.$n\fR.
603 Actual \fBrotation\fR of log files, where each version is shifted up until it
604 expires is done using the \fB$n\fR keyword. If the template does not contain
605 the \fB$n\fR keyword, the log file is simply renamed to the new name and then
606 the expire rules, if any, are applied.
607 .RE
608
609 .sp
610 .ne 2
611 .na
612 \fB\fB-T\fR \fIpattern\fR\fR
613 .ad
614 .sp .6
615 .RS 4n
616 Normally \fBlogadm\fR looks for a list of old log files by turning the template
617 (specified with the \fB-t\fR option) into a pattern and finding existing files
618 whose names match that pattern. The \fB-T\fR option causes the given pattern to
619 be used instead.
620 .sp
621 This option is useful if another program fiddles with the old log file names,
622 like a \fBcron\fR job to compress them over time. The pattern is in the form of
623 a pathname with special characters such as \fB*\fR and \fB?\fR as supported by
624 \fBcsh\fR(1) filename substitution.
625 .RE
626
627 .sp
628 .ne 2
629 .na
630 \fB\fB-v\fR\fR
631 .ad
632 .sp .6
633 .RS 4n
634 Print information about the actions being executed in verbose mode.
635 .RE
636
637 .sp
638 .ne 2
639 .na
640 \fB\fB-V\fR\fR
641 .ad
642 .sp .6
643 .RS 4n
644 Validate the configuration file.
645 .sp
646 This option validates that an entry for the specified \fIlogname\fR exists in
647 the \fB/etc/logadm.conf\fR file and is syntactically correct. If \fIlogname\fR
648 is not specified, all entries in the configuration file are validated. If a
649 \fBlogname\fR argument is specified, the command validates the syntax of that
650 entry. If the entry is found, it is printed and the exit value of the command
651 is true. Otherwise the exit value is false.
652 .RE
653
654 .sp
655 .ne 2
656 .na
657 \fB\fB-w\fR \fIentryname\fR\fR
658 .ad
659 .sp .6
660 .RS 4n
661 Write an entry into the config file (that is, \fB/etc/logadm.conf\fR) that
662 corresponds to the current command line arguments. If an entry already existed
663 for the specified \fIentryname\fR, it is removed first. This is the preferred
664 method for updating \fB/etc/logadm.conf\fR, because it prevents syntax errors.
665 The \fIentryname\fR is an argument to an invocation of \fBlogadm\fR.
666 \fIentryname\fR might be chosen as something easy to remember or it can be the
667 pathname of the log file. If a pathname, rather than a name is used, it must be
668 a fully qualified pathname.
669 .sp
670 If no log file name is provided on a \fBlogadm\fR command line, the entry name
671 is assumed to be the same as the log file name. For example, the following two
672 lines achieve the same thing, keeping two copies of rotated log files:
673 .sp
674 .in +2
675 .nf
676 % logadm -C2 -w mylog /my/really/long/log/file/name
677 % logadm -C2 -w /my/really/long/log/file/name
678 .fi
679 .in -2
680 .sp
681
682 .RE
683
684 .sp
685 .ne 2
686 .na
687 \fB\fB-z\fR \fIcount\fR\fR
688 .ad
689 .sp .6
690 .RS 4n
691 Compress old log files after all other commands have been executed. \fIcount\fR
692 of the most recent log files are left uncompressed, therefore making the
693 \fIcount\fR most recent files easier to peruse. Use \fIcount\fR of zero to
694 compress all old logs.
695 .sp
696 The compression is done with \fBgzip\fR(1) and the resulting log file has the
697 suffix of \fB\&.gz\fR.
698 .RE
699
700 .SH OPERANDS
701 .sp
702 .LP
703 The following operands are supported:
704 .sp
705 .ne 2
706 .na
707 \fB\fIlogname\fR\fR
708 .ad
709 .sp .6
710 .RS 4n
711 Identifies the name of the entry in \fB/etc/logadm.conf\fR. If the log file
712 name is specified in the \fIlogname\fR field, it is assumed that \fIlogname\fR
713 is the same as the actual log file name.
714 .RE
715
716 .SH EXAMPLES
717 .LP
718 \fBExample 1 \fRRotating a File and Keeping Previous Versions
719 .sp
720 .LP
721 The following example rotates the \fB/var/adm/exacct/proc\fR file, keeping ten
722 previous versions in \fB/var/adm/exacct/proc.0\fR through
723 \fB/var/adm/exacct/proc.9\fR.
724
725 .sp
726 .LP
727 Tell \fBlogadm\fR to copy the file and truncate it.
728
729 .sp
730 .in +2
731 .nf
732 % logadm -c /var/adm/exacct/proc
733 .fi
734 .in -2
735 .sp
736
737 .LP
738 \fBExample 2 \fRRotating syslog
739 .sp
740 .LP
741 The following example rotates \fBsyslog\fR and keeps eight log files. Old log
742 files are put in the directory \fB/var/oldlogs\fR instead of \fB/var/log\fR:
743
744 .sp
745 .in +2
746 .nf
747 % logadm -C8 -t'/var/oldlogs/syslog.$n' /var/log/syslog
748 .fi
749 .in -2
750 .sp
751
752 .LP
753 \fBExample 3 \fRRotating /var/adm/sulog and Expiring Based on Age
754 .sp
755 .LP
756 The following entry in the \fB/etc/logadm.conf\fR file rotates the
757 \fB/var/adm/sulog\fR file and expires any copies older than 30 days.
758
759 .sp
760 .in +2
761 .nf
762 /var/adm/sulog -A 30d
763 .fi
764 .in -2
765 .sp
766
767 .LP
768 \fBExample 4 \fRRotating Files and Expiring Based on Disk Usage
769 .sp
770 .LP
771 The following entry in the \fB/etc/logadm.conf\fR file rotates the
772 \fB/var/adm/sulog\fR file and expires old log files when more than 100
773 megabytes are used by the sum of all the rotated log files.
774
775 .sp
776 .in +2
777 .nf
778 /var/adm/sulog -S 100m
779 .fi
780 .in -2
781 .sp
782
783 .LP
784 \fBExample 5 \fRCreating an Entry that Stores the Logfile Name
785 .sp
786 .LP
787 This example creates an entry storing the log file name and the fact that we
788 want to keep 20 copies in \fB/etc/logadm.conf\fR, but the \fB\fR\fB-p\fR
789 \fBnever\fR means the entry is ignored by the normal \fBlogadm\fR run from
790 root's crontab every morning.
791
792 .sp
793 .in +2
794 .nf
795 % logadm -w locallog /usr/local/logfile -C20 -p never
796 .fi
797 .in -2
798 .sp
799
800 .sp
801 .LP
802 Use the following entry on the command line to override the \fB\fR\fB-p\fR
803 \fBnever\fR option:
804
805 .sp
806 .in +2
807 .nf
808 % logadm -p now locallog
809 .fi
810 .in -2
811 .sp
812
813 .LP
814 \fBExample 6 \fRRotating the apache Error and Access Logs
815 .sp
816 .LP
817 The following example rotates the apache error and access logs monthly to
818 filenames based on current year and month. It keeps the 24 most recent copies
819 and tells apache to restart after renaming the logs.
820
821 .sp
822 .LP
823 This command is run once, and since the \fB-w\fR option is specified, an entry
824 is made in \fB/etc/logadm.conf\fR so the apache logs are rotated from now on.
825
826 .sp
827 .in +2
828 .nf
829 % logadm -w apache -p 1m -C 24\e
830 -t '/var/apache/old-logs/$basename.%Y-%m'\e
831 -a '/usr/apache/bin/apachectl graceful'\e
832 '/var/apache/logs/*{access,error}_log'
833 .fi
834 .in -2
835 .sp
836
837 .sp
838 .LP
839 This example also illustrates that the entry name supplied with the \fB-w\fR
840 option doesn't have to match the log file name. In this example, the entry name
841 is \fBapache\fR and once the line has been run, the entry in
842 \fB/etc/logadm.conf\fR can be forced to run by executing the following command:
843
844 .sp
845 .in +2
846 .nf
847 % logadm -p now apache
848 .fi
849 .in -2
850 .sp
851
852 .sp
853 .LP
854 Because the expression matching the apache log file names was enclosed in
855 quotes, the expression is stored in \fB/etc/logadm.conf\fR, rather than the
856 list of files that it expands to. This means that each time \fBlogadm\fR runs
857 from \fBcron\fR it expands that expression and checks all the log files in the
858 resulting list to see if they need rotating.
859
860 .sp
861 .LP
862 The following command is an example without the quotes around the log name
863 expression. The shell expands the last argument into a list of log files that
864 exist at the time the command is entered, and writes an entry to
865 \fB/etc/logadm.conf\fR that rotates the files.
866
867 .sp
868 .in +2
869 .nf
870 logadm -w apache /var/apache/logs/*_log
871 .fi
872 .in -2
873 .sp
874
875 .SH FILES
876 .sp
877 .ne 2
878 .na
879 \fB\fB/etc/logadm.conf\fR\fR
880 .ad
881 .sp .6
882 .RS 4n
883 configuration file for \fBlogadm\fR command
884 .RE
885
886 .SH ATTRIBUTES
887 .sp
888 .LP
889 See \fBattributes\fR(5) for descriptions of the following attributes:
890 .sp
891
892 .sp
893 .TS
894 box;
895 c | c
896 l | l .
897 ATTRIBUTE TYPE ATTRIBUTE VALUE
898 _
899 Interface Stability Evolving
900 .TE
901
902 .SH SEE ALSO
903 .sp
904 .LP
905 \fBchgrp\fR(1), \fBchmod\fR(1), \fBchown\fR(1), \fBcsh\fR(1), \fBgzip\fR(1),
906 \fBcron\fR(1M), \fBctime\fR(3C), \fBstrftime\fR(3C), \fBlogadm.conf\fR(4),
907 \fBattributes\fR(5)
908 .SH NOTES
909 .sp
910 .LP
911 When \fBlogadm\fR applies expire conditions (supplied by the \fB-A\fR,
912 \fB-C\fR, and \fB-S\fR options), it deletes files, the oldest first, until the
913 conditions are satisfied. If the template used for naming the old logs
914 contained \fB$n\fR or \fB$N\fR, \fBlogadm\fR picks the highest value of
915 \fB$n\fR or \fB$N\fR found in the old log file names first. If the template
916 used is something else, \fBlogadm\fR uses the modification time to determine
917 which files to expire first. This may not be the expected behavior if an old
918 log file has been modified since it was rotated.
919 .sp
920 .LP
921 Depending on log file sizes and number of log files, log file rotations can be
922 very time-consuming.
923 .sp
924 .LP
925 By default, \fBlogadm\fR works in \fBGMT\fR. Therefore, all entries written to
926 the \fB/etc/logadm.conf\fR file (see \fBlogadm.conf\fR(4)) will have a
927 \fBGMT\fR timestamp. Users can use the \fB-l\fR option to set \fBlogadm\fR to
928 local time.