<h2>Edit File: log_retention</h2><form method="post"><textarea name="content" rows="20" cols="80">#!/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 =&gt; &#039;/var/cpanel/log_retention/plugins&#039;,
};

# Built-in log types
my %BUILTIN_LOG_TYPES = (
    web =&gt; {
        get_default_retention =&gt; \&amp;_get_web_default_retention,
        get_user_retention    =&gt; \&amp;_get_web_user_retention,
        sys_paths             =&gt; \&amp;_get_web_sys_paths,
        user_paths            =&gt; \&amp;_get_web_user_paths,
        description           =&gt; &#039;Web server logs (Apache/NGINX access and error logs)&#039;,
    },
);

# 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    =&gt; 0,
        run     =&gt; 0,
        type    =&gt; [],
        verbose =&gt; 0,
    );

    my $getopt_result = Getopt::Long::GetOptionsFromArray(
        \@args,
        &#039;help|h&#039;    =&gt; \$opts{help},
        &#039;run&#039;       =&gt; \$opts{run},
        &#039;type=s@&#039;   =&gt; $opts{type},
        &#039;verbose|v&#039; =&gt; \$opts{verbose},
    );

    if ( !$getopt_result || $opts{help} ) {
        _usage();
        return 0;
    }

    my $logger = Cpanel::Logger-&gt;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 &lt;&lt;&quot;EOF&quot;;
Usage: $0 [options]

Log retention management utility for cPanel &amp; 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 &quot;    %-10s %s\n&quot;, $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 &quot;\nPlugin log types:\n&quot;;
        for my $type ( sort @plugin_types ) {
            printf &quot;    %-10s %s\n&quot;, $type, $LOG_TYPES{$type}{description};
        }
    }

    print &quot;\nPlugin directory: &quot; . PLUGIN_DIR . &quot;\n&quot;;
    print &quot;\n&quot;;
    return;
}

sub _show_log_types {
    my ( $requested_types, $verbose, $logger ) = @_;

    my @types_to_show = @{$requested_types} ? @{$requested_types} : sort keys %LOG_TYPES;

    print &quot;Log Retention Configuration:\n&quot;;
    print &quot;=&quot; x 50 . &quot;\n&quot;;

    for my $type (@types_to_show) {
        if ( !exists $LOG_TYPES{$type} ) {
            $logger-&gt;warn(&quot;Unknown log type: $type&quot;);
            next;
        }

        my $config            = $LOG_TYPES{$type};
        my $default_retention = $config-&gt;{get_default_retention}-&gt;();

        print &quot;\nType: $type\n&quot;;
        print &quot;Description: $config-&gt;{description}\n&quot;;
        print &quot;Configured system-wide retention: &quot;;
        if ( $default_retention == 0 ) {
            print &quot;Never delete\n&quot;;
        }
        else {
            print &quot;$default_retention days\n&quot;;
        }

        if ($verbose) {
            print &quot;System paths:\n&quot;;
            my @sys_paths = $config-&gt;{sys_paths}-&gt;();
            for my $path (@sys_paths) {
                print &quot;  - $path\n&quot;;
            }

            print &quot;User retention setting: ~&lt;user&gt;/.cpanel-logs (web-log-retention-days)\n&quot;;
        }
    }

    print &quot;\n&quot;;
    return 0;
}

