[Development Guides Home](/guides)

# 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](#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](#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:

| Handler | Parameters | Returns |
|  --- | --- | --- |
| Required[`get_default_retention`](#get_default_retention) | None | Default number of retention days. |
| [`get_user_retention`](#get_user_retention) | username | 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`](#sys_paths) | None | One system path per line. |
| [`user_paths`](#user_paths) | username | One 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
```