Support diary: bypassing cPanel pkgacct and

Support diary: bypassing cPanel pkgacct and aligning customer communication#

Working in the trenches of high-level technical support means that daily life is a mix of tactical "hacking" and applied psychology. Today I document two real routine situations: how to bypass a structural limitation in cPanel backups via CLI and how to manage communication crises by isolating external issues.

The challenge of selective exclusion in `pkgacct`#

I needed to package a hosting account using the /scripts/pkgacct script via terminal, with the constraint of excluding large directories (such as caches and redundant upload folders) to optimize transfer time and storage.

The Technical Problem: The native cPanel pkgacct does not have a direct exclusion flag on the command line (e.g., --exclude). The --skiphomedir option is too drastic, as it ignores the entire /home/user/ directory.

The Forensic Solution: Use the cPanel Backup Subsystem global exclusion mechanism via a temporary .conf file.

1. Disk space mapping and identifying large directories#

Before deciding what to exclude, the administrator needs to track where the storage is concentrated on the user's account:

# List the user's home directory sorted by file size
ls -la /home/user/

# Find the top 10 largest directories under the user's home
du -sh /home/user/*/ | sort -rh | head -10

# List the detailed size of public_html subdirectories (e.g., wp-content in WordPress)
du -sh /home/user/public_html/wp-content/*/ | sort -rh

# Locate individual files larger than 100MB
find /home/user -type f -size +100M -exec ls -lh {} \;

2. Selective exclusion rules in `cpbackup-exclude.conf` (advanced syntax)#

The cpbackup-exclude.conf file allows you to exclude folders and files using relative patterns and wildcards (glob patterns).

Golden Rule: Paths inside this file must be strictly relative to the user's home directory (/home/user/).

Incorrect: /home/user/public_html/uploads (cPanel will ignore this pattern).
Correct: public_html/wp-content/uploads (Without a leading slash).

To apply precise exclusions, create the file:

nano /home/user/cpbackup-exclude.conf

Insert the recommended exclusion patterns:

# Exclude specific upload and heavy cache directories
public_html/wp-content/uploads/
public_html/wp-content/cache/
public_html/cache/
public_html/tmp/

# Exclude all log files and raw SQL dumps in home
*.log
*.sql

