This document explains the technical terms you will meet in the managelogs documentation.
log manager : the managelogs process reads data from its standard input and writes it to one or more output channels. The object controlling each channel is named a log manager. The role of the log manager is to receive the raw log data and to write it to its active log file. Each channel receives a copy of the same data. The log manager's behavior depends on its configuration, and includes data compression, log file rotation, file purge, symbolic or hard link management, and other features. If this is your first steps with managelogs, consider only cases with a single log manager per process. When you will be more familiar with the concept, you will consider cases with multiple log managers in the same process .
base path : Each log manager is assigned a base path. This is an absolute or relative path, composed of a directory part (the base dir), and a filename part. Every files created and maintained by the log manager (except the log files if a log path is defined) reside in this directory and all of these file names start with the base path. Different log managers can maintain their files in the same directory, provided each one is assigned a different base path.
base dir : The directory part of the base path. When starting managelogs, this directory must already exist. Its permissions must also allow the managelogs process to create new files in the directory (write permission on the directory).
log path : An optional path where log files will be stored. If an explicit log path is not specified on the command line, the log path and base path are equal. The log path can be set as a relative or absolute path. If it is a relative path, it is relative to the base dir.
log dir : the directory part of the log path. As base dir, the directory must exist before managelogs is started, and the permissions must allow the process to create files in the directory.
active log file : At any time, a log manager is associated with an active log file. This is the file it is currently writing into. When a rotation occurs, the active log file becomes a backup log file, and a new active log file is created in the log dir. Each log manager must be the only one to write to a given active log file. Active log files cannot be shared among log managers and nothing else on the system should write to the file or rename it, as long as it is active. Once a rotation occurs, it becomes a backup log file, which can be freely renamed or deleted (but not written to).
rotation : a rotation is the process of closing the current active log file, adding it to the list of backup log files, creating a new empty active log file, and refreshing/recreating the links (if link maintenance is on). Unlike other log rotation systems like logrotate, the only files whose name changes during a rotation are the link files.
purge : When the total size of log files (active + backups) exceeds the defined global limit, or when the number of log files (backups + 1) exceeds the defined keep count, the oldest backup file is deleted. The purge continues until the global conditions are met again.
backup log file : After being rotated, an active log file becomes a backup log file. A backup log file can be moved or deleted by an external process without causing any problem to the managelogs logic.
pid file : Each log manager creates a pid file when it starts. Its name is '<base-path>.pid'. This file contains the pid of the managelogs process this log manager belongs to. This file can be used to send a signal to the managelogs process. When the process stops, the pid file is removed.
status file : Each log manager maintains a status file in its base directory. The name of this file is '<base-path>.status'. When the log manager is stopped and then restarted, it uses this file to recover the state it was in when it was stopped. This way, the purge and rotation logic can remain consistent across restarts.
active link : The log manager can optionally maintain a link (symbolic or hard) to the active log file. When a rotation occurs, the link's target is modified to point to the newly-created active log file. The name of this link is equal to the base path.
backup links : This is the same for backup log files. These links are named in anti-chronological order : '<base-path>.001' corresponds to the most recent backup log file, then '<base-path>.002', and so on...
individual file limit : When the active log file exceeds this size, a rotation is triggered.
global size limit : When the sum of the sizes of the active and backup log files exceed this value, a purge is triggered.
keep count : As an alternative to the global size limit, the user can specify how many log files at most should be kept. This is the keep count : when the number of log files (number of backup log files + 1) exceeds this number, a purge is triggered.
compression engine/level : A log manager can optionally write compressed data to the active log file. The user can choose between several compression engines (currently gzip and bzip2 are supported) and levels.
effective user : As an Apache log management program, managelogs generally runs as root. But, in some cases, as with virtual hosts, it may be interesting to have the log files belong to another non-root user. An option on the command line causes managelogs to switch its effective uid/gid to another one. This way, this user has full control on its log files and can even control the managelogs process itself with signals (to trigger a rotation, for instance).