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. Average Joe and Jane’s Humble Distro are our most valued customers. 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, 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!
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 be able to 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.
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. 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:
$ firecfg --fix-sound
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”:
$ firejail firefox Reading profile /etc/firejail/firefox.profile Reading profile /etc/firejail/disable-common.inc Reading profile /etc/firejail/disable-programs.inc Reading profile /etc/firejail/disable-devel.inc Reading profile /etc/firejail/whitelist-common.inc Blacklist violations are logged to syslog Child process initialized
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:
$ sudo firecfg
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:
$ cat ~/Desktop/firefox.desktop [Desktop Entry] Type=Application Name=Firefox Icon=firefox.png Exec=firejail firefox Terminal=false
2.4 Global Configuration
/etc/firejail/firejail.config is the system-wide configuration file for Firejail software. The defaults cover regular home users, power users might want to take a look.
Depending on the particular system setup, an administrator can enable or disable some of Firejail features and Linux kernel security technologies. Here are some ideas:
no_new_privs kernel flag disables rising privileges inside the sandbox. The flag is enabled by Firejail only if a seccomp filter is installed. It will clear out all SUID problems, or so is believed… We don’t do it by default to allow Chromium-based browsers to install their own seccomp/namespaces sandbox inside Firejail. If you are not using such a browser, add a “force-nonewprivs yes” at the end of the file.
Depending on your network policy, you might need to disable some aspects of network namespaces installed by the sandbox.
It is always a good idea to disable in this file all the features you don’t need. This reduces the attack surface of the sandbox software. For example if you don’t care about OverlayFS add a “overlayfs no” at the end of this file.
2.5 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:
$ cat ~/.config/firejail/vlc.profile include /etc/firejail/vlc.profile net none
2.6 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,
$ firejail --list 3787:netblue:firejail --private 3860:netblue:firejail firefox 3963:root:firejail /etc/init.d/nginx start $
and then shutdown the sandbox using the PID number from the list. In this example I shut down Firefox browser:
$ firejail --shutdown=3860
--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:
$ firejail --join=3860 Switching to pid 3861, the first child process inside the sandbox [netblue@debian ~]$ ps aux USER PID %CPU %MEM VSZ RSS TTY STAT START TIME COMMAND netblue 1 12.1 4.5 996168 320576 ? Sl 07:33 1:59 firefox netblue 77 2.5 0.0 20916 3716 pts/2 S 07:49 0:00 /bin/bash netblue 120 0.0 0.0 16840 1256 pts/2 R+ 07:49 0:00 ps aux [netblue@debian ~]$
--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 --private firefox
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:
$ firejail --private=~/my_private_dir firefox
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:
$ sudo mkdir /chroot $ sudo debootstrap --arch=amd64 sid /chroot/sid
Step 2: Add a regular user account and install the target application (youtube-dl in this example):
$ sudo firejail --noprofile --chroot=/chroot/sid $ adduser netblue $ apt-get install youtube-dl $ exit
Step 3: Run the application:
$ firejail --chroot=/chroot/sid $ youtube-dl https://www.youtube.com/watch?v=Yk1HVPOeoTc
$ sudo firejail --noprofile --chroot=/chroot/sid $ sudo apt-get update $ sudo apt-get upgrade $ sudo apt-get install handbrake mpv
One use case for Firejail’s OverlayFS front-end is testing new software packages. All filesystem modifications performed while installing the software are stored in overlay layer. The host filesystem is not touched.
This is an example of installing Open Invaders game using a Debian package provided by the developer on SourceForge. The steps are as follow:
Step 1: Install the Debian package in overlay
Start a root sandbox, install the software and exit the sandbox. The new files are saved in
$ sudo firejail --overlay-named=open-invaders # dpkg -i open-invaders0.2.deb # exit
Step 2: Check the overlay
Take a look at what files were added or modified by the .deb package:
$ sudo find /root/.firejail/open-invaders
If anything looks suspicious, you should stop right away.
Step 3: Move the overlay in a regular user account
$ mkdir -p ~/.firejail $ sudo mv /root/.firejail/open-invaders /home/netblue/.firejail/.
Step 4: Run the program as a regular user
$ firejail --overlay-named=open-invaders --private open-invaders
Hide all your personal files (
--private) and start the game.
Important: use the OverlayFS method above to test programs from people you trust. As explained earlier the security is provided by the Linux kernel. It would take a significant effort to bring the kernel technology to the point where you can install on your system whatever you find on Internet.
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, and sandboxed in Firejail. I create a private home directory for this application and start the appimage in this directory:
$ mkdir ~/mykdenlive $ firejail --private=~/mykdenlive --appimage ~/Downloads/Kdenlive-17.12.0d-x86_64.AppImage Mounting appimage type 2 Reading profile /etc/firejail/default.profile Reading profile /etc/firejail/disable-common.inc Reading profile /etc/firejail/disable-passwdmgr.inc Reading profile /etc/firejail/disable-programs.inc ** Note: you can use --noprofile to disable default.profile ** Parent pid 17670, child pid 17673 Dropping all Linux capabilities and enforcing default seccomp filter Child process initialized in 60.82 ms ...
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/Mint:
$ sudo apt install apparmor apparmor-utils $ sudo mkdir -p /etc/default/grub.d $ echo 'GRUB_CMDLINE_LINUX_DEFAULT="$GRUB_CMDLINE_LINUX_DEFAULT apparmor=1 security=apparmor"' \ | sudo tee /etc/default/grub.d/apparmor.cfg $ sudo update-grub
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:
$ sudo aa-enforce firejail-default
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:
$ firejaile --apparmor warzon2100
In profile files, use
apparmor command. This is the previous VLC profile with AppArmor support:
$ cat ~/.config/firejail/vlc.profile include /etc/firejail/vlc.profile net none apparmor
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 the 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
$ cat /etc/fuse.conf # /etc/fuse.conf - Configuration file for Filesystem in Userspace (FUSE) # Set the maximum number of FUSE mounts allowed to non-root users. # The default is 1000. #mount_max = 1000 # Allow non-root users to specify the allow_other or allow_root mount options. user_allow_other
This is how to start a Firejail-friendly EncFS:
$ encfs -o allow_root ~/.crypt ~/crypt
And this is a SSHFS:
sshfs -o reconnect,allow_root email@example.com:/home/netblue/work work
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):
$ ip addr show 1: lo: mtu 65536 qdisc noqueue state UNKNOWN group default qlen 1 link/loopback 00:00:00:00:00:00 brd 00:00:00:00:00:00 inet 127.0.0.1/8 scope host lo valid_lft forever preferred_lft forever inet6 ::1/128 scope host valid_lft forever preferred_lft forever 2: eth0: mtu 1500 qdisc pfifo_fast state UP group default qlen 1000 link/ether e0:3f:4f:72:14:a9 brd ff:ff:ff:ff:ff:ff inet 192.168.1.50/24 brd 192.168.1.255 scope global eth0 valid_lft forever preferred_lft forever inet6 fe80::e23f:49ff:fe7a:1409/64 scope link valid_lft forever preferred_lft forever
and start the sandbox
$ firejail --net=eth0 firefox
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:
$ cat ~/.config/firejail/firefox-exr.profile include /etc/firejail/firefox-esr.profile net eth0 iprange 192.168.1.100,192.168.1.240
Similar, a profile for Transmission:
$ cat ~/.config/firejail/transmission-qt.profile include /etc/firejail/transmission-qt.profile net eth0 iprange 192.168.1.100,192.168.1.240
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:
#!/bin/bash # # Routed network configuration script # # bridge setup brctl addbr br0 ifconfig br0 10.10.20.1/24 up # enable ipv4 forwarding echo "1" > /proc/sys/net/ipv4/ip_forward # netfilter cleanup iptables --flush iptables -t nat -F iptables -X iptables -Z iptables -P INPUT ACCEPT iptables -P OUTPUT ACCEPT iptables -P FORWARD ACCEPT # netfilter network address translation iptables -t nat -A POSTROUTING -o eth0 -s 10.10.20.0/24 -j MASQUERADE
Starting the sandbox:
$ firejail --net=br0 firefox
For running servers I replace network address translation with port forwarding in the script above:
# host port 80 forwarded to sandbox port 80 iptables -t nat -A PREROUTING -p tcp --dport 80 -j DNAT --to 10.10.20.10:80
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:
$ firejail --name=browser --net=eth0 firefox & $ firejail --bandwidth=browser set eth0 80 20
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:
$ firejail --bandwidth=browser set eth0 40 10 $ firejail --bandwidth=browser clear eth0
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:
# firejail --net=eth0 --ip=192.168.1.244 /etc/init.d/apache2 start
The default server profile is /etc/firejail/server.profile. To further restrict your servers, here are some ideas:
# capabilities list for Apache server caps.keep chown,sys_resource,net_bind_service,setuid,setgid # capabilities list for nginx server caps.keep chown,net_bind_service,setgid,setuid # use a netfilter configuration netfilter /etc/firejail/webserver.net # instead of /var/www/html for webpages, use a different directory bind /server/web1,/var/www/html
You can run thousands of webservers on a regular system, each one with its own IP address, webpages, and applications.