From dae5b5d0f0bc7b50ec7cb92729171fc257dec423 Mon Sep 17 00:00:00 2001 From: glitsj16 Date: Sun, 25 Aug 2024 19:39:29 +0000 Subject: [PATCH] docs: man: sort commands and sections Sort commands and sections in firejail.1.in and sync the result with firejail-profile.5.in. * Commands: `--dbus-system.*`, `--dbus-user.*`, `--icmptrace`, `--ip=none`, `memory-deny-write-execute`, `--noinput` * Sections: "LANDLOCK", "NAME VALIDATION" Relates to #3190 #3406 #4209 #5856 #6078. --- src/man/firejail-profile.5.in | 60 +++---- src/man/firejail.1.in | 286 +++++++++++++++++----------------- 2 files changed, 175 insertions(+), 171 deletions(-) diff --git a/src/man/firejail-profile.5.in b/src/man/firejail-profile.5.in index 89784a98478..4d725ed998e 100644 --- a/src/man/firejail-profile.5.in +++ b/src/man/firejail-profile.5.in @@ -668,20 +668,20 @@ Enable filtered access to the system DBus. Filters can be specified with the dbu \fBdbus-system none Disable access to the system DBus. Once access is disabled, it cannot be relaxed to filtering. .TP +\fBdbus-system.broadcast org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications +Allow the application to receive broadcast signals from the interface org.freedesktop.Notifications of the object exposed at the path /org/freedesktop/Notifications by the client owning the bus name org.freedesktop.Notifications on the system DBus. +.TP +\fBdbus-system.call org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications +Allow the application to call methods of the interface org.freedesktop.Notifications of the object exposed at the path /org/freedesktop/Notifications by the client owning the bus name org.freedesktop.Notifications on the system DBus. +.TP \fBdbus-system.own org.gnome.ghex.* Allow the application to own the name org.gnome.ghex and all names underneath in on the system DBus. .TP -\fBdbus-system.talk org.freedesktop.Notifications -Allow the application to talk to the name org.freedesktop.Notifications on the system DBus. -.TP \fBdbus-system.see org.freedesktop.Notifications Allow the application to see but not talk to the name org.freedesktop.Notifications on the system DBus. .TP -\fBdbus-system.call org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications -Allow the application to call methods of the interface org.freedesktop.Notifications of the object exposed at the path /org/freedesktop/Notifications by the client owning the bus name org.freedesktop.Notifications on the system DBus. -.TP -\fBdbus-system.broadcast org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications -Allow the application to receive broadcast signals from the interface org.freedesktop.Notifications of the object exposed at the path /org/freedesktop/Notifications by the client owning the bus name org.freedesktop.Notifications on the system DBus. +\fBdbus-system.talk org.freedesktop.Notifications +Allow the application to talk to the name org.freedesktop.Notifications on the system DBus. .TP \fBdbus-user filter Enable filtered access to the session DBus. Filters can be specified with the dbus-user.talk and dbus-user.own commands. @@ -689,20 +689,20 @@ Enable filtered access to the session DBus. Filters can be specified with the db \fBdbus-user none Disable access to the session DBus. Once access is disabled, it cannot be relaxed to filtering. .TP +\fBdbus-user.broadcast org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications +Allow the application to receive broadcast signals from the the interface org.freedesktop.Notifications of the object exposed at the path /org/freedesktop/Notifications by the client owning the bus name org.freedesktop.Notifications on the session DBus. +.TP +\fBdbus-user.call org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications +Allow the application to call methods of the interface org.freedesktop.Notifications of the object exposed at the path /org/freedesktop/Notifications by the client owning the bus name org.freedesktop.Notifications on the session DBus. +.TP \fBdbus-user.own org.gnome.ghex.* Allow the application to own the name org.gnome.ghex and all names underneath in on the session DBus. .TP -\fBdbus-user.talk org.freedesktop.Notifications -Allow the application to talk to the name org.freedesktop.Notifications on the session DBus. -.TP \fBdbus-user.see org.freedesktop.Notifications Allow the application to see but not talk to the name org.freedesktop.Notifications on the session DBus. .TP -\fBdbus-user.call org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications -Allow the application to call methods of the interface org.freedesktop.Notifications of the object exposed at the path /org/freedesktop/Notifications by the client owning the bus name org.freedesktop.Notifications on the session DBus. -.TP -\fBdbus-user.broadcast org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications -Allow the application to receive broadcast signals from the the interface org.freedesktop.Notifications of the object exposed at the path /org/freedesktop/Notifications by the client owning the bus name org.freedesktop.Notifications on the session DBus. +\fBdbus-user.talk org.freedesktop.Notifications +Allow the application to talk to the name org.freedesktop.Notifications on the session DBus. .TP \fBnodbus \fR(deprecated) Disable D-Bus access (both system and session buses). Equivalent to dbus-system none and dbus-user none. @@ -866,20 +866,6 @@ net eth0 .br ip 10.10.20.56 -.TP -\fBip none -No IP address and no default gateway are configured for the last interface -defined by a net command. Use this option -in case you intend to start an external DHCP client in the sandbox. -.br - -.br -Example: -.br -net eth0 -.br -ip none - .TP \fBip dhcp Acquire an IP address and default gateway for the last interface defined by a @@ -907,6 +893,20 @@ If your DHCP server requires leases to be explicitly released, consider running a DHCP client and releasing the lease manually in conjunction with the net none command. +.TP +\fBip none +No IP address and no default gateway are configured for the last interface +defined by a net command. Use this option +in case you intend to start an external DHCP client in the sandbox. +.br + +.br +Example: +.br +net eth0 +.br +ip none + .TP \fBip6 address Assign IPv6 addresses to the last network interface defined by a net command. diff --git a/src/man/firejail.1.in b/src/man/firejail.1.in index 4edb0902e8e..bf447be9314 100644 --- a/src/man/firejail.1.in +++ b/src/man/firejail.1.in @@ -611,8 +611,9 @@ Example: $ firejail --dbus-user=filter --dbus-user.own=org.gnome.ghex.* .TP -\fB\-\-dbus-user.talk=name -Allows the application to talk to the specified well-known name on the session DBus. +\fB\-\-dbus-user.see=name +Allows the application to see, but not talk to the specified well-known name on +the session DBus. The name may have a .* suffix to match all names underneath it, including itself (e.g. "foo.bar.*" matches "foo.bar", "foo.bar.baz" and "foo.bar.baz.quux", but not "foobar"). @@ -621,14 +622,13 @@ not "foobar"). .br Example: .br -$ firejail --dbus-user=filter --dbus-user.talk=\\ +$ firejail --dbus-user=filter --dbus-user.see=\\ .br org.freedesktop.Notifications .TP -\fB\-\-dbus-user.see=name -Allows the application to see, but not talk to the specified well-known name on -the session DBus. +\fB\-\-dbus-user.talk=name +Allows the application to talk to the specified well-known name on the session DBus. The name may have a .* suffix to match all names underneath it, including itself (e.g. "foo.bar.*" matches "foo.bar", "foo.bar.baz" and "foo.bar.baz.quux", but not "foobar"). @@ -637,7 +637,7 @@ not "foobar"). .br Example: .br -$ firejail --dbus-user=filter --dbus-user.see=\\ +$ firejail --dbus-user=filter --dbus-user.talk=\\ .br org.freedesktop.Notifications #endif @@ -888,6 +888,32 @@ Example: .br $ firejail \-\-hosts-file=~/myhosts firefox +.TP +\fB\-\-icmptrace[=name|pid] +Monitor ICMP traffic. The sandbox can be specified by name or pid. Only networked sandboxes +created with \-\-net are supported. This option is only available when running the sandbox as root. +.br + +.br +Without a name/pid, Firejail will monitor the main system network namespace. +.br + +.br +Example +.br +$ sudo firejail --icmptrace +.br +20:53:54 192.168.1.60 -> 142.250.65.174 - 98 bytes - Echo request/0 +.br +20:53:54 142.250.65.174 -> 192.168.1.60 - 98 bytes - Echo reply/0 +.br +20:53:55 192.168.1.60 -> 142.250.65.174 - 98 bytes - Echo request/0 +.br +20:53:55 142.250.65.174 -> 192.168.1.60 - 98 bytes - Echo reply/0 +.br +20:53:55 192.168.1.60 -> 1.1.1.1 - 154 bytes - Destination unreachable/Port unreachable +.br + #ifdef HAVE_IDS .TP \fB\-\-ids-check @@ -924,32 +950,6 @@ $ firejail --ignore=seccomp --ignore=caps firefox $ firejail \-\-ignore="net eth0" firefox #endif -.TP -\fB\-\-icmptrace[=name|pid] -Monitor ICMP traffic. The sandbox can be specified by name or pid. Only networked sandboxes -created with \-\-net are supported. This option is only available when running the sandbox as root. -.br - -.br -Without a name/pid, Firejail will monitor the main system network namespace. -.br - -.br -Example -.br -$ sudo firejail --icmptrace -.br -20:53:54 192.168.1.60 -> 142.250.65.174 - 98 bytes - Echo request/0 -.br -20:53:54 142.250.65.174 -> 192.168.1.60 - 98 bytes - Echo reply/0 -.br -20:53:55 192.168.1.60 -> 142.250.65.174 - 98 bytes - Echo request/0 -.br -20:53:55 142.250.65.174 -> 192.168.1.60 - 98 bytes - Echo reply/0 -.br -20:53:55 192.168.1.60 -> 1.1.1.1 - 154 bytes - Destination unreachable/Port unreachable -.br - .TP \fB\-\-\include=file.profile Include a profile file before the regular profiles are used. @@ -983,23 +983,6 @@ Example: .br $ firejail \-\-net=eth0 \-\-ip=10.10.20.56 firefox -.TP -\fB\-\-ip=none -No IP address and no default gateway are configured for the last interface -defined by a \-\-net option. Use this option -in case you intend to start an external DHCP client in the sandbox. -.br - -.br -Example: -.br -$ firejail \-\-net=eth0 \-\-\ip=none -.br - -.br -If the corresponding interface doesn't have an IP address configured, this -option is enabled by default. - .TP \fB\-\-ip=dhcp Acquire an IP address and default gateway for the last interface defined by a @@ -1025,6 +1008,23 @@ If your DHCP server requires leases to be explicitly released, consider running a DHCP client and releasing the lease manually in conjunction with the \-\-net=none option. +.TP +\fB\-\-ip=none +No IP address and no default gateway are configured for the last interface +defined by a \-\-net option. Use this option +in case you intend to start an external DHCP client in the sandbox. +.br + +.br +Example: +.br +$ firejail \-\-net=eth0 \-\-\ip=none +.br + +.br +If the corresponding interface doesn't have an IP address configured, this +option is enabled by default. + .TP \fB\-\-ip6=address Assign IPv6 addresses to the last network interface defined by a \-\-net option. @@ -1323,6 +1323,21 @@ Example: .br $ firejail \-\-machine-id +.TP +\fB\-\-memory-deny-write-execute +Install a seccomp filter to block attempts to create memory mappings +that are both writable and executable, to change mappings to be +executable, or to create executable shared memory. The filter examines +the arguments of mmap, mmap2, mprotect, pkey_mprotect, memfd_create +and shmat system calls and returns error EPERM to the process (or +kills it or log the attempt, see \-\-seccomp-error-action below) if necessary. +.br + +.br +Note: shmat is not implemented +as a system call on some platforms including i386, and it cannot be +handled by seccomp-bpf. + .TP \fB\-\-mkdir=dirname Create a directory in user home. Parent directories are created as needed. @@ -1343,20 +1358,6 @@ Example: .br $ firejail --mkfile=~/work/project/readme -.TP -\fB\-\-memory-deny-write-execute -Install a seccomp filter to block attempts to create memory mappings -that are both writable and executable, to change mappings to be -executable, or to create executable shared memory. The filter examines -the arguments of mmap, mmap2, mprotect, pkey_mprotect, memfd_create -and shmat system calls and returns error EPERM to the process (or -kills it or log the attempt, see \-\-seccomp-error-action below) if necessary. -.br - -.br -Note: shmat is not implemented -as a system call on some platforms including i386, and it cannot be -handled by seccomp-bpf. #ifdef HAVE_NETWORK .TP \fB\-\-mtu=number @@ -1792,15 +1793,6 @@ Example: .br $ firejail \-\-nodvd .TP -\fB\-\-noinput -Disable input devices. -.br - -.br -Example: -.br -$ firejail \-\-noinput -.TP \fB\-\-noexec=dirname_or_filename Remount directory or file noexec, nodev and nosuid. File globbing is supported, see \fBFILE GLOBBING\fR section for more details. .br @@ -1844,6 +1836,16 @@ uid=1000(netblue) gid=1000(netblue) groups=1000(netblue) .br $ +.TP +\fB\-\-noinput +Disable input devices. +.br + +.br +Example: +.br +$ firejail \-\-noinput + .TP \fB\-\-nonewprivs Sets the NO_NEW_PRIVS prctl. This ensures that child processes @@ -3353,16 +3355,6 @@ $ firejail --net=eth0 --x11=xephyr --xephyr-screen=640x480 firefox .br #endif .\" Note: Keep this in sync with invalid_name() in src/firejail/util.c. -.SH NAME VALIDATION -For simplicity, the same name validation is used for multiple options. -Rules: -.PP -The name must be 1-253 characters long. -The name can only contain ASCII letters, digits and the special characters -"-._" (that is, the name cannot contain spaces or control characters). -The name cannot contain only digits. -The first and last characters must be an ASCII letter or digit and the name -may contain special characters in the middle. #ifdef HAVE_APPARMOR .SH APPARMOR .TP @@ -3408,64 +3400,6 @@ To enable AppArmor confinement on top of your current Firejail security features $ firejail --apparmor firefox #endif -#ifdef HAVE_LANDLOCK -.SH LANDLOCK -Warning: Landlock support in firejail is considered experimental and unstable. -The contents of landlock-common.inc are likely to change and the feature is -still being expanded upon in the Linux kernel. -Also, note that its functionality overlaps with existing firejail features, -such as the \fBblacklist\fR, \fBread-only\fR and \fBread-write\fR commands. -Its filesystem access rules can currently only restrict direct access to paths; -it is not able to make only select paths appear in the sandbox such as with the -\fBwhitelist\fR and \fBprivate-etc\fR commands (see also unveil(2) on OpenBSD). -Lastly, note that depending on the Linux kernel version, Landlock may not -protect all of the relevant syscalls (see the kernel's Landlock documentation -for details). -Therefore, it is recommended to treat Landlock as an extra layer of protection, -to be used together with other firejail features (rather than as a bulletproof -mechanism by itself). -.PP -Landlock is a Linux security module first introduced in version 5.13 of the -Linux kernel. -It allows unprivileged processes to restrict their access to the filesystem. -Once imposed, these restrictions can never be removed, and all child processes -created by a Landlock-restricted processes inherit these restrictions. -Firejail supports Landlock as an additional sandboxing feature. -It can be used to ensure that a sandboxed application can only access files and -directories that it was explicitly allowed to access. -Firejail supports populating the ruleset with both a basic set of rules (see -landlock-common.inc) and with a custom set of rules. -.TP -Important notes: -.PP -.RS -- Currently only Landlock ABI version 1 is supported. -.PP -- If "lsm=" is used in the kernel command line, it should contain "landlock" -(such as "lsm=apparmor,landlock"), or else it will be disabled. -.PP -- A process can install a Landlock ruleset only if it has either -\fBCAP_SYS_ADMIN\fR in its effective capability set, or the "No New -Privileges" restriction enabled. -Because of this, enabling the Landlock feature will also cause Firejail to -enable the "No New Privileges" restriction, regardless of the profile or the -\fB\-\-nonewprivs\fR command line option. -.PP -- Access to the /etc directory is automatically allowed. -To override this, use the \fB\-\-writable\-etc\fR command line option. -You can also use the \fB\-\-private\-etc\fR option to restrict access to the -/etc directory. -.RE -.PP -To enable Landlock self-restriction on top of your current Firejail security -features, pass \fB\-\-landlock.enforce\fR flag to Firejail command line. -Without it, the other Landlock commands have no effect. -Example: -.PP -$ firejail \-\-landlock.enforce \-\-landlock.fs.read=/media mc -.PP -To disable Landlock self-restriction, use \fB\-\-ignore=landlock.enforce\fR. -#endif .SH DESKTOP INTEGRATION A symbolic link to /usr/bin/firejail under the name of a program, will start the program in Firejail sandbox. The symbolic link should be placed in the first $PATH position. On most systems, a good place @@ -3713,6 +3647,65 @@ Currently while scanning the file system, symbolic links are not followed, and f The program can also be run as root (sudo firejail --ids-init/--ids-check). #endif +#ifdef HAVE_LANDLOCK +.SH LANDLOCK +Warning: Landlock support in firejail is considered experimental and unstable. +The contents of landlock-common.inc are likely to change and the feature is +still being expanded upon in the Linux kernel. +Also, note that its functionality overlaps with existing firejail features, +such as the \fBblacklist\fR, \fBread-only\fR and \fBread-write\fR commands. +Its filesystem access rules can currently only restrict direct access to paths; +it is not able to make only select paths appear in the sandbox such as with the +\fBwhitelist\fR and \fBprivate-etc\fR commands (see also unveil(2) on OpenBSD). +Lastly, note that depending on the Linux kernel version, Landlock may not +protect all of the relevant syscalls (see the kernel's Landlock documentation +for details). +Therefore, it is recommended to treat Landlock as an extra layer of protection, +to be used together with other firejail features (rather than as a bulletproof +mechanism by itself). +.PP +Landlock is a Linux security module first introduced in version 5.13 of the +Linux kernel. +It allows unprivileged processes to restrict their access to the filesystem. +Once imposed, these restrictions can never be removed, and all child processes +created by a Landlock-restricted processes inherit these restrictions. +Firejail supports Landlock as an additional sandboxing feature. +It can be used to ensure that a sandboxed application can only access files and +directories that it was explicitly allowed to access. +Firejail supports populating the ruleset with both a basic set of rules (see +landlock-common.inc) and with a custom set of rules. +.TP +Important notes: +.PP +.RS +- Currently only Landlock ABI version 1 is supported. +.PP +- If "lsm=" is used in the kernel command line, it should contain "landlock" +(such as "lsm=apparmor,landlock"), or else it will be disabled. +.PP +- A process can install a Landlock ruleset only if it has either +\fBCAP_SYS_ADMIN\fR in its effective capability set, or the "No New +Privileges" restriction enabled. +Because of this, enabling the Landlock feature will also cause Firejail to +enable the "No New Privileges" restriction, regardless of the profile or the +\fB\-\-nonewprivs\fR command line option. +.PP +- Access to the /etc directory is automatically allowed. +To override this, use the \fB\-\-writable\-etc\fR command line option. +You can also use the \fB\-\-private\-etc\fR option to restrict access to the +/etc directory. +.RE +.PP +To enable Landlock self-restriction on top of your current Firejail security +features, pass \fB\-\-landlock.enforce\fR flag to Firejail command line. +Without it, the other Landlock commands have no effect. +Example: +.PP +$ firejail \-\-landlock.enforce \-\-landlock.fs.read=/media mc +.PP +To disable Landlock self-restriction, use \fB\-\-ignore=landlock.enforce\fR. +#endif + .SH MONITORING Option \-\-list prints a list of all sandboxes. The format for each process entry is as follows: @@ -3770,6 +3763,17 @@ Sandbox running time in hours:minutes:seconds format. USER The owner of the sandbox. +.SH NAME VALIDATION +For simplicity, the same name validation is used for multiple options. +Rules: +.PP +The name must be 1-253 characters long. +The name can only contain ASCII letters, digits and the special characters +"-._" (that is, the name cannot contain spaces or control characters). +The name cannot contain only digits. +The first and last characters must be an ASCII letter or digit and the name +may contain special characters in the middle. + .SH RESTRICTED SHELL To configure a restricted shell, replace /bin/bash with /usr/bin/firejail in /etc/passwd file for each user that needs to be restricted. Alternatively,