1. cPanel & WHM Documentation
  2. WHM
  3. Scripts
  4. The log_retention Script
whmadvanced

The log_retention Script

Valid for versions 126 through the latest version

Version:

126

Last modified: 2026 March 11

Overview

The /usr/local/cpanel/scripts/log_retention script manages log file retention for cPanel & WHM logs. This script also automates the cleanup of rotated log files.

The script uses the default server retention period from the Number of days to retain web server logs before purging them setting in WHM’s Tweak Settings interface (WHM » Server Configuration » Tweak Settings). Users can override this value and set their own retention period in cPanel’s Raw Access interface (cPanel » Home » Metrics » Raw Access).

Run the script

To run this script on the command line, use the following format:

/usr/local/cpanel/scripts/log_retention [options]
Note:
  • Run this script as the root user to process both system and user logs.
  • Run this script as a non-root user to process the logs for that user.

Options

Use the following options with this script:

Option Description Example
--help, -h Display the script’s help documentation. --help
--run Run log retention cleanup for all log types. --run
--type Process specific log type(s):
  • web — The web log type.
  • custom — A custom log type.
Note:
You can repeat this option to process multiple types.
--type web
--verbose, -v Enable verbose output. Display detailed information about the processed paths and files. --verbose

File-matching patterns

The script uses different file matching patterns for system logs and user logs.

System logs

For system log paths (for example, /usr/local/apache/logs and /var/log/nginx), the script matches the following example file patterns:

Pattern Type
*.log.1, *.log.2 Numbered, rotated logs.
*.log.gz, *.log.bz2 Compressed logs.
*.log.1.gz, *.log.1.bz2 Numbered and compressed logs.
*.log.20241201, *.log.20241201.gz, *.log.20241201.bz2 Date-stamped files in YYYYMMDD format.

User logs

For user log paths (for example, ~/logs), the script matches the following pattern:

Pattern Type
*.gz gzip files that end in .gz.

Log types

The script supports the following log types:

web log type

The web log type manages these web server logs in the following directories:

Logs Directories
Apache access and error logs.
  • /usr/local/apache/logs
  • /var/log/apache2
  • /var/log/httpd
    The server’s NGINX® access and error logs. /var/log/nginx
    Domain-specific logs in system directories. /usr/local/apache/domlogs
    gzip log archives. Users’ ~/logs directories

    custom log type

    The custom log type allows you to retain or remove additional log files in other locations. For more information, read our Guide to Custom Plugins for the log_retention Script documentation.

    Additional Documentation