BUSCTL(1)

🚌 NAME

okay so bestie, meet busctl — the Introspect the bus icon from the BUSCTL(1) manual. she's here to make D-Bus feel less like a cryptic group chat and more like a vibe you actually understand. 💅✨

---

📜 SYNOPSIS

busctl [OPTIONS...] [COMMAND] [NAME...]

---

💖 DESCRIPTION

busctl may be used to introspect and monitor the D-Bus bus. that's the whole assignment, and she ate. 🫶

---

🎀 COMMANDS

The following commands are understood:

🌸 list

Show all peers on the bus, by their service names. By default, shows both unique and well-known names, but this may be changed with the --unique and --acquired switches. This is the default operation if no command is specified.

Added in version 209.

🌟 status [SERVICE]

Show process information and credentials of a bus service (if one is specified by its unique or well-known name), a process (if one is specified by its numeric PID), or the owner of the bus (if no parameter is specified).

Added in version 209.

👀 monitor [SERVICE...]

Dump messages being exchanged. If SERVICE is specified, show messages to or from this peer, identified by its well-known or unique name. Otherwise, show all messages on the bus. Use Ctrl+C to terminate the dump or limit it with the --limit-messages= option.

Added in version 209.

🎥 capture [SERVICE...]

Similar to monitor but writes the output in pcapng format (for details, see PCAP Next Generation (pcapng) Capture File Format[1]). Make sure to redirect standard output to a file or pipe. Tools like wireshark(1) may be used to dissect and view the resulting files.

Added in version 218.

🌳 tree [SERVICE...]

Shows an object tree of one or more services. If SERVICE is specified, show object tree of the specified services only. Otherwise, show all object trees of all services on the bus that acquired at least one well-known name.

Added in version 218.

🔍 introspect SERVICE OBJECT [INTERFACE]

Show interfaces, methods, properties and signals of the specified object (identified by its path) on the specified service. If the interface argument is passed, the output is limited to members of the specified interface.

Added in version 218.

📞 call SERVICE OBJECT INTERFACE METHOD [SIGNATURE [ARGUMENT...]]

Invoke a method and show the response. Takes a service name, object path, interface name and method name. If parameters shall be passed to the method call, a signature string is required, followed by the arguments, individually formatted as strings. For details on the formatting used, see below. To suppress output of the returned data, use the --quiet option.

Added in version 218.

📣 emit OBJECT INTERFACE SIGNAL [SIGNATURE [ARGUMENT...]]

Emit a signal. Takes an object path, interface name and method name. If parameters shall be passed, a signature string is required, followed by the arguments, individually formatted as strings. For details on the formatting used, see below. To specify the destination of the signal, use the --destination= option.

Added in version 242.

⏳ wait [SERVICE] OBJECT INTERFACE SIGNAL

Wait for a signal. Takes an object path, interface name, and signal name. Use the --limit-messages= option to wait for more than just one signal before exiting. To suppress output of the returned data, use the --quiet option. The service name may be omitted, in which case busctl will match signals from any sender.

Added in version 257.

🍓 get-property SERVICE OBJECT INTERFACE PROPERTY...

Retrieve the current value of one or more object properties. Takes a service name, object path, interface name and property name. Multiple properties may be specified at once, in which case their values will be shown one after the other, separated by newlines. The output is, by default, in terse format. Use --verbose for a more elaborate output format.

Added in version 218.

💅 set-property SERVICE OBJECT INTERFACE PROPERTY SIGNATURE ARGUMENT...

Set the current value of an object property. Takes a service name, object path, interface name, property name, property signature, followed by a list of parameters formatted as strings.

Added in version 218.

🫶 help

Show command syntax help.

Added in version 209.

---

and that's the commands, bestie — the options are coming next and they're giving main character energy 💅✨

✨ OPTIONS ✨

okay bestie, here's the whole toolkit. every single one, no skipping 💅

