Skip to content
rConfig Documentation

Updating PHP for rConfig

Preface: Maintaining Zero CVEs

Section titled “Preface: Maintaining Zero CVEs”

rConfig takes security seriously. We’re proud to maintain a Zero CVE (Common Vulnerabilities and Exposures) record, and we’re committed to keeping it that way. A critical component of maintaining this security posture is ensuring that all underlying dependencies, including PHP, remain current and patched.

Why This Update Matters

Section titled “Why This Update Matters”

If you’re running rConfig on PHP 8.3 or earlier, updating to PHP 8.4 is critical for several reasons:

  • Security: PHP 8.3 reached its coming to End of Life for active support on 31 Dec 2025. Running unsupported PHP versions exposes your system to known vulnerabilities that may never be patched.
  • Performance: PHP 8.4 includes significant performance improvements, meaning faster configuration backups, quicker searches, and more responsive UI interactions.
  • Compatibility: rConfig Pro and Vector Server 8.1 are optimized for PHP 8.4, ensuring you get the best experience with all features working as intended.
  • Long-term Support: PHP 8.4 receives active security support until 31 Dec 2028, giving you peace of mind for years to come.

Prerequisites

Section titled “Prerequisites”

Before updating PHP, ensure you have:

  • Root or sudo access to your server
  • A current backup of your rConfig installation and database
  • At least 15 minutes of maintenance window (rConfig will be briefly unavailable)
  • Stable internet connection for downloading packages

Update Instructions by Operating System

Section titled “Update Instructions by Operating System”

CentOS / Rocky Linux

Section titled “CentOS / Rocky Linux”
Terminal window
cd /home
yum -y install wget
wget https://dl.rconfig.com/downloads/php-updates/centos-php8-update.sh -O /home/centos-php8-update.sh
chmod +x centos-php8-update.sh
./centos-php8-update.sh

The script will:

  1. Add the Remi repository for PHP 8.4
  2. Remove existing PHP packages
  3. Install PHP 8.4 with all required extensions
  4. Configure PHP-FPM for optimal rConfig performance
  5. Restart Apache/Nginx and PHP-FPM services

What the Update Script Does

Section titled “What the Update Script Does”

Our automated update scripts handle the entire PHP upgrade process safely:

  1. Backup Configuration: Saves current PHP configuration files
  2. Repository Setup: Adds trusted repositories for PHP 8.4
  3. Package Removal: Cleanly removes old PHP versions
  4. Installation: Installs PHP 8.4 and all required extensions:
    • php8.4-cli
    • php8.4-fpm
    • php8.4-mysql
    • php8.4-mbstring
    • php8.4-xml
    • php8.4-curl
    • php8.4-zip
    • php8.4-gd
    • php8.4-intl
    • php8.4-bcmath
    • php8.4-soap
    • php8.4-ssh2
  5. Service Configuration: Configures PHP-FPM for optimal performance
  6. Service Restart: Restarts web server and PHP-FPM
  7. Verification: Confirms PHP 8.4 is active

Post-Update Verification

Section titled “Post-Update Verification”

After the script completes, verify your PHP version:

Terminal window
php -v

You should see output similar to:

PHP 8.4.x (cli) (built: ...)

Verify rConfig Functionality

Section titled “Verify rConfig Functionality”
  1. Log into your rConfig web interface
  2. Navigate to Admin > System Settings
  3. Check the system information panel - PHP version should show 8.4.x
  4. Test key functions:
    • Run a device backup
    • Perform a configuration search
    • Check compliance policies
    • View reports

Notes for Custom PHP Installations

Section titled “Notes for Custom PHP Installations”

If you have installed PHP manually from source, compiled custom PHP versions, or used alternative package managers, please note:

Custom Compiled PHP

Section titled “Custom Compiled PHP”

