diff options
Diffstat (limited to 'src/man/firejail.txt')
-rw-r--r-- | src/man/firejail.txt | 439 |
1 files changed, 370 insertions, 69 deletions
diff --git a/src/man/firejail.txt b/src/man/firejail.txt index 23db832c1..bb9ae270c 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 user home directories 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 | ||
@@ -798,13 +845,23 @@ PID User RX(KB/s) TX(KB/s) Command | |||
798 | .TP | 845 | .TP |
799 | \fB\-\-nice=value | 846 | \fB\-\-nice=value |
800 | Set nice value for all processes running inside the sandbox. | 847 | Set nice value for all processes running inside the sandbox. |
848 | Only root may specify a negative value. | ||
801 | .br | 849 | .br |
802 | 850 | ||
803 | .br | 851 | .br |
804 | Example: | 852 | Example: |
805 | .br | 853 | .br |
806 | $ firejail --nice=-5 firefox | 854 | $ firejail --nice=2 firefox |
855 | |||
856 | .TP | ||
857 | \fB\-\-no3d | ||
858 | Disable 3D hardware acceleration. | ||
859 | .br | ||
807 | 860 | ||
861 | .br | ||
862 | Example: | ||
863 | .br | ||
864 | $ firejail --no3d firefox | ||
808 | 865 | ||
809 | .TP | 866 | .TP |
810 | \fB\-\-noblacklist=dirname_or_filename | 867 | \fB\-\-noblacklist=dirname_or_filename |
@@ -831,6 +888,21 @@ $ nc dict.org 2628 | |||
831 | 220 pan.alephnull.com dictd 1.12.1/rf on Linux 3.14-1-amd64 | 888 | 220 pan.alephnull.com dictd 1.12.1/rf on Linux 3.14-1-amd64 |
832 | .br | 889 | .br |
833 | .TP | 890 | .TP |
891 | \fB\-\-noexec=dirname_or_filename | ||
892 | Remount directory or file noexec, nodev and nosuid. | ||
893 | .br | ||
894 | |||
895 | .br | ||
896 | Example: | ||
897 | .br | ||
898 | $ firejail \-\-noexec=/tmp | ||
899 | .br | ||
900 | |||
901 | .br | ||
902 | /etc and /var are noexec by default if the sandbox was started as a regular user. If there are more than one mount operation | ||
903 | 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. | ||
904 | |||
905 | .TP | ||
834 | \fB\-\-nogroups | 906 | \fB\-\-nogroups |
835 | Disable supplementary groups. Without this option, supplementary groups are enabled for the user starting the | 907 | 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. | 908 | sandbox. For root user supplementary groups are always disabled. |
@@ -865,7 +937,7 @@ Example: | |||
865 | .br | 937 | .br |
866 | $ firejail | 938 | $ firejail |
867 | .br | 939 | .br |
868 | Reading profile /etc/firejail/generic.profile | 940 | Reading profile /etc/firejail/default.profile |
869 | .br | 941 | .br |
870 | Parent pid 8553, child pid 8554 | 942 | Parent pid 8553, child pid 8554 |
871 | .br | 943 | .br |
@@ -908,6 +980,14 @@ ping: icmp open socket: Operation not permitted | |||
908 | $ | 980 | $ |
909 | 981 | ||
910 | .TP | 982 | .TP |
983 | \fB\-\-nonewprivs | ||
984 | Sets the NO_NEW_PRIVS prctl. This ensures that child processes | ||
985 | cannot acquire new privileges using execve(2); in particular, | ||
986 | this means that calling a suid binary (or one with file capabilities) | ||
987 | does not result in an increase of privilege. This option | ||
988 | is enabled by default if seccomp filter is activated. | ||
989 | |||
990 | .TP | ||
911 | \fB\-\-nosound | 991 | \fB\-\-nosound |
912 | Disable sound system. | 992 | Disable sound system. |
913 | .br | 993 | .br |
@@ -946,13 +1026,15 @@ $ ls -l sandboxlog* | |||
946 | 1026 | ||
947 | .TP | 1027 | .TP |
948 | \fB\-\-overlay | 1028 | \fB\-\-overlay |
949 | Mount a filesystem overlay on top of the current filesystem. All filesystem modifications go into the overlay. | 1029 | 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. | 1030 | the system directories are mounted read-write. All filesystem modifications go into the overlay. |
1031 | The overlay is stored in $HOME/.firejail/<PID> directory. | ||
951 | .br | 1032 | .br |
952 | 1033 | ||
953 | .br | 1034 | .br |
954 | OverlayFS support is required in Linux kernel for this option to work. | 1035 | OverlayFS support is required in Linux kernel for this option to work. |
955 | OverlayFS was officially introduced in Linux kernel version 3.18 | 1036 | OverlayFS was officially introduced in Linux kernel version 3.18. |
1037 | This option is not available on Grsecurity systems. | ||
956 | .br | 1038 | .br |
957 | 1039 | ||
958 | .br | 1040 | .br |
@@ -961,14 +1043,34 @@ Example: | |||
961 | $ firejail \-\-overlay firefox | 1043 | $ firejail \-\-overlay firefox |
962 | 1044 | ||
963 | .TP | 1045 | .TP |
1046 | \fB\-\-overlay-named=name | ||
1047 | Mount a filesystem overlay on top of the current filesystem. Unlike the regular filesystem container, | ||
1048 | the system directories are mounted read-write. All filesystem modifications go into the overlay. | ||
1049 | The overlay is stored in $HOME/.firejail/<NAME> directory. The created overlay can be reused between multiple | ||
1050 | sessions. | ||
1051 | .br | ||
1052 | |||
1053 | .br | ||
1054 | OverlayFS support is required in Linux kernel for this option to work. | ||
1055 | OverlayFS was officially introduced in Linux kernel version 3.18. | ||
1056 | This option is not available on Grsecurity systems. | ||
1057 | .br | ||
1058 | |||
1059 | .br | ||
1060 | Example: | ||
1061 | .br | ||
1062 | $ firejail \-\-overlay-named=jail1 firefox | ||
1063 | |||
1064 | .TP | ||
964 | \fB\-\-overlay-tmpfs | 1065 | \fB\-\-overlay-tmpfs |
965 | Mount a filesystem overlay on top of the current filesystem. All filesystem modifications go into the overlay, | 1066 | 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. | 1067 | and are discarded when the sandbox is closed. |
967 | .br | 1068 | .br |
968 | 1069 | ||
969 | .br | 1070 | .br |
970 | OverlayFS support is required in Linux kernel for this option to work. | 1071 | OverlayFS support is required in Linux kernel for this option to work. |
971 | OverlayFS was officially introduced in Linux kernel version 3.18 | 1072 | OverlayFS was officially introduced in Linux kernel version 3.18. |
1073 | This option is not available on Grsecurity systems. | ||
972 | .br | 1074 | .br |
973 | 1075 | ||
974 | .br | 1076 | .br |
@@ -977,6 +1079,17 @@ Example: | |||
977 | $ firejail \-\-overlay-tmpfs firefox | 1079 | $ firejail \-\-overlay-tmpfs firefox |
978 | 1080 | ||
979 | .TP | 1081 | .TP |
1082 | \fB\-\-overlay-clean | ||
1083 | Clean all overlays stored in $HOME/.firejail directory. Overlays created with --overlay-path=path | ||
1084 | outside $HOME/.firejail will not be deleted. | ||
1085 | .br | ||
1086 | |||
1087 | .br | ||
1088 | Example: | ||
1089 | .br | ||
1090 | $ firejail \-\-overlay-clean | ||
1091 | |||
1092 | .TP | ||
980 | \fB\-\-private | 1093 | \fB\-\-private |
981 | Mount new /root and /home/user directories in temporary | 1094 | Mount new /root and /home/user directories in temporary |
982 | filesystems. All modifications are discarded when the sandbox is | 1095 | filesystems. All modifications are discarded when the sandbox is |
@@ -998,9 +1111,24 @@ Example: | |||
998 | $ firejail \-\-private=/home/netblue/firefox-home firefox | 1111 | $ firejail \-\-private=/home/netblue/firefox-home firefox |
999 | 1112 | ||
1000 | .TP | 1113 | .TP |
1114 | \fB\-\-private-home=file,directory | ||
1115 | Build a new user home in a temporary | ||
1116 | filesystem, and copy the files and directories in the list in the | ||
1117 | new home. All modifications are discarded when the sandbox is | ||
1118 | closed. | ||
1119 | .br | ||
1120 | |||
1121 | .br | ||
1122 | Example: | ||
1123 | .br | ||
1124 | $ firejail \-\-private-home=.mozilla firefox | ||
1125 | |||
1126 | .TP | ||
1001 | \fB\-\-private-bin=file,file | 1127 | \fB\-\-private-bin=file,file |
1002 | Build a new /bin in a temporary filesystem, and copy the programs in the list. | 1128 | Build a new /bin in a temporary filesystem, and copy the programs in the list. |
1129 | 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. | 1130 | The same directory is also bind-mounted over /sbin, /usr/bin, /usr/sbin and /usr/local/bin. |
1131 | All modifications are discarded when the sandbox is closed. | ||
1004 | .br | 1132 | .br |
1005 | 1133 | ||
1006 | .br | 1134 | .br |
@@ -1018,7 +1146,7 @@ bash cat ls sed | |||
1018 | 1146 | ||
1019 | .TP | 1147 | .TP |
1020 | \fB\-\-private-dev | 1148 | \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. | 1149 | Create a new /dev directory. Only dri, null, full, zero, tty, pts, ptmx, random, snd, urandom, log and shm devices are available. |
1022 | .br | 1150 | .br |
1023 | 1151 | ||
1024 | .br | 1152 | .br |
@@ -1032,14 +1160,15 @@ Child process initialized | |||
1032 | .br | 1160 | .br |
1033 | $ ls /dev | 1161 | $ ls /dev |
1034 | .br | 1162 | .br |
1035 | dri full log null ptmx pts random shm tty urandom zero | 1163 | dri full log null ptmx pts random shm snd tty urandom zero |
1036 | .br | 1164 | .br |
1037 | $ | 1165 | $ |
1038 | .TP | 1166 | .TP |
1039 | \fB\-\-private-etc=file,directory | 1167 | \fB\-\-private-etc=file,directory |
1040 | Build a new /etc in a temporary | 1168 | Build a new /etc in a temporary |
1041 | filesystem, and copy the files and directories in the list. | 1169 | filesystem, and copy the files and directories in the list. |
1042 | All modifications are discarded when the sandbox is closed. | 1170 | If no listed file is found, /etc directory will be empty. |
1171 | All modifications are discarded when the sandbox is closed. | ||
1043 | .br | 1172 | .br |
1044 | 1173 | ||
1045 | .br | 1174 | .br |
@@ -1051,7 +1180,7 @@ nsswitch.conf,passwd,resolv.conf | |||
1051 | 1180 | ||
1052 | .TP | 1181 | .TP |
1053 | \fB\-\-private-tmp | 1182 | \fB\-\-private-tmp |
1054 | Mount an empty temporary filesystem on top of /tmp directory. | 1183 | Mount an empty temporary filesystem on top of /tmp directory whitelisting /tmp/.X11-unix. |
1055 | .br | 1184 | .br |
1056 | 1185 | ||
1057 | .br | 1186 | .br |
@@ -1120,6 +1249,9 @@ $ firejail \-\-protocol.print=3272 | |||
1120 | .br | 1249 | .br |
1121 | unix,inet,inet6,netlink | 1250 | unix,inet,inet6,netlink |
1122 | .TP | 1251 | .TP |
1252 | \fB\-\-put=name|pid src-filename dest-filename | ||
1253 | Put a file in sandbox container, see \fBFILE TRANSFER\fR section for more details. | ||
1254 | .TP | ||
1123 | \fB\-\-quiet | 1255 | \fB\-\-quiet |
1124 | Turn off Firejail's output. | 1256 | Turn off Firejail's output. |
1125 | .TP | 1257 | .TP |
@@ -1131,6 +1263,31 @@ Set directory or file read-only. | |||
1131 | Example: | 1263 | Example: |
1132 | .br | 1264 | .br |
1133 | $ firejail \-\-read-only=~/.mozilla firefox | 1265 | $ firejail \-\-read-only=~/.mozilla firefox |
1266 | .br | ||
1267 | |||
1268 | .br | ||
1269 | A short note about mixing \-\-whitelist and \-\-read-only options. Whitelisted directories | ||
1270 | should be made read-only independently. Making a parent directory read-only, will not | ||
1271 | make the whitelist read-only. Example: | ||
1272 | .br | ||
1273 | |||
1274 | .br | ||
1275 | $ firejail --whitelist=~/work --read-only=~ --read-only=~/work | ||
1276 | |||
1277 | .TP | ||
1278 | \fB\-\-read-write=dirname_or_filename | ||
1279 | Set directory or file read-write. Only files or directories belonging to the current user are allowed for | ||
1280 | this operation. Example: | ||
1281 | .br | ||
1282 | |||
1283 | .br | ||
1284 | $ mkdir ~/test | ||
1285 | .br | ||
1286 | $ touch ~/test/a | ||
1287 | .br | ||
1288 | $ firejail --read-only=~/test --read-write=~/test/a | ||
1289 | |||
1290 | |||
1134 | .TP | 1291 | .TP |
1135 | \fB\-\-rlimit-fsize=number | 1292 | \fB\-\-rlimit-fsize=number |
1136 | Set the maximum file size that can be created by a process. | 1293 | Set the maximum file size that can be created by a process. |
@@ -1143,6 +1300,17 @@ Set the maximum number of processes that can be created for the real user ID of | |||
1143 | .TP | 1300 | .TP |
1144 | \fB\-\-rlimit-sigpending=number | 1301 | \fB\-\-rlimit-sigpending=number |
1145 | Set the maximum number of pending signals for a process. | 1302 | Set the maximum number of pending signals for a process. |
1303 | |||
1304 | .TP | ||
1305 | \fB\-\-rmenv=name | ||
1306 | Remove environment variable in the new sandbox. | ||
1307 | .br | ||
1308 | |||
1309 | .br | ||
1310 | Example: | ||
1311 | .br | ||
1312 | $ firejail \-\-rmenv=DBUS_SESSION_BUS_ADDRESS | ||
1313 | |||
1146 | .TP | 1314 | .TP |
1147 | \fB\-\-scan | 1315 | \fB\-\-scan |
1148 | ARP-scan all the networks from inside a network namespace. | 1316 | ARP-scan all the networks from inside a network namespace. |
@@ -1156,13 +1324,13 @@ $ firejail \-\-net=eth0 \-\-scan | |||
1156 | .TP | 1324 | .TP |
1157 | \fB\-\-seccomp | 1325 | \fB\-\-seccomp |
1158 | Enable seccomp filter and blacklist the syscalls in the default list. The default list is as follows: | 1326 | 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, | 1327 | 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, | 1328 | 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, | 1329 | 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, | 1330 | add_key, request_key, keyctl, uselib, acct, modify_ldt, pivot_root, io_setup, |
1163 | io_destroy, io_getevents, io_submit, io_cancel, | 1331 | io_destroy, io_getevents, io_submit, io_cancel, |
1164 | remap_file_pages, mbind, get_mempolicy, set_mempolicy, | 1332 | remap_file_pages, mbind, get_mempolicy, set_mempolicy, |
1165 | migrate_pages, move_pages, vmsplice, perf_event_open, chroot, | 1333 | migrate_pages, move_pages, vmsplice, chroot, |
1166 | tuxcall, reboot, mfsservctl and get_kernel_syms. | 1334 | tuxcall, reboot, mfsservctl and get_kernel_syms. |
1167 | .br | 1335 | .br |
1168 | 1336 | ||
@@ -1425,15 +1593,7 @@ $ firejail \-\-tree | |||
1425 | 11969:netblue:firejail \-\-net=eth0 transmission-gtk | 1593 | 11969:netblue:firejail \-\-net=eth0 transmission-gtk |
1426 | .br | 1594 | .br |
1427 | 11970:netblue:transmission-gtk | 1595 | 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 | 1596 | ||
1433 | .br | ||
1434 | Example: | ||
1435 | .br | ||
1436 | # firejail \-\-user=www-data | ||
1437 | .TP | 1597 | .TP |
1438 | \fB\-\-version | 1598 | \fB\-\-version |
1439 | Print program version and exit. | 1599 | Print program version and exit. |
@@ -1445,66 +1605,106 @@ Example: | |||
1445 | $ firejail \-\-version | 1605 | $ firejail \-\-version |
1446 | .br | 1606 | .br |
1447 | firejail version 0.9.27 | 1607 | firejail version 0.9.27 |
1608 | |||
1609 | .TP | ||
1610 | \fB\-\-veth-name=name | ||
1611 | Use this name for the interface connected to the bridge for --net=bridge_interface commands, | ||
1612 | instead of the default one. | ||
1613 | .br | ||
1614 | |||
1615 | .br | ||
1616 | Example: | ||
1617 | .br | ||
1618 | $ firejail \-\-net=br0 --veth-name=if0 | ||
1619 | |||
1448 | .TP | 1620 | .TP |
1449 | \fB\-\-whitelist=dirname_or_filename | 1621 | \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. | 1622 | 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 | 1623 | whitelisted files are mount-binded inside. Modifications to whitelisted files are persistent, |
1452 | (home user, /media, /var etc.) | 1624 | everything else is discarded when the sandbox is closed. The top directory could be |
1625 | user home, /dev, /media, /mnt, /opt, /srv, /var, and /tmp. | ||
1626 | .br | ||
1627 | |||
1628 | .br | ||
1629 | Symbolic link handling: with the exception of user home, both the link and the real file should be in | ||
1630 | the same top directory. For user home, both the link and the real file should be owned by the user. | ||
1453 | .br | 1631 | .br |
1454 | 1632 | ||
1455 | .br | 1633 | .br |
1456 | Example: | 1634 | Example: |
1457 | .br | 1635 | .br |
1458 | $ firejail \-\-whitelist=~/.mozilla \-\-whitelist=~/Downloads | 1636 | $ firejail \-\-noprofile \-\-whitelist=~/.mozilla |
1459 | .br | 1637 | .br |
1460 | $ firejail \-\-whitelist=/tmp/.X11-unix --whitelist=/dev/null | 1638 | $ firejail \-\-whitelist=/tmp/.X11-unix --whitelist=/dev/null |
1461 | .br | 1639 | .br |
1462 | $ firejail "\-\-whitelist=/home/username/My Virtual Machines" | 1640 | $ firejail "\-\-whitelist=/home/username/My Virtual Machines" |
1463 | 1641 | ||
1464 | .TP | 1642 | .TP |
1465 | \fB\-\-x11 | 1643 | \fB\-\-writable-etc |
1466 | Start a new X11 server using Xpra or Xephyr and attach the sandbox to this server. | 1644 | 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 | 1645 | .br |
1471 | 1646 | ||
1472 | .br | 1647 | .br |
1473 | Firejail will try first Xpra, and if Xpra is not installed on the system, it will try to find Xephyr. | 1648 | Example: |
1474 | This feature is not available when running as root. | 1649 | .br |
1650 | $ sudo firejail --writable-etc | ||
1651 | |||
1652 | .TP | ||
1653 | \fB\-\-writable-var | ||
1654 | Mount /var directory read-write. | ||
1475 | .br | 1655 | .br |
1476 | 1656 | ||
1477 | .br | 1657 | .br |
1478 | Example: | 1658 | Example: |
1479 | .br | 1659 | .br |
1480 | $ firejail \-\-x11 --net=eth0 firefox | 1660 | $ sudo firejail --writable-var |
1661 | |||
1481 | 1662 | ||
1482 | .TP | 1663 | .TP |
1483 | \fB\-\-x11=xpra | 1664 | \fB\-\-x11 |
1484 | Start a new X11 server using Xpra (http://xpra.org) and attach the sandbox to this server. | 1665 | 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. | 1666 | 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. | 1667 | clients running outside the sandbox. |
1487 | This feature is not available when running as root. | 1668 | Firejail will try first Xpra, and if Xpra is not installed on the system, it will try to find Xephyr. |
1669 | If all fails, Firejail will not attempt to use X11 security extension. | ||
1670 | .br | ||
1671 | |||
1672 | .br | ||
1673 | Xpra and Xephyr modes require a network namespace to be instantiated in order to disable | ||
1674 | X11 abstract Unix socket. If this is not possible, the user can disable the abstract socket | ||
1675 | by adding "-nolisten local" on Xorg command line. | ||
1488 | .br | 1676 | .br |
1489 | 1677 | ||
1490 | .br | 1678 | .br |
1491 | Example: | 1679 | Example: |
1492 | .br | 1680 | .br |
1493 | $ firejail \-\-x11=xpra --net=eth0 firefox | 1681 | $ firejail \-\-x11 --net=eth0 firefox |
1682 | |||
1683 | .TP | ||
1684 | \fB\-\-x11=none | ||
1685 | Blacklist /tmp/.X11-unix directory, ${HOME}/.Xauthority and the file specified in ${XAUTHORITY} environment variable. | ||
1686 | Remove DISPLAY and XAUTHORITY environment variables. | ||
1687 | Stop with error message if X11 abstract socket will be accessible in jail. | ||
1494 | 1688 | ||
1495 | .TP | 1689 | .TP |
1496 | \fB\-\-x11=xephyr | 1690 | \fB\-\-x11=xephyr |
1497 | Start a new X11 server using Xephyr and attach the sandbox to this server. | 1691 | Start Xephyr and attach the sandbox to this server. |
1498 | Xephyr is a display server implementing the X11 display server protocol. | 1692 | 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. | 1693 | 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, | 1694 | .br |
1501 | see \fBman 5 firejail-config\fR for more details. | 1695 | |
1696 | .br | ||
1697 | Xephyr runs in a window just like any other X11 application. The default window size is 800x600. | ||
1698 | This can be modified in /etc/firejail/firejail.config file. | ||
1502 | .br | 1699 | .br |
1503 | 1700 | ||
1504 | .br | 1701 | .br |
1505 | The recommended way to use this feature is to run a window manager inside the sandbox. | 1702 | The recommended way to use this feature is to run a window manager inside the sandbox. |
1506 | A security profile for OpenBox is provided. | 1703 | A security profile for OpenBox is provided. |
1507 | On Debian platforms Xephyr is installed with the command \fBsudo apt-get install xserver-xephyr\fR. | 1704 | .br |
1705 | |||
1706 | .br | ||
1707 | 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. | 1708 | This feature is not available when running as root. |
1509 | .br | 1709 | .br |
1510 | 1710 | ||
@@ -1514,6 +1714,42 @@ Example: | |||
1514 | $ firejail \-\-x11=xephyr --net=eth0 openbox | 1714 | $ firejail \-\-x11=xephyr --net=eth0 openbox |
1515 | 1715 | ||
1516 | .TP | 1716 | .TP |
1717 | \fB\-\-x11=xorg | ||
1718 | Sandbox the application using the untrusted mode implemented by X11 security extension. | ||
1719 | The extension is available in Xorg package | ||
1720 | and it is installed by default on most Linux distributions. It provides support for a simple trusted/untrusted | ||
1721 | connection model. Untrusted clients are restricted in certain ways to prevent them from reading window | ||
1722 | contents of other clients, stealing input events, etc. | ||
1723 | |||
1724 | The untrusted mode has several limitations. A lot of regular programs assume they are a trusted X11 clients | ||
1725 | and will crash or lock up when run in untrusted mode. Chromium browser and xterm are two examples. | ||
1726 | Firefox and transmission-gtk seem to be working fine. | ||
1727 | A network namespace is not required for this option. | ||
1728 | .br | ||
1729 | |||
1730 | .br | ||
1731 | Example: | ||
1732 | .br | ||
1733 | $ firejail \-\-x11=xorg firefox | ||
1734 | |||
1735 | .TP | ||
1736 | \fB\-\-x11=xpra | ||
1737 | Start Xpra (http://xpra.org) and attach the sandbox to this server. | ||
1738 | Xpra is a persistent remote display server and client for forwarding X11 applications and desktop screens. | ||
1739 | A network namespace needs to be instantiated in order to deny access to X11 abstract Unix domain socket. | ||
1740 | .br | ||
1741 | |||
1742 | .br | ||
1743 | On Debian platforms Xpra is installed with the command \fBsudo apt-get install xpra\fR. | ||
1744 | This feature is not available when running as root. | ||
1745 | .br | ||
1746 | |||
1747 | .br | ||
1748 | Example: | ||
1749 | .br | ||
1750 | $ firejail \-\-x11=xpra --net=eth0 firefox | ||
1751 | |||
1752 | .TP | ||
1517 | \fB\-\-zsh | 1753 | \fB\-\-zsh |
1518 | Use /usr/bin/zsh as default user shell. | 1754 | Use /usr/bin/zsh as default user shell. |
1519 | .br | 1755 | .br |
@@ -1576,6 +1812,44 @@ $ firejail --tree | |||
1576 | 1221:netblue:/usr/lib/firefox/firefox | 1812 | 1221:netblue:/usr/lib/firefox/firefox |
1577 | .RE | 1813 | .RE |
1578 | 1814 | ||
1815 | .SH APPARMOR | ||
1816 | .TP | ||
1817 | AppArmor support is disabled by default at compile time. Use --enable-apparmor configuration option to enable it: | ||
1818 | .br | ||
1819 | |||
1820 | .br | ||
1821 | $ ./configure --prefix=/usr --enable-apparmor | ||
1822 | .TP | ||
1823 | 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: | ||
1824 | .br | ||
1825 | |||
1826 | .br | ||
1827 | # aa-enforce firejail-default | ||
1828 | .TP | ||
1829 | The installed profile tries to replicate some advanced security features inspired by kernel-based Grsecurity: | ||
1830 | .br | ||
1831 | |||
1832 | .br | ||
1833 | - Prevent information leakage in /proc and /sys directories. The resulting filesystem is barely enough for running | ||
1834 | commands such as "top" and "ps aux". | ||
1835 | .br | ||
1836 | |||
1837 | .br | ||
1838 | - Allow running programs only from well-known system paths, such as /bin, /sbin, /usr/bin etc. Running | ||
1839 | programs and scripts from user home or other directories writable by the user is not allowed. | ||
1840 | .br | ||
1841 | |||
1842 | .br | ||
1843 | - Disable D-Bus. D-Bus has long been a huge security hole, and most programs don't use it anyway. | ||
1844 | You should have no problems running Chromium or Firefox. | ||
1845 | |||
1846 | .TP | ||
1847 | 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: | ||
1848 | .br | ||
1849 | |||
1850 | .br | ||
1851 | $ firejail --apparmor firefox | ||
1852 | |||
1579 | .SH FILE TRANSFER | 1853 | .SH FILE TRANSFER |
1580 | These features allow the user to inspect the filesystem container of an existing sandbox | 1854 | 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. | 1855 | and transfer files from the container to the host filesystem. |
@@ -1583,12 +1857,16 @@ and transfer files from the container to the host filesystem. | |||
1583 | .TP | 1857 | .TP |
1584 | \fB\-\-get=name|pid filename | 1858 | \fB\-\-get=name|pid filename |
1585 | Retrieve the container file and store it on the host in the current working directory. | 1859 | 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. | 1860 | The container is specified by name or PID. |
1587 | 1861 | ||
1588 | .TP | 1862 | .TP |
1589 | \fB\-\-ls=name|pid dir_or_filename | 1863 | \fB\-\-ls=name|pid dir_or_filename |
1590 | List container files. The container is specified by name or PID. | 1864 | List container files. The container is specified by name or PID. |
1591 | Full path is needed for dir_or_filename. | 1865 | |
1866 | .TP | ||
1867 | \fB\-\-put=name|pid src-filename dest-filename | ||
1868 | Put src-filename in sandbox container. | ||
1869 | The container is specified by name or PID. | ||
1592 | 1870 | ||
1593 | .TP | 1871 | .TP |
1594 | Examples: | 1872 | Examples: |
@@ -1614,7 +1892,11 @@ drwxr-xr-x netblue netblue 4096 .. | |||
1614 | 1892 | ||
1615 | .br | 1893 | .br |
1616 | $ firejail \-\-get=mybrowser ~/Downloads/xpra-clipboard.png | 1894 | $ firejail \-\-get=mybrowser ~/Downloads/xpra-clipboard.png |
1895 | .br | ||
1617 | 1896 | ||
1897 | .br | ||
1898 | $ firejail \-\-put=mybrowser xpra-clipboard.png ~/Downloads/xpra-clipboard.png | ||
1899 | .br | ||
1618 | 1900 | ||
1619 | .SH TRAFFIC SHAPING | 1901 | .SH TRAFFIC SHAPING |
1620 | Network bandwidth is an expensive resource shared among all sandboxes running on a system. | 1902 | Network bandwidth is an expensive resource shared among all sandboxes running on a system. |
@@ -1626,15 +1908,15 @@ The shaper works at sandbox level, and can be used only for sandboxes configured | |||
1626 | 1908 | ||
1627 | Set rate-limits: | 1909 | Set rate-limits: |
1628 | 1910 | ||
1629 | firejail --bandwidth=name|pid set network download upload | 1911 | $ firejail --bandwidth=name|pid set network download upload |
1630 | 1912 | ||
1631 | Clear rate-limits: | 1913 | Clear rate-limits: |
1632 | 1914 | ||
1633 | firejail --bandwidth=name|pid clear network | 1915 | $ firejail --bandwidth=name|pid clear network |
1634 | 1916 | ||
1635 | Status: | 1917 | Status: |
1636 | 1918 | ||
1637 | firejail --bandwidth=name|pid status | 1919 | $ firejail --bandwidth=name|pid status |
1638 | 1920 | ||
1639 | where: | 1921 | where: |
1640 | .br | 1922 | .br |
@@ -1658,6 +1940,26 @@ Example: | |||
1658 | .br | 1940 | .br |
1659 | $ firejail \-\-bandwidth=mybrowser clear eth0 | 1941 | $ firejail \-\-bandwidth=mybrowser clear eth0 |
1660 | 1942 | ||
1943 | .SH AUDIT | ||
1944 | Audit feature allows the user to point out gaps in security profiles. The | ||
1945 | implementation replaces the program to be sandboxed with a test program. By | ||
1946 | default, we use faudit program distributed with Firejail. A custom test program | ||
1947 | can also be supplied by the user. Examples: | ||
1948 | |||
1949 | Running the default audit program: | ||
1950 | .br | ||
1951 | $ firejail --audit transmission-gtk | ||
1952 | |||
1953 | Running a custom audit program: | ||
1954 | .br | ||
1955 | $ firejail --audit=~/sandbox-test transmission-gtk | ||
1956 | |||
1957 | In the examples above, the sandbox configures transmission-gtk profile and | ||
1958 | starts the test program. The real program, transmission-gtk, will not be | ||
1959 | started. | ||
1960 | |||
1961 | Limitations: audit feature is not implemented for --x11 commands. | ||
1962 | |||
1661 | .SH MONITORING | 1963 | .SH MONITORING |
1662 | Option \-\-list prints a list of all sandboxes. The format | 1964 | Option \-\-list prints a list of all sandboxes. The format |
1663 | for each process entry is as follows: | 1965 | for each process entry is as follows: |
@@ -1751,7 +2053,7 @@ To disable default profile loading, use --noprofile command option. Example: | |||
1751 | .RS | 2053 | .RS |
1752 | $ firejail | 2054 | $ firejail |
1753 | .br | 2055 | .br |
1754 | Reading profile /etc/firejail/generic.profile | 2056 | Reading profile /etc/firejail/default.profile |
1755 | .br | 2057 | .br |
1756 | Parent pid 8553, child pid 8554 | 2058 | Parent pid 8553, child pid 8554 |
1757 | .br | 2059 | .br |
@@ -1818,7 +2120,6 @@ Homepage: http://firejail.wordpress.com | |||
1818 | \&\flfirecfg\fR\|(1), | 2120 | \&\flfirecfg\fR\|(1), |
1819 | \&\flfirejail-profile\fR\|(5), | 2121 | \&\flfirejail-profile\fR\|(5), |
1820 | \&\flfirejail-login\fR\|(5) | 2122 | \&\flfirejail-login\fR\|(5) |
1821 | \&\flfirejail-config\fR\|(5) | ||
1822 | 2123 | ||
1823 | 2124 | ||
1824 | 2125 | ||