Documentation for new DBus options

kris7t · May 7, 2020 · 28a3d38 · 28a3d38
1 parent d50d1a9
commit 28a3d38
Show file tree

Hide file tree

Showing 3 changed files with 163 additions and 0 deletions.
diff --git a/src/firejail/usage.c b/src/firejail/usage.c
@@ -53,11 +53,20 @@ 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-log=file - set DBus log file location.\n"
 	"    --dbus-system=filter|none - set system DBus access policy.\n"
+	"    --dbus-system.broadcast=rule - allow signals on the system DBus according to rule.\n"
+	"    --dbus-system.call=rule - allow calls on the system DBus according to rule.\n"
+	"    --dbus-system.log - turn on logging for the system DBus."
 	"    --dbus-system.own=name - allow ownership of name on the system DBus.\n"
+	"    --dbus-system.see=name - allow seeing 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.broadcast=rule - allow signals on the session DBus according to rule.\n"
+	"    --dbus-user.call=rule - allow calls on the session DBus according to rule.\n"
+	"    --dbus-user.log - turn on logging for the user DBus."
 	"    --dbus-user.own=name - allow ownership of name on the session DBus.\n"
+	"    --dbus-user.see=name - allow seeing 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"

diff --git a/src/man/firejail-profile.txt b/src/man/firejail-profile.txt
@@ -491,6 +491,15 @@ Allow the application to own the name org.gnome.ghex and all names underneath in
 \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 recieve 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 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
@@ -503,6 +512,15 @@ Allow the application to own the name org.gnome.ghex and all names underneath in
 \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 recieve 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
 \fBnodbus \fR(deprecated)
 Disable D-Bus access (both system and session buses). Equivalent to dbus-system none and dbus-user none.
 .TP

diff --git a/src/man/firejail.txt b/src/man/firejail.txt
@@ -325,6 +325,22 @@ $ firejail \-\-list
 .br
 $ firejail \-\-cpu.print=3272
 
+.TP
+\fB\-\-dbus-log=file
+Specify the location for the DBus log file.
+.br
+
+.br
+The log file contains events for both the system and session buses if both of
+the --dbus-sysem.log and --dbus-user.log options are specified. If no log file
+path is given, logs are written to the standard output instead.
+.br
+
+.br
+Example:
+.br
+$ firejail --dbus-system=filter --dbus-system.log --dbus-log=dbus.txt
+
 .TP
 \fB\-\-dbus-system=filter|none
 Set system DBus sandboxing policy. 
@@ -352,6 +368,52 @@ Example:
 .br
 $ firejail \-\-dbus-system=none
 
+.TP
+\fB\-\-dbus-system.broadcast=name=[member][@path]
+Allows the application to receive broadcast signals from theindicated interface
+member at the indicated object path exposed by the indicated bus name on the
+system DBus.
+The name may have a .* suffix to match all names underneath it, including
+itself.
+The interface member may have a .* to match all members of an interface, or be * to match all interfaces.
+The path may have a /* suffix to indicate all objects underneath it, including
+itself.
+Omitting the interface member or the object path will match all members and
+object paths, respectively.
+.br
+
+.br
+Example:
+.br
+$ firejail --dbus-system=filter --dbus-system.broadcast=org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications
+
+.TP
+\fB\-\-dbus-system.call=name=[member][@path]
+Allows the application to call the indicated interface member at the indicated
+object path exposed by the indicated bus name on the system DBus.
+The name may have a .* suffix to match all names underneath it, including
+itself.
+The interface member may have a .* to match all members of an interface, or be * to match all interfaces.
+The path may have a /* suffix to indicate all objects underneath it, including
+itself.
+Omitting the interface member or the object path will match all members and
+object paths, respectively.
+.br
+
+.br
+Example:
+.br
+$ firejail --dbus-system=filter --dbus-system.call=org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications
+
+.TP
+\fB\-\-dbus-system.log
+Turn on DBus logging for the system DBus. This option requires --dbus-system=log.
+
+.br
+Example:
+.br
+$ firejail --dbus-system=filter --dbus-system.log
+
 .TP
 \fB\-\-dbus-system.own=name
 Allows the application to own the specified well-known name on the system DBus.
@@ -365,6 +427,20 @@ Example:
 .br
 $ firejail --dbus-system=filter --dbus-system.own=org.gnome.ghex.*
 
+.TP
+\fB\-\-dbus-system.see=name
+Allows the application to see, but not 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.see=org.freedesktop.Notifications
+
 .TP
 \fB\-\-dbus-system.talk=name
 Allows the application to talk to the specified well-known name on the system DBus.
@@ -405,6 +481,52 @@ Example:
 .br
 $ firejail \-\-dbus-user=none
 
+.TP
+\fB\-\-dbus-user.broadcast=name=[member][@path]
+Allows the application to receive broadcast signals from theindicated interface
+member at the indicated object path exposed by the indicated bus name on the
+session DBus.
+The name may have a .* suffix to match all names underneath it, including
+itself.
+The interface member may have a .* to match all members of an interface, or be * to match all interfaces.
+The path may have a /* suffix to indicate all objects underneath it, including
+itself.
+Omitting the interface member or the object path will match all members and
+object paths, respectively.
+.br
+
+.br
+Example:
+.br
+$ firejail --dbus-user=filter --dbus-user.broadcast=org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications
+
+.TP
+\fB\-\-dbus-user.call=name=[member][@path]
+Allows the application to call the indicated interface member at the indicated
+object path exposed by the indicated bus name on the session DBus.
+The name may have a .* suffix to match all names underneath it, including
+itself.
+The interface member may have a .* to match all members of an interface, or be * to match all interfaces.
+The path may have a /* suffix to indicate all objects underneath it, including
+itself.
+Omitting the interface member or the object path will match all members and
+object paths, respectively.
+.br
+
+.br
+Example:
+.br
+$ firejail --dbus-user=filter --dbus-user.call=org.freedesktop.Notifications=org.freedesktop.Notifications.*@/org/freedesktop/Notifications
+
+.TP
+\fB\-\-dbus-user.log
+Turn on DBus logging for the session DBus. This option requires --dbus-user=log.
+
+.br
+Example:
+.br
+$ firejail --dbus-user=filter --dbus-user.log
+
 .TP
 \fB\-\-dbus-user.own=name
 Allows the application to own the specified well-known name on the session DBus.
@@ -431,6 +553,20 @@ Example:
 .br
 $ firejail --dbus-user=filter --dbus-user.talk=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.
+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.see=org.freedesktop.Notifications
+
 .TP
 \fB\-\-debug\fR
 Print debug messages.