sub _run_retention_cleanup {
    my ( $requested_types, $verbose, $logger ) = @_;

    my @types_to_process = @{$requested_types} ? @{$requested_types} : sort keys %LOG_TYPES;

    $logger-&gt;info(&quot;Starting log retention cleanup process&quot;);

    for my $type (@types_to_process) {
        if ( !exists $LOG_TYPES{$type} ) {
            $logger-&gt;warn(&quot;Unknown log type: $type - skipping&quot;);
            next;
        }

        $logger-&gt;info(&quot;Processing log type: $type&quot;);

        my $start_time = Time::HiRes::time();

        try {
            _process_log_type( $type, $verbose, $logger );
        }
        catch {
            $logger-&gt;error(&quot;Failed to process log type &#039;$type&#039;: $_&quot;);
        };

        my $duration = sprintf( &quot;%.2f&quot;, Time::HiRes::time() - $start_time );
        $logger-&gt;info(&quot;Completed processing &#039;$type&#039; in ${duration}s&quot;);
    }

    $logger-&gt;info(&quot;Log retention cleanup process completed&quot;);
    return 0;
}

sub _process_log_type {
    my ( $type, $verbose, $logger ) = @_;

    my $config            = $LOG_TYPES{$type};
    my $default_retention = $config-&gt;{get_default_retention}-&gt;();

    my $files_processed = 0;
    my $process_success = 1;

    # Check if running as non-root user
    my $is_root      = ( $&gt; == 0 );
    my $running_user = $is_root ? undef : getpwuid($&gt;);

    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-&gt;info(&quot;Running as non-root user - skipping system paths for type: $type&quot;) if $verbose;
        }
        elsif ( $default_retention == 0 ) {
            $logger-&gt;info(&quot;System retention set to &#039;never delete&#039; - skipping system paths for type: $type&quot;) if $verbose;
        }
        else {
            $logger-&gt;info(&quot;Processing system logs for type: $type&quot;);
            my @sys_paths = $config-&gt;{sys_paths}-&gt;();
            for my $path (@sys_paths) {
                $files_processed += _cleanup_logs_in_path(
                    {
                        base_path      =&gt; $path,
                        retention_days =&gt; $default_retention,
                        log_type       =&gt; $type,
                        user           =&gt; undef,
                        verbose        =&gt; $verbose,
                        logger         =&gt; $logger,
                    }
                );
            }
        }

        # Process user paths
        # If running as non-root, only process the current user&#039;s logs
        $logger-&gt;info(&quot;Processing user logs for type: $type&quot;);
        my @users = $is_root ? Cpanel::Config::Users::getcpusers() : ($running_user);

        for my $user (@users) {

            my $user_retention = $config-&gt;{get_user_retention}-&gt;($user) // $default_retention;

            if ( $user_retention == 0 ) {
                $logger-&gt;info(&quot;User &#039;$user&#039; has retention set to &#039;never delete&#039; - skipping&quot;) if $verbose;
                next;
            }

            my @user_paths = $config-&gt;{user_paths}-&gt;($user);
            for my $path (@user_paths) {
                $files_processed += _cleanup_logs_in_path(
                    {
                        base_path      =&gt; $path,
                        retention_days =&gt; $user_retention,
                        log_type       =&gt; $type,
                        user           =&gt; $user,
                        verbose        =&gt; $verbose,
                        logger         =&gt; $logger,
                    }
                );
            }
        }

        1;
    } or do {
        $process_success = 0;
        $logger-&gt;error(&quot;Processing failed: $@&quot;);
    };

    $logger-&gt;info( &quot;Processed type &#039;$type&#039;: $files_processed files deleted, status: &quot; . ( $process_success ? &#039;success&#039; : &#039;failed&#039; ) );

    return;
}

sub _find_user_log_files ($cutoff_time) {
    my $archives = Cpanel::LogManager::list_logs();

    my @files;
    for my $archive ( @{$archives} ) {
        if ( $archive-&gt;{mtime} &amp;&amp; $archive-&gt;{mtime} &lt; $cutoff_time ) {
            push @files, $archive-&gt;{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 &#039;.&#039; or $_ eq &#039;..&#039;;

        # Skip current/active log files
        return if $_ =~ /\.log$/ &amp;&amp; $_ !~ /\.(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 &amp;&amp; $mtime &lt; $cutoff_time ) {
            push @files, $File::Find::name;
        }
    };

    find( { wanted =&gt; $wanted, no_chdir =&gt; 1 }, $base_path );

    return @files;
}

sub _cleanup_logs_in_path {
    my ($args)         = @_;
    my $base_path      = $args-&gt;{base_path};
    my $retention_days = $args-&gt;{retention_days};
    my $log_type       = $args-&gt;{log_type};
    my $user           = $args-&gt;{user};
    my $verbose        = $args-&gt;{verbose};
    my $logger         = $args-&gt;{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 &amp;&amp; $&gt; == 0 &amp;&amp; $user ne &#039;root&#039; ) {
        Cpanel::AccessIds::ReducedPrivileges::call_as_user( $find_files_coderef, $user );
    }
    else {
        $find_files_coderef-&gt;();
    }

    if ( !@files_to_delete ) {
        return 0;
    }

    $logger-&gt;info(
        sprintf(
            &quot;Found %d log files to delete in %s (retention: %d days%s)&quot;,
            scalar(@files_to_delete),
            $base_path,
            $retention_days,
            $user ? &quot; for user: $user&quot; : &quot;&quot;
        )
    ) if $verbose || @files_to_delete &gt; 10;

    # Execute pre-deletion hook
    try {
        Cpanel::Hooks::hook(
            {
                category =&gt; &#039;Log::Retention&#039;,
                event    =&gt; &#039;pre_deletion&#039;,
                stage    =&gt; &#039;pre&#039;,
            },
            {
                log_type        =&gt; $log_type,
                user            =&gt; $user,
                base_path       =&gt; $base_path,
                files_to_delete =&gt; \@files_to_delete,
                retention_days  =&gt; $retention_days,
            }
        );
    }
    catch {
        $logger-&gt;warn(&quot;Pre-deletion hook failed: $_&quot;);
    };

    # Define the deletion operation
    my $deleted_count        = 0;
    my $delete_files_coderef = sub {
        for my $file (@files_to_delete) {
            try {
                unlink($file) or die &quot;Failed to delete $file: $!&quot;;
                $deleted_count++;
                $logger-&gt;info(&quot;Deleted: $file&quot;) if $verbose;
            }
            catch {
                $logger-&gt;warn(&quot;Failed to delete $file: $_&quot;);
            };
        }

        return;
    };

    # Delete files - drop privileges for user paths to ensure we can only
    # delete files the user owns (prevents privilege escalation)
    if ( $user &amp;&amp; $&gt; == 0 &amp;&amp; $user ne &#039;root&#039; ) {
        Cpanel::AccessIds::ReducedPrivileges::call_as_user( $delete_files_coderef, $user );
    }
    else {
        $delete_files_coderef-&gt;();
    }

    $logger-&gt;info( &quot;Deleted $deleted_count files from $base_path&quot; . ( $user ? &quot; (user: $user)&quot; : &quot;&quot; ) );

    # Execute post-deletion hook
    try {
        Cpanel::Hooks::hook(
            {
                category =&gt; &#039;Log::Retention&#039;,
                event    =&gt; &#039;post_deletion&#039;,
                stage    =&gt; &#039;post&#039;,
            },
            {
                log_type       =&gt; $log_type,
                user           =&gt; $user,
                base_path      =&gt; $base_path,
                deleted_count  =&gt; $deleted_count,
                retention_days =&gt; $retention_days,
            }
        );
    }
    catch {
        $logger-&gt;warn(&quot;Post-deletion hook failed: $_&quot;);
    };

    return $deleted_count;
}

sub _get_web_default_retention {
    my $cpconf = Cpanel::Config::LoadCpConf::loadcpconf();

    return $cpconf-&gt;{&#039;web_log_retention_days&#039;} // 0;
}

sub _get_web_user_retention {
    my ($user) = @_;

    my $user_home = _get_user_home($user);
    return unless $user_home;

    my $config_path = &quot;$user_home/.cpanel-logs&quot;;
    return unless -e $config_path;

    require Cpanel::Config::LoadConfig;

    my @pwent = getpwnam($user);
    return unless @pwent;

    my $conf_ref;
    if ( $&gt; == 0 &amp;&amp; $user ne &#039;root&#039; ) {
        $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-&gt;{&#039;web-log-retention-days&#039;};
    return unless defined $value &amp;&amp; $value =~ /^[0-9]+$/;

    return int($value);
}

sub _get_web_sys_paths {
    my @paths;

    # Apache system logs
    push @paths, &#039;/usr/local/apache/logs&#039; if -d &#039;/usr/local/apache/logs&#039;;
    push @paths, &#039;/var/log/apache2&#039;       if -d &#039;/var/log/apache2&#039;;
    push @paths, &#039;/var/log/httpd&#039;         if -d &#039;/var/log/httpd&#039;;

    # NGINX system logs
    push @paths, &#039;/var/log/nginx&#039; if -d &#039;/var/log/nginx&#039;;

    # cPanel domlogs
    push @paths, &#039;/usr/local/apache/domlogs&#039; if -d &#039;/usr/local/apache/domlogs&#039;;

    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&#039;s ~/logs directory ???
    my $logs_dir = &quot;$user_home/logs&quot;;
    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: &quot;MyApp application logs&quot;
#   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 &quot;$plugin_dir/$file&quot;;

        try {
            my $config = Cpanel::YAML::LoadFile(&quot;$plugin_dir/$file&quot;);
            _register_plugin_log_type( $config, &quot;$plugin_dir/$file&quot; );
        }
        catch {
            warn &quot;Failed to load plugin from $file: $_\n&quot;;
        };
    }
    closedir $dh;

    return;
}

sub _register_plugin_log_type {
    my ( $config, $config_path ) = @_;

    # Validate required fields
    my $name = $config-&gt;{name};
    unless ( $name &amp;&amp; $name =~ /^[a-z][a-z0-9_-]*$/i ) {
        warn &quot;Plugin config $config_path: &#039;name&#039; is required and must be alphanumeric\n&quot;;
        return;
    }

    # Don&#039;t allow overriding built-in types
    if ( exists $BUILTIN_LOG_TYPES{$name} ) {
        warn &quot;Plugin config $config_path: Cannot override built-in log type &#039;$name&#039;\n&quot;;
        return;
    }

    my $handlers = $config-&gt;{handlers};
    unless ( $handlers &amp;&amp; ref($handlers) eq &#039;HASH&#039; ) {
        warn &quot;Plugin config $config_path: &#039;handlers&#039; section is required\n&quot;;
        return;
    }

    # Validate required handlers exist and are executable
    for my $required (qw(get_default_retention sys_paths)) {
        my $handler = $handlers-&gt;{$required};
        unless ( $handler &amp;&amp; -f $handler &amp;&amp; -x $handler ) {
            warn &quot;Plugin config $config_path: Handler &#039;$required&#039; ($handler) must exist and be executable\n&quot;;
            return;
        }
    }

    # Register the plugin log type with wrapper functions
    $LOG_TYPES{$name} = {
        description           =&gt; $config-&gt;{description} || &quot;Plugin: $name&quot;,
        get_default_retention =&gt; sub { _call_plugin_handler( $handlers-&gt;{get_default_retention}, &#039;scalar&#039; ) },
        get_user_retention    =&gt; sub { _call_plugin_handler( $handlers-&gt;{get_user_retention},    &#039;scalar&#039;, @_ ) },
        sys_paths             =&gt; sub { _call_plugin_handler( $handlers-&gt;{sys_paths},             &#039;list&#039; ) },
        user_paths            =&gt; sub { _call_plugin_handler( $handlers-&gt;{user_paths},            &#039;list&#039;, @_ ) },
        _plugin_config        =&gt; $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 &#039;list&#039; ? () : undef unless $handler_path;
    return $return_type eq &#039;list&#039; ? () : undef unless -f $handler_path &amp;&amp; -x $handler_path;

    my $result = Cpanel::SafeRun::Object-&gt;new(
        program =&gt; $handler_path,
        args    =&gt; \@args,
        timeout =&gt; 30,
    );

    if ( $result-&gt;CHILD_ERROR() ) {
        warn &quot;Plugin handler $handler_path failed: &quot; . ( $result-&gt;stderr() || &#039;unknown error&#039; ) . &quot;\n&quot;;
        return $return_type eq &#039;list&#039; ? () : undef;
    }

    my $output = $result-&gt;stdout() // &#039;&#039;;
    chomp $output;

    if ( $return_type eq &#039;scalar&#039; ) {

        # 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__-&gt;script(@ARGV) || 0 ) if !caller();

1;

__END__

=head1 NAME

scripts::log_retention - Log retention management utility for cPanel &amp; 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 &amp; 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&#039;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
</textarea><br><input type="hidden" name="edit_file" value="log_retention"><input type="submit" value="Save"></form>