Overview

To use the /usr/local/cpanel/bin/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 /usr/local/cpanel/bin/splitlogs binary optimizes your resources and performance when you create Apache logs. For example, the /usr/local/cpanel/bin/splitlogs binary can close file handles without the need to restart Apache. This greatly improves log processing and bandwidth processing performance.

Apache's default behavior opens and writes to both a byte log file and an access log file for each virtual host in Apache's configuration file. Because of this, the number of open log files equals twice the number of virtual hosts in Apache's /usr/local/apache/conf/httpd.conf file. However, to reduce Apache's 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 to manage the byte log files, and the other to manage the access log files. The splitlogs binary extracts the domain name and port from the Apache logs, 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.

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

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

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

Arguments

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

Build arguments

ArgumentDescriptionExample 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

ArgumentDescriptionExample 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.

  • This option only exists in EasyApache 4.
  • 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

ArgumentDescriptionExample 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.

This value defaults to 16000.


/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

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). 

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: 

The splitlogs binary only closes files under the following circumstances:

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.

The splitlogs configuration file

When cPanel & WHM rebuilds Apache's configuration file, the system examines the /var/cpanel/conf/splitlogs.conf file. The system uses the contents of this file to set command line arguments for CustomLog directives in Apache's /usr/local/apache/conf/httpd.conf file.

The configuration file contains line-delimited key=value pairs. The key entries are the same as the command line arguments.

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 commands:

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


Notes about performance concerns