Learn how to securely add programs like SSH clients, PHP, and system utilities to chrooted shell environments in Plesk. This comprehensive guide explains the proper configuration techniques, common pitfalls, and best practices for maintaining security while expanding functionality within chrooted environments.

 

Advanced Guide to Adding Programs to Chrooted Shell Environments in Plesk

 

Table of Contents

Introduction to Chrooted Environments in Plesk

Chrooted shell environments are a powerful security feature in Plesk that isolates user sessions from the rest of the server, limiting potential damage from security breaches. However, by default, these environments are minimal and lack many programs users might need for day-to-day operations.

What is Plesk?

Plesk is a comprehensive web hosting control panel that simplifies server and website management through a graphical interface. It provides tools for domain management, email configuration, database administration, and security settings, making it a popular choice for web hosting providers and administrators.

What is a Chrooted Shell Environment?

A chrooted shell environment uses the "chroot" (change root) Unix operation to restrict a user's file system access to a specific directory subtree, effectively making that directory appear as the root (/) directory to the user. This isolation prevents users from accessing or modifying files outside their designated environment, significantly enhancing security by containing potential breaches.

What is ldconfig?

ldconfig is a Linux utility that configures the dynamic linker run-time bindings. It creates, updates, and removes necessary links and cache for the most recent shared libraries found in the directories specified in the system's configuration files. In a chrooted environment, ldconfig is crucial for ensuring that added programs can find their required libraries.

How Plesk Handles PHP

Plesk offers two primary PHP handling methods:

  1. OS-provided PHP: The default PHP version installed by your operating system's package manager.
  2. Plesk PHP: Custom PHP versions managed by Plesk, typically installed in the /opt/plesk/php/[version] directory, allowing multiple PHP versions to coexist.

In standard Plesk configurations, PHP scripts on websites are executed by the web server or PHP-FPM process pool in a non-chrooted context. Adding PHP to a chrooted environment is primarily useful for running PHP scripts via SSH/CLI within the chrooted environment, not for enhancing website PHP script security.

Prerequisites and System Requirements

Before You Begin

  • Root or sudo access to the Plesk server via SSH
  • Plesk properly installed and configured
  • Basic understanding of Linux command line operations
  • Knowledge of which programs you need to add to the chrooted environment
  • Verification that your target programs can function in a chrooted environment (not all software is compatible)

Compatible Systems

  • Plesk Obsidian and newer
  • Linux-based operating systems (CentOS, RHEL, AlmaLinux, Rocky Linux, Debian, Ubuntu)
  • Apache 2.4.x (latest version)
  • PHP 7.4, 8.0, 8.1, 8.2, and 8.3 (currently supported versions)
  • MySQL 8.0 or MariaDB 10.5+ (if database functionality is needed)

Important: Not all software can function correctly in a chrooted environment. Always check the software's documentation or verify compatibility before attempting to add it to your chrooted environment.

Setting Up the update-chroot Script

The update-chroot script is a utility developed by Plesk to simplify the process of adding programs to chrooted environments. Before adding any programs, you'll need to download and set up this script.

Download and Prepare the Script

  1. Log in to your server via SSH as root or with sudo privileges
  2. Download the update-chroot script using the following command:
curl -o update-chroot.sh https://raw.githubusercontent.com/plesk/kb-scripts/master/update-chroot/update-chroot.sh && chmod 700 update-chroot.sh

Verify the Script

Before using the script, verify it's working properly:

./update-chroot.sh --help

This command should display the available options and usage information for the script. Keep this reference handy as you'll use various options throughout the process.

Note: The update-chroot.sh script must be run with root or sudo privileges. Make sure you have the proper permissions before proceeding.

Adding Programs to Chrooted Environments

With the update-chroot script prepared, you can now add various programs to your chrooted environment template. The following sections cover some common programs administrators often need to add.

Adding SSH Client

The SSH client allows users in a chrooted environment to establish secure connections to other servers, which is often necessary for tasks like file transfers or remote management.

Step 1: Add Terminal Device Support

The SSH client requires access to terminal devices to function properly. Add them with the following command:

