1. cPanel & WHM Documentation
  2. cPanel Knowledge Base
  3. Accounts
  4. VirtFS Jailed Shell
ssh accounts jailedshell

VirtFS Jailed Shell

Last modified: May 5, 2023

Overview

cPanel & WHM uses VirtFS to provide 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 increases security for a server’s other users.

  • Users in a jailed shell environment can run otherwise-unavailable commands (for example, crontab and passwd).

Important:

  • Your servers may experience performance and connection issues if you attempt to mount more than 4000 targets in a Virtuozzo environment. Your servers may also experience these kinds of issues if you enable the EXPERIMENTAL: Jail Apache Virtual Hosts using mod_ruid2 and cPanel® jailshell setting in WHM’s Tweak Settings interface (WHM » Home » Server Configuration » Tweak Settings) on servers with more than 500 accounts.

  • If you enable a jailed shell on a server that runs CloudLinux™, you may cause a security vulnerability with symlinks to files outside of the caged directory. To solve this issue, you must enable link traversal protection. For more information, read CloudLinux’s Link traversal protection documentation.

The virtfs directory

Warning:

Do not use the rm command to remove any mounted file or directory within the /home/virtfs/ directory. If you run this on any mounted file or directory within the /home/virtfs/ directory, you will also delete all of the files in the directory to which it is mounted. This action will render your server nonfunctional.

When a user logs in to a jailed shell environment via SSH or SFTP for the first time, the system creates the /home/virtfs/ directory. This directory contains configuration files, utilities, and BIND mounts.

  • You cannot prevent the creation of this directory or disable it.

  • This directory does not use any disk space. However, because it is a virtual mount point, some commands (for example, du) report that the directory uses disk space.

  • BIND mounts create a virtual link between two locations on the file system. For example, if a user views the contents of the /home/virtfs/username/usr/bin/ directory, the user actually sees the contents of the /usr/bin/ directory. For more information about BIND mounts, run the man 8 mount command.

Note:

  • Servers that run the CentOS 7, CloudLinux™ 7 or higher, AlmaLinux OS, Rocky Linux™, Red Hat® Enterprise Linux® (RHEL) 7, or Ubuntu® operating systems may use additional mount points for common system paths (for example, /usr/bin). Do not unmount these mount points.

  • On servers that run the CentOS 7, CloudLinux 7 or higher, AlmaLinux, Rocky Linux, RHEL 7, or Ubuntu operating systems, the /etc/mtab symlink points to the /proc/self/mounts file.

Enable a jailed shell environment

WHM includes two options to activate a jailed shell environment. The option that you use depends on the type of users for whom you wish to enable jailed shells.

To enable a jailed shell environment for all new and modified users, use the Use cPanel® jailshell by default option in WHM’s Tweak Settings interface (WHM » Home » Server Configuration » Tweak Settings).

  • This option allows you to force the use of a jailed shell for new accounts and accounts that you subsequently edit in the following interfaces:

  • This option does not affect accounts that already exist on the server but that you have not edited in these interfaces.

To enable a jailed shell environment for a specific user, use WHM’s Manage Shell Access interface (WHM » Home » Account Functions » Manage Shell Access).

Note:

When you enable jailed shell access for a user, the system sets the user’s shell to the /usr/local/cpanel/bin/jailshell location.

Exim and VirtFS

When a user’s shell location is /usr/local/cpanel/bin/jailshell (jailed shell is enabled) or /usr/local/cpanel/bin/noshell (all shells are disabled), Exim runs any process from alias or filter files inside VirtFS. This action provides extra security because Exim commands run in a jailed shell and do not affect other users.

CSF or LFD alerts

If you use a utility that monitors system changes (for example, CSF or LFD), you may see an alert that resembles the following example after you upgrade:

1
2
3
4
5

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 files in the /usr/bin directory. These symlinks allow jailed shell environments to access the crontab and passwd commands.

Disable or remove a jailed shell environment

Warning:

You cannot completely remove the jailed shell system (VirtFS). The directions below remove a jailed shell environment, but cannot prevent the recreation of the jailed shell environment. The following processes may recreate the jailed shell environment:

  • Exim processing filters.

  • Piped email addresses.

  • Cron jobs.

  • Jailed Apache virtual hosts that use the mod_ruid2 module via the EXPERIMENTAL: Jail Apache Virtual Hosts using mod_ruid2 and cPanel® jailshell option in WHM’s Tweak Settings interface (WHM » Home » Server Configuration » Tweak Settings).

Disable the jailed shell environment

Warning:
You cannot disable the /home/virtfs/ directory for your users, even if you disable jailed shell access. For more information about the /home/virtfs/ directory, read the The /home/virtfs/ directory section above.

To disable the jailed shell environment for a specific user, use WHM’s Manage Shell Access interface (Home » Account Functions » Manage Shell Access).

To disable the jailed shell environment for all of the users on your server, perform the following steps:

  1. Disable the Use cPanel® jailshell by default option in WHM’s Tweak Settings interface (WHM » Home » Server Configuration » Tweak Settings).

  2. Select Disabled Shell for all of the server’s accounts in WHM’s Manage Shell Access interface (WHM » Home » Account Functions » Manage Shell Access).

Note:

When you disable jailed shell access, the system sets the users’ shells to the /usr/local/cpanel/bin/noshell location. With this location, the user retains access to SFTP in a non-jailed environment.

Remove a user’s jailed shell environment

To remove a jailed shell environment, perform the following steps:

  1. Disable the jailed shell environment for the user in WHM’s Manage Shell Access interface (WHM » Home » Account Functions » Manage Shell Access).

  2. To unmount the VirtFS BIND mounts, run the following command, where username is the desired account username: 

    umount /home/virtfs/username/usr/bin

The clear orphaned VirtFS mounts script

You can run the /usr/local/cpanel/scripts/clear_orphaned_virtfs_mounts script to unmount the BIND mounts for users who no longer exist or who no longer use a jailed shell environment. This script removes the /home/virtfs/username/ directory and its contents.

To force the removal of all VirtFS mount points, run the following command, where username is an account’s username:

/usr/local/cpanel/scripts/clear_orphaned_virtfs_mounts --clearall

To check your system for VirtFS mount points, run the following command, where username is the desired account username:

grep -i username /proc/mounts

Additional Documentation