Exploring D-Bus with "busctl" (with examples)

Introduction

D-Bus is a message bus system that allows communication between different applications running on the same machine. “busctl” is a command-line utility that can be used to introspect and monitor the D-Bus bus. In this article, we will explore eight different use cases of the “busctl” command with code examples.

Use Case 1: Show all peers on the bus

The busctl list command displays all the peers on the D-Bus bus, along with their service names. This can be useful to see which services are currently active on the bus.

busctl list

Motivation: This command helps in understanding the services running on the D-Bus bus and can be used for troubleshooting purposes.

Example Output:

NAME                                                          PID  UID  
:1.0                                                          1000  1000 
org.freedesktop.login1                                         -    -    
org.freedesktop.NetworkManager                                  -    -    
org.freedesktop.systemd1                                       -    -    

In the above example output, we can see the list of peers on the bus, including the service names and associated PIDs and UIDs.

Use Case 2: Show process information and credentials

The busctl status command is used to display process information and credentials of a bus service, a specified process, or the owner of the bus (if no parameter is specified).

busctl status service|pid

Motivation: This command can be used to gather information about a specific bus service or process running on the bus, such as its PID, UID, and security credentials.

Example Output:

PID: 1234
Executable: /usr/bin/my_service
UID: 1000
GID: 1000

Here, we can see the process information and credentials of the specified service or process.

Use Case 3: Monitor messages on the bus

The busctl monitor command is used to dump messages being exchanged on the D-Bus bus. If no service is specified, it will show all messages on the bus.

busctl monitor service1 service2 ...

Motivation: Monitoring bus messages can help in debugging and understanding the communication between different services on the D-Bus.

Example Output:

[S] 1544354921.432175 org.freedesktop.DBus /org/freedesktop/DBus org.freedesktop.DBus GetIdRequested cookie=1 sender=:1.0 -> destination=:1.139 serial=620 reply_serial=0

Here, we can see a message being exchanged between the sender “:1.0” and the destination “:1.139”.

Use Case 4: Show object tree of services

The busctl tree command displays an object tree of one or more specified services, or all services if no service is specified.

busctl tree service1 service2 ...

Motivation: This command helps in visualizing the hierarchy of objects provided by different services on the D-Bus.

Example Output:

└─/: object
  ├─org.freedesktop.DBus.Properties: interface
  │ └─Destination: property
  ├─org.freedesktop.DBus.Introspectable: interface
  │ └─Introspect: method
  └─org.freedesktop.DBus.Peer: interface
    ├─Ping: method
    └─GetMachineId: method

In the above example, we can see the object tree of the root path ("/") along with the interfaces, methods, and properties provided by each object.

Use Case 5: Introspect a service or object

The busctl introspect command is used to display interfaces, methods, properties, and signals of the specified object on the specified service.

busctl introspect service path/to/object

Motivation: This command helps in understanding the available interfaces, methods, properties, and signals exposed by a specific object on a service.

Example Output:

<node>
  <interface name="org.example">
    <method name="DoSomething">
      <arg name="input" type="s" direction="in"/>
      <arg name="output" type="s" direction="out"/>
    </method>
    <signal name="SomethingHappened">
      <arg name="data" type="s"/>
    </signal>
  </interface>
</node>

Here, we can see the interfaces, methods, and signals provided by the specified object on the service.

Use Case 6: Get the value of object properties

The busctl get-property command is used to retrieve the current value of one or more object properties.

busctl get-property service path/to/object interface_name property_name

Motivation: This command allows us to fetch the current value of a specific property of an object on a service.

Example Output:

Value: 42

Here, we can see the current value of the property “property_name” on the specified object.

Use Case 7: Invoke a method and show the response

The busctl call command is used to invoke a method on a specified service and object, and it displays the response.

busctl call service path/to/object interface_name method_name

Motivation: This command is useful for testing and interacting with methods exposed by services on the D-Bus.

Example Output:

s "Hello, World!"

In the above example, the method “method_name” is called on the specified object, and the response is displayed as a string.

Conclusion

In this article, we explored eight different use cases of the “busctl” command. We covered monitoring the D-Bus bus, retrieving process information, dumping messages, exploring object trees, introspecting services or objects, fetching object property values, and invoking methods. These examples can help in understanding and troubleshooting the D-Bus communication between different services.