Add documentation for DBus filtering

3 files changed, 161 insertions, 11 deletions

diff --git a/src/firejail/usage.c b/src/firejail/usage.c
index 81a1a6099..0636a23c2 100644
--- a/src/firejail/usage.c
+++ b/src/firejail/usage.c
@@ -53,6 +53,12 @@ static char *usage_str =
 #endif
         "    --cpu=cpu-number,cpu-number - set cpu affinity.\n"
         "    --cpu.print=name|pid - print the cpus in use.\n"
+        "    --dbus-system=filter|none - set system DBus access policy.\n"
+        "    --dbus-system.own=name - allow ownership of name on the system DBus.\n"
+        "    --dbus-system.talk-name - allow talking to name on the system DBus.\n"
+        "    --dbus-user=filter|none - set session DBus access policy.\n"
+        "    --dbus-user.own=name - allow ownership of name on the session DBus.\n"
+        "    --dbus-user.talk-name - allow talking to name on the session DBus.\n"
         "    --debug - print sandbox debug messages.\n"
         "    --debug-blacklists - debug blacklisting.\n"
         "    --debug-caps - print all recognized capabilities.\n"
diff --git a/src/man/firejail-profile.txt b/src/man/firejail-profile.txt
index 203d4543d..7ef512bbf 100644
--- a/src/man/firejail-profile.txt
+++ b/src/man/firejail-profile.txt
@@ -447,7 +447,55 @@ xephyr-screen 640x480
 .br
 x11 xephyr
 
+.SH DBus filtering
 
+Access to the session and system DBus UNIX sockets can be allowed, filtered or
+disabled. To disable the abstract sockets (and force applications to use the
+filtered UNIX socket) you would need to request a new network namespace using
+\-\-net command. Another option is to remove unix from the \-\-protocol set.
+.br
+
+.br
+Filtering requires installing the xdg-dbus-proxy utility. Filter rules can be
+specified for well-known DBus names, but they are also propagated to the owning
+unique name, too. The permissions are "sticky" and are kept even if the
+corresponding well-know name is released (however, applications rarely release
+well-known names in practice). Names may have a .* suffix to match all names
+underneath them, including themselves (e.g. "foo.bar.*" matches "foo.bar",
+"foo.bar.baz" and "foo.bar.baz.quux", but not "foobar"). For more information,
+see xdg-dbus-proxy(1).
+.br
+
+.br
+Examples:
+
+.TP
+\fBdbus-system filter
+Enable filtered access to the system DBus. Filters can be specified with the dbus-system.talk and dbus-system.own commands.
+.TP
+\fBdbus-system none
+Disable access to the system DBus. Once access is disabled, it cannot be relaxed to filtering.
+.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-user filter
+Enable filtered access to the session DBus. Filters can be specified with the dbus-user.talk and dbus-user.own commands.
+.TP
+\fBdbus-user none
+Disable access to the session DBus. Once access is disabled, it cannot be relaxed to filtering.
+.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
+\fBnodbus
+Disable D-Bus access (both system and session buses). Equivalent to dbus-system none and dbus-user none.
 
 .SH Resource limits, CPU affinity, Control Groups
 These profile entries define the limits on system resources (rlimits) for the processes inside the sandbox.
@@ -522,12 +570,6 @@ Disable 3D hardware acceleration.
 Disable automatic ~/.config/pulse init, for complex setups such as remote
 pulse servers or non-standard socket paths.
 .TP
-\fBnodbus
-Disable D-Bus access. Only the regular UNIX socket is handled by
-this command. To disable the abstract socket, you would need to
-request a new network namespace using the net command. Another
-option is to remove unix from protocol set.
-.TP
 \fBnodvd
 Disable DVD and audio CD devices.
 .TP
diff --git a/src/man/firejail.txt b/src/man/firejail.txt
index 02c1d27b2..b0c4eeb15 100644
--- a/src/man/firejail.txt
+++ b/src/man/firejail.txt
@@ -326,6 +326,112 @@ $ firejail \-\-list
 $ firejail \-\-cpu.print=3272
 
 .TP
+\fB\-\-dbus-system=filter|none
+Set system DBus sandboxing policy. 
+.br
+
+.br
+The \fBfilter\fR policy enables the system DBus filter. This option requires
+installing the xdg-dbus-proxy utility. Permissions for well-known can be
+specified with the --dbus-system.talk and --dbus-system.own options.
+.br
+
+.br
+The \fBnone\fR policy disables access to the system DBus.
+.br
+
+.br
+Only the regular system DBus UNIX socket is handled by this option. To disable
+the abstract sockets (and force applications to use the filtered UNIX socket)
+you would need to request a new network namespace using \-\-net command. Another
+option is to remove unix from the \-\-protocol set.
+.br
+
+.br
+Example:
+.br
+$ firejail \-\-dbus-system=none
+
+.TP
+\fB\-\-dbus-system.own=name
+Allows the application to own the specified well-known name on the system 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").
+.br
+
+.br
+Example:
+.br
+$ firejail --dbus-system=filter --dbus-system.own=org.gnome.ghex.*
+
+.TP
+\fB\-\-dbus-system.talk=name
+Allows the application to talk to the specified well-known name on the system 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").
+.br
+
+.br
+Example:
+.br
+$ firejail --dbus-system=filter --dbus-system.talk=org.freedesktop.Notifications
+
+.TP
+\fB\-\-dbus-user=filter|none
+Set session DBus sandboxing policy.
+.br
+
+.br
+The \fBfilter\fR policy enables the session DBus filter. This option requires
+installing the xdg-dbus-proxy utility. Permissions for well-known names can be
+added with the --dbus-user.talk and --dbus-user.own options.
+.br
+
+.br
+The \fBnone\fR policy disables access to the session DBus.
+.br
+
+.br
+Only the regular session DBus UNIX socket is handled by this option. To disable
+the abstract sockets (and force applications to use the filtered UNIX socket)
+you would need to request a new network namespace using \-\-net command. Another
+option is to remove unix from the \-\-protocol set.
+.br
+
+.br
+Example:
+.br
+$ firejail \-\-dbus-user=none
+
+.TP
+\fB\-\-dbus-user.own=name
+Allows the application to own 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").
+.br
+
+.br
+Example:
+.br
+$ 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.
+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").
+.br
+
+.br
+Example:
+.br
+$ firejail --dbus-user=filter --dbus-user.talk=org.freedesktop.Notifications
+
+.TP
 \fB\-\-debug\fR
 Print debug messages.
 .br
@@ -1171,11 +1277,7 @@ $ nc dict.org 2628
 .br
 .TP
 \fB\-\-nodbus
-Disable D-Bus access (both system and session buses). Only the regular
-UNIX sockets are handled by this command. To disable the abstract
-sockets you would need to request a new network namespace using
-\-\-net command. Another option is to remove unix from \-\-protocol
-set.
+Disable D-Bus access (both system and session buses). Equivalent to --dbus-system=none --dbus-user=none.
 .br
 
 .br