aslmanager.tproj/aslmanager.8

   1 .\"Copyright (c) 2004-2009 Apple Inc. All rights reserved.
   2 .\"
   3 .\"@APPLE_LICENSE_HEADER_START@
   4 .\"
   5 .\"This file contains Original Code and/or Modifications of Original Code
   6 .\"as defined in and that are subject to the Apple Public Source License
   7 .\"Version 2.0 (the 'License'). You may not use this file except in
   8 .\"compliance with the License. Please obtain a copy of the License at
   9 .\"http://www.opensource.apple.com/apsl/ and read it before using this
  10 .\"file.
  11 .\"
  12 .\"The Original Code and all software distributed under the License are
  13 .\"distributed on an 'AS IS' basis, WITHOUT WARRANTY OF ANY KIND, EITHER
  14 .\"EXPRESS OR IMPLIED, AND APPLE HEREBY DISCLAIMS ALL SUCH WARRANTIES,
  15 .\"INCLUDING WITHOUT LIMITATION, ANY WARRANTIES OF MERCHANTABILITY,
  16 .\"FITNESS FOR A PARTICULAR PURPOSE, QUIET ENJOYMENT OR NON-INFRINGEMENT.
  17 .\"Please see the License for the specific language governing rights and
  18 .\"limitations under the License.
  19 .\"
  20 .\"@APPLE_LICENSE_HEADER_END@
  21 .\"
  22 .Dd December 7, 2007
  23 .Dt ASLMANAGER 8
  24 .Os "Mac OS X"
  25 .Sh NAME
  26 .Nm aslmanager
  27 .Nd Apple System Log data life-cycle manager
  28 .Sh SYNOPSIS
  29 .Nm
  30 .Op Fl s Ar store_dir
  31 .Op Fl a Op Ar archive_dir
  32 .Op Fl ttl Ar days
  33 .Op Fl store_ttl Ar days
  34 .Op Fl module_ttl Ar days
  35 .Op Fl size Ar max_size
  36 .Op Fl asldb
  37 .Op Fl module Op Ar name
  38 .Op Fl checkpoint
  39 .Op Fl d Op level
  40 .Op Fl dd Op level
  41 .Sh DESCRIPTION
  42 .Nm aslmanager
  43 manages rotated files and ASL data written by the
  44 .Nm syslogd
  45 server.
  46 It is started automatically at various times by
  47 .Nm syslogd .
  48 It may also be invoked from the command line by the superuser (root).
  49 It manages the life-cycle of data in the ASL database, rotated log files,
  50 and ASL directory data stores.
  51 Configuration information for
  52 .Nm aslmanager
  53 comes from the /etc/asl.conf configuration file,
  54 any ASL output module configuration files in the /etc/asl directory,
  55 and from command-line options that may be specified to override some settings
  56 found in the configuration files.
  57 In normal operation, it first checks the ASL database in /var/log/asl,
  58 then it checks the files and directories specified by /etc/asl.conf and each ASL output module.
  59 .Pp
  60 If the
  61 .Fl asldb
  62 flag is specified, then only the ASL database will be processed.
  63 .Pp
  64 If the
  65 .Fl module
  66 flag is specified, then the ASL database will not be processed.
  67 All ASL output modules, or a single module if
  68 .Ar name
  69 is specified, will be processed.
  70 .Pp
  71 If
  72 .Fl checkpoint
  73 is specified, then
  74 .Nm aslmanager
  75 will signal
  76 .Nm syslogd
  77 to checkpoint files for all modules, or for a single named module, before processing.
  78 .Pp
  79 The
  80 .Fl d
  81 flag causes
  82 .Nm
  83 to print debug messages tracing it's actions as they are performed.
  84 An integer value (1, 2, or 3) may follow the
  85 .Fl d
  86 flag.
  87 Higher values cause more fine-grained messages to be printed.
  88 The default value is 1.
  89 The
  90 .Fl dd
  91 flag directs
  92 .Nm
  93 to do a
  94 .Dq dry run .
  95 Debug messages are printed as with
  96 .Fl d ,
  97 but no actions are actually performed.
  98 An optional debug level may follow the
  99 .Fl dd
 100 flag.
 101 .Ss ASL DATABASE MANAGEMENT
 102 .Nm aslmanager
 103 scans the ASL database in /var/log/asl, or some other path specified by the setting of the
 104 .Dq store_path
 105 parameter in asl.conf, or by the path supplied following the
 106 .Fl s
 107 flag.
 108 Data files that are older than the time-to-live for the database are either archived or removed.
 109 Files that contain messages with explicit expire times are removed or archived monthly after all their contents expire.
 110 The default 7 day time-to-live value may be overridden by the setting of the
 111 .Dq store_ttl
 112 parameter in asl.conf or by supplying a value following the
 113 .Fl store_ttl
 114 flag or the
 115 .Fl ttl
 116 flag (which overrides the time-to-live for both the ASL database and for all ASL modules).
 117 A time-to-live value of zero allows files to remain in the store with no time limit.
 118 .Pp
 119 A maximum size for the entire database is provided by the setting of the
 120 .Dq max_store_size
 121 parameter in asl.conf, or as a value following the
 122 .Fl size
 123 flag.
 124 This will cause
 125 .Nm
 126 to archive (if enabled) and remove files to keep the database size below the specified limit.
 127 The default value is 150000000 bytes.
 128 A value of zero means the size is unlimited.
 129 An unlimited size specification should be used with great caution,
 130 since a runaway process could quickly fill all available disk space.
 131 Files are removed in order starting from oldest to newest.
 132 Files with the same date are removed in standard lexicographic sort order by file name.
 133 .Pp
 134 Files are either removed entirely or copied to an archive directory.
 135 If the
 136 .Fl a
 137 flag is specified with no argument, files are copied to the /var/log/asl.archive directory.
 138 An alternate directory path may be specified following the
 139 .Fl a
 140 flag.
 141 The archive parameter setting in asl.conf enables or disables archiving.
 142 The archive parameter requires a value of "1" to enable archiving, or a value of "0" to disable it.
 143 An option archive directory path may follow the "0" or "1".
 144 .Pp
 145 .Ss ASL OUTPUT MODULE MANAGEMENT
 146 For each ASL output module, or a single module specified as an argument following
 147 .Fl module ,
 148 .Nm aslmanager
 149 first locates all checkpoint files produced by
 150 .Nm syslogd
 151 for that module.
 152 .Nm aslmanager
 153 checks all ASL directory data stores and all rotated log files - those with a
 154 .Dq rotate
 155 option in the module's configuration rules.
 156 Checkpoint files are renamed if necessary to conform to the naming style specified for the file by a
 157 .Dq style
 158 option in the module's configuration file.
 159 .Nm aslmanager
 160 will compress the file if directed by a
 161 .Dq compress
 162 option, and it will move the file to a destination directory if a
 163 .Dq dest
 164 option is specified for the file.
 165 Following this,
 166 .Nm
 167 will delete expired files.
 168 The time-to-live for files is 7 days by default, but may be specified using the
 169 .Dq ttl
 170 option for the file in the module's configuration rules.
 171 If
 172 .Fl module_ttl
 173 or
 174 .Fl ttl
 175 are specified command line, then value specified as an argument is used as a time-to-live instead.
 176 .Fl module_ttl
 177 specifies time-to-live for module processing.
 178 .Fl ttl
 179 specifies time-to-live for both the ASL database and for modules.
 180 .Pp
 181 Finally, if the
 182 .Dq all_max
 183 option is specified for the output file,
 184 .Nm
 185 checks the total size of all the rotated versions,
 186 and will delete them, (oldest first) to limit the total size as specified by
 187 .Dq all_max .
 188 When processing ASL directory data stores,
 189 .Nm
 190 will similarly delete data files after the expiry of their time-to-live,
 191 and will delete data files (oldest first) to limit the total size as specified by
 192 .Dq all_max .
 193 .Pp
 194 .Sh SEE ALSO
 195 .Xr syslogd 8 ,
 196 .Xr syslog 1 ,
 197 .Xr asl 3 ,
 198 .Xr asl.conf 5 ,
 199 .Xr syslog 3 .
 200 .Sh HISTORY
 201 The
 202 .Nm
 203 utility appeared in Mac OS X 10.6.
 204 Support for log file and ASL directory life-cycle management was added in OS X 10.9.