aboutsummaryrefslogtreecommitdiffstats
path: root/README.md
diff options
context:
space:
mode:
Diffstat (limited to 'README.md')
-rw-r--r--README.md263
1 files changed, 35 insertions, 228 deletions
diff --git a/README.md b/README.md
index 7f6f573b4..609533a91 100644
--- a/README.md
+++ b/README.md
@@ -31,255 +31,62 @@ Features: https://firejail.wordpress.com/features-3/
31Documentation: https://firejail.wordpress.com/documentation-2/ 31Documentation: https://firejail.wordpress.com/documentation-2/
32 32
33FAQ: https://firejail.wordpress.com/support/frequently-asked-questions/ 33FAQ: https://firejail.wordpress.com/support/frequently-asked-questions/
34`````
35
36`````
37# Current development version: 0.9.40-rc2
38Version 0.9.40-rc1 released!
39
40## X11 sandboxing support
41
42X11 support is built around Xpra (http://xpra.org/) or Xephyr.
43`````
44 --x11 Start a new X11 server using Xpra or Xephyr and attach the sand‐
45 box to this server. The regular X11 server (display 0) is not
46 visible in the sandbox. This prevents screenshot and keylogger
47 applications started in the sandbox from accessing other X11
48 displays. A network namespace needs to be instantiated in order
49 to deny access to X11 abstract Unix domain socket.
50
51 Firejail will try first Xpra, and if Xpra is not installed on
52 the system, it will try to find Xephyr. This feature is not
53 available when running as root.
54
55 Example:
56 $ firejail --x11 --net=eth0 firefox
57
58 --x11=xpra
59 Start a new X11 server using Xpra (http://xpra.org) and attach
60 the sandbox to this server. Xpra is a persistent remote display
61 server and client for forwarding X11 applications and desktop
62 screens. On Debian platforms Xpra is installed with the command
63 sudo apt-get install xpra. This feature is not available when
64 running as root.
65
66 Example:
67 $ firejail --x11 --net=eth0 firefox
68
69 --x11=xephyr
70 Start a new X11 server using Xephyr and attach the sandbox to
71 this server. Xephyr is a display server implementing the X11
72 display server protocol. It runs in a window just like other X
73 applications, but it is an X server itself in which you can run
74 other software. The default Xephyr window size is 800x600. This
75 can be modified in /etc/firejail/firejail.config file, see man 5
76 firejail-config for more details.
77
78 The recommended way to use this feature is to run a window man‐
79 ager inside the sandbox. A security profile for OpenBox is pro‐
80 vided. On Debian platforms Xephyr is installed with the command
81 sudo apt-get install xserver-xephyr. This feature is not avail‐
82 able when running as root.
83 34
84 Example:
85 $ firejail --x11 --net=eth0 openbox
86`````
87More information here: https://firejail.wordpress.com/documentation-2/x11-guide/
88
89## File transfers
90`````
91FILE TRANSFER
92 These features allow the user to inspect the filesystem container of an
93 existing sandbox and transfer files from the container to the host
94 filesystem.
95
96 --get=name filename
97 Retrieve the container file and store it on the host in the cur‐
98 rent working directory. The container is specified by name
99 (--name option). Full path is needed for filename.
100
101 --get=pid filename
102 Retrieve the container file and store it on the host in the cur‐
103 rent working directory. The container is specified by process
104 ID. Full path is needed for filename.
105
106 --ls=name dir_or_filename
107 List container files. The container is specified by name
108 (--name option). Full path is needed for dir_or_filename.
109
110 --ls=pid dir_or_filename
111 List container files. The container is specified by process ID.
112 Full path is needed for dir_or_filename.
113
114 Examples:
115
116 $ firejail --name=mybrowser --private firefox
117
118 $ firejail --ls=mybrowser ~/Downloads
119 drwxr-xr-x netblue netblue 4096 .
120 drwxr-xr-x netblue netblue 4096 ..
121 -rw-r--r-- netblue netblue 7847 x11-x305.png
122 -rw-r--r-- netblue netblue 6800 x11-x642.png
123 -rw-r--r-- netblue netblue 34139 xpra-clipboard.png
124
125 $ firejail --get=mybrowser ~/Downloads/xpra-clipboard.png
126````` 35`````
127 36
128## Firecfg
129````` 37`````
130NAME 38## User submitted profile repositories
131 Firecfg - Desktop configuration program for Firejail software.
132
133SYNOPSIS
134 firecfg [OPTIONS]
135
136DESCRIPTION
137 Firecfg is the desktop configuration utility for Firejail software. The
138 utility creates several symbolic links to firejail executable. This
139 allows the user to sandbox applications automatically, just by clicking
140 on a regular desktop menus and icons.
141 39
142 The symbolic links are placed in /usr/local/bin. For more information, 40If you keep your Firejail profiles in a public repository, please give us a link:
143 see DESKTOP INTEGRATION section in man 1 firejail.
144 41
145OPTIONS 42* https://github.com/chiraag-nataraj/firejail-profiles
146 --clear
147 Clear all firejail symbolic links
148 43
149 -?, --help 44* https://github.com/triceratops1/fe
150 Print options end exit.
151 45
152 --list List all firejail symbolic links 46Use this issue to request new profiles: https://github.com/netblue30/firejail/issues/825
153
154 --version
155 Print program version and exit.
156
157 Example:
158
159 $ sudo firecfg
160 /usr/local/bin/firefox created
161 /usr/local/bin/vlc created
162 [...]
163 $ firecfg --list
164 /usr/local/bin/firefox
165 /usr/local/bin/vlc
166 [...]
167 $ sudo firecfg --clear
168 /usr/local/bin/firefox removed
169 /usr/local/bin/vlc removed
170 [...]
171````` 47`````
172 48
173
174## Compile time and run time configuration support
175
176Most Linux kernel security features require root privileges during configuration.
177The same is true for kernel networking features. Firejail (SUID binary) opens the
178access to these features to regular users. The privilege escalation is restricted
179to the sandbox being configured, and is not extended to the rest of the system.
180This arrangement works fine for user desktops or servers where the access is already limited.
181
182If you not happy with a particular feature, all the support can be eliminated from SUID binary at compile time,
183or at run time by editing /etc/firejail/firejail.config file.
184
185The following features can be enabled or disabled:
186````` 49`````
187 bind Enable or disable bind support, default enabled. 50# Current development version: 0.9.45
188
189 chroot Enable or disable chroot support, default enabled.
190
191 file-transfer
192 Enable or disable file transfer support, default enabled.
193
194 network
195 Enable or disable networking features, default enabled.
196
197 restricted-network
198 Enable or disable restricted network support, default disabled.
199 If enabled, networking features should also be enabled (network
200 yes). Restricted networking grants access to --interface and
201 --net=ethXXX only to root user. Regular users are only allowed
202 --net=none.
203
204 secomp Enable or disable seccomp support, default enabled.
205
206 userns Enable or disable user namespace support, default enabled.
207
208 x11 Enable or disable X11 sandboxing support, default enabled.
209
210 xephyr-screen
211 Screen size for --x11=xephyr, default 800x600. Run
212 /usr/bin/xrandr for a full list of resolutions available on your
213 specific setup. Examples:
214
215 xephyr-screen 640x480
216 xephyr-screen 800x600
217 xephyr-screen 1024x768
218 xephyr-screen 1280x1024
219````` 51`````
220 52
221## Default seccomp filter update
222
223Currently 50 syscalls are blacklisted by default, out of a total of 318 calls (AMD64, Debian Jessie).
224
225## STUN/WebRTC disabled in default netfilter configuration
226
227The current netfilter configuration (--netfilter option) looks like this:
228````` 53`````
229 *filter 54## AppImage type 2 support
230 :INPUT DROP [0:0]
231 :FORWARD DROP [0:0]
232 :OUTPUT ACCEPT [0:0]
233 -A INPUT -i lo -j ACCEPT
234 -A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT
235 # allow ping
236 -A INPUT -p icmp --icmp-type destination-unreachable -j ACCEPT
237 -A INPUT -p icmp --icmp-type time-exceeded -j ACCEPT
238 -A INPUT -p icmp --icmp-type echo-request -j ACCEPT
239 # drop STUN (WebRTC) requests
240 -A OUTPUT -p udp --dport 3478 -j DROP
241 -A OUTPUT -p udp --dport 3479 -j DROP
242 -A OUTPUT -p tcp --dport 3478 -j DROP
243 -A OUTPUT -p tcp --dport 3479 -j DROP
244 COMMIT
245````` 55`````
246 56
247The filter is loaded by default for Firefox if a network namespace is configured:
248`````
249$ firejail --net=eth0 firefox
250````` 57`````
251 58## New command line options
252## Set sandbox nice value
253````` 59`````
254 --nice=value 60 --private-opt=file,directory
255 Set nice value for all processes running inside the sandbox. 61 Build a new /opt in a temporary filesystem, and copy the files
62 and directories in the list. If no listed file is found, /opt
63 directory will be empty. All modifications are discarded when
64 the sandbox is closed.
256 65
257 Example: 66 Example:
258 $ firejail --nice=-5 firefox 67 $ firejail --private-opt=firefox /opt/firefox/firefox
259`````
260
261## mkdir
262
263`````
264$ man firejail-profile
265[...]
266 mkdir directory
267 Create a directory in user home. Use this command for
268 whitelisted directories you need to preserve when the sandbox is
269 closed. Subdirectories also need to be created using mkdir.
270 Example from firefox profile:
271 68
272 mkdir ~/.mozilla 69 --private-srv=file,directory
273 whitelist ~/.mozilla 70 Build a new /srv in a temporary filesystem, and copy the files
274 mkdir ~/.cache 71 and directories in the list. If no listed file is found, /srv
275 mkdir ~/.cache/mozilla 72 directory will be empty. All modifications are discarded when
276 mkdir ~/.cache/mozilla/firefox 73 the sandbox is closed.
277 whitelist ~/.cache/mozilla/firefox
278 74
279[...] 75 Example:
280````` 76 # firejail --private-srv=www /etc/init.d/apache2 start
281 77
282## New security profiles 78 --machine-id
283lxterminal, Epiphany, cherrytree, Polari, Vivaldi, Atril, qutebrowser, SlimJet, Battle for Wesnoth, Hedgewars, qTox, 79 Preserve id number in /etc/machine-id file. By default a new
284OpenSSH client, OpenBox window manager, Dillo, cmus, dnsmasq, PaleMoon, Icedove, abrowser, 0ad 80 random id is generated inside the sandbox.
285 81
82 Example:
83 $ firejail --machine-id
84`````
85## New Profiles
86xiphos, Tor Browser Bundle, display (imagemagik), Wire, mumble, zoom, Guayadeque, qemu, keypass2,
87amarok, ark, atool, bleachbit, brasero, dolphin, dragon, elinks, enchant, exiftool, file-roller, gedit,
88gjs, gnome-books, gnome-clocks, gnome-documents, gnome-maps, gnome-music, gnome-photos, gnome-weather,
89goobox, gpa, gpg, gpg-agent, highlight, img2txt, k3b, kate, lynx, mediainfo, nautilus, odt2txt, pdftotext,
90simple-scan, skanlite, ssh-agent, tracker, transmission-cli, transmission-show, w3m, xfburn, xpra, wget,
91xed, pluma, Cryptocat, Bless, Gnome 2048, Gnome Calculator, Gnome Contacts, JD-GUI, Lollypop, MultiMC5,
92PDFSam, Pithos, Xonotic, wireshark
generated by cgit v1.2.3-70-g09d2 (git 2.46.0) at 2024-09-01 12:19:58 +0000