The splitlogs Binary
For cPanel & WHM version 11.40
utility allows you to fine-tune your resource and performance trade-offs when creating Apache
utility also provides some performance optimizations, including the ability to close file handles without restarting Apache
. This greatly improves performance during log and bandwidth
By design, Apache
opens and writes to a single log file for each domain. Each virtual host in Apache
's configuration file is assigned its own log.
cPanel & WHM systems open and write to 2 log files:
- One log file tracks the domain's resource usage (byte log).
- The other log file tracks how the domain is accessed, and by whom (access log).
cPanel & WHM systems use Apache
's piped logs
functionality, along with the
utility, to process Apache
log information. In effect, cPanel & WHM is able to reduce Apache
's memory consumption by changing how the access and byte logs are written.
cPanel & WHM systems run 2 instances of the
utility — one to manage byte logs, and another to manage access logs.
utility will extract the domain name and port, and use this information as the space-separated line in the log file. The log file's name is based on this information, and written to either the directory you specify using this utility, or the default location for Apache
/usr/local/cpanel/bin/splitlogs --dir="/logs/apache" --suffix=".log" --sslsuffixi="_ssl.log" --maxopen="20000" --buffer="yes"
|| Input type
|| This parameter allows you to verify that the
splitlogs utility is built correctly. If the utility can run, the
--bincheck parameter will return
BinCheck Ok via STDOUT and exit. If
splitlogs is improperly built, the script will exit without a message.
Apache configuration options
|| Input type
|| The directory in which you wish to store Apache log files. This parameter's default value is
|| The suffix to use with unencrypted (non-SSL) Apache access logs. By default, this value is an empty string.
|| The suffix to use with SSL Apache access logs. Log files for SSL-encrypted Apache requests use a suffix. By default, this parameter's value is
|| The port on which SSL connections are made. The
splitlogs utility examines the port number and includes this port number in the log file. This parameter's default value is 443. Port 443 is the standard default port number for encrypted (HTTPS) Apache requests.
|| The server's hostname. By default, Apache routes requests without a corresponding virtual host to the default log, rather than a separate domain log. This parameter allows you to specify the server's hostname so that
splitlogs will recognize requests that need to be re-routed to the default log file. This parameter, alongside
--mainout, allows cPanel & WHM to mirror standard Apache behavior.
|| The path to the default access log where requests without a corresponding virtual host are logged. This parameter, alongside
‑‑main, allows cPanel & WHM to mirror standard Apache behavior.
Performance tweaking options
|| Input type
|| The maximum number of file handles
splitlogs can keep open at one time. This parameter's default value is
16000 (16,000). The
--maxopen parameter can accept any whole number between 1 and the maximum number of file handles any one process can open. This value is dictated by your operating system.
|| Select whether to enable buffered file writing. This value accepts 2 strings:
no. In most cases, this parameter is set to
yes by default. However, under certain conditions, this value may default to
no. See the More about --buffer section for details.
More about --maxopen
The parameter allows you to configure a resource vs. speed trade-off. The
parameter allows you to specify the maximum number of log files
can keep open at any one time.
Essentially, this value is the number of files
can write to at any time without closing and opening additional log files.
The default value for this parameter is 16,000. If the value you choose is too large, the OS will refuse to open a file when it needs to, and the parameter's value will return to the default value of 16,000.
- When the maximum number of files are opened and
splitlogs needs to write to a new file, the oldest file is closed and the new file is opened. This allows the
splitlogs utility to write to the log file.
splitlogs utility will not close any log files until the value set in
--maxopen is exceeded. This means that, as long as the number of log files opened by
splitlogs is less than the value set in
--maxopen, no action is taken.
spllitlogs utility also closes files during log and bandwidth processing, and when Apache restarts.
splitlogs utility will only open a log file to write to it when its corresponding domain is accessed. This differs from Apache's default behavior, wherein the number of log files opened is equal to twice the number of virtual hosts configured in the Apache configuration file (
/usr/local/apache/conf/httpd.conf). This happens because there are 2 log files for each virtual host (1 access log and 1 byte log).
- Setting this parameter too low will cause the
splitlogs binary to open and close files more than necessary, reducing performance.
- Setting this parameter too high requires more system resources and OS file handles, increasing the overall system load. This problem is exacerbated if buffering is enabled.
- Ultimately, you should determine the
--maxopen parameter's value based on the current pattern of access to sites on your system.
More about --buffer
This configuration option is another resource vs. speed trade-off. Under most conditions, the
utility uses buffered writes by default.
- Enabling buffered writes makes writing to individual log files faster, but requires more memory for each open log file.
- You will only experience this performance increase if the system has memory to spare and the server's load is light enough to flush bufferers in a timely fashion.
- If the system is overloaded or does not have extra memory to spare, write buffering will decrease performance overall.
- Disabling buffered writes substantially reduces the amount of memory required by the
- For example, on a system that has an OS buffer of 4,000 file handles and where the
--maxopen parameter is set to
1024, 4 MB of memory is used per
- If the
/var/cpanel/conserve_memory flag file exists, buffered writes are disabled by default. You can override this setting using the
splitlogs utility by passing the
- You may experience some data loss if the
splitlogs is terminated ungracefully before the buffers are flushed.
If you decide to modify the
option, monitor the system load and memory usage to determine whether the trade-off is reasonable.
The splitlogs utility's configuration file
When rebuilding Apache
's configuration, the cPanel & WHM system will examine the
utility's configuration file at
. The system uses the contents of the configuration file to set command line options for
directives in Apache
's configuration file (
The configuration file consists of line-delimited
entries are the same as the command line parameters described in the parameters
section of this document.
After specifying custom directives in
, you must rebuild and restart Apache
. To do so, you can use the following commands:
/etc/init.d/httpd -k graceful
Notes about performance concerns
splitlogs utility writes information to its log file whenever it reaches its file handle limit 1,000 times. Ultimately, these log messages should indicate how often the
splitlogs utility is opening and closing log files.
- If you do not encounter these messages in the
splitlogs utility's log file, you should reduce the
--maxopen parameter's value.
- If you encounter an unusually high number of these messages in the
splitlog utility's log file, you should increase the
--maxopen parameter's value. You should determine this value based on the current pattern of access to sites on your system.
- As a part of the regular maintenance of your system, you should examine these values whenever changes in load occur or whenever the number of domains hosted by the system changes. The correct value today may be wrong in the future.