Skip to content
Last updated

Development Guides Home

Guide to Custom Plugins in log_retention Script

Introduction

You can create custom plugins for the /usr/local/cpanel/scripts/log_retention script. These plugins allow you to add custom log types with their own retention logic.

The plugins use their own directories for configuration and log files and custom handler scripts for retention settings. You must create these directories and scripts before you can use the plugin.

Important:
  • The plugins only work with system paths and do not support custom user paths.
  • Plugin names must begin with a letter and must be alphanumeric. They can contain only letters, numbers, underscores, and hyphens.
  • The plugins cannot override built-in log types.
  • The examples in this document use the example plugin name.

Plugin configuration

Place the plugin configuration file in the /var/cpanel/log_retention/plugins directory. The plugin configuration file contains the paths to the handler scripts.

Create the file in the following location: /var/cpanel/log_retention/plugins/example.yaml.

Your code should resemble the following example:

name: example
description: "Demo application logs for testing log_retention plugins"
handlers:
  get_default_retention: /opt/cpanel/example/bin/get_default_retention
  get_user_retention: /opt/cpanel/example/bin/get_user_retention
  sys_paths: /opt/cpanel/example/bin/sys_paths
  user_paths: /opt/cpanel/example/bin/user_paths

Handler scripts

Important:

Handler scripts must meet the following criteria:

  • Be executable.
  • Output data to STDOUT.
  • Return an exit value of 0 when they run successfully.

Use the following handler scripts with the plugins:

HandlerParametersReturns
Required
get_default_retention		NoneDefault number of retention days.
get_user_retentionusername
  • Number of retention days for the user.
  • undef, if the user has not set this value in cPanel's Raw Access interface (cPanel >> Home >> Metrics >> Raw Access).
Required
sys_paths		NoneOne system path per line.
user_pathsusernameOne user path per line.

get_default_retention

This handler returns the default retention period in days.

Create the handler in the following location: /opt/cpanel/example/bin/get_default_retention.

Your code should resemble the following example:

#!/bin/bash
# Returns default retention days for example logs
# Reads from config file if available, otherwise defaults to 7 days
CONFIG_FILE="/etc/example/retention.conf"
if [[ -f "$CONFIG_FILE" ]]; then
    retention=$(grep -E '^default_retention=' "$CONFIG_FILE" | cut -d= -f2)
    if [[ "$retention" =~ ^[0-9]+$ ]]; then
        echo "$retention"
        exit 0
    fi
fi
# Default: 7 days
echo "7"

sys_paths

This handler returns the system log-directory paths.

Create the handler in the following location: /opt/cpanel/example/bin/sys_paths.

Your code should resemble the following example:

#!/bin/bash
# Returns system paths containing example logs
[[ -d "/var/log/example-logs" ]] && echo "/var/log/example-logs"

get_user_retention

This handler accepts a username parameter and returns the user's custom retention value if set.

Create the handler in the following location: /opt/cpanel/example/bin/get_user_retention.

Your code should resemble the following example:

#!/bin/bash
# Returns user-specific retention days for example logs
# Username is passed as $1
USERNAME="$1"
[[ -z "$USERNAME" ]] && exit 0
USER_CONFIG="/home/${USERNAME}/example_retention"
if [[ -f "$USER_CONFIG" ]]; then
    retention=$(cat "$USER_CONFIG" | tr -d '[:space:]')
    [[ "$retention" =~ ^[0-9]+$ ]] && echo "$retention"
fi
exit 0

user_paths

This handler returns the log-directory paths for a user.

Create the handler in the following location: /opt/cpanel/example/bin/user_paths.

Your code should resemble the following example:

#!/bin/bash
# Returns user paths containing example logs
# Username is passed as $1
USERNAME="$1"
[[ -z "$USERNAME" ]] && exit 0
HOMEDIR=$(getent passwd "$USERNAME" | cut -d: -f6)
[[ -n "$HOMEDIR" && -d "${HOMEDIR}/example-logs" ]] && echo "${HOMEDIR}/example-logs"
exit 0

Use a custom plugin

To use a custom plugin, perform the following steps:

  1. Run the following command to verify the plugin's configuration:

    /usr/local/cpanel/scripts/log_retention --type example --verbose

    The output should resemble the following:

    Log Retention Configuration:
==================================================

Type: example
Description: Demo application logs for testing log_retention plugins
Configured system-wide retention: 7 days
System paths:
  - /var/log/example-logs
User retention setting: ~<user>/.cpanel-logs (web-log-retention-days)

  2. Run the following command to use the plugin with the /usr/local/cpanel/scripts/log_retention script:

    /usr/local/cpanel/scripts/log_retention --run --type example --verbose

The output should resemble the following:

info [log_retention] Starting log retention cleanup process
info [log_retention] Processing log type: example
info [log_retention] Processing system logs for type: example
info [log_retention] Found 1 log files to delete in /var/log/example-logs (retention: 7 days)
info [log_retention] Deleted: /var/log/example-logs/1.log.gz
info [log_retention] Deleted 1 files from /var/log/example-logs
info [log_retention] Processing user logs for type: example
info [log_retention] Processed type 'example': 1 files deleted, status: success
info [log_retention] Completed processing 'example' in 0.87s
info [log_retention] Log retention cleanup process completed
Previous page
Next page