From 399dcf178043ebbf2ea92e91ddb9b0c2ec0a5df4 Mon Sep 17 00:00:00 2001 From: glitsj16 Date: Tue, 26 Feb 2019 08:39:59 +0000 Subject: Sort items alphabetically in man firejail (#2479) --- src/man/firejail.txt | 495 +++++++++++++++++++++++++-------------------------- 1 file changed, 247 insertions(+), 248 deletions(-) (limited to 'src/man') diff --git a/src/man/firejail.txt b/src/man/firejail.txt index e6eaa1685..c3981336d 100644 --- a/src/man/firejail.txt +++ b/src/man/firejail.txt @@ -99,33 +99,33 @@ $ firejail --allusers \fB\-\-apparmor Enable AppArmor confinement. For more information, please see \fBAPPARMOR\fR section below. .TP -\fB\-\-appimage -Sandbox an AppImage (https://appimage.org/) application. If the sandbox is started -as a regular user, nonewprivs and a default capabilities filter are enabled. +\fB\-\-apparmor.print=name|pid +Print the AppArmor confinement status for the sandbox identified by name or by PID. .br .br Example: .br -$ firejail --appimage krita-3.0-x86_64.appimage +$ firejail \-\-apparmor.print=browser .br -$ firejail --appimage --private krita-3.0-x86_64.appimage +5074:netblue:/usr/bin/firejail /usr/bin/firefox-esr .br -$ firejail --appimage --net=none --x11 krita-3.0-x86_64.appimage + AppArmor: firejail-default enforce .TP -\fB\-\-apparmor.print=name|pid -Print the AppArmor confinement status for the sandbox identified by name or by PID. +\fB\-\-appimage +Sandbox an AppImage (https://appimage.org/) application. If the sandbox is started +as a regular user, nonewprivs and a default capabilities filter are enabled. .br .br Example: .br -$ firejail \-\-apparmor.print=browser +$ firejail --appimage krita-3.0-x86_64.appimage .br -5074:netblue:/usr/bin/firejail /usr/bin/firefox-esr +$ firejail --appimage --private krita-3.0-x86_64.appimage .br - AppArmor: firejail-default enforce +$ firejail --appimage --net=none --x11 krita-3.0-x86_64.appimage .TP \fB\-\-audit @@ -700,10 +700,6 @@ Example: .br $ firejail --keep-var-tmp -.TP -\fB\-\-ls=name|pid dir_or_filename -List files in sandbox container, see \fBFILE TRANSFER\fR section for more details. - .TP \fB\-\-list List all sandboxes, see \fBMONITORING\fR section for more details. @@ -720,7 +716,10 @@ $ firejail \-\-list .br 7064:netblue::firejail \-\-noroot xterm .br -$ +.TP +\fB\-\-ls=name|pid dir_or_filename +List files in sandbox container, see \fBFILE TRANSFER\fR section for more details. + .TP \fB\-\-mac=address Assign MAC addresses to the last network interface defined by a \-\-net option. This option @@ -735,7 +734,6 @@ $ firejail \-\-net=eth0 \-\-mac=00:11:22:33:44:55 firefox .TP \fB\-\-machine-id Spoof id number in /etc/machine-id file - a new random id is generated inside the sandbox. -.br Note that this breaks audio support. Enable it when sound is not required. .br @@ -815,6 +813,24 @@ $ sudo ifconfig br1 10.10.30.1/24 .br $ firejail \-\-net=br0 \-\-net=br1 +.TP +\fB\-\-net=none +Enable a new, unconnected network namespace. The only interface +available in the new namespace is a new loopback interface (lo). +Use this option to deny +network access to programs that don't really need network access. +.br + +.br +Example: +.br +$ firejail \-\-net=none vlc +.br + +.br +Note: \-\-net=none can crash the application on some platforms. +In these cases, it can be replaced with \-\-protocol=unix. + .TP \fB\-\-net=ethernet_interface|wireless_interface Enable a new network namespace and connect it @@ -848,24 +864,6 @@ Example: .br $ firejail \-\-net=tap0 \-\-ip=10.10.20.80 \-\-netmask=255.255.255.0 \-\-defaultgw=10.10.20.1 firefox -.TP -\fB\-\-net=none -Enable a new, unconnected network namespace. The only interface -available in the new namespace is a new loopback interface (lo). -Use this option to deny -network access to programs that don't really need network access. -.br - -.br -Example: -.br -$ firejail \-\-net=none vlc -.br - -.br -Note: \-\-net=none can crash the application on some platforms. -In these cases, it can be replaced with \-\-protocol=unix. - .TP \fB\-\-net.print=name|pid If a new network namespace is enabled, print network interface configuration for the sandbox specified by name or PID. Example: @@ -1068,6 +1066,17 @@ Example: .br $ firejail --no3d firefox +.TP +\fB\-\-noautopulse +Disable automatic ~/.config/pulse init, for complex setups such as remote +pulse servers or non-standard socket paths. +.br + +.br +Example: +.br +$ firejail \-\-noautopulse firefox + .TP \fB\-\-noblacklist=dirname_or_filename Disable blacklist for this directory or file. @@ -1157,6 +1166,14 @@ uid=1000(netblue) gid=1000(netblue) groups=1000(netblue) .br $ +.TP +\fB\-\-nonewprivs +Sets the NO_NEW_PRIVS prctl. This ensures that child processes +cannot acquire new privileges using execve(2); in particular, +this means that calling a suid binary (or one with file capabilities) +does not result in an increase of privilege. This option +is enabled by default if seccomp filter is activated. + .TP \fB\-\-noprofile Do not use a security profile. @@ -1209,14 +1226,6 @@ ping: icmp open socket: Operation not permitted .br $ -.TP -\fB\-\-nonewprivs -Sets the NO_NEW_PRIVS prctl. This ensures that child processes -cannot acquire new privileges using execve(2); in particular, -this means that calling a suid binary (or one with file capabilities) -does not result in an increase of privilege. This option -is enabled by default if seccomp filter is activated. - .TP \fB\-\-nosound Disable sound system. @@ -1227,17 +1236,6 @@ Example: .br $ firejail \-\-nosound firefox -.TP -\fB\-\-noautopulse -Disable automatic ~/.config/pulse init, for complex setups such as remote -pulse servers or non-standard socket paths. -.br - -.br -Example: -.br -$ firejail \-\-noautopulse firefox - .TP \fB\-\-notv Disable DVB (Digital Video Broadcasting) TV devices. @@ -1317,6 +1315,16 @@ Example: .br $ firejail \-\-overlay firefox +.TP +\fB\-\-overlay-clean +Clean all overlays stored in $HOME/.firejail directory. +.br + +.br +Example: +.br +$ firejail \-\-overlay-clean + .TP \fB\-\-overlay-named=name Mount a filesystem overlay on top of the current filesystem. Unlike the regular filesystem container, @@ -1355,16 +1363,6 @@ Example: .br $ firejail \-\-overlay-tmpfs firefox -.TP -\fB\-\-overlay-clean -Clean all overlays stored in $HOME/.firejail directory. -.br - -.br -Example: -.br -$ firejail \-\-overlay-clean - .TP \fB\-\-private Mount new /root and /home/user directories in temporary @@ -1376,6 +1374,7 @@ closed. Example: .br $ firejail \-\-private firefox + .TP \fB\-\-private=directory Use directory as user home. @@ -1387,17 +1386,26 @@ Example: $ firejail \-\-private=/home/netblue/firefox-home firefox .TP -\fB\-\-private-home=file,directory -Build a new user home in a temporary -filesystem, and copy the files and directories in the list in the -new home. All modifications are discarded when the sandbox is -closed. +\fB\-\-private-bin=file,file +Build a new /bin in a temporary filesystem, and copy the programs in the list. +If no listed file is found, /bin directory will be empty. +The same directory is also bind-mounted over /sbin, /usr/bin, /usr/sbin and /usr/local/bin. +All modifications are discarded when the sandbox is closed. File globbing is supported, +see \fBFILE GLOBBING\fR section for more details. .br .br Example: .br -$ firejail \-\-private-home=.mozilla firefox +$ firejail \-\-private-bin=bash,sed,ls,cat +.br +Parent pid 20841, child pid 20842 +.br +Child process initialized +.br +$ ls /bin +.br +bash cat ls sed .TP \fB\-\-private-cache @@ -1411,26 +1419,51 @@ Example: $ firejail \-\-private-cache openbox .TP -\fB\-\-private-bin=file,file -Build a new /bin in a temporary filesystem, and copy the programs in the list. -If no listed file is found, /bin directory will be empty. -The same directory is also bind-mounted over /sbin, /usr/bin, /usr/sbin and /usr/local/bin. -All modifications are discarded when the sandbox is closed. File globbing is supported, -see \fBFILE GLOBBING\fR section for more details. +\fB\-\-private-dev +Create a new /dev directory. Only disc, dri, null, full, zero, tty, pts, ptmx, random, snd, urandom, video, log and shm devices are available. .br .br Example: .br -$ firejail \-\-private-bin=bash,sed,ls,cat +$ firejail \-\-private-dev .br -Parent pid 20841, child pid 20842 +Parent pid 9887, child pid 9888 .br Child process initialized .br -$ ls /bin +$ ls /dev .br -bash cat ls sed +cdrom cdrw dri dvd dvdrw full log null ptmx pts random shm snd sr0 tty urandom zero +.br +$ +.TP +\fB\-\-private-etc=file,directory +Build a new /etc in a temporary +filesystem, and copy the files and directories in the list. +If no listed file is found, /etc directory will be empty. +All modifications are discarded when the sandbox is closed. +.br + +.br +Example: +.br +$ firejail --private-etc=group,hostname,localtime, \\ +.br +nsswitch.conf,passwd,resolv.conf + +.TP +\fB\-\-private-home=file,directory +Build a new user home in a temporary +filesystem, and copy the files and directories in the list in the +new home. All modifications are discarded when the sandbox is +closed. +.br + +.br +Example: +.br +$ firejail \-\-private-home=.mozilla firefox .TP \fB\-\-private-lib=file,directory @@ -1482,41 +1515,6 @@ $ ps $ .br - -.TP -\fB\-\-private-dev -Create a new /dev directory. Only disc, dri, null, full, zero, tty, pts, ptmx, random, snd, urandom, video, log and shm devices are available. -.br - -.br -Example: -.br -$ firejail \-\-private-dev -.br -Parent pid 9887, child pid 9888 -.br -Child process initialized -.br -$ ls /dev -.br -cdrom cdrw dri dvd dvdrw full log null ptmx pts random shm snd sr0 tty urandom zero -.br -$ -.TP -\fB\-\-private-etc=file,directory -Build a new /etc in a temporary -filesystem, and copy the files and directories in the list. -If no listed file is found, /etc directory will be empty. -All modifications are discarded when the sandbox is closed. -.br - -.br -Example: -.br -$ firejail --private-etc=group,hostname,localtime, \\ -.br -nsswitch.conf,passwd,resolv.conf - .TP \fB\-\-private-opt=file,directory Build a new /opt in a temporary @@ -2422,6 +2420,69 @@ Example: $ firejail --net=eth0 --x11=xephyr --xephyr-screen=640x480 firefox .br +.SH APPARMOR +.TP +AppArmor support is disabled by default at compile time. Use --enable-apparmor configuration option to enable it: +.br + +.br +$ ./configure --prefix=/usr --enable-apparmor +.TP +During software install, a generic AppArmor profile file, firejail-default, is placed in /etc/apparmor.d directory. The local customizations must be placed in /etc/apparmor.d/local/firejail-local. The profile needs to be loaded into the kernel by reloading apparmor.service, rebooting the system or running the following command as root: +.br + +.br +# apparmor_parser -r /etc/apparmor.d/firejail-default +.TP +The installed profile is supplemental for main firejail functions and among other things does the following: +.br + +.br +- Disable ptrace. With ptrace it is possible to inspect and hijack running programs. Usually this is needed only for debugging. You should have no problems running Chromium or Firefox. This feature is available only on Ubuntu kernels. +.br + +.br +- Whitelist write access to several files under /run, /proc and /sys. +.br + +.br +- Allow running programs only from well-known system paths, such as /bin, /sbin, /usr/bin etc. Those paths are available as read-only. Running programs and scripts from user home or other directories writable by the user is not allowed. +.br + +.br +- Prevent using non-standard network sockets. Only unix, inet, inet6, netlink, raw and packet are allowed. +.br + +.br +- Deny access to known sensitive paths like .snapshots. + +.TP +To enable AppArmor confinement on top of your current Firejail security features, pass \fB\-\-apparmor\fR flag to Firejail command line. You can also include \fBapparmor\fR command in a Firejail profile file. Example: +.br + +.br +$ firejail --apparmor firefox + +.SH AUDIT +Audit feature allows the user to point out gaps in security profiles. The +implementation replaces the program to be sandboxed with a test program. By +default, we use faudit program distributed with Firejail. A custom test program +can also be supplied by the user. Examples: + +Running the default audit program: +.br + $ firejail --audit transmission-gtk + +Running a custom audit program: +.br + $ firejail --audit=~/sandbox-test transmission-gtk + +In the examples above, the sandbox configures transmission-gtk profile and +starts the test program. The real program, transmission-gtk, will not be +started. + +Limitations: audit feature is not implemented for --x11 commands. + .SH DESKTOP INTEGRATION A symbolic link to /usr/bin/firejail under the name of a program, will start the program in Firejail sandbox. The symbolic link should be placed in the first $PATH position. On most systems, a good place @@ -2477,6 +2538,35 @@ $ firejail --tree We provide a tool that automates all this integration, please see \fBman 1 firecfg\fR for more details. +.SH EXAMPLES +.TP +\f\firejail +Sandbox a regular /bin/bash session. +.TP +\f\firejail firefox +Start Mozilla Firefox. +.TP +\f\firejail \-\-debug firefox +Debug Firefox sandbox. +.TP +\f\firejail \-\-private firefox +Start Firefox with a new, empty home directory. +.TP +\f\firejail --net=none vlc +Start VLC in an unconnected network namespace. +.TP +\f\firejail \-\-net=eth0 firefox +Start Firefox in a new network namespace. An IP address is +assigned automatically. +.TP +\f\firejail \-\-net=br0 \-\-ip=10.10.20.5 \-\-net=br1 \-\-net=br2 +Start a /bin/bash session in a new network namespace and connect it +to br0, br1, and br2 host bridge devices. IP addresses are assigned +automatically for the interfaces connected to br1 and b2 +.TP +\f\firejail \-\-list +List all sandboxed processes. + .SH FILE GLOBBING .TP Globbing is the operation that expands a wildcard pattern into the list of pathnames matching the pattern. Matching is defined by: @@ -2511,49 +2601,6 @@ $ firejail --blacklist=~/dir[1234] $ firejail --read-only=~/dir[1-4] .br -.SH APPARMOR -.TP -AppArmor support is disabled by default at compile time. Use --enable-apparmor configuration option to enable it: -.br - -.br -$ ./configure --prefix=/usr --enable-apparmor -.TP -During software install, a generic AppArmor profile file, firejail-default, is placed in /etc/apparmor.d directory. The local customizations must be placed in /etc/apparmor.d/local/firejail-local. The profile needs to be loaded into the kernel by reloading apparmor.service, rebooting the system or running the following command as root: -.br - -.br -# apparmor_parser -r /etc/apparmor.d/firejail-default -.TP -The installed profile is supplemental for main firejail functions and among other things does the following: -.br - -.br -- Disable ptrace. With ptrace it is possible to inspect and hijack running programs. Usually this is needed only for debugging. You should have no problems running Chromium or Firefox. This feature is available only on Ubuntu kernels. -.br - -.br -- Whitelist write access to several files under /run, /proc and /sys. -.br - -.br -- Allow running programs only from well-known system paths, such as /bin, /sbin, /usr/bin etc. Those paths are available as read-only. Running programs and scripts from user home or other directories writable by the user is not allowed. -.br - -.br -- Prevent using non-standard network sockets. Only unix, inet, inet6, netlink, raw and packet are allowed. -.br - -.br -- Deny access to known sensitive paths like .snapshots. - -.TP -To enable AppArmor confinement on top of your current Firejail security features, pass \fB\-\-apparmor\fR flag to Firejail command line. You can also include \fBapparmor\fR command in a Firejail profile file. Example: -.br - -.br -$ firejail --apparmor firefox - .SH FILE TRANSFER These features allow the user to inspect the filesystem container of an existing sandbox and transfer files from the container to the host filesystem. @@ -2602,68 +2649,6 @@ $ firejail \-\-get=mybrowser ~/Downloads/xpra-clipboard.png $ firejail \-\-put=mybrowser xpra-clipboard.png ~/Downloads/xpra-clipboard.png .br -.SH 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 the sandboxes. - -Firejail implements a simple rate-limiting shaper based on Linux command tc. -The shaper works at sandbox level, and can be used only for sandboxes configured with new network namespaces. - -Set rate-limits: - - $ firejail --bandwidth=name|pid set network download upload - -Clear rate-limits: - - $ firejail --bandwidth=name|pid clear network - -Status: - - $ firejail --bandwidth=name|pid status - -where: -.br - name - sandbox name -.br - pid - sandbox pid -.br - network - network interface as used by \-\-net option -.br - download - download speed in KB/s (kilobyte per second) -.br - upload - upload speed in KB/s (kilobyte per second) - -Example: -.br - $ firejail \-\-name=mybrowser \-\-net=eth0 firefox & -.br - $ firejail \-\-bandwidth=mybrowser set eth0 80 20 -.br - $ firejail \-\-bandwidth=mybrowser status -.br - $ firejail \-\-bandwidth=mybrowser clear eth0 - -.SH AUDIT -Audit feature allows the user to point out gaps in security profiles. The -implementation replaces the program to be sandboxed with a test program. By -default, we use faudit program distributed with Firejail. A custom test program -can also be supplied by the user. Examples: - -Running the default audit program: -.br - $ firejail --audit transmission-gtk - -Running a custom audit program: -.br - $ firejail --audit=~/sandbox-test transmission-gtk - -In the examples above, the sandbox configures transmission-gtk profile and -starts the test program. The real program, transmission-gtk, will not be -started. - -Limitations: audit feature is not implemented for --x11 commands. - .SH MONITORING Option \-\-list prints a list of all sandboxes. The format for each process entry is as follows: @@ -2799,34 +2784,48 @@ adduser \-\-shell /usr/bin/firejail username Additional arguments passed to firejail executable upon login are declared in /etc/firejail/login.users file. -.SH EXAMPLES -.TP -\f\firejail -Sandbox a regular /bin/bash session. -.TP -\f\firejail firefox -Start Mozilla Firefox. -.TP -\f\firejail \-\-debug firefox -Debug Firefox sandbox. -.TP -\f\firejail \-\-private firefox -Start Firefox with a new, empty home directory. -.TP -\f\firejail --net=none vlc -Start VLC in an unconnected network namespace. -.TP -\f\firejail \-\-net=eth0 firefox -Start Firefox in a new network namespace. An IP address is -assigned automatically. -.TP -\f\firejail \-\-net=br0 \-\-ip=10.10.20.5 \-\-net=br1 \-\-net=br2 -Start a /bin/bash session in a new network namespace and connect it -to br0, br1, and br2 host bridge devices. IP addresses are assigned -automatically for the interfaces connected to br1 and b2 -.TP -\f\firejail \-\-list -List all sandboxed processes. +.SH 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 the sandboxes. + +Firejail implements a simple rate-limiting shaper based on Linux command tc. +The shaper works at sandbox level, and can be used only for sandboxes configured with new network namespaces. + +Set rate-limits: + + $ firejail --bandwidth=name|pid set network download upload + +Clear rate-limits: + + $ firejail --bandwidth=name|pid clear network + +Status: + + $ firejail --bandwidth=name|pid status + +where: +.br + name - sandbox name +.br + pid - sandbox pid +.br + network - network interface as used by \-\-net option +.br + download - download speed in KB/s (kilobyte per second) +.br + upload - upload speed in KB/s (kilobyte per second) + +Example: +.br + $ firejail \-\-name=mybrowser \-\-net=eth0 firefox & +.br + $ firejail \-\-bandwidth=mybrowser set eth0 80 20 +.br + $ firejail \-\-bandwidth=mybrowser status +.br + $ firejail \-\-bandwidth=mybrowser clear eth0 + .SH LICENSE This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. .PP -- cgit v1.2.3-70-g09d2