Inspect and Call D-Bus Services with gdbus

This guide uses gdbus to inspect a live D-Bus object, call a harmless method, watch signals and wait for a bus name. The examples use the gdbus shipped by libglib2.0-bin 2.80.0-6ubuntu3.9 on this machine. Allow about fifteen minutes. You need a shell and access to the bus that owns the service you want to inspect.

Checkpoint: gdbus talks to a real D-Bus daemon. A command can be syntactically correct and still fail because the selected bus is absent, the name is not owned, or policy denies the operation.

1. Choose the bus before choosing the object

Every bus-aware command needs one connection choice: --system, --session, or --address ADDRESS. The system bus normally carries operating-system services and may require policy authorisation. The session bus belongs to a user login. An explicit address is useful for a private or application-specific bus.

Do not add both --system and --session. If neither is supplied, do not rely on an implicit default when writing a script: make the intended bus visible in the command.

$ gdbus help
Usage:
  gdbus COMMAND

Commands:
  help         Shows this information
  introspect   Introspect a remote object
  monitor      Monitor a remote object
  call         Invoke a method on a remote object
  emit         Emit a signal
  wait         Wait for a bus name to appear

This is a read-only check and does not need elevated privileges. On a machine without the selected bus, expect an error such as Could not connect: No such file or directory. Do not try sudo as a first response: root has a different session environment, and access to the system bus is controlled by D-Bus policy.

2. Discover an object with introspection

Introspection asks an object for its interfaces, methods, signals and properties. You need the service's well-known bus name and an object path. The root object, /, is a useful starting point when the service documents it.

$ gdbus introspect --session \
    --dest org.freedesktop.DBus \
    --object-path / \
    --only-properties
node / {
  interface org.freedesktop.DBus {
    properties:
      readonly as Features;
      readonly as Interfaces;
  };
  node org/freedesktop/DBus {
  };
};

The exact properties and annotations vary by daemon version. The installed command also accepts --recurse to inspect child objects and --xml to print the raw introspection XML. Use --only-properties when a recursive tree is too noisy.

Checkpoint: Copy the exact interface and method name from introspection. D-Bus names are case-sensitive, and a plausible object path is not enough. If you see an error about an unknown object or name, check ownership first rather than changing the path at random.

3. Call a method using GVariant values

call invokes one remote method. Its arguments are serialised GVariant values. Strings are the convenient exception: they do not need explicit quotes unless shell quoting requires them. Arrays, dictionaries, booleans and typed values need the GVariant notation shown by the method signature.

$ gdbus call --session \
    --dest org.freedesktop.DBus \
    --object-path /org/freedesktop/DBus \
    --method org.freedesktop.DBus.ListNames
(['org.freedesktop.DBus', ':1.1'],)

This call takes no arguments and returns an array of bus names. Your unique name will not necessarily be :1.1, and the list changes as clients connect. The parentheses are part of the serialised return tuple, not shell syntax.

For a method with arguments, let introspection define their order and types. For example, a notification method commonly expects strings followed by an unsigned integer, an array of strings, a dictionary and a signed integer. Do not copy an argument list from an unrelated service. A remote method can reject a value even when the shell accepted it.

Safety boundary: A method call can change state, restart a service, alter settings or expose data. Start with an introspection call or another documented read-only method. Before using a mutating method, check its documentation, target bus and authorisation requirements. There is no generic undo for a D-Bus method.

4. Monitor signals without losing the terminal

monitor prints signals emitted by objects owned by a bus name. Add --object-path to narrow the stream to one object. Monitoring is long-running, so run it in a terminal you can stop with Ctrl-C.

$ gdbus monitor --session \
    --dest org.freedesktop.DBus \
    --object-path /org/freedesktop/DBus
Monitoring signals on object /org/freedesktop/DBus owned by org.freedesktop.DBus

A quiet terminal after the heading is normal: signals only appear when something emits them. Press Ctrl-C to stop the monitor. The command does not alter the service, but a broad monitor can produce a large amount of output, so prefer an object path when you know it.

5. Wait for a service, with a deliberate timeout

wait blocks until a well-known bus name is owned. Its timeout is disabled by default, so add one in automation. The --activate option asks the bus to auto-start a service before waiting; without it, the command only waits for a service that another process starts.

$ gdbus wait --session --timeout 30 org.example.Service
$ printf 'wait status: %s\n' "$?"
wait status: 0

Use --timeout 0 to make the timeout explicitly unlimited. A prerequisite service can be auto-started while you wait for a different name:

$ gdbus wait --session --activate \
    org.example.Prerequisite \
    org.example.Service

Auto-starting is a service action, not merely a lookup. Use it only when the service's activation contract is known and starting it is acceptable. A timeout or connection failure is a diagnostic result; do not turn it into an infinite wait by accident.

6. Treat signal emission as an application action

emit sends a signal from the command line. It needs an object path and a fully qualified signal name. Its arguments use the same GVariant rules as call. A destination can be supplied with --dest, but it must be a unique bus name, not an arbitrary process ID.

$ gdbus emit --session \
    --object-path /example \
    --signal org.example.Events.Changed \
    "['dry-run']"

Only run this against an application designed to accept that signal. Emitting an unexpected signal can trigger actions in listeners, and there is no general undo. For routine troubleshooting, introspection, a read-only call and a narrowly scoped monitor are safer starting points.

7. Diagnose failures in the right order

  1. Confirm the binary and package: command -v gdbus and dpkg-query -W -f='${Package} ${Version}\n' libglib2.0-bin.
  2. Confirm the bus choice. A missing socket usually means the daemon or session is unavailable, not that the object path is wrong.
  3. Confirm that the destination name is owned and that the object path is exported.
  4. Run introspection and copy the exact interface, method or signal spelling.
  5. Check the method signature before changing GVariant quoting or argument types.
  6. Read the D-Bus error text. Policy denial, an absent name and a remote application error require different fixes.

Most examples are ordinary user commands. Use elevated privileges only when the service's documented policy requires it, and understand that sudo can change the session bus environment. Never paste credentials or opaque user input into a method argument without understanding how the shell and GVariant parser will interpret it.

Done means