diff options
Diffstat (limited to 'src/man/firejail.txt')
-rw-r--r-- | src/man/firejail.txt | 479 |
1 files changed, 410 insertions, 69 deletions
diff --git a/src/man/firejail.txt b/src/man/firejail.txt index 23db832c1..5b43b1ca5 100644 --- a/src/man/firejail.txt +++ b/src/man/firejail.txt | |||
@@ -11,7 +11,7 @@ firejail [OPTIONS] [program and arguments] | |||
11 | File transfer from an existing sandbox | 11 | File transfer from an existing sandbox |
12 | .PP | 12 | .PP |
13 | .RS | 13 | .RS |
14 | firejail {\-\-ls | \-\-get} dir_or_filename | 14 | firejail {\-\-ls | \-\-get | \-\-put} dir_or_filename |
15 | .RE | 15 | .RE |
16 | .PP | 16 | .PP |
17 | Network traffic shaping for an existing sandbox: | 17 | Network traffic shaping for an existing sandbox: |
@@ -50,15 +50,16 @@ of applications. The software includes security profiles for a number of more co | |||
50 | Linux programs, such as Mozilla Firefox, Chromium, VLC, Transmission etc. | 50 | Linux programs, such as Mozilla Firefox, Chromium, VLC, Transmission etc. |
51 | 51 | ||
52 | .SH USAGE | 52 | .SH USAGE |
53 | Without any options, the sandbox consists of a chroot filesystem build in a new mount namespace, | 53 | Without any options, the sandbox consists of a filesystem build in a new mount namespace, |
54 | and new PID and UTS namespaces. IPC, network and user namespaces can be added using the command line options. | 54 | and new PID and UTS namespaces. IPC, network and user namespaces can be added using the |
55 | The default Firejail filesystem is based on the host filesystem with the main directories mounted read-only. | 55 | command line options. The default Firejail filesystem is based on the host filesystem with the main |
56 | Only /home and /tmp are writable. | 56 | system directories mounted read-only. These directories are /etc, /var, /usr, /bin, /sbin, /lib, /lib32, |
57 | /libx32 and /lib64. Only /home and /tmp are writable. | ||
57 | .PP | 58 | .PP |
58 | As it starts up, Firejail tries to find a security profile based on the name of the application. | 59 | As it starts up, Firejail tries to find a security profile based on the name of the application. |
59 | If an appropriate profile is not found, Firejail will use a default profile. | 60 | If an appropriate profile is not found, Firejail will use a default profile. |
60 | The default profile is quite restrictive. In case the application doesn't work, use --noprofile option | 61 | The default profile is quite restrictive. In case the application doesn't work, use --noprofile option |
61 | to disable it. For more information, please see \fBSECURITY PROFILES\fR section. | 62 | to disable it. For more information, please see \fBSECURITY PROFILES\fR section below. |
62 | .PP | 63 | .PP |
63 | If a program argument is not specified, Firejail starts /bin/bash shell. | 64 | If a program argument is not specified, Firejail starts /bin/bash shell. |
64 | Examples: | 65 | Examples: |
@@ -74,6 +75,46 @@ $ firejail [OPTIONS] firefox # starting Mozilla Firefox | |||
74 | \fB\-\- | 75 | \fB\-\- |
75 | Signal the end of options and disables further option processing. | 76 | Signal the end of options and disables further option processing. |
76 | .TP | 77 | .TP |
78 | \fB\-\-allow-debuggers | ||
79 | Allow tools such as strace and gdb inside the sandbox. | ||
80 | .br | ||
81 | |||
82 | .br | ||
83 | Example: | ||
84 | .br | ||
85 | $ firejail --allow-debuggers --profile=/etc/firejail/firefox.profile strace -f firefox | ||
86 | .TP | ||
87 | \fB\-\-allusers | ||
88 | All directories under /home are visible inside the sandbox. By default, only current user home directory is visible. | ||
89 | .br | ||
90 | |||
91 | .br | ||
92 | Example: | ||
93 | .br | ||
94 | $ firejail --allusers | ||
95 | .TP | ||
96 | \fB\-\-apparmor | ||
97 | Enable AppArmor confinement. For more information, please see \fBAPPARMOR\fR section below. | ||
98 | .TP | ||
99 | \fB\-\-appimage | ||
100 | Sandbox an AppImage (http://appimage.org/) application. | ||
101 | .br | ||
102 | |||
103 | .br | ||
104 | Example: | ||
105 | .br | ||
106 | $ firejail --appimage krita-3.0-x86_64.appimage | ||
107 | .br | ||
108 | $ firejail --appimage --private krita-3.0-x86_64.appimage | ||
109 | .br | ||
110 | $ firejail --appimage --net=none --x11 krita-3.0-x86_64.appimage | ||
111 | .TP | ||
112 | \fB\-\-audit | ||
113 | Audit the sandbox, see \fBAUDIT\fR section for more details. | ||
114 | .TP | ||
115 | \fB\-\-audit=test-program | ||
116 | Audit the sandbox, see \fBAUDIT\fR section for more details. | ||
117 | .TP | ||
77 | \fB\-\-bandwidth=name|pid | 118 | \fB\-\-bandwidth=name|pid |
78 | Set bandwidth limits for the sandbox identified by name or PID, see \fBTRAFFIC SHAPING\fR section for more details. | 119 | Set bandwidth limits for the sandbox identified by name or PID, see \fBTRAFFIC SHAPING\fR section for more details. |
79 | .TP | 120 | .TP |
@@ -152,14 +193,7 @@ Example: | |||
152 | .br | 193 | .br |
153 | $ sudo firejail \-\-caps.keep=chown,net_bind_service,setgid,\\ | 194 | $ sudo firejail \-\-caps.keep=chown,net_bind_service,setgid,\\ |
154 | setuid /etc/init.d/nginx start | 195 | setuid /etc/init.d/nginx start |
155 | .br | ||
156 | 196 | ||
157 | .br | ||
158 | A short note about mixing \-\-whitelist and \-\-read-only options. Whitelisted directories | ||
159 | should be made read-only independently. Making a parent directory read-only, will not | ||
160 | make the whitelist read-only. Example: | ||
161 | .br | ||
162 | $ firejail --whitelist=~/work --read-only=~/ --read-only=~/work | ||
163 | .TP | 197 | .TP |
164 | \fB\-\-caps.print=name|pid | 198 | \fB\-\-caps.print=name|pid |
165 | Print the caps filter for the sandbox identified by name or by PID. | 199 | Print the caps filter for the sandbox identified by name or by PID. |
@@ -194,7 +228,8 @@ Example: | |||
194 | 228 | ||
195 | .TP | 229 | .TP |
196 | \fB\-\-chroot=dirname | 230 | \fB\-\-chroot=dirname |
197 | Chroot the sandbox into a root filesystem. If the sandbox is started as a | 231 | Chroot the sandbox into a root filesystem. Unlike the regular filesystem container, |
232 | the system directories are mounted read-write. If the sandbox is started as a | ||
198 | regular user, default seccomp and capabilities filters are enabled. This | 233 | regular user, default seccomp and capabilities filters are enabled. This |
199 | option is not available on Grsecurity systems. | 234 | option is not available on Grsecurity systems. |
200 | .br | 235 | .br |
@@ -465,6 +500,11 @@ in case you intend to start an external DHCP client in the sandbox. | |||
465 | Example: | 500 | Example: |
466 | .br | 501 | .br |
467 | $ firejail \-\-net=eth0 \-\-\ip=none | 502 | $ firejail \-\-net=eth0 \-\-\ip=none |
503 | .br | ||
504 | |||
505 | .br | ||
506 | If the corresponding interface doesn't have an IP address configured, this | ||
507 | option is enabled by default. | ||
468 | 508 | ||
469 | .TP | 509 | .TP |
470 | \fB\-\-ip6=address | 510 | \fB\-\-ip6=address |
@@ -547,19 +587,19 @@ $ firejail --net=eth0 --name=browser firefox & | |||
547 | .br | 587 | .br |
548 | # change netfilter configuration | 588 | # change netfilter configuration |
549 | .br | 589 | .br |
550 | $ sudo firejail --join-network=browser "cat /etc/firejail/nolocal.net | /sbin/iptables-restore" | 590 | $ sudo firejail --join-network=browser bash -c "cat /etc/firejail/nolocal.net | /sbin/iptables-restore" |
551 | .br | 591 | .br |
552 | 592 | ||
553 | .br | 593 | .br |
554 | # verify netfilter configuration | 594 | # verify netfilter configuration |
555 | .br | 595 | .br |
556 | $ sudo firejail --join-network=browser "/sbin/iptables -vL" | 596 | $ sudo firejail --join-network=browser /sbin/iptables -vL |
557 | .br | 597 | .br |
558 | 598 | ||
559 | .br | 599 | .br |
560 | # verify IP addresses | 600 | # verify IP addresses |
561 | .br | 601 | .br |
562 | $ sudo firejail --join-network=browser "ip addr" | 602 | $ sudo firejail --join-network=browser ip addr |
563 | .br | 603 | .br |
564 | Switching to pid 1932, the first child process inside the sandbox | 604 | Switching to pid 1932, the first child process inside the sandbox |
565 | .br | 605 | .br |
@@ -588,6 +628,13 @@ Switching to pid 1932, the first child process inside the sandbox | |||
588 | valid_lft forever preferred_lft forever | 628 | valid_lft forever preferred_lft forever |
589 | 629 | ||
590 | .TP | 630 | .TP |
631 | \fB\-\-join-or-start=name | ||
632 | Join the sandbox identified by name or start a new one. | ||
633 | Same as "firejail --join=name" if sandbox with specified name exists, otherwise same as "firejail --name=name ..." | ||
634 | .br | ||
635 | Note that in contrary to other join options there is respective profile option. | ||
636 | |||
637 | .TP | ||
591 | \fB\-\-ls=name|pid dir_or_filename | 638 | \fB\-\-ls=name|pid dir_or_filename |
592 | List files in sandbox container, see \fBFILE TRANSFER\fR section for more details. | 639 | List files in sandbox container, see \fBFILE TRANSFER\fR section for more details. |
593 | 640 | ||
@@ -619,6 +666,16 @@ Example: | |||
619 | $ firejail \-\-net=eth0 \-\-mac=00:11:22:33:44:55 firefox | 666 | $ firejail \-\-net=eth0 \-\-mac=00:11:22:33:44:55 firefox |
620 | 667 | ||
621 | .TP | 668 | .TP |
669 | \fB\-\-machine-id | ||
670 | Preserve id number in /etc/machine-id file. By default a new random id is generated inside the sandbox. | ||
671 | .br | ||
672 | |||
673 | .br | ||
674 | Example: | ||
675 | .br | ||
676 | $ firejail \-\-machine-id | ||
677 | |||
678 | .TP | ||
622 | \fB\-\-mtu=number | 679 | \fB\-\-mtu=number |
623 | Assign a MTU value to the last network interface defined by a \-\-net option. | 680 | Assign a MTU value to the last network interface defined by a \-\-net option. |
624 | .br | 681 | .br |
@@ -798,13 +855,23 @@ PID User RX(KB/s) TX(KB/s) Command | |||
798 | .TP | 855 | .TP |
799 | \fB\-\-nice=value | 856 | \fB\-\-nice=value |
800 | Set nice value for all processes running inside the sandbox. | 857 | Set nice value for all processes running inside the sandbox. |
858 | Only root may specify a negative value. | ||
801 | .br | 859 | .br |
802 | 860 | ||
803 | .br | 861 | .br |
804 | Example: | 862 | Example: |
805 | .br | 863 | .br |
806 | $ firejail --nice=-5 firefox | 864 | $ firejail --nice=2 firefox |
865 | |||
866 | .TP | ||
867 | \fB\-\-no3d | ||
868 | Disable 3D hardware acceleration. | ||
869 | .br | ||
807 | 870 | ||
871 | .br | ||
872 | Example: | ||
873 | .br | ||
874 | $ firejail --no3d firefox | ||
808 | 875 | ||
809 | .TP | 876 | .TP |
810 | \fB\-\-noblacklist=dirname_or_filename | 877 | \fB\-\-noblacklist=dirname_or_filename |
@@ -831,6 +898,21 @@ $ nc dict.org 2628 | |||
831 | 220 pan.alephnull.com dictd 1.12.1/rf on Linux 3.14-1-amd64 | 898 | 220 pan.alephnull.com dictd 1.12.1/rf on Linux 3.14-1-amd64 |
832 | .br | 899 | .br |
833 | .TP | 900 | .TP |
901 | \fB\-\-noexec=dirname_or_filename | ||
902 | Remount directory or file noexec, nodev and nosuid. | ||
903 | .br | ||
904 | |||
905 | .br | ||
906 | Example: | ||
907 | .br | ||
908 | $ firejail \-\-noexec=/tmp | ||
909 | .br | ||
910 | |||
911 | .br | ||
912 | /etc and /var are noexec by default if the sandbox was started as a regular user. If there are more than one mount operation | ||
913 | on the path of the file or directory, noexec should be applied to the last one. Always check if the change took effect inside the sandbox. | ||
914 | |||
915 | .TP | ||
834 | \fB\-\-nogroups | 916 | \fB\-\-nogroups |
835 | Disable supplementary groups. Without this option, supplementary groups are enabled for the user starting the | 917 | Disable supplementary groups. Without this option, supplementary groups are enabled for the user starting the |
836 | sandbox. For root user supplementary groups are always disabled. | 918 | sandbox. For root user supplementary groups are always disabled. |
@@ -865,7 +947,7 @@ Example: | |||
865 | .br | 947 | .br |
866 | $ firejail | 948 | $ firejail |
867 | .br | 949 | .br |
868 | Reading profile /etc/firejail/generic.profile | 950 | Reading profile /etc/firejail/default.profile |
869 | .br | 951 | .br |
870 | Parent pid 8553, child pid 8554 | 952 | Parent pid 8553, child pid 8554 |
871 | .br | 953 | .br |
@@ -908,6 +990,14 @@ ping: icmp open socket: Operation not permitted | |||
908 | $ | 990 | $ |
909 | 991 | ||
910 | .TP | 992 | .TP |
993 | \fB\-\-nonewprivs | ||
994 | Sets the NO_NEW_PRIVS prctl. This ensures that child processes | ||
995 | cannot acquire new privileges using execve(2); in particular, | ||
996 | this means that calling a suid binary (or one with file capabilities) | ||
997 | does not result in an increase of privilege. This option | ||
998 | is enabled by default if seccomp filter is activated. | ||
999 | |||
1000 | .TP | ||
911 | \fB\-\-nosound | 1001 | \fB\-\-nosound |
912 | Disable sound system. | 1002 | Disable sound system. |
913 | .br | 1003 | .br |
@@ -946,13 +1036,15 @@ $ ls -l sandboxlog* | |||
946 | 1036 | ||
947 | .TP | 1037 | .TP |
948 | \fB\-\-overlay | 1038 | \fB\-\-overlay |
949 | Mount a filesystem overlay on top of the current filesystem. All filesystem modifications go into the overlay. | 1039 | Mount a filesystem overlay on top of the current filesystem. Unlike the regular filesystem container, |
950 | The overlay is stored in $HOME/.firejail directory. This option is not available on Grsecurity systems. | 1040 | the system directories are mounted read-write. All filesystem modifications go into the overlay. |
1041 | The overlay is stored in $HOME/.firejail/<PID> directory. | ||
951 | .br | 1042 | .br |
952 | 1043 | ||
953 | .br | 1044 | .br |
954 | OverlayFS support is required in Linux kernel for this option to work. | 1045 | OverlayFS support is required in Linux kernel for this option to work. |
955 | OverlayFS was officially introduced in Linux kernel version 3.18 | 1046 | OverlayFS was officially introduced in Linux kernel version 3.18. |
1047 | This option is not available on Grsecurity systems. | ||
956 | .br | 1048 | .br |
957 | 1049 | ||
958 | .br | 1050 | .br |
@@ -961,14 +1053,34 @@ Example: | |||
961 | $ firejail \-\-overlay firefox | 1053 | $ firejail \-\-overlay firefox |
962 | 1054 | ||
963 | .TP | 1055 | .TP |
1056 | \fB\-\-overlay-named=name | ||
1057 | Mount a filesystem overlay on top of the current filesystem. Unlike the regular filesystem container, | ||
1058 | the system directories are mounted read-write. All filesystem modifications go into the overlay. | ||
1059 | The overlay is stored in $HOME/.firejail/<NAME> directory. The created overlay can be reused between multiple | ||
1060 | sessions. | ||
1061 | .br | ||
1062 | |||
1063 | .br | ||
1064 | OverlayFS support is required in Linux kernel for this option to work. | ||
1065 | OverlayFS was officially introduced in Linux kernel version 3.18. | ||
1066 | This option is not available on Grsecurity systems. | ||
1067 | .br | ||
1068 | |||
1069 | .br | ||
1070 | Example: | ||
1071 | .br | ||
1072 | $ firejail \-\-overlay-named=jail1 firefox | ||
1073 | |||
1074 | .TP | ||
964 | \fB\-\-overlay-tmpfs | 1075 | \fB\-\-overlay-tmpfs |
965 | Mount a filesystem overlay on top of the current filesystem. All filesystem modifications go into the overlay, | 1076 | Mount a filesystem overlay on top of the current filesystem. All filesystem modifications go into the overlay, |
966 | and are discarded when the sandbox is closed. This option is not available on Grsecurity systems. | 1077 | and are discarded when the sandbox is closed. |
967 | .br | 1078 | .br |
968 | 1079 | ||
969 | .br | 1080 | .br |
970 | OverlayFS support is required in Linux kernel for this option to work. | 1081 | OverlayFS support is required in Linux kernel for this option to work. |
971 | OverlayFS was officially introduced in Linux kernel version 3.18 | 1082 | OverlayFS was officially introduced in Linux kernel version 3.18. |
1083 | This option is not available on Grsecurity systems. | ||
972 | .br | 1084 | .br |
973 | 1085 | ||
974 | .br | 1086 | .br |
@@ -977,6 +1089,17 @@ Example: | |||
977 | $ firejail \-\-overlay-tmpfs firefox | 1089 | $ firejail \-\-overlay-tmpfs firefox |
978 | 1090 | ||
979 | .TP | 1091 | .TP |
1092 | \fB\-\-overlay-clean | ||
1093 | Clean all overlays stored in $HOME/.firejail directory. Overlays created with --overlay-path=path | ||
1094 | outside $HOME/.firejail will not be deleted. | ||
1095 | .br | ||
1096 | |||
1097 | .br | ||
1098 | Example: | ||
1099 | .br | ||
1100 | $ firejail \-\-overlay-clean | ||
1101 | |||
1102 | .TP | ||
980 | \fB\-\-private | 1103 | \fB\-\-private |
981 | Mount new /root and /home/user directories in temporary | 1104 | Mount new /root and /home/user directories in temporary |
982 | filesystems. All modifications are discarded when the sandbox is | 1105 | filesystems. All modifications are discarded when the sandbox is |
@@ -998,9 +1121,24 @@ Example: | |||
998 | $ firejail \-\-private=/home/netblue/firefox-home firefox | 1121 | $ firejail \-\-private=/home/netblue/firefox-home firefox |
999 | 1122 | ||
1000 | .TP | 1123 | .TP |
1124 | \fB\-\-private-home=file,directory | ||
1125 | Build a new user home in a temporary | ||
1126 | filesystem, and copy the files and directories in the list in the | ||
1127 | new home. All modifications are discarded when the sandbox is | ||
1128 | closed. | ||
1129 | .br | ||
1130 | |||
1131 | .br | ||
1132 | Example: | ||
1133 | .br | ||
1134 | $ firejail \-\-private-home=.mozilla firefox | ||
1135 | |||
1136 | .TP | ||
1001 | \fB\-\-private-bin=file,file | 1137 | \fB\-\-private-bin=file,file |
1002 | Build a new /bin in a temporary filesystem, and copy the programs in the list. | 1138 | Build a new /bin in a temporary filesystem, and copy the programs in the list. |
1139 | If no listed file is found, /bin directory will be empty. | ||
1003 | The same directory is also bind-mounted over /sbin, /usr/bin, /usr/sbin and /usr/local/bin. | 1140 | The same directory is also bind-mounted over /sbin, /usr/bin, /usr/sbin and /usr/local/bin. |
1141 | All modifications are discarded when the sandbox is closed. | ||
1004 | .br | 1142 | .br |
1005 | 1143 | ||
1006 | .br | 1144 | .br |
@@ -1018,7 +1156,7 @@ bash cat ls sed | |||
1018 | 1156 | ||
1019 | .TP | 1157 | .TP |
1020 | \fB\-\-private-dev | 1158 | \fB\-\-private-dev |
1021 | Create a new /dev directory. Only dri, null, full, zero, tty, pts, ptmx, random, urandom, log and shm devices are available. | 1159 | Create a new /dev directory. Only dri, null, full, zero, tty, pts, ptmx, random, snd, urandom, log and shm devices are available. |
1022 | .br | 1160 | .br |
1023 | 1161 | ||
1024 | .br | 1162 | .br |
@@ -1032,14 +1170,15 @@ Child process initialized | |||
1032 | .br | 1170 | .br |
1033 | $ ls /dev | 1171 | $ ls /dev |
1034 | .br | 1172 | .br |
1035 | dri full log null ptmx pts random shm tty urandom zero | 1173 | dri full log null ptmx pts random shm snd tty urandom zero |
1036 | .br | 1174 | .br |
1037 | $ | 1175 | $ |
1038 | .TP | 1176 | .TP |
1039 | \fB\-\-private-etc=file,directory | 1177 | \fB\-\-private-etc=file,directory |
1040 | Build a new /etc in a temporary | 1178 | Build a new /etc in a temporary |
1041 | filesystem, and copy the files and directories in the list. | 1179 | filesystem, and copy the files and directories in the list. |
1042 | All modifications are discarded when the sandbox is closed. | 1180 | If no listed file is found, /etc directory will be empty. |
1181 | All modifications are discarded when the sandbox is closed. | ||
1043 | .br | 1182 | .br |
1044 | 1183 | ||
1045 | .br | 1184 | .br |
@@ -1050,8 +1189,34 @@ $ firejail --private-etc=group,hostname,localtime, \\ | |||
1050 | nsswitch.conf,passwd,resolv.conf | 1189 | nsswitch.conf,passwd,resolv.conf |
1051 | 1190 | ||
1052 | .TP | 1191 | .TP |
1192 | \fB\-\-private-opt=file,directory | ||
1193 | Build a new /opt in a temporary | ||
1194 | filesystem, and copy the files and directories in the list. | ||
1195 | If no listed file is found, /opt directory will be empty. | ||
1196 | All modifications are discarded when the sandbox is closed. | ||
1197 | .br | ||
1198 | |||
1199 | .br | ||
1200 | Example: | ||
1201 | .br | ||
1202 | $ firejail --private-opt=firefox /opt/firefox/firefox | ||
1203 | |||
1204 | .TP | ||
1205 | \fB\-\-private-srv=file,directory | ||
1206 | Build a new /srv in a temporary | ||
1207 | filesystem, and copy the files and directories in the list. | ||
1208 | If no listed file is found, /srv directory will be empty. | ||
1209 | All modifications are discarded when the sandbox is closed. | ||
1210 | .br | ||
1211 | |||
1212 | .br | ||
1213 | Example: | ||
1214 | .br | ||
1215 | # firejail --private-srv=www /etc/init.d/apache2 start | ||
1216 | |||
1217 | .TP | ||
1053 | \fB\-\-private-tmp | 1218 | \fB\-\-private-tmp |
1054 | Mount an empty temporary filesystem on top of /tmp directory. | 1219 | Mount an empty temporary filesystem on top of /tmp directory whitelisting /tmp/.X11-unix. |
1055 | .br | 1220 | .br |
1056 | 1221 | ||
1057 | .br | 1222 | .br |
@@ -1120,6 +1285,9 @@ $ firejail \-\-protocol.print=3272 | |||
1120 | .br | 1285 | .br |
1121 | unix,inet,inet6,netlink | 1286 | unix,inet,inet6,netlink |
1122 | .TP | 1287 | .TP |
1288 | \fB\-\-put=name|pid src-filename dest-filename | ||
1289 | Put a file in sandbox container, see \fBFILE TRANSFER\fR section for more details. | ||
1290 | .TP | ||
1123 | \fB\-\-quiet | 1291 | \fB\-\-quiet |
1124 | Turn off Firejail's output. | 1292 | Turn off Firejail's output. |
1125 | .TP | 1293 | .TP |
@@ -1131,6 +1299,31 @@ Set directory or file read-only. | |||
1131 | Example: | 1299 | Example: |
1132 | .br | 1300 | .br |
1133 | $ firejail \-\-read-only=~/.mozilla firefox | 1301 | $ firejail \-\-read-only=~/.mozilla firefox |
1302 | .br | ||
1303 | |||
1304 | .br | ||
1305 | A short note about mixing \-\-whitelist and \-\-read-only options. Whitelisted directories | ||
1306 | should be made read-only independently. Making a parent directory read-only, will not | ||
1307 | make the whitelist read-only. Example: | ||
1308 | .br | ||
1309 | |||
1310 | .br | ||
1311 | $ firejail --whitelist=~/work --read-only=~ --read-only=~/work | ||
1312 | |||
1313 | .TP | ||
1314 | \fB\-\-read-write=dirname_or_filename | ||
1315 | Set directory or file read-write. Only files or directories belonging to the current user are allowed for | ||
1316 | this operation. Example: | ||
1317 | .br | ||
1318 | |||
1319 | .br | ||
1320 | $ mkdir ~/test | ||
1321 | .br | ||
1322 | $ touch ~/test/a | ||
1323 | .br | ||
1324 | $ firejail --read-only=~/test --read-write=~/test/a | ||
1325 | |||
1326 | |||
1134 | .TP | 1327 | .TP |
1135 | \fB\-\-rlimit-fsize=number | 1328 | \fB\-\-rlimit-fsize=number |
1136 | Set the maximum file size that can be created by a process. | 1329 | Set the maximum file size that can be created by a process. |
@@ -1143,6 +1336,17 @@ Set the maximum number of processes that can be created for the real user ID of | |||
1143 | .TP | 1336 | .TP |
1144 | \fB\-\-rlimit-sigpending=number | 1337 | \fB\-\-rlimit-sigpending=number |
1145 | Set the maximum number of pending signals for a process. | 1338 | Set the maximum number of pending signals for a process. |
1339 | |||
1340 | .TP | ||
1341 | \fB\-\-rmenv=name | ||
1342 | Remove environment variable in the new sandbox. | ||
1343 | .br | ||
1344 | |||
1345 | .br | ||
1346 | Example: | ||
1347 | .br | ||
1348 | $ firejail \-\-rmenv=DBUS_SESSION_BUS_ADDRESS | ||
1349 | |||
1146 | .TP | 1350 | .TP |
1147 | \fB\-\-scan | 1351 | \fB\-\-scan |
1148 | ARP-scan all the networks from inside a network namespace. | 1352 | ARP-scan all the networks from inside a network namespace. |
@@ -1156,13 +1360,13 @@ $ firejail \-\-net=eth0 \-\-scan | |||
1156 | .TP | 1360 | .TP |
1157 | \fB\-\-seccomp | 1361 | \fB\-\-seccomp |
1158 | Enable seccomp filter and blacklist the syscalls in the default list. The default list is as follows: | 1362 | Enable seccomp filter and blacklist the syscalls in the default list. The default list is as follows: |
1159 | mount, umount2, ptrace, kexec_load, kexec_file_load, open_by_handle_at, init_module, finit_module, delete_module, | 1363 | mount, umount2, ptrace, kexec_load, kexec_file_load, name_to_handle_at, open_by_handle_at, create_module, init_module, finit_module, delete_module, |
1160 | iopl, ioperm, swapon, swapoff, syslog, process_vm_readv, process_vm_writev, | 1364 | iopl, ioperm, ioprio_set, swapon, swapoff, syslog, process_vm_readv, process_vm_writev, |
1161 | sysfs,_sysctl, adjtimex, clock_adjtime, lookup_dcookie, perf_event_open, fanotify_init, kcmp, | 1365 | sysfs,_sysctl, adjtimex, clock_adjtime, lookup_dcookie, perf_event_open, fanotify_init, kcmp, |
1162 | add_key, request_key, keyctl, uselib, acct, modify_ldt, pivot_root, io_setup, | 1366 | add_key, request_key, keyctl, uselib, acct, modify_ldt, pivot_root, io_setup, |
1163 | io_destroy, io_getevents, io_submit, io_cancel, | 1367 | io_destroy, io_getevents, io_submit, io_cancel, |
1164 | remap_file_pages, mbind, get_mempolicy, set_mempolicy, | 1368 | remap_file_pages, mbind, get_mempolicy, set_mempolicy, |
1165 | migrate_pages, move_pages, vmsplice, perf_event_open, chroot, | 1369 | migrate_pages, move_pages, vmsplice, chroot, |
1166 | tuxcall, reboot, mfsservctl and get_kernel_syms. | 1370 | tuxcall, reboot, mfsservctl and get_kernel_syms. |
1167 | .br | 1371 | .br |
1168 | 1372 | ||
@@ -1173,6 +1377,10 @@ both 32-bit and 64-bit filters are installed. | |||
1173 | .br | 1377 | .br |
1174 | 1378 | ||
1175 | .br | 1379 | .br |
1380 | Firejail will print seccomp violations to the audit log if the kernel was compiled with audit support (CONFIG_AUDIT flag). | ||
1381 | .br | ||
1382 | |||
1383 | .br | ||
1176 | Example: | 1384 | Example: |
1177 | .br | 1385 | .br |
1178 | $ firejail \-\-seccomp | 1386 | $ firejail \-\-seccomp |
@@ -1425,15 +1633,7 @@ $ firejail \-\-tree | |||
1425 | 11969:netblue:firejail \-\-net=eth0 transmission-gtk | 1633 | 11969:netblue:firejail \-\-net=eth0 transmission-gtk |
1426 | .br | 1634 | .br |
1427 | 11970:netblue:transmission-gtk | 1635 | 11970:netblue:transmission-gtk |
1428 | .TP | ||
1429 | \fB\-\-user=new-user | ||
1430 | Switch the user before starting the sandbox. This command should be run as root. | ||
1431 | .br | ||
1432 | 1636 | ||
1433 | .br | ||
1434 | Example: | ||
1435 | .br | ||
1436 | # firejail \-\-user=www-data | ||
1437 | .TP | 1637 | .TP |
1438 | \fB\-\-version | 1638 | \fB\-\-version |
1439 | Print program version and exit. | 1639 | Print program version and exit. |
@@ -1445,66 +1645,106 @@ Example: | |||
1445 | $ firejail \-\-version | 1645 | $ firejail \-\-version |
1446 | .br | 1646 | .br |
1447 | firejail version 0.9.27 | 1647 | firejail version 0.9.27 |
1648 | |||
1649 | .TP | ||
1650 | \fB\-\-veth-name=name | ||
1651 | Use this name for the interface connected to the bridge for --net=bridge_interface commands, | ||
1652 | instead of the default one. | ||
1653 | .br | ||
1654 | |||
1655 | .br | ||
1656 | Example: | ||
1657 | .br | ||
1658 | $ firejail \-\-net=br0 --veth-name=if0 | ||
1659 | |||
1448 | .TP | 1660 | .TP |
1449 | \fB\-\-whitelist=dirname_or_filename | 1661 | \fB\-\-whitelist=dirname_or_filename |
1450 | Whitelist directory or file. This feature is implemented only for user home, /dev, /media, /opt, /var, and /tmp directories. | 1662 | Whitelist directory or file. A temporary file system is mounted on the top directory, and the |
1451 | When whitlisting symbolic links, both the link and the real file should be in the same top directory | 1663 | whitelisted files are mount-binded inside. Modifications to whitelisted files are persistent, |
1452 | (home user, /media, /var etc.) | 1664 | everything else is discarded when the sandbox is closed. The top directory could be |
1665 | user home, /dev, /media, /mnt, /opt, /srv, /var, and /tmp. | ||
1666 | .br | ||
1667 | |||
1668 | .br | ||
1669 | Symbolic link handling: with the exception of user home, both the link and the real file should be in | ||
1670 | the same top directory. For user home, both the link and the real file should be owned by the user. | ||
1453 | .br | 1671 | .br |
1454 | 1672 | ||
1455 | .br | 1673 | .br |
1456 | Example: | 1674 | Example: |
1457 | .br | 1675 | .br |
1458 | $ firejail \-\-whitelist=~/.mozilla \-\-whitelist=~/Downloads | 1676 | $ firejail \-\-noprofile \-\-whitelist=~/.mozilla |
1459 | .br | 1677 | .br |
1460 | $ firejail \-\-whitelist=/tmp/.X11-unix --whitelist=/dev/null | 1678 | $ firejail \-\-whitelist=/tmp/.X11-unix --whitelist=/dev/null |
1461 | .br | 1679 | .br |
1462 | $ firejail "\-\-whitelist=/home/username/My Virtual Machines" | 1680 | $ firejail "\-\-whitelist=/home/username/My Virtual Machines" |
1463 | 1681 | ||
1464 | .TP | 1682 | .TP |
1465 | \fB\-\-x11 | 1683 | \fB\-\-writable-etc |
1466 | Start a new X11 server using Xpra or Xephyr and attach the sandbox to this server. | 1684 | Mount /etc directory read-write. |
1467 | The regular X11 server (display 0) is not visible in the sandbox. This prevents screenshot and keylogger | ||
1468 | applications started in the sandbox from accessing other X11 displays. | ||
1469 | A network namespace needs to be instantiated in order to deny access to X11 abstract Unix domain socket. | ||
1470 | .br | 1685 | .br |
1471 | 1686 | ||
1472 | .br | 1687 | .br |
1473 | Firejail will try first Xpra, and if Xpra is not installed on the system, it will try to find Xephyr. | 1688 | Example: |
1474 | This feature is not available when running as root. | 1689 | .br |
1690 | $ sudo firejail --writable-etc | ||
1691 | |||
1692 | .TP | ||
1693 | \fB\-\-writable-var | ||
1694 | Mount /var directory read-write. | ||
1475 | .br | 1695 | .br |
1476 | 1696 | ||
1477 | .br | 1697 | .br |
1478 | Example: | 1698 | Example: |
1479 | .br | 1699 | .br |
1480 | $ firejail \-\-x11 --net=eth0 firefox | 1700 | $ sudo firejail --writable-var |
1701 | |||
1481 | 1702 | ||
1482 | .TP | 1703 | .TP |
1483 | \fB\-\-x11=xpra | 1704 | \fB\-\-x11 |
1484 | Start a new X11 server using Xpra (http://xpra.org) and attach the sandbox to this server. | 1705 | Sandbox the application using Xpra, Xephyr or Xorg security extension. |
1485 | Xpra is a persistent remote display server and client for forwarding X11 applications and desktop screens. | 1706 | The sandbox will prevents screenshot and keylogger applications started inside the sandbox from accessing |
1486 | On Debian platforms Xpra is installed with the command \fBsudo apt-get install xpra\fR. | 1707 | clients running outside the sandbox. |
1487 | This feature is not available when running as root. | 1708 | Firejail will try first Xpra, and if Xpra is not installed on the system, it will try to find Xephyr. |
1709 | If all fails, Firejail will not attempt to use X11 security extension. | ||
1710 | .br | ||
1711 | |||
1712 | .br | ||
1713 | Xpra and Xephyr modes require a network namespace to be instantiated in order to disable | ||
1714 | X11 abstract Unix socket. If this is not possible, the user can disable the abstract socket | ||
1715 | by adding "-nolisten local" on Xorg command line. | ||
1488 | .br | 1716 | .br |
1489 | 1717 | ||
1490 | .br | 1718 | .br |
1491 | Example: | 1719 | Example: |
1492 | .br | 1720 | .br |
1493 | $ firejail \-\-x11=xpra --net=eth0 firefox | 1721 | $ firejail \-\-x11 --net=eth0 firefox |
1722 | |||
1723 | .TP | ||
1724 | \fB\-\-x11=none | ||
1725 | Blacklist /tmp/.X11-unix directory, ${HOME}/.Xauthority and the file specified in ${XAUTHORITY} environment variable. | ||
1726 | Remove DISPLAY and XAUTHORITY environment variables. | ||
1727 | Stop with error message if X11 abstract socket will be accessible in jail. | ||
1494 | 1728 | ||
1495 | .TP | 1729 | .TP |
1496 | \fB\-\-x11=xephyr | 1730 | \fB\-\-x11=xephyr |
1497 | Start a new X11 server using Xephyr and attach the sandbox to this server. | 1731 | Start Xephyr and attach the sandbox to this server. |
1498 | Xephyr is a display server implementing the X11 display server protocol. | 1732 | Xephyr is a display server implementing the X11 display server protocol. |
1499 | It runs in a window just like other X applications, but it is an X server itself in which you can run other software. | 1733 | A network namespace needs to be instantiated in order to deny access to X11 abstract Unix domain socket. |
1500 | The default Xephyr window size is 800x600. This can be modified in /etc/firejail/firejail.config file, | 1734 | .br |
1501 | see \fBman 5 firejail-config\fR for more details. | 1735 | |
1736 | .br | ||
1737 | Xephyr runs in a window just like any other X11 application. The default window size is 800x600. | ||
1738 | This can be modified in /etc/firejail/firejail.config file. | ||
1502 | .br | 1739 | .br |
1503 | 1740 | ||
1504 | .br | 1741 | .br |
1505 | The recommended way to use this feature is to run a window manager inside the sandbox. | 1742 | The recommended way to use this feature is to run a window manager inside the sandbox. |
1506 | A security profile for OpenBox is provided. | 1743 | A security profile for OpenBox is provided. |
1507 | On Debian platforms Xephyr is installed with the command \fBsudo apt-get install xserver-xephyr\fR. | 1744 | .br |
1745 | |||
1746 | .br | ||
1747 | Xephyr is developed by Xorg project. On Debian platforms it is installed with the command \fBsudo apt-get install xserver-xephyr\fR. | ||
1508 | This feature is not available when running as root. | 1748 | This feature is not available when running as root. |
1509 | .br | 1749 | .br |
1510 | 1750 | ||
@@ -1514,6 +1754,42 @@ Example: | |||
1514 | $ firejail \-\-x11=xephyr --net=eth0 openbox | 1754 | $ firejail \-\-x11=xephyr --net=eth0 openbox |
1515 | 1755 | ||
1516 | .TP | 1756 | .TP |
1757 | \fB\-\-x11=xorg | ||
1758 | Sandbox the application using the untrusted mode implemented by X11 security extension. | ||
1759 | The extension is available in Xorg package | ||
1760 | and it is installed by default on most Linux distributions. It provides support for a simple trusted/untrusted | ||
1761 | connection model. Untrusted clients are restricted in certain ways to prevent them from reading window | ||
1762 | contents of other clients, stealing input events, etc. | ||
1763 | |||
1764 | The untrusted mode has several limitations. A lot of regular programs assume they are a trusted X11 clients | ||
1765 | and will crash or lock up when run in untrusted mode. Chromium browser and xterm are two examples. | ||
1766 | Firefox and transmission-gtk seem to be working fine. | ||
1767 | A network namespace is not required for this option. | ||
1768 | .br | ||
1769 | |||
1770 | .br | ||
1771 | Example: | ||
1772 | .br | ||
1773 | $ firejail \-\-x11=xorg firefox | ||
1774 | |||
1775 | .TP | ||
1776 | \fB\-\-x11=xpra | ||
1777 | Start Xpra (http://xpra.org) and attach the sandbox to this server. | ||
1778 | Xpra is a persistent remote display server and client for forwarding X11 applications and desktop screens. | ||
1779 | A network namespace needs to be instantiated in order to deny access to X11 abstract Unix domain socket. | ||
1780 | .br | ||
1781 | |||
1782 | .br | ||
1783 | On Debian platforms Xpra is installed with the command \fBsudo apt-get install xpra\fR. | ||
1784 | This feature is not available when running as root. | ||
1785 | .br | ||
1786 | |||
1787 | .br | ||
1788 | Example: | ||
1789 | .br | ||
1790 | $ firejail \-\-x11=xpra --net=eth0 firefox | ||
1791 | |||
1792 | .TP | ||
1517 | \fB\-\-zsh | 1793 | \fB\-\-zsh |
1518 | Use /usr/bin/zsh as default user shell. | 1794 | Use /usr/bin/zsh as default user shell. |
1519 | .br | 1795 | .br |
@@ -1576,6 +1852,44 @@ $ firejail --tree | |||
1576 | 1221:netblue:/usr/lib/firefox/firefox | 1852 | 1221:netblue:/usr/lib/firefox/firefox |
1577 | .RE | 1853 | .RE |
1578 | 1854 | ||
1855 | .SH APPARMOR | ||
1856 | .TP | ||
1857 | AppArmor support is disabled by default at compile time. Use --enable-apparmor configuration option to enable it: | ||
1858 | .br | ||
1859 | |||
1860 | .br | ||
1861 | $ ./configure --prefix=/usr --enable-apparmor | ||
1862 | .TP | ||
1863 | During software install, a generic AppArmor profile file, firejail-default, is placed in /etc/apparmor.d directory. The profile needs to be loaded into the kernel by running the following command as root: | ||
1864 | .br | ||
1865 | |||
1866 | .br | ||
1867 | # aa-enforce firejail-default | ||
1868 | .TP | ||
1869 | The installed profile tries to replicate some advanced security features inspired by kernel-based Grsecurity: | ||
1870 | .br | ||
1871 | |||
1872 | .br | ||
1873 | - Prevent information leakage in /proc and /sys directories. The resulting filesystem is barely enough for running | ||
1874 | commands such as "top" and "ps aux". | ||
1875 | .br | ||
1876 | |||
1877 | .br | ||
1878 | - Allow running programs only from well-known system paths, such as /bin, /sbin, /usr/bin etc. Running | ||
1879 | programs and scripts from user home or other directories writable by the user is not allowed. | ||
1880 | .br | ||
1881 | |||
1882 | .br | ||
1883 | - Disable D-Bus. D-Bus has long been a huge security hole, and most programs don't use it anyway. | ||
1884 | You should have no problems running Chromium or Firefox. | ||
1885 | |||
1886 | .TP | ||
1887 | 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: | ||
1888 | .br | ||
1889 | |||
1890 | .br | ||
1891 | $ firejail --apparmor firefox | ||
1892 | |||
1579 | .SH FILE TRANSFER | 1893 | .SH FILE TRANSFER |
1580 | These features allow the user to inspect the filesystem container of an existing sandbox | 1894 | These features allow the user to inspect the filesystem container of an existing sandbox |
1581 | and transfer files from the container to the host filesystem. | 1895 | and transfer files from the container to the host filesystem. |
@@ -1583,12 +1897,16 @@ and transfer files from the container to the host filesystem. | |||
1583 | .TP | 1897 | .TP |
1584 | \fB\-\-get=name|pid filename | 1898 | \fB\-\-get=name|pid filename |
1585 | Retrieve the container file and store it on the host in the current working directory. | 1899 | Retrieve the container file and store it on the host in the current working directory. |
1586 | The container is specified by name or PID. Full path is needed for filename. | 1900 | The container is specified by name or PID. |
1587 | 1901 | ||
1588 | .TP | 1902 | .TP |
1589 | \fB\-\-ls=name|pid dir_or_filename | 1903 | \fB\-\-ls=name|pid dir_or_filename |
1590 | List container files. The container is specified by name or PID. | 1904 | List container files. The container is specified by name or PID. |
1591 | Full path is needed for dir_or_filename. | 1905 | |
1906 | .TP | ||
1907 | \fB\-\-put=name|pid src-filename dest-filename | ||
1908 | Put src-filename in sandbox container. | ||
1909 | The container is specified by name or PID. | ||
1592 | 1910 | ||
1593 | .TP | 1911 | .TP |
1594 | Examples: | 1912 | Examples: |
@@ -1614,7 +1932,11 @@ drwxr-xr-x netblue netblue 4096 .. | |||
1614 | 1932 | ||
1615 | .br | 1933 | .br |
1616 | $ firejail \-\-get=mybrowser ~/Downloads/xpra-clipboard.png | 1934 | $ firejail \-\-get=mybrowser ~/Downloads/xpra-clipboard.png |
1935 | .br | ||
1617 | 1936 | ||
1937 | .br | ||
1938 | $ firejail \-\-put=mybrowser xpra-clipboard.png ~/Downloads/xpra-clipboard.png | ||
1939 | .br | ||
1618 | 1940 | ||
1619 | .SH TRAFFIC SHAPING | 1941 | .SH TRAFFIC SHAPING |
1620 | Network bandwidth is an expensive resource shared among all sandboxes running on a system. | 1942 | Network bandwidth is an expensive resource shared among all sandboxes running on a system. |
@@ -1626,15 +1948,15 @@ The shaper works at sandbox level, and can be used only for sandboxes configured | |||
1626 | 1948 | ||
1627 | Set rate-limits: | 1949 | Set rate-limits: |
1628 | 1950 | ||
1629 | firejail --bandwidth=name|pid set network download upload | 1951 | $ firejail --bandwidth=name|pid set network download upload |
1630 | 1952 | ||
1631 | Clear rate-limits: | 1953 | Clear rate-limits: |
1632 | 1954 | ||
1633 | firejail --bandwidth=name|pid clear network | 1955 | $ firejail --bandwidth=name|pid clear network |
1634 | 1956 | ||
1635 | Status: | 1957 | Status: |
1636 | 1958 | ||
1637 | firejail --bandwidth=name|pid status | 1959 | $ firejail --bandwidth=name|pid status |
1638 | 1960 | ||
1639 | where: | 1961 | where: |
1640 | .br | 1962 | .br |
@@ -1658,6 +1980,26 @@ Example: | |||
1658 | .br | 1980 | .br |
1659 | $ firejail \-\-bandwidth=mybrowser clear eth0 | 1981 | $ firejail \-\-bandwidth=mybrowser clear eth0 |
1660 | 1982 | ||
1983 | .SH AUDIT | ||
1984 | Audit feature allows the user to point out gaps in security profiles. The | ||
1985 | implementation replaces the program to be sandboxed with a test program. By | ||
1986 | default, we use faudit program distributed with Firejail. A custom test program | ||
1987 | can also be supplied by the user. Examples: | ||
1988 | |||
1989 | Running the default audit program: | ||
1990 | .br | ||
1991 | $ firejail --audit transmission-gtk | ||
1992 | |||
1993 | Running a custom audit program: | ||
1994 | .br | ||
1995 | $ firejail --audit=~/sandbox-test transmission-gtk | ||
1996 | |||
1997 | In the examples above, the sandbox configures transmission-gtk profile and | ||
1998 | starts the test program. The real program, transmission-gtk, will not be | ||
1999 | started. | ||
2000 | |||
2001 | Limitations: audit feature is not implemented for --x11 commands. | ||
2002 | |||
1661 | .SH MONITORING | 2003 | .SH MONITORING |
1662 | Option \-\-list prints a list of all sandboxes. The format | 2004 | Option \-\-list prints a list of all sandboxes. The format |
1663 | for each process entry is as follows: | 2005 | for each process entry is as follows: |
@@ -1751,7 +2093,7 @@ To disable default profile loading, use --noprofile command option. Example: | |||
1751 | .RS | 2093 | .RS |
1752 | $ firejail | 2094 | $ firejail |
1753 | .br | 2095 | .br |
1754 | Reading profile /etc/firejail/generic.profile | 2096 | Reading profile /etc/firejail/default.profile |
1755 | .br | 2097 | .br |
1756 | Parent pid 8553, child pid 8554 | 2098 | Parent pid 8553, child pid 8554 |
1757 | .br | 2099 | .br |
@@ -1818,7 +2160,6 @@ Homepage: http://firejail.wordpress.com | |||
1818 | \&\flfirecfg\fR\|(1), | 2160 | \&\flfirecfg\fR\|(1), |
1819 | \&\flfirejail-profile\fR\|(5), | 2161 | \&\flfirejail-profile\fR\|(5), |
1820 | \&\flfirejail-login\fR\|(5) | 2162 | \&\flfirejail-login\fR\|(5) |
1821 | \&\flfirejail-config\fR\|(5) | ||
1822 | 2163 | ||
1823 | 2164 | ||
1824 | 2165 | ||