Page tree
Skip to end of metadata
Go to start of metadata

This document is for a previous release of cPanel & WHM. To view our latest documentation, visit our Home page.

For cPanel & WHM 11.44

Overview

VirtFS provides a jailed shell environment for users who connect to a server via SSH. The jailed shell acts as a container for the user, and does not allow the user to access other users' home directories on the server.

Unlike a normal shell environment, a jailed shell environment prevents access to data outside of the user's home directory.

A jailed shell helps increase security for a system administrator's other users.

Warning:

If you run the rm command on any mounted file or directory within the /home/virtfs directory, you will also delete all of the files stored in the directory to which it is mounted. This will render your server nonfunctional. We do not recommend that you attempt to remove any of these files or directories in this way. 

Enable VirtFS

System administrators have two options which allow them to activate a jailed shell:

  1. WHM's Manage Shell Access interface (Home >> Account Functions >> Manage Shell Access). After a system administrator enables jailed shell access for a user, the user's shell will be set to the follopwing location: /usr/local/cpanel/bin/jailshell.
  2. The Use cPanel® jailshell by default option in WHM's Tweak Settings interface (Home >> Server Configuration >> Tweak Settings). This option allows a system administrator to force the use of a jailed shell for the following types of accounts:
    • New accounts.
    • Accounts that are modified in the Modify An Account interface (Home >> Account Functions >> Modify an Account).
    • Accounts with packages that have been changed from the Upgrade/Downgrade An Account interface (Home >> Account Functions >> Upgrade/Downgrade an Account).

Remember:

These configuration options only affect new or modified accounts. To configure an existing account to use a jailed shell, system administrators can review the options in WHM's Manage Shell Access interface (Home >> Account Functions >> Manage Shell Access). 

The system creates the /home/virtfs directory, which contains configuration files, utilities, and bind mounts, when a user first logs in to a jailed shell environment via SSH or SFTP.

Notes:

  • A bind mount is a transparent link between two places on the file system. For example, if a user views the contents of the /home/virtfs/username/usr/bin file the user actually sees the contents of /usr/bin.
  •  Users can run the man 8 mount command via the command line to retrieve more information about bind mounts.

 

Disable VirtFS

To disable VirtFS, system administrators can disable jailed shell access through WHM's Tweak Settings interface (Home >> Server Configuration >> Tweak Settings) and Manage Shell Access interface (Home >> Account Functions >> Manage Shell Access).

Note:

If a system administrator disables jailed shell access for a user, the user's shell will be set to the following option: /usr/local/cpanel/bin/noshell. The user will still have access to SFTP in a non-jailed environment. 

Remove VirtFS

Important:

  • It is not possible to completely remove the jailed shell system. 
  • The directions below will remove a jailed shell, but cannot prevent the recreation of the jailed environment. Examples of processes that recreate the jailed environment include:
    • Exim processing filters
    • Piped e-mail addresses
    • Cron tasks
    • Jailed Apache Virtual Hosts that use mod_ruid2 via the EXPERIMENTAL: Jail Apache Virtual Hosts using mod_ruid2 and cPanel® jailshell Tweak Settings option (Home >> Server Configuration >> Tweak Settings).

Unmount the bind mounts

Warning:

The directions below will remove a jailed shell, but cannot prevent the recreation of the jailed environment. Examples of processes that recreate the jailed environment include:

  • Exim processing filters
  • Piped e-mail addresses
  • Cron tasks
  • via the EXPERIMENTAL: Jail Apache Virtual Hosts using mod_ruid2 and cPanel® jailshell Tweak Settings option (Home >> Server Configuration >> Tweak Settings).

Before you can safely remove the jailed shell environment, you must switch the user's shell to a normal shell through the Manage Shell Access interface (Home >> Account Functions >> Manage Shell Access). To do this, perform the following steps:

  1. Switch to the normal shell.
  2. Unmount all bind mounts under the /home/virtfs/$user/ directory with the umount command. 
    For example, to unmount /home/virtfs/username/usr/bin, where username represents the cPanel user's name, run the following command:

    umount /home/virtfs/username/usr/bin 

To discover whether a directory is still bind-mounted, search for the appropriate username in the /proc/mounts directory. Run the following command and replace username with the cPanel & WHM user's username:

grep -i username /proc/mounts 

If you wish to unmount the bind mounts for users who no longer exist or no longer use Jailed Shell, run the /scripts/ clear_orphaned_virtfs_mounts script.

The /scripts/clear_orphaned_virtfs_mounts script will remove the contents of the /home/virtfs/$user/etc directory. The script will also remove the account's /home/virtfs/$user directory.

If you wish to force the removal of all of the virtfs mounts, add the -- clearall flag when you run the script:

/scripts/clear_orphaned_virtfs_mounts --clearall

Warning:

If you run the rm command on any file or directory within the /home/virtfs directory that is still mounted, you will also delete all of the files in the directory to which it is mounted. This will render your server nonfunctional. We do not recommend that you attempt to remove any of these files or directories in this way.  

Exim in a jailed or disabled shell

When a user's shell is configured to jailshell or noshell, Exim runs any process created from alias or filter files inside of VirtFS. This action provides extra security because Exim commands will run in a jailed shell and not affect other users.

Additional Information

All versions of cPanel & WHM

  • A jailed shell is a binary that cPanel distributes to users. Users with a jailed shell will have their shell set to /usr/local/cpanel/bin/jailshell.
  • A disabled shell does not have command line access. Users with a disabled shell will have their shell set to /usr/local/cpanel/bin/noshell.

cPanel & WHM version 11.40

* As of cPanel & WHM version 11.40, users with a jail shelled environment have the ability to utilize previously unavailable commands, such as crontab and passwd. You can enable this option within the Tweak Settings interface (Home >> Server Configuration >> Tweak Settings).

Warning:

If you use a utility that monitors system changes (for example, CSF or LFD), you may see the following alert after you upgrade to cPanel & WHM version 11.40:

The following list of files have FAILED the md5sum comparison test. This means that the file has been changed in some way.
This could be a result of an OS update or application upgrade. If the change is unexpected it should be investigated:

/bin/crontab: FAILED
/bin/passwd: FAILED

This is a false positive warning. cPanel & WHM uses the /bin/crontab and /bin/passwd  symlinks to link to the CentOS files in the /usr/bin directory. These symlinks allow jailshelled environments to access both crontab and passwd.