1. cPanel & WHM Documentation
  2. cPanel Knowledge Base
  3. Web Services
  4. The splitlogs Binary
whmadvanced apache logs

The splitlogs Binary

Last modified: 2026 March 17

Overview

To configure the web server to use the splitlogs binary, you must enable the Enable Piped Apache Logs setting in the Piped Log Configuration section of WHM’s Apache Configuration interface (WHM » Home » Server Configuration » Apache Configuration). The Enable Piped Apache Logs setting applies to both Apache® and NGINX® web servers.

The Piped Log Configuration configures Apache (or NGINX) to use a single target for all virtual host access and bandwidth logs. The system then pipes the combined logs to a helper application — the splitlogs binary — which splits them into separate domain logs. This option reduces the number of log files that Apache manages, which requires less system resources.

The splitlogs binary processes a data stream from the web server. When you enable piped logging, the system automatically starts the splitlogs binary and passes log data to it for processing.

  • You do not need to run the splitlogs binary from the command-line during normal operation. The system runs it in the background.
  • You might need to call this binary from the command-line by using the syntax and arguments in this documentation only in specific cases. For example, when you need to debug logging issues or configure a custom logging solution.
  • To define custom settings for the Apache piped log configuration, create a splitlogs configuration file that contacts line-delimited key=value pairs. For more information, read The splitlogs configuration file section of the documentation.

The splitlogs Binary

When you enable the Enable Piped Apache Logs setting, the system uses the /usr/local/cpanel/bin/splitlogs binary to process Apache logs more efficiently. For example, the /usr/local/cpanel/bin/splitlogs binary can close file handles without the need to restart Apache, which improves log and bandwidth processing performance.

By default, Apache opens and writes to both a byte log file and an access log file for each virtual host defined in the /usr/local/apache/conf/httpd.conf file. This behavior requires Apache to maintain twice as many open log files as configured virtual hosts. To reduce memory consumption, cPanel & WHM uses Apache’s piped logs functionality with the splitlogs binary to process Apache log information. The splitlogs binary only opens and writes to a single log file when a visitor accesses a virtual host.

cPanel & WHM runs two instances of the splitlogs binary. One instance manages byte log files, and the other manages access log files.

The splitlogs binary extracts the domain name and port from each Apache log entry and uses this information as a space-separated line in the log file. This information determines the log file’s name, which the system writes to either a specified directory, or to the default location for Apache logs in the /usr/local/apache/ directory.

Note:

If a visitor accesses the shared IP address, the splitlogs binary will only write to Apache’s byte and access log file. It will not write to the domain log file for the shared IP address.

Syntax and Arguments

This section describes the syntax and command-line arguments for the splitlogs binary. Use this information only in specific cases, such as when you debug logging issues or configure a custom logging solution.

To call the splitlogs binary from the command-line, use the following syntax:

 /usr/local/cpanel/bin/splitlogs [arguments]

Use the following arguments when you call the splitlogs binary. If you do not specify an argument, the splitlogs binary uses the indicated default value.

Build arguments

Argument Description Example command
--bincheck This argument verifies that the splitlogs binary built correctly.
  • If the binary built correctly, the script returns the BinCheck Ok message and exits.
  • If the binary did not build correctly, the script exits without a message.
 /usr/local/cpanel/bin/splitlogs ‑‑bincheck

Apache configuration arguments

Argument Description Example command
--dir Pass this argument with a value to specify the directory in which you wish to store Apache log files. This value defaults to the /usr/local/apache file. /usr/local/cpanel/bin/splitlogs ‑‑dir="/logs/apache"
--suffix Pass this argument with a value to specify the suffix to use with unencrypted (non-SSL) Apache access logs. This value defaults to an empty string. /usr/local/cpanel/bin/splitlogs ‑‑suffix=".logs"
--sslsuffix Pass this argument with a value to specify the suffix to use with SSL Apache access logs. This value defaults to the ssl_log log. /usr/local/cpanel/bin/splitlogs ‑‑sslsuffix="ssl_log"
--sslport Pass this argument with a value to specify the port on which the system makes SSL connections. The splitlogs binary examines the port number and includes this port number in the log file. This value defaults to 443.
Note:
Port 443 is the standard default port number for encrypted (HTTPS) Apache requests.
/usr/local/cpanel/bin/splitlogs ‑‑sslport="8080"
--main Pass this argument with a value to specify the server’s hostname. By default, Apache routes requests that do not have a virtual host to the default log, rather than to a separate domain log. This argument allows you to specify the server’s hostname to cause the splitlogs binary to recognize requests that it should reroute to the default log file. This argument and the --mainout argument allow cPanel & WHM to mirror standard Apache behavior. /usr/local/cpanel/bin/splitlogs ‑‑main="host.example.com"
--mainout Pass this argument with a value to specify the path to the default access log file in which the system logs requests without a virtual host. This argument and the ‑‑main argument allow cPanel & WHM to mirror standard Apache behavior. /usr/local/cpanel/bin/splitlogs ‑‑mainout="/logs/apache/host.example.com.log"