• --address=ADDRESS — connect to the bus at ADDRESS instead of vibing with the default system-or-user bus (that's the --system / --user situation). Added in version 209.
• --show-machine — when you're listing peers, this pops in an extra column showing which containers they live in. peep systemd-machined.service(8) for the lore. Added in version 209.
• --unique — when listing peers, only show the "unique" names, aka the ones shaped like :number.number. Added in version 209.
• --acquired — the literal opposite of --unique, bestie. only "well-known" names get shown. Added in version 209.
• --activatable — when listing peers, only show the ones that haven't actually been activated yet but could auto-start if someone pokes them. Added in version 209.
• --match=MATCH — when showing messages being exchanged, only show the subset that matches MATCH. see sd_bus_add_match(3). Added in version 209.
• --size= — with the capture command, this sets the max bus message size to capture (the "snaplen", iconic name tbh). defaults to 4096 bytes. Added in version 218.
• --list — with the tree command, shows a flat list of object paths instead of the tree. Added in version 218.
• -q, --quiet — with the call command, suppresses showing the response message payload. but bestie, note this: even with --quiet, errors still get printed, and the tool still tells you success or failure via the process exit code. Added in version 218.
• --verbose — with the call or get-property command, gives you a more verbose output format. Added in version 218.
• --xml-interface — with the introspect call, dumps the XML description you got from the D-Bus org.freedesktop.DBus.Introspectable.Introspect call instead of the normal output. Added in version 243.
• --expect-reply=BOOL — with the call command, decides whether busctl waits for the method call to finish, prints the returned method response data, and reports success or failure through the process exit code. set it to "no" and the method call still goes out, but no response is expected — the tool terminates immediately, so no response can be shown and no success or failure comes back via the exit code. if you only wanna hide the reply payload, use --quiet up above instead. defaults to "yes". Added in version 218.
• --auto-start=BOOL — with the call or emit command, decides whether the method call should implicitly activate the called service when it's not running yet but is configured to auto-start. defaults to "yes". Added in version 218.
• --allow-interactive-authorization=BOOL — with the call command, decides whether services may enforce interactive authorization while doing the thing, if the security policy is set up for that. defaults to "yes". Added in version 218.
• --timeout=SECS — with the call command, this is the max time to wait for the method call to complete. with the monitor command, since version v257, it's the max time to wait for messages before auto-exiting. no time unit given? it assumes seconds. the usual other units are understood too: ms, us, s, min, h, d, w, month, y. note that this timeout does not apply if you're using --expect-reply=no together with the call command, because the tool isn't waiting for any reply then. when it's not specified, or set to 0, the default is "25s" for the call command, and it's disabled for the monitor command. Added in version 218.
• --limit-messages=NUMBER, -N NUMBER — with the monitor command, if enabled, makes busctl exit once it's received and printed that many messages. lowkey perfect combined with --match=, to wait for a specific number of occurrences of specific D-Bus messages. if it's not specified, or set to the special value "infinity", the default is to keep monitoring with zero limits.

with the wait command, it makes busctl exit once that many D-Bus signals have been received and printed. setting it to the special value "infinity" keeps busctl receiving and printing signals continuously, no limits. when nothing is specified, the default is to exit immediately after receiving and printing the first signal. Added in version 257.

• --augment-creds=BOOL — controls whether credential data reported by list or status gets augmented with data from /proc/. when this is on, the data shown can be inconsistent, because the stuff read from /proc/ might be more recent than the rest of the credential info. defaults to "yes". Added in version 218.
• --watch-bind=BOOL — controls whether to wait for the specified AF_UNIX bus socket to show up in the file system before connecting to it. defaults to off. turn it on and the tool watches the file system until the socket is created, then connects. Added in version 237.
• --destination=SERVICE — takes a service name. with the emit command, a signal is emitted to the specified service. Added in version 242.
• --user — talk to the service manager of the calling user, not the service manager of the system.
• --system — talk to the service manager of the system. this is the implied default, bestie.
• -H, --host= — run the operation remotely. give it a hostname, or a username and hostname separated by "@". the hostname can optionally have a port ssh is listening on suffixed with ":", and then a container name after a "/", which connects straight to a specific container on that host. this uses SSH to talk to the remote machine manager instance. container names can be enumerated with machinectl -H HOST. put IPv6 addresses in brackets.
• -M, --machine= — run the operation on a local container. give a container name to connect to, optionally prefixed by a username to connect as and a separating "@". if the special string ".host" is used instead of the container name, a connection to the local system is made (so useful for connecting to a specific user's user bus: "--user --machine=lennart@.host"). if the "@" syntax isn't used, the connection is made as root. if the "@" syntax is used, either the left side or the right side may be omitted (but not both), in which case the local username and ".host" are implied.
• -C, --capsule= — run the operation on a capsule. give a capsule name to connect to. see capsule@.service(5) for the deets on capsules. Added in version 256.
• -l, --full — don't ellipsize the output in the list command. Added in version 245.
• --json=MODE — shows output formatted as JSON. expects one of "short" (the shortest possible output, no redundant whitespace or line breaks), "pretty" (a pretty version of the same, with indentation and line breaks) or "off" (turns JSON output off — this is the default).
• -j — same as --json=pretty if you're running on a terminal, and --json=short otherwise.
• --no-pager — don't pipe output into a pager.
• --no-legend — don't print the legend, meaning the column headers and the footer with hints.
• -h, --help — print a short help text and exit.
• --version — print a short version string and exit.

---

🌸 PARAMETER FORMATTING 🌸

okay so the call and set-property commands take a signature string followed by a list of parameters formatted as string (for the deets on D-Bus signature strings, see the Type system chapter of the D-Bus specification[2]). for simple types, each parameter after the signature should just be the parameter's value formatted as string. positive boolean values may be formatted as "true", "yes", "on", or "1"; negative boolean values may be given as "false", "no", "off", or "0". for arrays, you give a numeric argument for the number of entries followed by the entries. for variants, you give the signature of the contents, followed by the contents. for dictionaries and structs, you just directly give the contents of them.

for example,

s jawoll

is the formatting of a single string "jawoll". 💖

as 3 hello world foobar

is the formatting of a string array with three entries, "hello", "world" and "foobar".

a{sv} 3 One s Eins Two u 2 Yes b true

is the formatting of a dictionary array that maps strings to variants, with three entries. the string "One" is assigned the string "Eins". the string "Two" is assigned the 32-bit unsigned integer 2. the string "Yes" is assigned a positive boolean.

note that the call, get-property, and introspect commands will also generate output in this format for the returned data. and since this format is sometimes too terse to easily understand, the call and get-property commands may generate a more verbose, multi-line output when you pass the --verbose option. ✨

🎀 EXAMPLES 🎀

okok this is the part where it all clicks, bestie. real commands, real output, no cap. ✨

---

🌸 Example 1. Write and Read a Property 🌸

so the vibe here is: we write a property, then we read it right back. iconic little one-two punch. 💅

where does this property live? on the /org/freedesktop/systemd1 object, of the org.freedesktop.systemd1 service. its name is LogLevel, and it sits on the org.freedesktop.systemd1.Manager interface. and it's holding exactly one string. one. single. string. 🎀

# busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
# busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
s "debug"

see that s "debug"? that's the read-back, confirming she ate. 💖

---

🦋 Example 2. Terse and Verbose Output 🦋

okay now this one is about aesthetics. same property, two different lewks. the property here holds an array of strings, and we're gonna see it first in terse format, then in verbose format:

$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
$ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
ARRAY "s" {
        STRING "LANG=en_US.UTF-8";
        STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
};

terse is giving minimal. verbose is giving main character energy, all nested and structured and pretty. both valid, both slay. 🫶

---

💜 Example 3. Invoking a Method 💜

last one, and it's a method call, the moment we've all been waiting for. 👑

this command invokes the StartUnit method on the org.freedesktop.systemd1.Manager interface of the /org/freedesktop/systemd1 object of the org.freedesktop.systemd1 service, and it hands over two strings: "cups.service" and "replace". then, because the method call actually did something, we get back a single object path parameter, and it gets shown to us:

# busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
o "/org/freedesktop/systemd1/job/42684"

that o "/org/freedesktop/systemd1/job/42684"? that's the job object path, bestie. she's real, she's out there, she's doing the work. 🔥

---

🌈 SEE ALSO 🌈

go read these too, iykyk, the lore is deep:

• dbus-daemon(1)
• D-Bus[3]
• sd-bus(3)
• varlinkctl(1)
• systemd(1)
• machinectl(1)
• wireshark(1)

---

📝 NOTES 📝

1. PCAP Next Generation (pcapng) Capture File Format https://github.com/pcapng/pcapng/
2. Type system chapter of the D-Bus specification https://dbus.freedesktop.org/doc/dbus-specification.html#type-system
3. D-Bus https://www.freedesktop.org/wiki/Software/dbus

---

aaaand that's the whole page, you made it, so proud of you fr fr 😭💖 this little beauty ships with systemd 262.1 — shoutout to the systemd girlies who wrote her, absolute legends, no notes. now go busctl something and tell me all about it. bye bestie! 🎀✨💅