gdebugcontroller: Add some more documentation

Signed-off-by: Philip Withnall <pwithnall@endlessos.org>

Helps: #1190
This commit is contained in:
Philip Withnall 2022-02-10 19:24:17 +00:00
parent 35f6c65b35
commit 6d5953ee48
2 changed files with 103 additions and 0 deletions

View File

@ -44,6 +44,10 @@
* default. Application code may connect to the #GObject::notify signal for it
* to control other parts of its debug infrastructure as necessary.
*
* If your application or service is using the default GLib log writer function,
* creating one of the built-in implementations of #GDebugController should be
* all thats needed to dynamically enable or disable debug output.
*
* Since: 2.72
*/

View File

@ -42,6 +42,105 @@
* #GDebugControllerDBus:connection once its initialized. The object will be
* unregistered when the last reference to the #GDebugControllerDBus is dropped.
*
* This D-Bus object can be used by remote processes to enable or disable debug
* output in this process. Remote processes calling
* `org.gtk.Debugging.SetDebugEnabled()` will affect the value of
* #GDebugController:debug-enabled and, by default, g_log_get_debug_enabled().
* default.
*
* By default, all processes will be able to call `SetDebugEnabled()`. If this
* process is privileged, or might expose sensitive information in its debug
* output, you may want to restrict the ability to enable debug output to
* privileged users or processes.
*
* One option is to install a D-Bus security policy which restricts access to
* `SetDebugEnabled()`, installing something like the following in
* `$datadir/dbus-1/system.d/`:
* |[<!-- language="XML" -->
* <?xml version="1.0"?> <!--*-nxml-*-->
* <!DOCTYPE busconfig PUBLIC "-//freedesktop//DTD D-BUS Bus Configuration 1.0//EN"
* "http://www.freedesktop.org/standards/dbus/1.0/busconfig.dtd">
* <busconfig>
* <policy user="root">
* <allow send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/>
* </policy>
* <policy context="default">
* <deny send_destination="com.example.MyService" send_interface="org.gtk.Debugging"/>
* </policy>
* </busconfig>
* ]|
*
* This will prevent the `SetDebugEnabled()` method from being called by all
* except root. It will not prevent the `DebugEnabled` property from being read,
* as its accessed through the `org.freedesktop.DBus.Properties` interface.
*
* Another option is to use polkit to allow or deny requests on a case-by-case
* basis, allowing for the possibility of dynamic authorisation. To do this,
* connect to the #GDebugControllerDBus::authorize signal and query polkit in
* it:
* |[<!-- language="C" -->
* g_autoptr(GError) child_error = NULL;
* g_autoptr(GDBusConnection) connection = g_bus_get_sync (G_BUS_TYPE_SYSTEM, NULL, NULL);
* gulong debug_controller_authorize_id = 0;
*
* // Set up the debug controller.
* debug_controller = G_DEBUG_CONTROLLER (g_debug_controller_dbus_new (priv->connection, NULL, &child_error));
* if (debug_controller == NULL)
* {
* g_error ("Could not register debug controller on bus: %s"),
* child_error->message);
* }
*
* debug_controller_authorize_id = g_signal_connect (debug_controller,
* "authorize",
* G_CALLBACK (debug_controller_authorize_cb),
* self);
*
* static gboolean
* debug_controller_authorize_cb (GDebugControllerDBus *debug_controller,
* GDBusMethodInvocation *invocation,
* gpointer user_data)
* {
* g_autoptr(PolkitAuthority) authority = NULL;
* g_autoptr(PolkitSubject) subject = NULL;
* g_autoptr(PolkitAuthorizationResult) auth_result = NULL;
* g_autoptr(GError) local_error = NULL;
* GDBusMessage *message;
* GDBusMessageFlags message_flags;
* PolkitCheckAuthorizationFlags flags = POLKIT_CHECK_AUTHORIZATION_FLAGS_NONE;
*
* message = g_dbus_method_invocation_get_message (invocation);
* message_flags = g_dbus_message_get_flags (message);
*
* authority = polkit_authority_get_sync (NULL, &local_error);
* if (authority == NULL)
* {
* g_warning ("Failed to get polkit authority: %s", local_error->message);
* return FALSE;
* }
*
* if (message_flags & G_DBUS_MESSAGE_FLAGS_ALLOW_INTERACTIVE_AUTHORIZATION)
* flags |= POLKIT_CHECK_AUTHORIZATION_FLAGS_ALLOW_USER_INTERACTION;
*
* subject = polkit_system_bus_name_new (g_dbus_method_invocation_get_sender (invocation));
*
* auth_result = polkit_authority_check_authorization_sync (authority,
* subject,
* "com.example.MyService.set-debug-enabled",
* NULL,
* flags,
* NULL,
* &local_error);
* if (auth_result == NULL)
* {
* g_warning ("Failed to get check polkit authorization: %s", local_error->message);
* return FALSE;
* }
*
* return polkit_authorization_result_get_is_authorized (auth_result);
* }
* ]|
*
* Since: 2.72
*/