Copyright | Will Thompson and Iñaki García Etxebarria |
---|---|
License | LGPL-2.1 |
Maintainer | Iñaki García Etxebarria |
Safe Haskell | None |
Language | Haskell2010 |
GDebugControllerDBus
is an implementation of DebugController
which exposes debug settings as a D-Bus object.
It is a Initable
object, and will register an object at
/org/gtk/Debugging
on the bus given as
DebugControllerDBus:connection once it’s 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
DebugController
:debug-enabled
and, by default,
logGetDebugEnabled
.
By default, no processes are allowed to call SetDebugEnabled()
unless a
DebugControllerDBus::authorize signal handler is installed. This
is because the process may be 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/
:
xml code
<?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 it’s 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 DebugControllerDBus::authorize signal and query polkit in it:
c code
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
Synopsis
- newtype DebugControllerDBus = DebugControllerDBus (ManagedPtr DebugControllerDBus)
- class (GObject o, IsDescendantOf DebugControllerDBus o) => IsDebugControllerDBus o
- toDebugControllerDBus :: (MonadIO m, IsDebugControllerDBus o) => o -> m DebugControllerDBus
- debugControllerDBusNew :: (HasCallStack, MonadIO m, IsDBusConnection a, IsCancellable b) => a -> Maybe b -> m (Maybe DebugControllerDBus)
- debugControllerDBusStop :: (HasCallStack, MonadIO m, IsDebugControllerDBus a) => a -> m ()
- constructDebugControllerDBusConnection :: (IsDebugControllerDBus o, MonadIO m, IsDBusConnection a) => a -> m (GValueConstruct o)
- getDebugControllerDBusConnection :: (MonadIO m, IsDebugControllerDBus o) => o -> m (Maybe DBusConnection)
- type DebugControllerDBusAuthorizeCallback = DBusMethodInvocation -> IO Bool
- afterDebugControllerDBusAuthorize :: (IsDebugControllerDBus a, MonadIO m) => a -> ((?self :: a) => DebugControllerDBusAuthorizeCallback) -> m SignalHandlerId
- onDebugControllerDBusAuthorize :: (IsDebugControllerDBus a, MonadIO m) => a -> ((?self :: a) => DebugControllerDBusAuthorizeCallback) -> m SignalHandlerId
Exported types
newtype DebugControllerDBus Source #
Memory-managed wrapper type.
Instances
Eq DebugControllerDBus Source # | |
Defined in GI.Gio.Objects.DebugControllerDBus (==) :: DebugControllerDBus -> DebugControllerDBus -> Bool # (/=) :: DebugControllerDBus -> DebugControllerDBus -> Bool # | |
GObject DebugControllerDBus Source # | |
Defined in GI.Gio.Objects.DebugControllerDBus | |
ManagedPtrNewtype DebugControllerDBus Source # | |
TypedObject DebugControllerDBus Source # | |
Defined in GI.Gio.Objects.DebugControllerDBus | |
HasParentTypes DebugControllerDBus Source # | |
Defined in GI.Gio.Objects.DebugControllerDBus | |
IsGValue (Maybe DebugControllerDBus) Source # | Convert |
Defined in GI.Gio.Objects.DebugControllerDBus gvalueGType_ :: IO GType # gvalueSet_ :: Ptr GValue -> Maybe DebugControllerDBus -> IO () # gvalueGet_ :: Ptr GValue -> IO (Maybe DebugControllerDBus) # | |
type ParentTypes DebugControllerDBus Source # | |
Defined in GI.Gio.Objects.DebugControllerDBus |
class (GObject o, IsDescendantOf DebugControllerDBus o) => IsDebugControllerDBus o Source #
Type class for types which can be safely cast to DebugControllerDBus
, for instance with toDebugControllerDBus
.
Instances
(GObject o, IsDescendantOf DebugControllerDBus o) => IsDebugControllerDBus o Source # | |
Defined in GI.Gio.Objects.DebugControllerDBus |
toDebugControllerDBus :: (MonadIO m, IsDebugControllerDBus o) => o -> m DebugControllerDBus Source #
Cast to DebugControllerDBus
, for types for which this is known to be safe. For general casts, use castTo
.
Methods
Click to display all available methods, including inherited ones
Methods
bindProperty, bindPropertyFull, forceFloating, freezeNotify, getv, init, isFloating, notify, notifyByPspec, ref, refSink, runDispose, stealData, stealQdata, stop, thawNotify, unref, watchClosure.
Getters
getData, getDebugEnabled, getProperty, getQdata.
Setters
new
debugControllerDBusNew Source #
:: (HasCallStack, MonadIO m, IsDBusConnection a, IsCancellable b) | |
=> a |
|
-> Maybe b |
|
-> m (Maybe DebugControllerDBus) | Returns: a new |
Create a new DebugControllerDBus
and synchronously initialize it.
Initializing the object will export the debug object on connection
. The
object will remain registered until the last reference to the
DebugControllerDBus
is dropped.
Initialization may fail if registering the object on connection
fails.
Since: 2.72
stop
debugControllerDBusStop Source #
:: (HasCallStack, MonadIO m, IsDebugControllerDBus a) | |
=> a |
|
-> m () |
Stop the debug controller, unregistering its object from the bus.
Any pending method calls to the object will complete successfully, but new ones will return an error. This method will block until all pending DebugControllerDBus::authorize signals have been handled. This is expected to not take long, as it will just be waiting for threads to join. If any DebugControllerDBus::authorize signal handlers are still executing in other threads, this will block until after they have returned.
This method will be called automatically when the final reference to the
DebugControllerDBus
is dropped. You may want to call it explicitly to know
when the controller has been fully removed from the bus, or to break
reference count cycles.
Calling this method from within a DebugControllerDBus::authorize signal handler will cause a deadlock and must not be done.
Since: 2.72
Properties
connection
The D-Bus connection to expose the debugging interface on.
Typically this will be the same connection (to the system or session bus) which the rest of the application or service’s D-Bus objects are registered on.
Since: 2.72
constructDebugControllerDBusConnection :: (IsDebugControllerDBus o, MonadIO m, IsDBusConnection a) => a -> m (GValueConstruct o) Source #
Construct a GValueConstruct
with valid value for the “connection
” property. This is rarely needed directly, but it is used by new
.
getDebugControllerDBusConnection :: (MonadIO m, IsDebugControllerDBus o) => o -> m (Maybe DBusConnection) Source #
Get the value of the “connection
” property.
When overloading is enabled, this is equivalent to
get
debugControllerDBus #connection
Signals
authorize
type DebugControllerDBusAuthorizeCallback Source #
= DBusMethodInvocation |
|
-> IO Bool |
Emitted when a D-Bus peer is trying to change the debug settings and used to determine if that is authorized.
This signal is emitted in a dedicated worker thread, so handlers are
allowed to perform blocking I/O. This means that, for example, it is
appropriate to call polkit_authority_check_authorization_sync()
to check
authorization using polkit.
If False
is returned then no further handlers are run and the request to
change the debug settings is rejected.
Otherwise, if True
is returned, signal emission continues. If no handlers
return False
, then the debug settings are allowed to be changed.
Signal handlers must not modify invocation
, or cause it to return a value.
The default class handler just returns True
.
Since: 2.72
afterDebugControllerDBusAuthorize :: (IsDebugControllerDBus a, MonadIO m) => a -> ((?self :: a) => DebugControllerDBusAuthorizeCallback) -> m SignalHandlerId Source #
Connect a signal handler for the authorize signal, to be run after the default handler. When overloading is enabled, this is equivalent to
after
debugControllerDBus #authorize callback
By default the object invoking the signal is not passed to the callback.
If you need to access it, you can use the implit ?self
parameter.
Note that this requires activating the ImplicitParams
GHC extension.
onDebugControllerDBusAuthorize :: (IsDebugControllerDBus a, MonadIO m) => a -> ((?self :: a) => DebugControllerDBusAuthorizeCallback) -> m SignalHandlerId Source #
Connect a signal handler for the authorize signal, to be run before the default handler. When overloading is enabled, this is equivalent to
on
debugControllerDBus #authorize callback