#!/usr/local/cpanel/3rdparty/bin/perl
# Copyright 2026 WebPros International, LLC
# All rights reserved.
# copyright@cpanel.net http://cpanel.net
# This code is subject to the cPanel license. Unauthorized copying is prohibited.
package scripts::log_retention;
use cPstrict;
use Getopt::Long ();
use Try::Tiny;
use File::Find;
use File::Path qw(remove_tree);
use File::Basename;
use Time::HiRes;
use Cpanel::AccessIds::ReducedPrivileges ();
use Cpanel::Config::LoadCpConf ();
use Cpanel::Config::Users ();
use Cpanel::Hooks ();
use Cpanel::Logger ();
use Cpanel::LogManager ();
use Cpanel::SafeRun::Object ();
use Cpanel::YAML ();
use constant {
PLUGIN_DIR => '/var/cpanel/log_retention/plugins',
};
# Built-in log types
my %BUILTIN_LOG_TYPES = (
web => {
get_default_retention => \&_get_web_default_retention,
get_user_retention => \&_get_web_user_retention,
sys_paths => \&_get_web_sys_paths,
user_paths => \&_get_web_user_paths,
description => 'Web server logs (Apache/NGINX access and error logs)',
},
);
# Combined log types (built-in + plugins)
my %LOG_TYPES;
sub script {
my (@args) = @_;
local $| = 1;
# Load built-in types first, then plugins
%LOG_TYPES = %BUILTIN_LOG_TYPES;
_load_plugin_log_types();
my %opts = (
help => 0,
run => 0,
type => [],
verbose => 0,
);
my $getopt_result = Getopt::Long::GetOptionsFromArray(
\@args,
'help|h' => \$opts{help},
'run' => \$opts{run},
'type=s@' => $opts{type},
'verbose|v' => \$opts{verbose},
);
if ( !$getopt_result || $opts{help} ) {
_usage();
return 0;
}
my $logger = Cpanel::Logger->new();
if ( $opts{run} ) {
return _run_retention_cleanup( $opts{type}, $opts{verbose}, $logger );
}
else {
return _show_log_types( $opts{type}, $opts{verbose}, $logger );
}
}
sub _usage {
print <<"EOF";
Usage: $0 [options]
Log retention management utility for cPanel & WHM
Options:
--help, -h Show this help message
--run Execute log retention cleanup
--type TYPE Process specific log type(s) only (can be repeated)
--verbose, -v Enable verbose output
Examples:
$0 # Show all log types and their settings
$0 --run # Process all log types
$0 --run --type web # Process only web logs
$0 --run --type web --type custom # Process web and custom log types
$0 --verbose # Show detailed information
Built-in log types:
EOF
for my $type ( sort keys %BUILTIN_LOG_TYPES ) {
printf " %-10s %s\n", $type, $BUILTIN_LOG_TYPES{$type}{description};
}
# Show plugin log types if any
my @plugin_types = grep { !exists $BUILTIN_LOG_TYPES{$_} } keys %LOG_TYPES;
if (@plugin_types) {
print "\nPlugin log types:\n";
for my $type ( sort @plugin_types ) {
printf " %-10s %s\n", $type, $LOG_TYPES{$type}{description};
}
}
print "\nPlugin directory: " . PLUGIN_DIR . "\n";
print "\n";
return;
}
sub _show_log_types {
my ( $requested_types, $verbose, $logger ) = @_;
my @types_to_show = @{$requested_types} ? @{$requested_types} : sort keys %LOG_TYPES;
print "Log Retention Configuration:\n";
print "=" x 50 . "\n";
for my $type (@types_to_show) {
if ( !exists $LOG_TYPES{$type} ) {
$logger->warn("Unknown log type: $type");
next;
}
my $config = $LOG_TYPES{$type};
my $default_retention = $config->{get_default_retention}->();
print "\nType: $type\n";
print "Description: $config->{description}\n";
print "Configured system-wide retention: ";
if ( $default_retention == 0 ) {
print "Never delete\n";
}
else {
print "$default_retention days\n";
}
if ($verbose) {
print "System paths:\n";
my @sys_paths = $config->{sys_paths}->();
for my $path (@sys_paths) {
print " - $path\n";
}
print "User retention setting: ~<user>/.cpanel-logs (web-log-retention-days)\n";
}
}
print "\n";
return 0;
}
sub _run_retention_cleanup {
my ( $requested_types, $verbose, $logger ) = @_;
my @types_to_process = @{$requested_types} ? @{$requested_types} : sort keys %LOG_TYPES;
$logger->info("Starting log retention cleanup process");
for my $type (@types_to_process) {
if ( !exists $LOG_TYPES{$type} ) {
$logger->warn("Unknown log type: $type - skipping");
next;
}
$logger->info("Processing log type: $type");
my $start_time = Time::HiRes::time();
try {
_process_log_type( $type, $verbose, $logger );
}
catch {
$logger->error("Failed to process log type '$type': $_");
};
my $duration = sprintf( "%.2f", Time::HiRes::time() - $start_time );
$logger->info("Completed processing '$type' in ${duration}s");
}
$logger->info("Log retention cleanup process completed");
return 0;
}
sub _process_log_type {
my ( $type, $verbose, $logger ) = @_;
my $config = $LOG_TYPES{$type};
my $default_retention = $config->{get_default_retention}->();
my $files_processed = 0;
my $process_success = 1;
# Check if running as non-root user
my $is_root = ( $> == 0 );
my $running_user = $is_root ? undef : getpwuid($>);
eval {
# Process system paths
# Skip if default retention is 0 = never delete
# Also skip system paths if running as non-root user
if ( !$is_root ) {
$logger->info("Running as non-root user - skipping system paths for type: $type") if $verbose;
}
elsif ( $default_retention == 0 ) {
$logger->info("System retention set to 'never delete' - skipping system paths for type: $type") if $verbose;
}
else {
$logger->info("Processing system logs for type: $type");
my @sys_paths = $config->{sys_paths}->();
for my $path (@sys_paths) {
$files_processed += _cleanup_logs_in_path(
{
base_path => $path,
retention_days => $default_retention,
log_type => $type,
user => undef,
verbose => $verbose,
logger => $logger,
}
);
}
}
# Process user paths
# If running as non-root, only process the current user's logs
$logger->info("Processing user logs for type: $type");
my @users = $is_root ? Cpanel::Config::Users::getcpusers() : ($running_user);
for my $user (@users) {
my $user_retention = $config->{get_user_retention}->($user) // $default_retention;
if ( $user_retention == 0 ) {
$logger->info("User '$user' has retention set to 'never delete' - skipping") if $verbose;
next;
}
my @user_paths = $config->{user_paths}->($user);
for my $path (@user_paths) {
$files_processed += _cleanup_logs_in_path(
{
base_path => $path,
retention_days => $user_retention,
log_type => $type,
user => $user,
verbose => $verbose,
logger => $logger,
}
);
}
}
1;
} or do {
$process_success = 0;
$logger->error("Processing failed: $@");
};
$logger->info( "Processed type '$type': $files_processed files deleted, status: " . ( $process_success ? 'success' : 'failed' ) );
return;
}
sub _find_user_log_files ($cutoff_time) {
my $archives = Cpanel::LogManager::list_logs();
my @files;
for my $archive ( @{$archives} ) {
if ( $archive->{mtime} && $archive->{mtime} < $cutoff_time ) {
push @files, $archive->{path};
}
}
return @files;
}
sub _find_system_log_files ( $base_path, $cutoff_time ) {
my @files;
my $wanted = sub {
return unless -f $_;
return if -l $_; # Skip symlinks to prevent symlink attack vulnerabilities
return if $_ eq '.' or $_ eq '..';
# Skip current/active log files
return if $_ =~ /\.log$/ && $_ !~ /\.(gz|bz2|\d+)$/;
# Look for rotated logs: .log.1, .log.gz, .log.20241201, etc.
return unless $_ =~ /\.log\.(?:\d+(?:\.gz|\.bz2)?|gz|bz2|\d{8}(?:\.gz|\.bz2)?)$/;
my $mtime = ( stat($_) )[9];
if ( $mtime && $mtime < $cutoff_time ) {
push @files, $File::Find::name;
}
};
find( { wanted => $wanted, no_chdir => 1 }, $base_path );
return @files;
}
sub _cleanup_logs_in_path {
my ($args) = @_;
my $base_path = $args->{base_path};
my $retention_days = $args->{retention_days};
my $log_type = $args->{log_type};
my $user = $args->{user};
my $verbose = $args->{verbose};
my $logger = $args->{logger};
return 0 unless -d $base_path;
my $cutoff_time = time() - ( $retention_days * 24 * 60 * 60 );
my @files_to_delete;
# Define the file finding operation
my $find_files_coderef = sub {
@files_to_delete =
$user
? _find_user_log_files($cutoff_time)
: _find_system_log_files( $base_path, $cutoff_time );
return;
};
# Find rotated log files - drop privileges for user paths to prevent
# symlink attacks and unauthorized access (TOCTOU mitigation)
if ( $user && $> == 0 && $user ne 'root' ) {
Cpanel::AccessIds::ReducedPrivileges::call_as_user( $find_files_coderef, $user );
}
else {
$find_files_coderef->();
}
if ( !@files_to_delete ) {
return 0;
}
$logger->info(
sprintf(
"Found %d log files to delete in %s (retention: %d days%s)",
scalar(@files_to_delete),
$base_path,
$retention_days,
$user ? " for user: $user" : ""
)
) if $verbose || @files_to_delete > 10;
# Execute pre-deletion hook
try {
Cpanel::Hooks::hook(
{
category => 'Log::Retention',
event => 'pre_deletion',
stage => 'pre',
},
{
log_type => $log_type,
user => $user,
base_path => $base_path,
files_to_delete => \@files_to_delete,
retention_days => $retention_days,
}
);
}
catch {
$logger->warn("Pre-deletion hook failed: $_");
};
# Define the deletion operation
my $deleted_count = 0;
my $delete_files_coderef = sub {
for my $file (@files_to_delete) {
try {
unlink($file) or die "Failed to delete $file: $!";
$deleted_count++;
$logger->info("Deleted: $file") if $verbose;
}
catch {
$logger->warn("Failed to delete $file: $_");
};
}
return;
};
# Delete files - drop privileges for user paths to ensure we can only
# delete files the user owns (prevents privilege escalation)
if ( $user && $> == 0 && $user ne 'root' ) {
Cpanel::AccessIds::ReducedPrivileges::call_as_user( $delete_files_coderef, $user );
}
else {
$delete_files_coderef->();
}
$logger->info( "Deleted $deleted_count files from $base_path" . ( $user ? " (user: $user)" : "" ) );
# Execute post-deletion hook
try {
Cpanel::Hooks::hook(
{
category => 'Log::Retention',
event => 'post_deletion',
stage => 'post',
},
{
log_type => $log_type,
user => $user,
base_path => $base_path,
deleted_count => $deleted_count,
retention_days => $retention_days,
}
);
}
catch {
$logger->warn("Post-deletion hook failed: $_");
};
return $deleted_count;
}
sub _get_web_default_retention {
my $cpconf = Cpanel::Config::LoadCpConf::loadcpconf();
return $cpconf->{'web_log_retention_days'} // 0;
}
sub _get_web_user_retention {
my ($user) = @_;
my $user_home = _get_user_home($user);
return unless $user_home;
my $config_path = "$user_home/.cpanel-logs";
return unless -e $config_path;
require Cpanel::Config::LoadConfig;
my @pwent = getpwnam($user);
return unless @pwent;
my $conf_ref;
if ( $> == 0 && $user ne 'root' ) {
$conf_ref = Cpanel::AccessIds::ReducedPrivileges::call_as_user(
sub { Cpanel::Config::LoadConfig::loadConfig($config_path) },
$pwent[2], $pwent[3]
);
}
else {
$conf_ref = Cpanel::Config::LoadConfig::loadConfig($config_path);
}
my $value = $conf_ref->{'web-log-retention-days'};
return unless defined $value && $value =~ /^[0-9]+$/;
return int($value);
}
sub _get_web_sys_paths {
my @paths;
# Apache system logs
push @paths, '/usr/local/apache/logs' if -d '/usr/local/apache/logs';
push @paths, '/var/log/apache2' if -d '/var/log/apache2';
push @paths, '/var/log/httpd' if -d '/var/log/httpd';
# NGINX system logs
push @paths, '/var/log/nginx' if -d '/var/log/nginx';
# cPanel domlogs
push @paths, '/usr/local/apache/domlogs' if -d '/usr/local/apache/domlogs';
return @paths;
}
sub _get_web_user_paths {
my ($user) = @_;
my $user_home = _get_user_home($user);
return () unless $user_home;
my @paths;
# web specific logs in user's ~/logs directory ???
my $logs_dir = "$user_home/logs";
push @paths, $logs_dir if -d $logs_dir;
return @paths;
}
sub _get_user_home {
my ($user) = @_;
my @pwent = getpwnam($user);
return @pwent ? $pwent[7] : undef;
}
#
# Plugin System
#
# Third-party plugins can be installed by dropping a YAML file in PLUGIN_DIR.
# Each plugin YAML file should define handlers that point to executable scripts.
#
# Example plugin YAML structure:
#
# name: myapp
# description: "MyApp application logs"
# handlers:
# get_default_retention: /opt/cpanel/myapp/bin/log_retention_default
# get_user_retention: /opt/cpanel/myapp/bin/log_retention_user
# sys_paths: /opt/cpanel/myapp/bin/log_retention_sys_paths
# user_paths: /opt/cpanel/myapp/bin/log_retention_user_paths
#
# Handler scripts should:
# - get_default_retention: Print the default retention days (integer) to STDOUT
# - get_user_retention: Accept username as $1, print retention days to STDOUT (or nothing for default)
# - sys_paths: Print one path per line to STDOUT
# - user_paths: Accept username as $1, print one path per line to STDOUT
#
sub _load_plugin_log_types {
my $plugin_dir = PLUGIN_DIR;
return unless -d $plugin_dir;
opendir my $dh, $plugin_dir or return;
while ( my $file = readdir($dh) ) {
next unless $file =~ /^([a-z][a-z0-9_-]*)\.(?:yaml|yml)$/i;
my $potential_name = $1;
next unless -f "$plugin_dir/$file";
try {
my $config = Cpanel::YAML::LoadFile("$plugin_dir/$file");
_register_plugin_log_type( $config, "$plugin_dir/$file" );
}
catch {
warn "Failed to load plugin from $file: $_\n";
};
}
closedir $dh;
return;
}
sub _register_plugin_log_type {
my ( $config, $config_path ) = @_;
# Validate required fields
my $name = $config->{name};
unless ( $name && $name =~ /^[a-z][a-z0-9_-]*$/i ) {
warn "Plugin config $config_path: 'name' is required and must be alphanumeric\n";
return;
}
# Don't allow overriding built-in types
if ( exists $BUILTIN_LOG_TYPES{$name} ) {
warn "Plugin config $config_path: Cannot override built-in log type '$name'\n";
return;
}
my $handlers = $config->{handlers};
unless ( $handlers && ref($handlers) eq 'HASH' ) {
warn "Plugin config $config_path: 'handlers' section is required\n";
return;
}
# Validate required handlers exist and are executable
for my $required (qw(get_default_retention sys_paths)) {
my $handler = $handlers->{$required};
unless ( $handler && -f $handler && -x $handler ) {
warn "Plugin config $config_path: Handler '$required' ($handler) must exist and be executable\n";
return;
}
}
# Register the plugin log type with wrapper functions
$LOG_TYPES{$name} = {
description => $config->{description} || "Plugin: $name",
get_default_retention => sub { _call_plugin_handler( $handlers->{get_default_retention}, 'scalar' ) },
get_user_retention => sub { _call_plugin_handler( $handlers->{get_user_retention}, 'scalar', @_ ) },
sys_paths => sub { _call_plugin_handler( $handlers->{sys_paths}, 'list' ) },
user_paths => sub { _call_plugin_handler( $handlers->{user_paths}, 'list', @_ ) },
_plugin_config => $config,
};
return 1;
}
sub _call_plugin_handler {
my ( $handler_path, $return_type, @args ) = @_;
# If no handler defined (optional handlers like get_user_retention)
return $return_type eq 'list' ? () : undef unless $handler_path;
return $return_type eq 'list' ? () : undef unless -f $handler_path && -x $handler_path;
my $result = Cpanel::SafeRun::Object->new(
program => $handler_path,
args => \@args,
timeout => 30,
);
if ( $result->CHILD_ERROR() ) {
warn "Plugin handler $handler_path failed: " . ( $result->stderr() || 'unknown error' ) . "\n";
return $return_type eq 'list' ? () : undef;
}
my $output = $result->stdout() // '';
chomp $output;
if ( $return_type eq 'scalar' ) {
# Return first line as scalar (e.g., retention days)
my ($value) = split /\n/, $output, 2;
return $value;
}
else {
# Return all lines as list (e.g., paths)
return grep { length $_ } split /\n/, $output;
}
}
exit( __PACKAGE__->script(@ARGV) || 0 ) if !caller();
1;
__END__
=head1 NAME
scripts::log_retention - Log retention management utility for cPanel & WHM
=head1 SYNOPSIS
/usr/local/cpanel/scripts/log_retention [options]
Options:
--help, -h Show help message
--run Execute log retention cleanup
--type TYPE Process specific log type(s) only
--verbose, -v Enable verbose output
=head1 DESCRIPTION
This script manages log file retention across different log types in cPanel & WHM.
It supports:
=over 4
=item * System-wide default retention policies
=item * User-specific retention overrides
=item * Multiple log types (web, and extensible for others)
=item * Hook points for custom pre/post deletion actions
=item * Resource-aware processing
=back
=head1 LOG TYPES
=head2 web
Manages web server logs including:
=over 4
=item * Apache access and error logs
=item * NGINX access and error logs
=item * Domain-specific logs in user directories
=item * System-wide web server logs
=back
=head1 CONFIGURATION
=head2 System Configuration
Default web log retention is configured via WHM Tweak Settings
(web_log_retention_days in /var/cpanel/cpanel.config):
web_log_retention_days=30
Set to 0 to never delete (this is the default).
=head2 User Configuration
Users can override the system default via the .cpanel-logs file
in the user's home directory (~user/.cpanel-logs):
web-log-retention-days=60
Set to 0 to never delete user logs.
If not set or invalid, the system default is used.
=head1 HOOKS
The following hooks are available for custom integration, such as archiving
logs to external storage before deletion:
=head2 Log::Retention::pre_deletion
Called before deleting files. This is the recommended integration point for
archiving solutions - copy or upload the files before they are deleted.
Receives:
=over 4
=item * log_type - The type of logs being processed
=item * user - Username (if processing user logs, undef for system logs)
=item * base_path - Base directory being processed
=item * files_to_delete - Array reference of files to be deleted
=item * retention_days - Retention period in days
=back
=head2 Log::Retention::post_deletion
Called after deleting files. Receives:
=over 4
=item * log_type - The type of logs processed
=item * user - Username (if processing user logs, undef for system logs)
=item * base_path - Base directory processed
=item * deleted_count - Number of files actually deleted
=item * retention_days - Retention period in days
=back
=cut