Performance tweaking arguments

Argument Description Example command
‑‑maxopen Pass this argument with a value to specify the maximum number of log files that the splitlogs binary can open at the same time.
  • Pass any whole number between 1 and the maximum number of file handles that your operating system will allow a single process to open.
  • For more information, read the More about the --maxopen argument section below.
 /usr/local/cpanel/bin/splitlogs ‑‑maxopen=20000
‑‑buffer Pass this argument with a value to specify whether to enable buffered file writing.
  • Specify yes to enable buffered file writing, or no to disable buffered file writing.
  • For more information, read the More about the --buffer argument section below.
In most cases, this value defaults to yes. However, under some conditions, this value defaults to no.		 /usr/local/cpanel/bin/splitlogs ‑‑buffer=yes

More about the --maxopen argument

The --maxopen argument specifies the maximum number of log files to open at the same time. Use this argument to optimize either speed or resources:

  • If you set a low --maxopen value, the splitlogs binary opens and closes files more often, which reduces performance.
  • If you set a high --maxopen value, the splitlogs binary requires more system resources and operating system file handles, which increases the overall system load. This load increases if you also enable buffered file writing with the --buffer argument.
    Warning:

    If you specify a very high value, your operating system may experience problems when it attempts to open files. If this problem occurs, the system returns the --maxopen value to the default value (16000).

  • We recommend that you use the current pattern of access to sites on your system in order to determine the --maxopen value. The splitlogs log file provides additional information that may help you determine this value. For more information, read the Notes about performance concerns section below.

The splitlogs binary only closes files under the following circumstances:

  • If the maximum number of files are already open and the splitlogs binary needs to write to a new file, the system closes the oldest file and open the new file.
  • The splitlogs binary closes some open files during log and bandwidth processing.
  • The splitlogs binary closes all of the open files when Apache restarts.

More about the --buffer argument

The --buffer argument allows you to specify whether to enable buffered file writing. Under most conditions, the splitlogs binary uses buffered file writing by default. However, if the /var/cpanel/conserve_memory flag file exists, the system disables buffered filing writing by default. The --buffer argument overrides these defaults.

  • If you enable buffered file writing, the splitlogs binary writes to individual log files faster, but requires more memory for each open log file.
    Warning:
    • To experience this performance increase, the system must have extra memory and the server must possess a light load to allow it to flush buffers in a timely fashion. If the system becomes overloaded or does not have extra memory, buffered file writing decreases overall performance.
    • If the splitlogs binary terminates ungracefully before the buffers flush, you may experience some data loss.
  • If you disable buffered file writing, the splitlogs binary requires substantially less memory. For example, on a system with an operating system buffer of 4,000 file handles and a --maxopen value of 1024, the system uses 4 MB of memory for each splitlogs instance.

The splitlogs configuration file

The webserver runs the splitlogs binary with default settings when you enable Apache piped logging. If you need to modify these settings, create the /var/cpanel/conf/splitlogs.conf file manually.

When EasyApache rebuilds Apache’s configuration, the system reads the /var/cpanel/conf/splitlogs.conf file and uses its contents to define the command-line arguments in the CustomLog directives in Apache’s /usr/local/apache/conf/httpd.conf file.

The configuration file contains line-delimited key=value pairs. The system supports the following options in this file:

  • maxopen
  • buffer

Each key corresponds to an available command-line option for the splitlogs binary (run /usr/local/cpanel/bin/splitlogs -h to view option details). For example: 

maxopen=512

When you add this entry, the system passes the corresponding argument (--maxopen=512) to the splitlogs binary during Apache configuration generation.

After you specify custom directives for the /var/cpanel/conf/splitlogs.conf file, you must rebuild and restart Apache. To do this, run the following: 

1
2

/usr/local/cpanel/scripts/rebuildhttpdconf
/scripts/restartsrv_httpd

Important:
  • The system applies the settings in splitlogs.conf to all services that use piped logging. Incorrect values can disrupt log processing.
  • We strongly recommend you only create a splitlogs.conf file when you fully understand the impact. Do not modify the splitlogs binary without a specific reason.

Notes about performance concerns

  • The splitlogs binary writes information to its log file whenever it reaches 1,000 times its file handle limit. These log messages indicate how often the splitlogs binary opens and closes log files.
    • If you do not encounter these messages in the splitlogs binary’s log file, reduce the --maxopen value.
    • If you encounter an unusually high number of these messages in the splitlog binary’s log file, increase the --maxopen value.
  • We recommend that you reevaluate these values whenever changes in load occur or whenever the number of domains that the system hosts changes.

Additional Documentation