./update-chroot.sh --devices tty

Important: Without access to /dev/tty, SSH will not be able to work. This step is crucial for SSH functionality.

Step 2: Add the SSH Executable

Next, add the SSH client binary to the chrooted environment:

./update-chroot.sh --add ssh

Step 3: Apply Changes to Domains

Apply these changes to specific domains:

./update-chroot.sh --apply example-1.com example-2.com

Or apply to all domains at once:

./update-chroot.sh --apply all

After applying these changes, domain users will be able to use the SSH client from within their chrooted environment.

Adding PHP by OS Vendor

Adding the system's PHP version to the chrooted environment allows users to execute PHP scripts from the command line. This is useful for running maintenance scripts, cron jobs, or testing.

Note: Adding PHP to the chrooted environment will not enhance the security of PHP scripts executed by the web server, as those scripts run in a non-chrooted context.

Step 1: Add the PHP Binary

./update-chroot.sh --add php

Step 2: Set vhosts Path Variable

Define the Plesk virtual hosts directory path:

VHOSTS=`grep HTTPD_VHOSTS_D /etc/psa/psa.conf | awk '{print $2}'`

Step 3: Add Timezone Definitions

PHP requires timezone data to properly handle date and time functions:


        mkdir -p $VHOSTS/chroot/usr/share
        cp -a /usr/share/zoneinfo $VHOSTS/chroot/usr/share/zoneinfo

Warning: Without proper timezone definitions, PHP will produce errors when date/time functions are used, such as:

glibc detected php: free(): invalid pointer: 0x00007f11249fccd8 ***

Step 4: Add PHP Extensions

The PHP binary itself doesn't depend on extensions, so they need to be added separately:

For RHEL/CentOS/AlmaLinux/Rocky Linux:

