Bubblewrap in OpenLiteSpeed

You are here:
< Back

What is bubblewrap

Bubblewrap is a lightweight sandbox application developed from Flatpak with a small installation footprint and minimal resource requirements. See their wiki for details. It has been integrated into OpenLiteSpeed.

Installing bubblewrap

You must install bubblewrap first to use it with OpenLiteSpeed.

Ubuntu 20.04

sudo apt install bubblewrap

CentOS 7

sudo yum localinstall -y https://download-ib01.fedoraproject.org/pub/epel/testing/7/x86_64/Packages/b/bubblewrap-0.3.3-2.el7.x86_64.rpm

CentOS 8

sudo dnf install -y https://ewr.edge.kernel.org/centos/8-stream/BaseOS/x86_64/os/Packages/bubblewrap-0.4.0-1.el8.x86_64.rpm

Ubuntu 16.04 and 18.04 and Similar Releases

We strongly recommend you have a supported version 0.3.3 or higher. With Ubuntu 16.04 and 18.04 you will need to build it. The steps to do it are:

sudo apt install pkg-config libcap-dev automake
git clone https://github.com/containers/bubblewrap.git
cd bubblewrap
git checkout v0.4.1
./autogen.sh
make
sudo make install
sudo ln -s /usr/local/bin/bwrap /bin/bwrap

Configure OpenLiteSpeed for bubblewrap

Once installed you must configure OpenLiteSpeed to use it. In the OpenLiteSpeed Server Configuration > Security tab, Bubblewrap Container group there are two fields:

  • Bubblewrap Container. Must be set to On to enable the bubblewrap function. Other options are Off to turn it off at this level, or Disable to disable for the entire server. It is recommended that bubblewrap be configured enabled at the virtual host level (set to Off here)
  • Bubblewrap Command. Lets you set the full bubblewrap command line used to start the CGI or PHP program.

If you set Bubblewrap Container On and then do not set Bubblewrap Command it will use the default of:

/bin/bwrap --ro-bind /usr /usr --ro-bind /lib /lib --ro-bind-try /lib64 /lib64 --ro-bind /bin /bin --ro-bind /sbin /sbin --dir /var --dir /tmp --proc /proc --symlink../tmp var/tmp --dev /dev --ro-bind-try /etc/localtime /etc/localtime --ro-bind-try /etc/ld.so.cache /etc/ld.so.cache --ro-bind-try /etc/resolv.conf /etc/resolv.conf --ro-bind-try /etc/ssl /etc/ssl --ro-bind-try /etc/pki /etc/pki --ro-bind-try /etc/man_db.conf /etc/man_db.conf --ro-bind-try /home/$USER /home/$USER --bind-try /var/lib/mysql/mysql.sock /var/lib/mysql/mysql.sock --bind-try /home/mysql/mysql.sock /home/mysql/mysql.sock --bind-try /tmp/mysql.sock /tmp/mysql.sock  --unshare-all --share-net --die-with-parent --dir /run/user/$UID ‘$PASSWD 65534’ ‘$GROUP 65534’

This particular default is intended to give you a very secure environment to run your CGI or PHP scripts from.

You can also enable Bubblewrap at the virtual host configuration level in the Security tab, Bubblewrap Container group. It is recommended that it be configured at the virtual host level to give you fine control of the domains that are being affected.

Manual Configuration

The bubblewrap configuration is not in a group in the main configuration. Note that virtual host configuration overrides this value, unless it it disabled here.

  • bubbleWrap set to 0 to disable (the default or not set value), 1 to turn off at this level, 2 to turn on at this level. It is recommended that bubblewrap be configured enabled at the virtual host level (set to 1 here).
  • bubbleWrapCmd is optional and can be set to the fully qualified and specified bubblewrap command line. The example above is the default. A very simple one might be /bin/bwrap --dev-bind / /.

At the Virtual Host configuration level, the option is:

  • bubbleWrap set to 0 to not set, which is the default and indicates to use the value at the server level, 1 to turn off at this level, or 2 to turn on. It is not in a configuration file group.

Customizing

To create a customized bubblewrap environment, you will want to know the following:

  • All parameters are much like the command line when run from bash, space separated parameters as documented.
  • The first parameter must always be the exact location of the bubblewrap executable. You must change the default if it is not installed in /bin/bash or /usr/bin/bwrap in your environment.
  • You must change the default if it is missing access to Unix Domain Sockets that you may need to access your databases (other than the default for mysql).
  • The current user name can be specified with the token $USER and is used in the default.
  • The current user ID can be specified with the token $UID.
  • The current group ID can be specified with the token $GID.
  • A virtual file /etc/passwd can be created with the token $PASSWD with command line parameters of the users you wish to preserve (by ID). By default the current effective user ID is the only entry; you can add others by specifying the numbers, after the entry, quoted. For example: '$PASSWD 65534’. It is used in the default.
  • A virtual file /etc/group can be created with the token $GROUP with command line parameters of the groups you wish to preserve (by ID). By default the current effective group ID is the only entry; you can add others by specifying the numbers, after the entry, quoted. For example: ‘$GROUP 65534’. It is used in the default.
  • All space separated parameters are assumed to be individual parameters. If you need to embed a space in a parameter (like for a space in a directory name), you can enclose the parameter in single quotes: 'parameter' or double quotes: "parameter".
    Any attempt to run a shell from within bwrap will be denied.
  • We always recommend that you specify the option --die-with-parent so that you do not have orphaned tasks.
  • bwrap v0.3.0 (the default with CentOS 7 and 8 and even earlier versions installed with Ubuntu 18.04 and earlier) does not support --ro-bind-try. Version 0.3.1 or higher is required for that feature. Since this is one of the defaults with Litespeed, it is strongly recommended that you upgrade to a higher version. The CentOS 7 and 8 and Ubuntu 16.04 and 18.04 install instructions above have you installing it from a test repo to assure that a new enough version is obtained.