Welcome to Firejail, a SUID security sandbox based on Linux namespaces and seccomp-bpf. We are a volunteer weekend project and our target is the desktop. Linux beginner or accomplished programmer, you are welcome to join us at http://github.com/netblue30/firejail.
This document is an effort to centralize Firejail information currently spread across several howtos, blogs and discussion threads. I’ll start with a short description of the kernel technologies involved, move to sandbox configuration and management, and explore some of the most common usage scenarios.
There is nothing magic about the internal workings of a sandbox, just some kernel security technologies stack one on top of the other. As a user you don’t deal with them directly, Firejail takes care of it. We offer preconfigured security profiles for more than 400 Linux applications, and if your application is not among them, no problem – the default configuration should just work!
1.1. The Linux Kernel
All Firejail security features are implemented inside Linux kernel. The sandbox program configures the kernel and goes to sleep. The setup is very fast, usually tens of milliseconds. In very complicated setups it can go as high as 1 second. The memory requirements are low, all it needs is a few MB of memory. As for slowing down the application, I don’t think you’ll notice any.
We divide the kernel technologies used for sandboxing in three categories:
Front-end technologies are simple and very effective. They are designed to withstand a massive attack. We use mount, PID and network namespaces. The user can also request chroot, overlayfs and a netfilter firewall.
Back-end technologies are smart and sophisticated. They play a support role: to keep the front-end in place. Our main support technologies are seccomp and Linux capabilities. We use them to lock the attacker inside the sandbox, and prevent him from becoming root. If requested, we also start a noroot user namespace, and configure an AppArmor profile.
In the third category, we place the technologies we use to configure the kernel. Currently there are exactly two technologies available: SUID and user namespaces. Both of them are insecure. User namespace has the advantage when things go wrong you can blame it on kernel developers. For Firejail we use SUID.
1.2 What is SUID, and how does it affect me?
SUID (Set owner User ID upon execution) is a special type of file permissions. Most programs running on your computer inherit access permissions from the user logged in. SUID allows the program to run as root, rather that the user who started the program.
We use this Linux feature to start the sandbox, since most kernel technologies involved in sandboxing require root access. Once the sandbox is installed, root permissions are dropped, and the real program is started with regular user permissions. For example in the case of a Firefox browser, we start the sandbox as root, drop privileges, then we start the browser as a regular user.
SUID programs are considered dangerous on multiuser systems. It is not a great idea to install Firejail on such systems. If you have a server full of people logging in over SSH, forget about it!
Firejail was built for single-user desktop systems. We try to address desktop specific threats, such as:
- Mozilla Firefox PDF exploit (2015). You click on a link on a website, and by the time anything shows on the screen, the guys already read various passwords and encryption keys stored in your home directory. Among them, the private SSH keys in ~/.ssh.
- Google Chrome scanning files in your Documents directory (2018). They say they scan for Windows malware and viruses. It is only a mater of time until this “technology” comes to Linux.
We make the assumption data stored on user’s computer is more valuable then the computer itself. This stands in direct contrast with the corporate/multiuser system philosophy, where the software the company is trying to sell is more important than user’s data. We also assume a clean, updated system without any malicious software already installed.
There are ways to mitigate some of the problems introduced by SUID. Here are some of them:
Integrate your desktop software with Firejail, by running
firecfg utility described in Desktop Integration section. As a result, most of your desktop programs will be sandboxed automatically. From inside a sandbox it is not possible to run SUID programs, including Firejail.
If you are not using Chromium or a browser based on Chromium (Opera, etc.) turn on
force-nonewprivs flag in
/etc/firejail/firejail.config file. As root, open the file in a text editor and add this line:
The flag prevents rising privileges after the sandbox was started. It is believed to clean most SUID problems that will ever be attributed to Firejail. Unfortunately, Chromium-based browsers need to rise privileges in order to install their own SUID sandbox.
3. Create a special
To further restrict the SUID binary, create a
firejail group, set
/usr/bin/firejail executable as part of this group, change the file mode to 4750, and add only the users allowed to use Firejail to the group. Sample set of instructions on Debian:
To add the user to the group, type:
A logout and login back is necessary after adding the user to the group.
4. Consider running the long term support release
The current LTS release was branched out from version 0.9.38 in February 2016. It includes only bugfixes and additional SUID hardening. The code base is much smaller, and easier to audit.
2. Usage and Configuration
Try installing Firejail using your package manager first. Firejail is included in a large number of distributions. Among them Arch, Debian, Gentoo, Mint, Slackware, Ubuntu.
You can find newer versions of the software on our download page. We keep there up to date .deb packages for Debian/Ubuntu/Mint and .rpm packages for CentOS/Fedora/OpenSUSE. You can also download the source archive and compile it yourself. There are no external dependencies, all you need is a C compiler (
sudo apt-get install build-essential) and a regular compile/install (
./configure && make && make install).
After install run:
This command fixes some bugs in PulseAudio software versions available on most Linux platforms. After running it, logout and login again for the modifications to take effect.
2.2 Basic Usage
Start the sandbox by prefixing your application with “firejail”:
Any type of GUI programs should work, with sound, video and hardware acceleration support. This makes Firejail ideal for running desktop applications such as web browsers, media players, and games.
2.3 Desktop Integration
To integrate Firejail with your desktop environment run:
As a result:
- Clicking on desktop manager icons and menus will sandbox the application automatically. We support Cinnamon, KDE, LXDE/LXQT, MATE and XFCE desktop managers, and partially Gnome 3 and Unity. This part works well across all Linux distributions.
- Clicking on files in your file manager will open the file in a sandboxed application. It works fine in newer Linux distributions like Debian “stretch”, Ubuntu 17.04, Arch, Gentoo.
You can always check if your application was sandboxed by running
"firejail --list" in a terminal. Or you can keep a terminal running
"firejail --top" to track your sandboxes.
Some users prefer desktop launchers for stating applications. A launcher is a regular text file with .desktop extension placed in
~/Desktop directory. This is an example for Mozilla Firefox browser:
2.4 Security profiles
We distribute Firejail with over 400 security profiles, covering most common Linux applications. Profile files have a friendly syntax, and are stored in
Profiles build by users should be placed in
~/.config/firejail directory. If you need to add something to an existing profile, use
"include" command to bring in the original profile file, then add your commands. For example, this is a profile for a VLC media player without network access:
2.5 Managing Sandboxes
The relevant command line options are as follow:
firejail --list– list all running sandboxes
firejail --tree– list all running sandboxes and the processes running in each sandbox
firejail --top– similar to Linux
In case a sandbox is not responding and you need to shut it down, use
--shutdown option. First, list the sandboxes,
and then shutdown the sandbox using the PID number from the list. In this example I shut down Firefox browser:
--join option if you need to join an already running sandbox and modify the filesystem, the network parameters, or do some other admin work. I am using firefox sandbox from the previous example:
--join works like a regular terminal login in the sandbox. The new shell session inherits all the sandbox restrictions.
3.1 Private Mode
Private mode is a quick way to hide all the files in your home directory from sandboxed programs. Enable it using
--private command line option:
Firejail mounts a temporary
tmpfs filesystem on top of
/home/user directory. Any files created in this directory will be deleted when you close the sandbox. You can also use an existing directory as home for your sandbox, allowing you to have a persistent home:
Most of the time I’m happy with the applications distributed by Debian “stable”, but occasionally I need a much newer version of a program or another. In this case, I build a Debian “unstable” chroot on my “stable” system, and run my application using Firejail’s chroot feature. These are the steps:
Step 1: Build a basic Debian sid filesystem:
Step 2: Add a regular user account and install the target application (youtube-dl in this example):
Step 3: Run the application:
One use case for Firejail’s OverlayFS front-end is testing new software packages. All filesystem modifications performed while installing and running the software are stored in overlay layer. The host filesystem is not touched.
This is an example of testing Gnome AisleRiot game from the regular Debian repository. AisleRiot is a collection of over eighty different solitaire card games, including popular variants such as spider, freecell, klondike, thirteen (pyramid), yukon, canfield and many more.
The steps are as follow:
Step 1: Start a root sandbox with a temporary OverlayFS filesystem
This is a very relaxed sandbox. All directories are visible, with an overlay on top of them. The only filter installed is seccomp. This means you package manager will not be able to install and load new kernel modules. Also, if you are thinking about installing server programs, it will not work – systemd lives in a different namespace, and it will fail to find your new server.
Step 2: Install the program
Step 3: Switch to your regular user and run the program
The previous chroot and OverlayFS tricks will only get you so far. As more and more complex applications are built by thousands of Linux users, new ways of distributing software emerged. My favourite is AppImage.
We introduced AppImage support in 2016, and since then we added more features, bug fixes etc. On their side, AppImage team kept on bringing in new cool stuff, such as a new filesystem layout and a croud-sourced repository of appimages for most Linux applications.
Here is a simple usage example: the latest and greatest Kdenlive video editor built and distributed by the developer.
I create a private home directory for this application and start the appimage in this directory:
All the files I am editing are in
~/mykdenlive directory, no other files in my home are visible in the sandbox. You can find more examples in our AppImage Support document.
Currently, AppArmor Linux security module is enabled by default on Ubuntu. On other distribution you’ll have to enable it yourself. The setup process is very easy, and it can be followed even by Linux beginners. Here are the official instructions for Debian:
Like Firejail, AppArmor restricts programs’ capabilities with per-program profiles. If you have an AppArmor profile for your application, enable it. Firejail should work fine on top of AppArmor. There is some overlap between the two technologies: both of them blacklist the same filesystem. In case one of them misses something important, hopefully the other one picks it up.
If you don’t have an AppArmor profile for your specific application, we give you one. The profile is installed in
/etc/apparmor.d/firejail-default file when you install Firejail. You would need to load it into the kernel by running the following command:
Note: next time you start your computer, Firejail AppArmor profile will be loaded automatically into the kernel.
--apparmor command line option to enable AppArmor confinement inside your sandboxed application:
In profile files, use
apparmor command. This is the previous VLC profile with AppArmor support:
3.6 EncFS and SSHFS
EncFS is an encrypted filesystem built on top of FUSE library. It is available on most Linux distributions, and it runs in user space. Integrating EncFS with Firejail brings up an interesting problem. Take a look at this paragraph in man encfs:
By default, all FUSE based filesystems are visible only to the user who mounted them. No other users (including root) can view the filesystem contents.
For various reasons, during sandbox setup Firejail handles EncFS filesystems as root user. FUSE will prevent the root access to user’s files and the sandbox will fail to start.
This problem affects all filesystems based on FUSE library. Quite popular among them is sshfs. The solution is to allow root user to access the filesystem using
allow_root FUSE mount flag. On some distributions (Debian & friends) you might have to change FUSE config file in
/etc/fuse.conf and uncomment
This is how to start a Firejail-friendly EncFS:
And this is a SSHFS:
After mounting your FUSE filesystem, start your sandboxes the regular way.
A network namespace is a new, independent TCP/IP stack attached to the sandbox. The stack has its own routing table, firewall and set of interfaces. Apart from “net none” and an optional “netfilter”, we never configure networking features in the security profiles distributed with the sandbox software.
You can create a network namespace with –net command. There are three setups to choose from:
- –net=none creates a network namespace unconnected to the real network. The sandbox looks like a computer without any network interfaces.
- –net=macvlan-device creates a direct network setup. The namespace is connected on the same network as your Ethernet interface using a macvlan kernel device. This is the easiest setup for home users. Unfortunately, the macvlan Linux kernel device works only for wired Ethernet interfaces.
- –net=bridge-device connects the sandbox to a bridge kernel device. The regular network stack routes the sandbox traffic to your main wired/wireless interface.
4.1 Direct Network Setup
Run “ip addr show” to find the name of your wired Ethernet interface (eth0 in my case):
and start the sandbox
You can specify an IP address (–ip=192.168.1.207), a range of IP addresses (–iprange=192.168.1.100,192.168.1.240) to choose from, or you can let the sandbox find an unused IP address on your network.
Because of the way macvlan kernel drivers are wired to the real Ethernet interface, it is not possible for the sandboxed application to access TCP/IP services running on the host, and the other way around. The sandbox and the host are totally disconnected, even if both of them are on the same network.
This is a Firefox profile adding network namespace support to the sandbox:
Similar, a profile for Transmission:
In the examples above, I let Firefox and Transmission fight for address in 192.168.1.100 – 192.168.1.240 range. Actually, all network clients on my home network are fighting for addresses in this range. To monitor the traffic use “firejail –netstats”.
4.2 Routed Network Setup
In a routed setup sandboxes are connected to a Linux bridge, and the bridge traffic is routed by the host. This setup works for both wired and wireless interfaces. Address translation needs to be enabled on the host in order for the sandbox traffic to go out on Internet:
Script for setting this up – I assume a wired eth0 interface for the system:
Starting the sandbox:
For running servers I replace network address translation with port forwarding in the script above:
4.3 Traffic shaping
Network bandwidth is an expensive resource shared among all sandboxes running on a system. Traffic shaping allows the user to increase network performance by controlling the amount of data that flows into and out of sandboxes. Firejail implements a simple rate-limiting shaper based on Linux tc command. The shaper works at sandbox level:
In this example I set a bandwidth of 80 kilobytes per second on receive side and a bandwidth of 20 kilobytes per second on transmit side. As the sandbox is running, I can change the values or even reset them:
5. X11 Sandboxing
If you don’t have Wayland running, the most reliable way to sandbox X11 with Firejail is Xephyr. Xephyr is a light X11 server you can run in parallel with the main xorg server on your machine. The software is part of X.Org.
In this example I use Firejail to sandbox two applications, Inkscape and Firefox, in a the same Xephyr window.
Step 1. Sandbox Xephyr
In order to be able to rearrange and resize windows, I start OpenBox window manager on top of Xephyr. Notice
--net=none command option.
Note: You can replace openbox with any other supported window manager. Currently we support openbox, fluxbox, blackbox, awesome and i3.
As a rule, whenever we are dealing with X11 we also need to install a new network namespace. This is the only way to block access to the abstract Unix socket opened by the main X11 server already running on your box. Every application sandboxed on this display server is required to install a network namespace, either
Step 2. Find the display number for the new server
Each X11 server server running on your box is identified by a unique display number. This number is used to connect X11 applications to a specific X11 server. Run
firemon -x11 to find Xephyr’s display number:
The display number is 265. Notice how Xephyr and OpenBox are running in independent Firejal sandboxes. Let’s start some more sandboxes:
Step 3. Start your applications
In this moment I have 4 independent sandboxes, one for each program involved: Xephyr, OpenBox, Inkscape and Firefox.
As a rule, always use a new network namespace for server sandboxes in order to isolate services such as SSH, X11, DBus running on your workstation. This is an Apache server example:
The default server profile is /etc/firejail/server.profile. To further restrict your servers, here are some ideas:
You can run thousands of webservers on a regular system, each one with its own IP address, webpages, and applications.