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.
You must install bubblewrap first to use it with OpenLiteSpeed.
sudo apt install bubblewrap
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
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
Onto enable the bubblewrap function. Other options are
Offto turn it off at this level, or
Disableto disable for the entire server. It is recommended that bubblewrap be configured enabled at the virtual host level (set to
- 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.
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
0to disable (the default or not set value),
1to turn off at this level,
2to 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
0to not set, which is the default and indicates to use the value at the server level,
1to turn off at this level, or
2to turn on. It is not in a configuration file group.
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
$USERand is used in the default.
- The current user ID can be specified with the token
- The current group ID can be specified with the token
- A virtual file /etc/passwd can be created with the token
$PASSWDwith 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
$GROUPwith 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:
Any attempt to run a shell from within bwrap will be denied.
- We always recommend that you specify the option
--die-with-parentso 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.