for i in /usr/lib64/php/modules/*.so ; do ./update-chroot.sh --add $i ; done

For Ubuntu/Debian:

for i in /usr/lib/php/modules/*.so ; do ./update-chroot.sh --add $i ; done

To find the correct path to PHP modules on your system:

php -i | grep -E "^extension_dir"

Step 5: Copy PHP Configuration


        mkdir -p $VHOSTS/chroot/etc
        cp -a /etc/php.ini /etc/php.d $VHOSTS/chroot/etc/

To find the correct configuration path on your system:

php -i | grep -E "^Configuration File|^Scan this dir for additional"

Step 6: Set Default Timezone

sed -i.bkp 's/;date.timezone =/date.timezone = Europe\/Zurich/' $VHOSTS/chroot/etc/php.ini

Note: By default, the date.timezone variable is not set, which can cause PHP scripts to fail when using the date("r") function. It will return a warning before returning the date.

Step 7: Apply Changes

For specific domains:

./update-chroot.sh --apply example-1.com example-2.com

Or for all domains:

./update-chroot.sh --apply all

Important: Changes will not be applied if the "Access to the server over SSH" value in Plesk > Domains > example_domain.com > Web Hosting Access is not set to "/bin/bash (chrooted)".

Adding Plesk PHP

Plesk installs its own PHP versions separate from the system PHP. These versions can be added to the chrooted environment to ensure consistency with website PHP versions.

Step 1: Set PHP Version Variable

Define the Plesk PHP version path you want to add:

PHPPATH='/opt/plesk/php/8.2'

To see available Plesk PHP versions on your server:

ls -d /opt/plesk/php/*

Step 2: Add the PHP Binary

./update-chroot.sh --add $PHPPATH/bin/php

Step 3: Set vhosts Path Variable

VHOSTS=`grep HTTPD_VHOSTS_D /etc/psa/psa.conf | awk '{print $2}'`

Step 4: Add Timezone Definitions


        mkdir -p $VHOSTS/chroot/usr/share
        cp -a /usr/share/zoneinfo $VHOSTS/chroot/usr/share/zoneinfo

Warning: Without proper timezone definitions, PHP will produce errors when date/time functions are used.

Step 5: Add PHP Extensions

For RHEL/CentOS/AlmaLinux/Rocky Linux:

for i in $PHPPATH/lib64/php/modules/*.so; do ./update-chroot.sh --add $i; done

For Ubuntu/Debian:

for i in $PHPPATH/lib/php/modules/*.so; do ./update-chroot.sh --add $i; done

Step 6: Copy PHP Configuration


        mkdir -p $VHOSTS/chroot$PHPPATH/etc/
        cp -a $PHPPATH/etc/ $VHOSTS/chroot$PHPPATH/; rm -rf $VHOSTS/chroot$PHPPATH/etc/php-fpm.d

Step 7: Set Default Timezone

sed -i.bkp 's/;date.timezone =/date.timezone = Europe\/Zurich/' $VHOSTS/chroot/$PHPPATH/etc/php.ini

Step 8: Apply Changes

./update-chroot.sh --apply all

Note: When using PHP in the chrooted environment, users must specify the full path to the PHP executable, for example:

$PHPPATH/bin/php -v

Configuring ldconfig

The ldconfig utility updates the dynamic linker run-time bindings, which is essential for programs to find their required shared libraries. In newer versions of update-chroot.sh (1.2 and above), ldconfig is automatically installed when adding new applications, but you may need to configure it manually in some cases.

Note: If you're using update_chroot.sh version 1.2 or newer, ldconfig should be automatically installed. These steps are primarily for older versions or manual configuration.

Step 1: Set vhosts Path Variable

VHOSTS=`grep HTTPD_VHOSTS_D /etc/psa/psa.conf | awk '{print $2}'`

Step 2: Copy Configuration Files

cp -a /etc/ld.so.conf* $VHOSTS/chroot/etc

Step 3: Add ldconfig to the Template

./update-chroot.sh --add ldconfig

Step 4: Update the Linker's Configuration

chroot $VHOSTS/chroot /bin/sh -c "ldconfig -v"

Step 5: Apply Changes

./update-chroot.sh --apply all

Important: Running ldconfig is crucial after adding new libraries to ensure they are properly linked and available to programs in the chrooted environment.

 

Troubleshooting and Common Issues

Program Not Found After Adding

Symptoms: After adding a program and applying changes, users get "command not found" errors when trying to use it in the chrooted environment.

Possible Solutions:

  1. Verify the program is correctly added to the template: 
    ls -la $VHOSTS/chroot/usr/bin/[program-name]
  2. Check if all dependencies were added: 
    ldd /usr/bin/[program-name] | awk '{print $3}' | grep -v '^$' | xargs -I{} ./update-chroot.sh --add {}
  3. Update the dynamic linker cache: 
    chroot $VHOSTS/chroot /bin/sh -c "ldconfig -v"
  4. Reapply changes to the affected domains: 
    ./update-chroot.sh --apply [domain-name]

Missing Shared Libraries

Symptoms: Programs fail to run with errors about missing shared libraries even after being added to the chrooted environment.

Possible Solutions:

  1. Identify missing libraries: 
    chroot $VHOSTS/chroot /bin/sh -c "/usr/bin/[program-name]" 2>&1 | grep "cannot open shared object"
  2. Add the missing libraries: 
    find /usr/lib64 /usr/lib -name "libname.so*" | xargs -I{} ./update-chroot.sh --add {}
  3. Run ldconfig in the chroot environment: 
    chroot $VHOSTS/chroot /bin/sh -c "ldconfig -v"

PHP Date/Time Errors

Symptoms: PHP scripts fail with errors related to date/time functions or invalid pointers when running in the chrooted environment.

Possible Solutions:

  1. Verify timezone data is correctly copied: 
    ls -la $VHOSTS/chroot/usr/share/zoneinfo
  2. Check that date.timezone is properly set in php.ini: 
    grep "date.timezone" $VHOSTS/chroot/etc/php.ini
    or for Plesk PHP: 
    grep "date.timezone" $VHOSTS/chroot/$PHPPATH/etc/php.ini
  3. Set timezone if not already configured: 
    sed -i.bkp 's/;date.timezone =/date.timezone = Europe\/Zurich/' $VHOSTS/chroot/etc/php.ini

Changes Not Applied to Domains

Symptoms: After adding programs and applying changes, they don't appear in the chrooted environment for domains.

Possible Solutions:

  1. Verify that SSH access for the domain is set to chrooted: 
    plesk bin subscription --info example.com | grep "Shell access"
    The output should include "chrooted". If not, update it via Plesk UI or with: 
    plesk bin subscription --update example.com -shell /bin/bash -shell-login true -ssl true -php-settings-type chrooted
  2. Reapply changes: 
    ./update-chroot.sh --apply example.com
  3. Verify permissions: 
    ls -la $VHOSTS/system/example.com

 

Best Practices and Security Considerations

General Recommendations

  • Minimize Added Programs: Only add programs that are essential for users' operations to maintain the security benefits of chrooted environments.
  • Keep Templates Updated: When updating system packages, remember to update the corresponding programs in the chroot template.
  • Document Customizations: Maintain documentation of all programs added to the chroot template for easier maintenance and troubleshooting.
  • Test Before Deployment: Always test programs in a non-production environment before deploying to production chrooted environments.
  • Use Version Control: Consider putting your chroot template configuration under version control to track changes and facilitate recovery if needed.

Security Considerations

  • Avoid Dangerous Programs: Avoid adding programs that could potentially escape the chroot jail or compromise security.
  • Regularly Audit: Periodically review the programs added to your chroot templates to ensure they remain necessary and secure.
  • Monitor Logs: Implement logging and monitoring for suspicious activities within chrooted environments.
  • Keep Programs Updated: Regularly update programs in the chroot environment to patch security vulnerabilities.
  • Principle of Least Privilege: Only add programs that users actually need, following the principle of least privilege.

Performance Considerations

  • Minimize Duplicated Files: The update-chroot script adds necessary dependencies, but try to avoid adding redundant programs that serve similar functions.
  • Be Mindful of Disk Space: Each program added to the chroot template increases disk usage across all domains using chrooted environments.
  • Consider Resource Usage: Some programs may consume significant resources when run in a chrooted environment. Monitor system performance after adding resource-intensive programs.

 

Frequently Asked Questions

Why would I need to add programs to a chrooted environment?

By default, chrooted environments in Plesk are minimal to maximize security. However, users often need additional tools for development, file management, or specific operations. Adding programs enables these capabilities while maintaining the security benefits of isolation.

Will adding PHP to the chrooted environment improve the security of my websites?

No. Adding PHP to the chrooted environment only affects PHP execution via the command line within the chrooted shell. Website PHP scripts are executed by the web server or PHP-FPM in a non-chrooted context, so their security is not affected by this configuration.

How do I determine which programs are compatible with chrooted environments?

Not all programs can function in chrooted environments. Programs that require access to system-wide resources, kernel modules, or specific device files may not work correctly. Check the program's documentation or test it in a controlled environment before widespread deployment.

Do I need to repeat these steps after Plesk updates?

Plesk updates generally preserve chroot templates, but major updates or operating system upgrades might require reconfiguration. It's a good practice to verify the chroot environment after significant updates and re-add programs if necessary.

Can I add graphical programs to the chrooted environment?

While technically possible, adding graphical programs to a chrooted environment is generally impractical. Chrooted environments are primarily designed for command-line operations,

Did this answer help? 0 People found this helpful (0 Votes)

Top Articles

How To Add Public SSH Key To Your WebHostingM cPanel For SSH Access

Take website security to the next level! This comprehensive guide explores generating SSH keys...
How To Banish Unwanted Visitors From Accessing Your Site In cPanel

Learn how to block IP addresses from accessing your website using cPanel's IP Blocker interface....
How To Change An Email Account Password In WebHostingM cPanel

Learn how to change your email account password in cPanel to enhance email security and protect...
How To Create A cPanel Sub-Account For Your Website Developer

Learn how to create and manage sub-accounts for your website developers using cPanel's Manage...
How To Deal With cPanel Terminal Error: The WebSocket Handshake Failed

Learn how to resolve the "WebSocket handshake failed" error in your cPanel Terminal interface....