aboutsummaryrefslogtreecommitdiffstats
path: root/src/firejail/usage.c
diff options
context:
space:
mode:
Diffstat (limited to 'src/firejail/usage.c')
-rw-r--r--src/firejail/usage.c312
1 files changed, 312 insertions, 0 deletions
diff --git a/src/firejail/usage.c b/src/firejail/usage.c
new file mode 100644
index 000000000..71ae203ff
--- /dev/null
+++ b/src/firejail/usage.c
@@ -0,0 +1,312 @@
1/*
2 * Copyright (C) 2014, 2015 netblue30 (netblue30@yahoo.com)
3 *
4 * This file is part of firejail project
5 *
6 * This program is free software; you can redistribute it and/or modify
7 * it under the terms of the GNU General Public License as published by
8 * the Free Software Foundation; either version 2 of the License, or
9 * (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License along
17 * with this program; if not, write to the Free Software Foundation, Inc.,
18 * 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.
19*/
20#include "firejail.h"
21
22void usage(void) {
23 printf("firejail - version %s\n\n", VERSION);
24 printf("Firejail is a SUID sandbox program that reduces the risk of security breaches by\n");
25 printf("restricting the running environment of untrusted applications using Linux\n");
26 printf("namespaces. It includes a sandbox profile for Mozilla Firefox.\n\n");
27 printf("\n");
28 printf("Usage: firejail [options] [program and arguments]\n\n");
29 printf("\n");
30 printf("Without any options, the sandbox consists of a filesystem chroot build from the\n");
31 printf("current system directories mounted read-only, and new PID and IPC\n");
32 printf("namespaces. If no program is specified as an argument, /bin/bash is started by\n");
33 printf("default in the sandbox.\n\n");
34 printf("\n");
35 printf("Options:\n\n");
36 printf("\t-- - signal the end of options and disables further option processing.\n\n");
37 printf("\t--bandwidth=name - set bandwidth limits for the sandbox identified\n");
38 printf("\t\tby name, see Traffic Shaping section for more details.\n\n");
39 printf("\t--bandwidth=pid - set bandwidth limits for the sandbox identified\n");
40 printf("\t\tby PID, see Traffic Shaping section for more details.\n\n");
41#ifdef HAVE_BIND
42 printf("\t--bind=dirname1,dirname2 - mount-bind dirname1 on top of dirname2.\n\n");
43 printf("\t--bind=filename1,dirname2 - mount-bind filename1 on top of filename2.\n\n");
44#endif
45 printf("\t--blacklist=dirname_or_filename - blacklist directory or file.\n\n");
46 printf("\t-c - execute command and exit.\n\n");
47 printf("\t--caps - enable default Linux capabilities filter. The filter disables\n");
48 printf("\t\tCAP_SYS_MODULE, CAP_SYS_RAWIO, CAP_SYS_BOOT, CAP_SYS_NICE,\n");
49 printf("\t\tCAP_SYS_TTY_CONFIG, CAP_SYSLOG, CAP_MKNOD, CAP_SYS_ADMIN.\n\n");
50 printf("\t--caps.drop=all - drop all capabilities.\n\n");
51 printf("\t--caps.drop=capability,capability,capability - blacklist Linux\n");
52 printf("\t\tcapabilities filter.\n\n");
53 printf("\t--caps.keep=capability,capability,capability - whitelist Linux\n");
54 printf("\t\tcapabilities filter.\n\n");
55 printf("\t--caps.print=name - print the caps filter for the sandbox identified\n");
56 printf("\t\tby name.\n\n");
57 printf("\t--caps.print=pid - print the caps filter for the sandbox identified\n");
58 printf("\t\tby PID.\n\n");
59 printf("\t--cgroup=tasks-file - place the sandbox in the specified control group.\n");
60 printf("\t\ttasks-file is the full path of cgroup tasks file.\n");
61 printf("\t\tExample: --cgroup=/sys/fs/cgroup/g1/tasks\n\n");
62#ifdef HAVE_CHROOT
63 printf("\t--chroot=dirname - chroot into dirname directory.\n\n");
64#endif
65 printf("\t--cpu=cpu-number,cpu-number - set cpu affinity.\n");
66 printf("\t\tExample: cpu=0,1,2\n\n");
67 printf("\t--csh - use /bin/csh as default shell.\n\n");
68 printf("\t--debug - print sandbox debug messages.\n\n");
69 printf("\t--debug-syscalls - print all recognized system calls in the current\n");
70 printf("\t\tFirejail software build and exit.\n\n");
71 printf("\t--debug-caps - print all recognized capabilities in the current\n");
72 printf("\t\tFirejail software build and exit.\n\n");
73 printf("\t--defaultgw=address - use this address as default gateway in the new\n");
74 printf("\t\tnetwork namespace.\n\n");
75 printf("\t--dns=address - set a DNS server for the sandbox. Up to three DNS\n");
76 printf("\t\tservers can be defined.\n\n");
77 printf("\t--dns.print=name - print DNS configuration for the sandbox identified\n");
78 printf("\t\tby name.\n\n");
79 printf("\t--dns.print=pid - print DNS configuration of the sandbox identified.\n");
80 printf("\t\tby PID.\n\n");
81 printf("\t--help, -? - this help screen.\n\n");
82 printf("\t--ip=address - set interface IP address.\n\n");
83 printf("\t--ip=none - no IP address and no default gateway address are configured\n");
84 printf("\t\tin the new network namespace. Use this option in case you intend\n");
85 printf("\t\tto start an external DHCP client in the sandbox.\n\n");
86 printf("\t--iprange=address,address - configure an IP address in this range\n\n");
87 printf("\t--ipc-namespace - enable a new IPC namespace if the sandbox was started\n");
88 printf("\t\tas a regular user. IPC namespace is enabled by default only if\n");
89 printf("\t\tthe sandbox is started as root.\n\n");
90 printf("\t--join=name - join the sandbox identified by name.\n\n");
91 printf("\t--join=pid - join the sandbox identified by PID.\n\n");
92 printf("\t--list - list all sandboxes.\n\n");
93 printf("\t--mac=xx:xx:xx:xx:xx:xx - set interface MAC address.\n\n");
94 printf("\t--name=name - set sandbox hostname.\n\n");
95 printf("\t--net=bridgename - enable network namespaces and connect to this bridge\n");
96 printf("\t\tdevice. Unless specified with option --ip and --defaultgw, an\n");
97 printf("\t\tIP address and a default gateway will be assigned automatically\n");
98 printf("\t\tto the sandbox. The IP address is checked using ARP before\n");
99 printf("\t\tassignment. The IP address assigned as default gateway is the\n");
100 printf("\t\tbridge device IP address. Up to four --net devices can\n");
101 printf("\t\tbe defined. Mixing bridge and macvlan devices is allowed.\n\n");
102 printf("\t--net=ethernet_interface - enable network namespaces and connect\n");
103 printf("\t\tto this ethernet_interface using the standard Linux macvlan\n");
104 printf("\t\tdriver. Unless specified with option --ip and --defaultgw, an\n");
105 printf("\t\tIP address and a default gateway will be assigned automatically\n");
106 printf("\t\tto the sandbox. The IP address is checked using ARP before\n");
107 printf("\t\tassignment. The IP address assigned as default gateway is the\n");
108 printf("\t\tdefault gateway of the host. Up to four --net devices can\n");
109 printf("\t\tbe defined. Mixing bridge and macvlan devices is allowed.\n\n");
110 printf("\t--net=none - enable a new, unconnected network namespace.\n\n");
111
112 printf("\t--netfilter - enable the default client network filter in the new\n");
113 printf("\t\tnetwork namespace:\n\n");
114 printf("\t\t*filter\n");
115 printf("\t\t:INPUT DROP [0:0]\n");
116 printf("\t\t:FORWARD DROP [0:0]\n");
117 printf("\t\t:OUTPUT ACCEPT [0:0]\n");
118 printf("\t\t-A INPUT -i lo -j ACCEPT\n");
119 printf("\t\t-A INPUT -m state --state RELATED,ESTABLISHED -j ACCEPT\n");
120 printf("\t\t-A INPUT -p icmp --icmp-type destination-unreachable -j ACCEPT\n");
121 printf("\t\t-A INPUT -p icmp --icmp-type time-exceeded -j ACCEPT\n");
122 printf("\t\t-A INPUT -p icmp --icmp-type echo-request -j ACCEPT \n");
123 printf("\t\tCOMMIT\n\n");
124 printf("\t--netfilter=filename - enable the network filter specified by\n");
125 printf("\t\tfilename in the new network namespace. The filter file format\n");
126 printf("\t\tis the format of iptables-save and iptable-restore commands.\n\n");
127
128 printf("\t--netstats - monitor network statistics for sandboxes creating a new\n");
129 printf("\t\tnetwork namespace.\n\n");
130 printf("\t--nogroups - disable supplementary groups. Without this option,\n");
131 printf("\t\tsupplementary groups are enabled for the user starting the\n");
132 printf("\t\tsandbox. For root user supplementary groups are always\n");
133 printf("\t\tdisabled.\n\n");
134
135 printf("\t--noroot - install a user namespace with a single user - the current\n");
136 printf("\t\tuser. root user does not exist in the new namespace. This option\n");
137 printf("\t\tis not supported for --chroot and --overlay configurations.\n\n");
138
139 printf("\t--output=logfile - stdout logging and log rotation. Copy stdout to\n");
140 printf("\t\tlogfile, and keep the size of the file under 500KB using log\n");
141 printf("\t\trotation. Five files with prefixes .1 to .5 are used in\n");
142 printf("\t\trotation.\n\n");
143 printf("\t--overlay - mount a filesystem overlay on top of the current filesystem.\n");
144 printf("\t\t(OverlayFS support is required in Linux kernel for this option\n");
145 printf("\t\tto work)\n\n");
146
147 printf("\t--private - mount new /root and /home/user directories in temporary\n");
148 printf("\t\tfilesystems. All modifications are discarded when the sandbox is\n");
149 printf("\t\tclosed.\n\n");
150 printf("\t--private=directory - use directory as user home.\n\n");
151 printf("\t--private.keep=file,directory - build a new user home in a temporary\n");
152 printf("\t\tfilesystem, and copy the files and directories in the list in\n");
153 printf("\t\tthe new home. All modifications are discarded when the sandbox\n");
154 printf("\t\tis closed.\n\n");
155 printf("\t--private-dev - create a new /dev directory. Only null, full, zero, tty,\n");
156 printf("\t\tpst, ptms, random, urandom and shm devices are available.\n\n");
157
158 printf("\t--profile=filename - use a custom profile.\n\n");
159 printf("\t--read-only=dirname_or_filename - set directory or file read-only.\n\n");
160 printf("\t--rlimit-fsize=number - set the maximum file size that can be created\n");
161 printf("\t\tby a process.\n\n");
162 printf("\t--rlimit-nofile=number - set the maximum number of files that can be\n");
163 printf("\t\topened by a process.\n\n");
164 printf("\t--rlimit-nproc=number - set the maximum number of processes that can be\n");
165 printf("\t\tcreated for the real user ID of the calling process.\n\n");
166 printf("\t--rlimit-sigpending=number - set the maximum number of pending signals\n");
167 printf("\t\tfor a process.\n\n");
168
169 printf("\t--scan - ARP-scan all the networks from inside a network namespace.\n");
170 printf("\t\tThis makes it possible to detect macvlan kernel device drivers\n");
171 printf("\t\trunning on the current host.\n\n");
172
173#ifdef HAVE_SECCOMP
174 printf("\t--seccomp - enable seccomp filter and blacklist the syscalls in the\n");
175 printf("\t\tlist. The default list is as follows: mount, umount2,\n");
176 printf("\t\tptrace, kexec_load, open_by_handle_at, init_module,\n");
177 printf("\t\tfinit_module, delete_module, iopl, ioperm, swapon, swapoff,\n");
178 printf("\t\tmknode, syslog, process_vm_readv and process_vm_writev\n");
179 printf("\t\tsysfs,_sysctl, adjtimex, clock_adjtime, lookup_dcookie,\n");
180 printf("\t\tperf_event_open, fanotify_init and kcmp.\n\n");
181
182 printf("\t--seccomp=syscall,syscall,syscall - enable seccomp filter, blacklist the\n");
183 printf("\t\tdefault syscall list and the syscalls specified by the command.\n\n");
184
185 printf("\t--seccomp.drop=syscall,syscall,syscall - enable seccomp filter, and\n");
186 printf("\t\tblacklist the syscalls specified by the command.\n\n");
187
188 printf("\t--seccomp.keep=syscall,syscall,syscall - enable seccomp filter, and\n");
189 printf("\t\twhitelist the syscalls specified by the command.\n\n");
190
191 printf("\t--seccomp.print=name - print the seccomp filter for the sandbox\n");
192 printf("\t\tidentified by name.\n\n");
193 printf("\t--seccomp.print=pid - print the seccomp filter for the sandbox\n");
194 printf("\t\tidentified by PID.\n\n");
195#endif
196
197 printf("\t--shell=none - run the program directly without a user shell.\n\n");
198 printf("\t--shell=program - set default user shell.\n\n");
199 printf("\t--shutdown=name - shutdown the sandbox identified by name.\n\n");
200 printf("\t--shutdown=pid - shutdown the sandbox identified by PID.\n\n");
201 printf("\t--tmpfs=dirname - mount a tmpfs filesystem on directory dirname.\n\n");
202 printf("\t--top - monitor the most CPU-intensive sandboxes.\n\n");
203 printf("\t--trace - trace open, access and connect system calls.\n\n");
204 printf("\t--tree - print a tree of all sandboxed processes.\n\n");
205 printf("\t--version - print program version and exit.\n\n");
206 printf("\t--zsh - use /usr/bin/zsh as default shell.\n\n");
207 printf("\n");
208 printf("\n");
209
210
211 printf("Traffic Shaping\n\n");
212
213 printf("Network bandwidth is an expensive resource shared among all sandboxes\n");
214 printf("running on a system. Traffic shaping allows the user to increase network\n");
215 printf("performance by controlling the amount of data that flows into and out of the\n");
216 printf("sandboxes. Firejail implements a simple rate-limiting shaper based on Linux\n");
217 printf("command tc. The shaper works at sandbox level, and can be used only for\n");
218 printf("sandboxes configured with new network namespaces.\n\n");
219
220 printf("Set rate-limits:\n");
221 printf("\tfirejail --bandwidth={name|pid} set network-name down-speed up-speed\n\n");
222 printf("Clear rate-limits:\n");
223 printf("\tfirejail --bandwidth={name|pid} clear network-name\n\n");
224 printf("Status:\n");
225 printf("\tfirejail --bandwidth={name|pid} status\n\n");
226 printf("where:\n");
227 printf("\tname - sandbox name\n");
228 printf("\tpid - sandbox pid\n");
229 printf("\tnetwork-name - network name as used by --net option\n");
230 printf("\tdown-speed - download speed in KB/s (decimal kilobyte per second)\n");
231 printf("\tup-speed - upload speed in KB/s (decimal kilobyte per second)\n");
232 printf("\n");
233 printf("Example:\n");
234 printf("\t$ firejail --name=mybrowser --net=eth0 firefox &\n");
235 printf("\t$ firejail --bandwidth=mybrowser set eth0 80 20\n");
236 printf("\t$ firejail --bandwidth=mybrowser status\n");
237 printf("\t$ firejail --bandwidth=mybrowser clear eth0\n");
238 printf("\n");
239 printf("\n");
240
241
242
243 printf("Monitoring\n\n");
244
245 printf("Option --list prints a list of all sandboxes. The format for each entry is as\n");
246 printf("follows:\n\n");
247 printf("\tPID:USER:Command\n\n");
248
249 printf("Option --tree prints the tree of processes running in the sandbox. The format\n");
250 printf("for each process entry is as follows:\n\n");
251 printf("\tPID:USER:Command\n\n");
252
253 printf("Option --top is similar to the UNIX top command, however it applies only to\n");
254 printf("sandboxes. Listed below are the available fields (columns) in alphabetical\n");
255 printf("order:\n\n");
256 printf("\tCommand - command used to start the sandbox.\n");
257 printf("\tCPU%% - CPU usage, the sandbox share of the elapsed CPU time since the\n");
258 printf("\t last screen update\n");
259 printf("\tPID - Unique process ID for the task controlling the sandbox.\n");
260 printf("\tPrcs - number of processes running in sandbox, including the controlling\n");
261 printf("\t process.\n");
262 printf("\tRES - Resident Memory Size (KiB), sandbox non-swapped physical memory.\n");
263 printf("\t It is a sum of the RES values for all processes running in the\n");
264 printf("\t sandbox.\n");
265 printf("\tSHR - Shared Memory Size (KiB), it reflects memory shared with other\n");
266 printf("\t processes. It is a sum of the SHR values for all processes running\n");
267 printf("\t in the sandbox, including the controlling process.\n");
268 printf("\tUptime - sandbox running time in hours:minutes:seconds format.\n");
269 printf("\tUser - The owner of the sandbox.\n");
270 printf("\n");
271 printf("\n");
272 printf("Profile files\n\n");
273 printf("Several command line configuration options can be passed to the program using\n");
274 printf("profile files. Default Firejail profile files are stored in /etc/firejail\n");
275 printf("directory, user profile files are stored in ~/.config/firejail directory. See\n");
276 printf("man 5 firejail-profile for more information.\n\n");
277 printf("\n");
278 printf("Restricted shell\n\n");
279 printf("To configure a restricted shell, replace /bin/bash with /usr/bin/firejail i\n");
280 printf("/etc/password file for each user that needs to be restricted.\n");
281 printf("Alternatively, you can specify /usr/bin/firejail in adduser command:\n\n");
282 printf(" adduser --shell /usr/bin/firejail username\n\n");
283 printf("Arguments to be passed to firejail executable upon login are declared in\n");
284 printf("/etc/firejail/login.users file.\n\n");
285 printf("\n");
286 printf("Examples:\n\n");
287 printf(" $ firejail\n");
288 printf(" start a regular /bin/bash session in sandbox\n");
289 printf(" $ firejail firefox\n");
290 printf(" start Mozilla Firefox\n");
291 printf(" $ firejail --seccomp firefox\n");
292 printf(" start Mozilla Firefox in a seccomp sandbox\n");
293 printf(" $ firejail --caps firefox\n");
294 printf(" start Mozilla Firefox in a Linux capabilities sandbox\n");
295 printf(" $ firejail --debug firefox\n");
296 printf(" debug Firefox sandbox\n");
297 printf(" $ firejail --private\n");
298 printf(" start a /bin/bash session with a new tmpfs home directory\n");
299 printf(" $ firejail --net=br0 ip=10.10.20.10\n");
300 printf(" start a /bin/bash session in a new network namespace; the session is\n");
301 printf(" connected to the main network using br0 bridge device, an IP address\n");
302 printf(" of 10.10.20.10 is assigned to the sandbox\n");
303 printf(" $ firejail --net=br0 --net=br1 --net=br2\n");
304 printf(" start a /bin/bash session in a new network namespace and connect it\n");
305 printf(" to br0, br1, and br2 host bridge devices\n");
306 printf(" $ firejail --list\n");
307 printf(" list all running sandboxes\n");
308 printf("\n");
309 printf("License GPL version 2 or later\n");
310 printf("Homepage: http://firejail.sourceforge.net\n");
311 printf("\n");
312}
generated by cgit v1.2.3-54-g00ecf (git 2.45.2) at 2024-07-05 13:53:15 +0000