# Wildcard glob pattern to ignore contents under any temporary folders
**/tmp/*

3. File permissions and security for the `.conf` file#

cPanel runs backup operations as root or under the user's privileges depending on the execution context. Incorrect permissions will prevent the .conf file from being read, leading cPanel to silently ignore the exclusion rules.

Configure the file with strict security permissions:

# If cPanel reads it as root (common in CLI administrative backups):
chmod 644 /home/user/cpbackup-exclude.conf
chown root:root /home/user/cpbackup-exclude.conf

# If running within the restricted context of the user account:
chown user:user /home/user/cpbackup-exclude.conf
chmod 600 /home/user/cpbackup-exclude.conf

4. Preventive backups and `pkgacct` execution#

Before overwriting configurations or initiating compression, create preventive backups of existing exclusion files if any, and set up safeguard backups:

# Backup the current exclude file (if it exists)
cp /home/user/cpbackup-exclude.conf /home/user/cpbackup-exclude.conf.bak 2>/dev/null

# Quick and safe backup of the user home directory before running pkgacct
tar czf /root/user-home-backup-$(date +%Y%m%d).tar.gz /home/user/

Now, execute the native packaging:

/scripts/pkgacct user

Or save it to a specific directory with a timestamp:

/scripts/pkgacct user /root/backup-user-$(date +%Y%m%d).tar.gz

5. Verification and auditing of backup logs#

Do not trust only console output. Audit the corresponding log files to ensure the process completed successfully and verify if any errors occurred:

# Logs in the user's home directory
tail -100 /home/user/logs/pkgacct.log

# Global cPanel administrative logs
tail -100 /usr/local/cpanel/logs/pkgacct.log

# Search for file exclusion messages
grep -i "exclude" /usr/local/cpanel/logs/pkgacct.log

# Search for errors or silent compilation failures
grep -iE "error|fail" /usr/local/cpanel/logs/pkgacct.log

6. Post-exclusion validation audit#

After the backup is generated, you must formally verify that the exclusion of large directories succeeded and that the file is not corrupted.

# 1. Compare backup size (it should be smaller than the sum of the original home directory)
du -sh /home/backup-*.tar.gz

# 2. List the internal contents of the file without extracting it
tar -tvf /home/backup-*.tar.gz | grep public_html/wp-content/uploads

# 3. Test controlled extraction in a temporary directory for inspection
mkdir -p /tmp/backup-check
tar -xzf /home/backup-*.tar.gz -C /tmp/backup-check

# 4. Validate that the excluded folder is not present
ls -la /tmp/backup-check/home/user/public_html/wp-content/uploads 2>/dev/null
# If the command returns "No such file or directory" (exit code 2), the exclusion worked successfully!

# Clean up the temporary check directory
rm -rf /tmp/backup-check

7. Rollback and recovery procedure#

If packaging fails, hangs, or corrupts files on the source account, follow the immediate rollback routine:

# 1. Remove corrupted or partial temporary backup files
rm -f /home/backup-*.tar.gz /root/backup-*.tar.gz

# 2. Restore the original exclusion file
if [ -f /home/user/cpbackup-exclude.conf.bak ]; then
    mv /home/user/cpbackup-exclude.conf.bak /home/user/cpbackup-exclude.conf
else
    rm -f /home/user/cpbackup-exclude.conf
fi

# 3. If necessary, restore from a verified previous backup
/scripts/unpkgacct /root/user-home-backup-[previous_date].tar.gz

# 4. Rebuild Apache configurations if virtual host path configurations broke
/usr/local/cpanel/scripts/rebuildhttpdconf
/usr/local/cpanel/scripts/restartsrv httpd

8. Batch backup automation script (multiple users)#

To avoid operational overhead when migrating multiple servers or accounts, use the following automation Bash script:

#!/bin/bash
# backup-selective.sh - Automated selective backup for multiple users in cPanel

USERS=("user1" "user2" "user3")
BACKUP_DIR="/root/selective_backups"
mkdir -p "$BACKUP_DIR"

for user in "${USERS[@]}"; do
    echo "=============================================="
    echo "Starting processing for account: $user"
    echo "=============================================="
    
    # 1. Backup existing cpbackup-exclude.conf if any
    if [ -f "/home/$user/cpbackup-exclude.conf" ]; then
        cp "/home/$user/cpbackup-exclude.conf" "/home/$user/cpbackup-exclude.conf.bak"
    fi

    # 2. Create temporary configuration with default exclusions
    cat > "/home/$user/cpbackup-exclude.conf" << 'EOF'
public_html/wp-content/uploads/
public_html/wp-content/cache/
public_html/cache/
public_html/tmp/
*.log
*.sql
EOF

    # Configure secure permissions
    chown root:root "/home/$user/cpbackup-exclude.conf"
    chmod 644 "/home/$user/cpbackup-exclude.conf"

    # 3. Run native pkgacct saving to destination directory
    /scripts/pkgacct "$user" "$BACKUP_DIR/backup-$user-$(date +%Y%m%d).tar.gz"
    
    if [ $? -eq 0 ]; then
        echo "✅ Backup of account $user completed successfully."
    else
        echo "❌ ERROR: Failed to generate backup for account $user."
    fi

    # 4. Clean up temporary cpbackup-exclude.conf and restore backup if it existed
    rm -f "/home/$user/cpbackup-exclude.conf"
    if [ -f "/home/$user/cpbackup-exclude.conf.bak" ]; then
        mv "/home/$user/cpbackup-exclude.conf.bak" "/home/$user/cpbackup-exclude.conf"
    fi
done

9. Selective backup checklist#

## Checklist: pkgacct with selective exclusion

### Pre-backup
- [ ] Map large directories with `du -sh` and list heavy files.
- [ ] Take a preventive backup of the original `cpbackup-exclude.conf` if it exists.
- [ ] Create the `cpbackup-exclude.conf` file with valid relative paths.
- [ ] Validate file permissions and ownership (chmod 644 / chown root:root).

### Execution
- [ ] Trigger the native packaging routine `/scripts/pkgacct`.
- [ ] Monitor command line output and check logs at `/usr/local/cpanel/logs/pkgacct.log`.
- [ ] Verify there are no system I/O errors or exceptions.

### Post-backup
- [ ] Validate `.tar.gz` integrity by listing its contents (`tar -tvf`).
- [ ] Test extraction inside a temporary `/tmp/` folder and inspect exclusions.
- [ ] Clean up temporary `cpbackup-exclude.conf` files or restore the backup copy.
- [ ] Document the backup scope and excluded directories.

Diagnosing HTTP 404 errors and DNS validation#

I received a critical ticket about a domain returning an error when loading an external landing page. After auditing the DNS zone and confirming correct propagation (dig +short A domain.com), I identified that the final destination (third-party infrastructure) responded with HTTP 404 (Not Found).

1. Technical diagnosis of HTTP errors (cURL and --resolve)#

To isolate the issue and prove that the failure is not originating from the web server I manage, perform thorough checks using curl:

# 1. Check only the HTTP response header
curl -I https://domain.com/

# 2. View SSL handshakes and detailed headers
curl -v https://domain.com/ 2>&1 | grep -E "* TLS|* SSL|< HTTP"

# 3. Loop to test multiple subdomains or application paths
for path in "" "/wp-admin" "/login" "/page"; do
    echo "Path: $path -> HTTP Status: $(curl -o /dev/null -s -w '%{http_code}' https://domain.com$path)"
done

# 4. Validate requests simulating different target IP backends (Bypass local DNS resolver with --resolve)
# Format: --resolve <host>:<port>:<address>
for dns_ip in "192.168.1.100" "192.168.1.101"; do
    echo "Testing against backend IP $dns_ip:"
    curl -o /dev/null -s -w 'HTTP Code: %{http_code}\n' --resolve domain.com:443:$dns_ip https://domain.com/
done

2. Complete DNS audit and propagation verification#

Diagnosing external pointings requires validating all DNS record types and their propagation window status:

# 1. Verify A record (destination IP address)
dig A domain.com +short

# 2. Verify delegated Name Servers (NS)
dig NS domain.com +short

# 3. Verify mail exchange records (MX)
dig MX domain.com +short

# 4. Check the TTL (Time To Live) configured in the ANSWER SECTION
dig domain.com | grep -A1 "ANSWER SECTION"

# 5. Loop to monitor global propagation of DNS records against public resolvers
for resolver in 8.8.8.8 1.1.1.1 208.67.222.222 9.9.9.9; do
    echo "Resolver $resolver -> IP: $(dig @$resolver domain.com A +short)"
done

3. Customer communication engineering (N3 support)#

Here, the senior SRE's role is to isolate technical responsibility without appearing evasive. A blunt response like "Everything is fine here, the error is on their side" generates friction and useless new tickets.

The Difference Between Informing and Resolving:#

Amateur Approach: "On our server, DNS is OK. The 404 error is on their end. Check with the landing page support."

Senior Approach (Assertive):

"Hello, [Customer Name]! We have performed a full name resolution (DNS) audit and confirmed the correct pointing to the partner's servers. However, when testing direct connectivity with the destination (https://domain.com), their application server returns the HTTP 404 status. This confirms that traffic is reaching the destination, but the final application cannot locate the files. We recommend checking the following steps with them: 1. Confirm with the provider if the virtual directory was correctly provisioned on the destination server. 2. Verify that the corresponding index file is present in the application's root directory. 3. Validate if there are any specific rewrite rules (.htaccess/Nginx) redirecting traffic incorrectly to non-existent paths. We are available to send the full logs and DNS report if your partner needs additional technical proof."

Impact: You isolate the problem with evidence, deliver value by helping the client with next steps, and close the technical doubt loop. In N3 support, communication clarity must be as absolute as terminal command precision.

Was this article helpful?

Leave a quick reaction to help prioritize future technical guides:

This post is licensed under CC BY-NC.