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.48

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 directory's files 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 with this action.

Enable VirtFS

Two options allow you to activate a jailed shell environment:

  1. WHM's Manage Shell Access interface (Home >> Account Functions >> Manage Shell Access). After you enable jailed shell access for a user, the system sets the user's shell to the /usr/local/cpanel/bin/jailshell location.
  2. The Use cPanel® jailshell by default option in WHM's Tweak Settings interface (Home >> Server Configuration >> Tweak Settings). This option allows you to force the use of a jailed shell for the following types of accounts:
    • New accounts.
    • Existing accounts, when you modify them in WHM's Modify An Account interface (Home >> Account Functions >> Modify an Account).
    • Existing accounts, when you change their packages in WHM's 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 environment, 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 locations 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 the /usr/bin directory
  • Users can run the man 8 mount command via the command line to retrieve more information about bind mounts.

Disable VirtFS

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

Note:

If you disable jailed shell access for a user, the system will set the user's shell to the /usr/local/cpanel/bin/noshell option. 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 remove a jailed shell, but cannot prevent the recreation of the jailed environment. Processes that recreate the jailed environment include the following:
    • 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 remove a jailed shell, but cannot prevent the recreation of the jailed environment. Processes that recreate the jailed environment include the following:

  • 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 option in WHM's Tweak Settings interface (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 WHM's 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 of the bind mounts under the /home/virtfs/$user/ directory with the umount command. 
    For example, to unmount the /home/virtfs/username/usr/bin directory, 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, where username represents 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 also removes 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 run in a jailed shell and do not affect other users.

Additional information

  • 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.
  • Disabled shells cannot access the command line. Users with a disabled shell will have their shell set to /usr/local/cpanel/bin/noshell.
  • Users with a jail shelled environment can use previously-unavailable commands, such as the crontab and passwd commands. Enable this option in WHM's Tweak Settings interface (Home >> Server Configuration >> Tweak Settings).
  • If you use a utility that monitors system changes (for example, CSF or LFD), you may see an alert after you upgrade. 

    • 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 jailed shell environments to access both the crontab  and passwd commands.

      This warning resembles the following example:

      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