If you compiled PHP from source:

  1. Backup your php.ini: Your custom configuration will be preserved, but create a backup:

    Terminal window
    cp /usr/local/lib/php.ini /usr/local/lib/php.ini.backup

  2. Check Installation Paths: Custom PHP installations may use different paths:

    Terminal window
    which php
    php-config --prefix

  3. Manual Update Required: The automated scripts assume standard package manager installations. For custom builds, you’ll need to:

    • Download PHP 8.4 source from php.net
    • Compile with the same configure options you used previously
    • Ensure all rConfig-required extensions are compiled
    • Update your web server configuration to use the new PHP version

Docker/Container Installations

Section titled “Docker/Container Installations”

If rConfig is running in Docker or containers:

  1. Update the base image in your Dockerfile:

    FROM php:8.4-fpm

  2. Rebuild the container:

    Terminal window
    docker-compose down
    docker-compose build --no-cache
    docker-compose up -d

NOTE: rConfig official Docker images will be updated to PHP 8.4 in future releases.

Troubleshooting

Section titled “Troubleshooting”

Script Fails to Download

Section titled “Script Fails to Download”

If wget fails to download the update script:

Terminal window
# Try with curl instead
curl -o /home/php8-update.sh https://dl.rconfig.com/downloads/php-updates/centos-php8-update.sh


# Or check your firewall/proxy settings
curl -v https://dl.rconfig.com

rConfig Shows Blank Page After Update

Section titled “rConfig Shows Blank Page After Update”

This usually indicates a PHP extension is missing:

Terminal window
# Check PHP error log
tail -f /var/log/php-fpm/error.log


# Check Apache/Nginx error log
tail -f /var/log/apache2/error.log  # Ubuntu/Debian
tail -f /var/log/httpd/error_log     # CentOS/RHEL


# Verify all required extensions are loaded
php -m

Service Fails to Start

Section titled “Service Fails to Start”

If PHP-FPM or your web server fails to start:

Terminal window
# Check service status
systemctl status php8.4-fpm
systemctl status apache2  # or nginx


# Check for configuration errors
php-fpm8.4 -t
apachectl configtest

Permission Issues

Section titled “Permission Issues”

If you encounter permission errors:

Terminal window
# Ensure proper ownership
chown -R www-data:www-data /var/www/rconfig  # Ubuntu/Debian
chown -R apache:apache /var/www/rconfig      # CentOS/RHEL


# Verify PHP-FPM pool permissions
ls -la /var/run/php/

Rolling Back (If Necessary)

Section titled “Rolling Back (If Necessary)”

If you need to roll back to your previous PHP version:

  1. Stop services:

    Terminal window
    systemctl stop php8.4-fpm
    systemctl stop apache2  # or nginx

  2. Remove PHP 8.4:

    Terminal window
    # Ubuntu/Debian
    sudo apt-get remove --purge php8.4*
    

    # CentOS/RHEL
    yum remove php84*

  3. Reinstall previous version (example for PHP 8.1):

    Terminal window
    # Ubuntu/Debian
    sudo apt-get install php8.1 php8.1-fpm php8.1-mysql php8.1-mbstring php8.1-xml
    

    # CentOS/RHEL
    yum install php81 php81-php-fpm php81-php-mysqlnd php81-php-mbstring php81-php-xml

  4. Restore configuration from your backup

  5. Restart services

Best Practices

Section titled “Best Practices”
  • Schedule Updates During Maintenance Windows: Plan PHP updates during off-peak hours
  • Test First: Always test in a non-production environment before updating production
  • Monitor After Update: Watch logs and system performance for 24-48 hours post-update
  • Document Custom Changes: Keep records of any custom PHP configurations or extensions
  • Stay Current: Enable automatic security updates for your OS where possible
  • Subscribe to Security Advisories: Stay informed about PHP security announcements

Support

Section titled “Support”

If you encounter issues during the PHP update process:

  1. Check the rConfig Community Forums
  2. Review the troubleshooting section above
  3. Contact rConfig Support with:
    • Your OS and version
    • Output from php -v and php -m
    • Relevant error logs
    • Steps you’ve already taken

Additional Resources

Section titled “Additional Resources”

Last Updated: December 2025