1logadm(1M) System Administration Commands logadm(1M)
2
3
4
6 logadm - manage endlessly growing log files
7
9 logadm
10
11
12 logadm [-options] logname...
13
14
16 logadm is a general log rotation tool that is suitable for running from
17 cron(1M).
18
19
20 Without arguments, logadm reads the /etc/logadm.conf file, and for
21 every entry found in that file checks the corresponding log file to see
22 if it should be rotated. Typically this check is done each morning by
23 an entry in the root's crontab.
24
25
26 If the logname argument is specified, logadm renames the corresponding
27 log file by adding a suffix so that the most recent log file ends with
28 .0 (that is, logfile.0), the next most recent ends with .1 (that is,
29 logfile.1), and so forth. By default, ten versions of old log files are
30 kept (that is, logfile.0 through logfile.9). At the point when what
31 would be the eleventh file is logged, logadm automatically deletes the
32 oldest version to keep the count of files at ten.
33
34
35 logadm takes a number of options. You can specify these options on the
36 command line or in the /etc/logadm.conf file. The logadm command
37 searches /etc/logadm.conf for lines of the form logname options
38
39 logname
40
41 Identifies an entry in /etc/logadm.conf. This can be a name or the
42 pathname of the log file. If you specify a log file, rather than a
43 name, for this field, it must be a fully qualified pathname.
44
45
46 options
47
48 Identifies command line options exactly as they would be entered on
49 the command line. This allows commonly used log rotation policies
50 to be stored in the /etc/logadm.conf file. See EXAMPLES.
51
52 If options are specified both in /etc/logadm.conf and on the com‐
53 mand line, those in the /etc/logadm.conf file are applied first.
54 Therefore, the command line options override those in
55 /etc/logadm.conf.
56
57 Log file names specified in /etc/logadm.conf may contain filename
58 substitution characters such as * and ?, that are supported by
59 csh(1).
60
61
62
63 Two options control when a log file is rotated. They are: -s size -p
64 period.
65
66
67 When using more than one of these options at a time, there is an
68 implied and between them. This means that all conditions must be met
69 before the log is rotated.
70
71
72 If neither of these two options are specified, the default conditions
73 for rotating a log file are: -s 1b -p 1w, which means the log file is
74 only rotated if the size is non-zero and if at least 1 week has passed
75 since the last time it was rotated.
76
77
78 By specifying -p never as a rotation condition, any other rotation con‐
79 ditions are ignored and logadm moves on to the expiration of old log
80 files. By specifying -p now as a rotation condition, a log rotation is
81 forced.
82
83
84 Unless specified by the -o, -g, or -m options, logadm replaces the log
85 file (after renaming it) by creating an empty file whose owner, group
86 ID, and permissions match the original file.
87
88
89 Three options control when old log files are expired: -A age -C count
90 -S size. These options expire the oldest log files until a particular
91 condition or conditions are met. For example, the combination -C 5 and
92 the -S 10m options expires old log files until there are no more than 5
93 of the and their combined disk usage is no more than 10 megabytes. If
94 none of these options are specified, the default expiration is -C 10
95 which keeps ten old log files. If no files are to be expired, use -C 0
96 to prevent expiration by default.
97
99 The following options are supported:
100
101 -a post_command
102
103 Execute the post_command after renaming the log file. post_command
104 is passed to sh -c.
105
106 Specify post_command as a valid shell command. Use quotes to pro‐
107 tect spaces or shell metacharacters in post_command.
108
109 This option can be used to restart a daemon that is writing to the
110 file. When rotating multiple logs with one logadm command,
111 post_command is executed only once after all the logs are rotated,
112 not once per rotated log.
113
114
115 -A age
116
117 Delete any versions that have not been modified for the amount of
118 time specified by age.
119
120 Specify age as a number followed by an h (hours), d (days),
121 w(weeks), m (months), or y (years).
122
123
124 -b pre_command
125
126 Execute pre_command before renaming the log file. pre_command is
127 passed to sh -c.
128
129 Specify pre_command as a valid shell command. Use quotes to protect
130 spaces or shell metacharacters in the pre_command.
131
132 This option can be used to stop a daemon that is writing to the
133 file. When rotating multiple logs with one logadm command, pre_com‐
134 mand is executed only once before all the logs are rotated, not
135 once per rotated log.
136
137
138 -c
139
140 Rotate the log file by copying it and truncating the original log‐
141 file to zero length, rather than renaming the file.
142
143
144 -C count
145
146 Delete the oldest versions until there are not more than count
147 files left.
148
149 If no expire options (-A, -C, or -S) are specified, -C 10 is the
150 default. To prevent the default expire rule from being added auto‐
151 matically, specify -C 0 .
152
153
154 -e mail_addr
155
156 Send error messages by email to mail_addr.
157
158 As logadm is typically run from cron(1M), error messages are cap‐
159 tured by cron and mailed to the owner of the crontab.
160
161 This option is useful if you want the mail regarding error messages
162 to go to another address instead. If no errors are encountered, no
163 mail message is generated.
164
165
166 -E cmd
167
168 Execute cmd to expire the file, rather than deleting the old log
169 file to expire it.
170
171 cmd is passed it to sh -c. The file is considered expired after cmd
172 completes. If the old log file is not removed or renamed by the
173 cmd, logadm considers it for expiration the next time that it runs
174 on the specified log file. If present, the keyword $file is
175 expanded in the specified cmdto the name of the file being expired.
176
177 This option is useful for tasks such as mailing old log files to
178 administrators, or copying old log files to long term storage.
179
180
181 -f conf_file
182
183 Use conf_file instead of /etc/logadm.conf.
184
185 This option allows non-root users to keep their own logadm configu‐
186 ration files.
187
188
189 -g group
190
191 Create a new empty file with the ID specified by group, instead of
192 preserving the group ID of the log file.
193
194 Specify group by name or by numeric group ID, as accepted by
195 chgrp(1).
196
197 This option requires the ability to change file group ownership
198 using the chgrp(1) command.
199
200
201 -h
202
203 Print a help message that describes logadm's options.
204
205
206 -l
207
208 Use local time rather than the Coordinated Universal Time (UTC)
209 when naming rotated log files (see the discussion of percent
210 sequences in the templates supplied with the -t option).
211
212
213 -m mode
214
215 Create a new empty file with the mode specified by mode, instead of
216 preserving the mode of the log file.
217
218 Specify mode in any form that is accepted by the chmod(1) command.
219
220
221 -M cmd
222
223 Use cmd to rename the log file. If the keyword $file is specified,
224 it is expanded to the name of the log file. Similarly, the keyword
225 $nfile is expanded to the new name of the log file. The $nfile key‐
226 word is only available with commands provided with the -M option.
227 After the command completes, the log file is replaced by the rotate
228 file. The default cmd is "/bin/mv $file$nfile".
229
230
231 -n
232
233 Print the actions that the logadm command will perform without
234 actually performing them.
235
236 This option is useful for checking arguments before making any
237 changes to the system.
238
239 It is important to remember, however, that since log rotating
240 actions are only printed with this option, logadm might not find
241 files that need expiring, but if run without the -n logadm might
242 create a file that needs expiring by performing the log rotating
243 actions. Therefore, if you see no files being expired with the -n
244 option, files still might be expired without it.
245
246
247 -N
248
249 Prevent an error message if the specified logfile does not exist.
250 Normally, logadm produces an error message if the log file is not
251 found. With -N, if the log file doesn't exist logadm moves on to
252 the expire rules (if any) and then to the next log file (if any),
253 without creating the empty replacement log file.
254
255
256 -o owner
257
258 Create the new empty file with owner, instead of preserving the
259 owner of the log file.
260
261 Specify owner in any form that is accepted by the chown(1) command.
262
263
264 -p period
265
266 Rotate a log file after the specified time period (period).
267
268 Specify period as a number followed by d for days, h for hours, w
269 for weeks, m for months (30 days) or y for years. There are also
270 two special values for period: now and never. "-p now" forces log
271 rotation. "-p never" forces no log rotation.
272
273
274 -P timestamp
275
276 Used by logadm to record the last time the log was rotated in
277 /etc/logadm.conf.
278
279 This option uses timestamp to determine if the log rotation period
280 has passed. The format of timestamp matches the format generated by
281 ctime(3C), with quotes around it to protect embedded spaces. time‐
282 stamp is always recorded in the Coordinated Universal Time (UTC)
283 timezone.
284
285
286 -r
287
288 Remove any entries corresponding to the specified logname from the
289 /etc/logadm.conf.
290
291
292 -R cmd
293
294 Run the cmd when an old log file is created by a log rotation. If
295 the keyword $file is embedded in the specified command, it is
296 expanded to the name of the old log file just created by log rota‐
297 tion.
298
299 This option is useful for processing log file contents after rotat‐
300 ing the log. cmd is executed by passing it to sh -c. When rotating
301 multiple logs with one logadm command, the command supplied with -R
302 is executed once every time a log is rotated. This is useful for
303 post-processing a log file (that is, sorting it, removing uninter‐
304 esting lines, etc.). The -a option is a better choice for restart‐
305 ing daemons after log rotation.
306
307
308 -s size
309
310 Rotate the log file only if its size is greater than or equal to
311 size.
312
313 Specify size as a number followed by the letter b for bytes, k for
314 kilobytes, m for megabytes, or g for gigabytes.
315
316
317 -S size
318
319 Delete the oldest versions until the total disk space used by the
320 old log files is less than the specified size.
321
322 Specify size as a number followed by the letter b for bytes, k for
323 kilobytes, m for megabytes, or g for gigabytes.
324
325
326 -t template
327
328 Specify the template to use when renaming log files.
329
330 template can be a simple name, such as /var/adm/oldfile, or it can
331 contain special keywords which are expanded by logadm and are in
332 the form $word. Allowed sequences are:
333
334 $basename
335
336 The log file name, without the directory name
337
338
339 $dirname
340
341 The directory of the file to be rotated
342
343
344 $domain
345
346 Expands to the output of domainname
347
348
349 $file
350
351 The full path name of the file to be rotated
352
353
354 $isa
355
356 Expands to the output of uname -p
357
358
359 $machine
360
361 Expands to the output of uname -m
362
363
364 $n
365
366 The version number, 0 is most recent, 1 is next most recent,
367 and so forth
368
369
370 $N
371
372 The same as $n, but starts at 1 instead of zero
373
374
375 $nodename
376
377 Expands to the output of uname -n
378
379
380 $platform
381
382 Expands to the output of uname -i
383
384
385 $release
386
387 Expands to the output of uname -r
388
389
390 $secs
391
392 The number of seconds since 00:00:00 UTC, January 1,1970
393
394
395 $zonename
396
397 Expands to the output of zonename(1).
398
399 To actually have the dollar sign character in the file name, use
400 $$. Any percent sequences allowed by strftime(3C) are also allowed,
401 for example, %d expands to the day of the month. To actually have a
402 percent sign character in the file name, use %%. Both dollar-sign
403 keywords and percent sequences can appear anywhere in the template.
404 If the template results in a pathname with non-existent directo‐
405 ries, they are created as necessary when rotating the log file.
406
407 If no -t option is specified, the default template is $file.$n.
408 Actual rotation of log files, where each version is shifted up
409 until it expires is done using the $n keyword. If the template does
410 not contain the $n keyword, the log file is simply renamed to the
411 new name and then the expire rules, if any, are applied.
412
413
414 -T pattern
415
416 Normally logadm looks for a list of old log files by turning the
417 template (specified with the -t option) into a pattern and finding
418 existing files whose names match that pattern. The -T option causes
419 the given pattern to be used instead.
420
421 This option is useful if another program fiddles with the old log
422 file names, like a cron job to compress them over time. The pattern
423 is in the form of a pathname with special characters such as * and
424 ? as supported by csh(1) filename substitution.
425
426
427 -v
428
429 Print information about the actions being executed in verbose mode.
430
431
432 -V
433
434 Validate the configuration file.
435
436 This option validates that an entry for the specified logname
437 exists in the /etc/logadm.conf file and is syntactically correct.
438 If logname is not specified, all entries in the configuration file
439 are validated. If a logname argument is specified, the command val‐
440 idates the syntax of that entry. If the entry is found, it is
441 printed and the exit value of the command is true. Otherwise the
442 exit value is false.
443
444
445 -w entryname
446
447 Write an entry into the config file (that is, /etc/logadm.conf)
448 that corresponds to the current command line arguments. If an entry
449 already existed for the specified entryname, it is removed first.
450 This is the preferred method for updating /etc/logadm.conf, because
451 it prevents syntax errors. The entryname is an argument to an invo‐
452 cation of logadm. entryname might be chosen as something easy to
453 remember or it can be the pathname of the log file. If a pathname,
454 rather than a name is used, it must be a fully qualified pathname.
455
456 If no log file name is provided on a logadm command line, the entry
457 name is assumed to be the same as the log file name. For example,
458 the following two lines achieve the same thing, keeping two copies
459 of rotated log files:
460
461 % logadm -C2 -w mylog /my/really/long/log/file/name
462 % logadm -C2 -w /my/really/long/log/file/name
463
464
465
466
467 -z count
468
469 Compress old log files after all other commands have been executed.
470 count of the most recent log files are left uncompressed, therefore
471 making the count most recent files easier to peruse. Use count of
472 zero to compress all old logs.
473
474 The compression is done with gzip(1) and the resulting log file has
475 the suffix of .gz.
476
477
479 The following operands are supported:
480
481 logname
482
483 Identifies the name of the entry in /etc/logadm.conf. If the log
484 file name is specified in the logname field, it is assumed that
485 logname is the same as the actual log file name.
486
487
489 Example 1 Rotating a File and Keeping Previous Versions
490
491
492 The following example rotates the /var/adm/exacct/proc file, keeping
493 ten previous versions in /var/adm/exacct/proc.0 through
494 /var/adm/exacct/proc.9.
495
496
497
498 Tell logadm to copy the file and truncate it.
499
500
501 % logadm -c /var/adm/exacct/proc
502
503
504
505 Example 2 Rotating syslog
506
507
508 The following example rotates syslog and keeps eight log files. Old log
509 files are put in the directory /var/oldlogs instead of /var/log:
510
511
512 % logadm -C8 -t'/var/oldlogs/syslog.$n' /var/log/syslog
513
514
515
516 Example 3 Rotating /var/adm/sulog and Expiring Based on Age
517
518
519 The following entry in the /etc/logadm.conf file rotates the
520 /var/adm/sulog file and expires any copies older than 30 days.
521
522
523 /var/adm/sulog -A 30d
524
525
526
527 Example 4 Rotating Files and Expiring Based on Disk Usage
528
529
530 The following entry in the /etc/logadm.conf file rotates the
531 /var/adm/sulog file and expires old log files when more than 100
532 megabytes are used by the sum of all the rotated log files.
533
534
535 /var/adm/sulog -S 100m
536
537
538
539 Example 5 Creating an Entry that Stores the Logfile Name
540
541
542 This example creates an entry storing the log file name and the fact
543 that we want to keep 20 copies in /etc/logadm.conf, but the -p never
544 means the entry is ignored by the normal logadm run from root's crontab
545 every morning.
546
547
548 % logadm -w locallog /usr/local/logfile -C20 -p never
549
550
551
552
553 Use the following entry on the command line to override the -p never
554 option:
555
556
557 % logadm -p now locallog
558
559
560
561 Example 6 Rotating the apache Error and Access Logs
562
563
564 The following example rotates the apache error and access logs monthly
565 to filenames based on current year and month. It keeps the 24 most
566 recent copies and tells apache to restart after renaming the logs.
567
568
569
570 This command is run once, and since the -w option is specified, an
571 entry is made in /etc/logadm.conf so the apache logs are rotated from
572 now on.
573
574
575 % logadm -w apache -p 1m -C 24\
576 -t '/var/apache/old-logs/$basename.%Y-%m'\
577 -a '/usr/apache/bin/apachectl graceful'\
578 '/var/apache/logs/*{access,error}_log'
579
580
581
582
583 This example also illustrates that the entry name supplied with the -w
584 option doesn't have to match the log file name. In this example, the
585 entry name is apache and once the line has been run, the entry in
586 /etc/logadm.conf can be forced to run by executing the following com‐
587 mand:
588
589
590 % logadm -p now apache
591
592
593
594
595 Because the expression matching the apache log file names was enclosed
596 in quotes, the expression is stored in /etc/logadm.conf, rather than
597 the list of files that it expands to. This means that each time logadm
598 runs from cron it expands that expression and checks all the log files
599 in the resulting list to see if they need rotating.
600
601
602
603 The following command is an example without the quotes around the log
604 name expression. The shell expands the last argument into a list of log
605 files that exist at the time the command is entered, and writes an
606 entry to /etc/logadm.conf that rotates the files.
607
608
609 logadm -w apache /var/apache/logs/*_log
610
611
612
614 /etc/logadm.conf
615
616 configuration file for logadm command
617
618
620 See attributes(5) for descriptions of the following attributes:
621
622
623
624
625 ┌─────────────────────────────┬─────────────────────────────┐
626 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
627 ├─────────────────────────────┼─────────────────────────────┤
628 │Availability │SUNWcsu │
629 ├─────────────────────────────┼─────────────────────────────┤
630 │Interface Stability │Evolving │
631 └─────────────────────────────┴─────────────────────────────┘
632
634 chgrp(1), chmod(1), chown(1), csh(1), gzip(1), cron(1M), ctime(3C),
635 strftime(3C), logadm.conf(4), attributes(5)
636
638 When logadm applies expire conditions (supplied by the -A, -C, and -S
639 options), it deletes files, the oldest first, until the conditions are
640 satisfied. If the template used for naming the old logs contained $n or
641 $N, logadm picks the highest value of $n or $N found in the old log
642 file names first. If the template used is something else, logadm uses
643 the modification time to determine which files to expire first. This
644 may not be the expected behavior if an old log file has been modified
645 since it was rotated.
646
647
648 Depending on log file sizes and number of log files, log file rotations
649 can be very time-consuming.
650
651
652 By default, logadm works in GMT. Therefore, all entries written to the
653 /etc/logadm.conf file (see logadm.conf(4)) will have a GMT timestamp.
654 Users can use the -l option to set logadm to local time.
655
656
657
658SunOS 5.11 23 May 2007 logadm(1M)