2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.5//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
4 <!-- SPDX-License-Identifier: LGPL-2.1+ -->
7 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
11 <productname>systemd
</productname>
15 <refentrytitle>busctl
</refentrytitle>
16 <manvolnum>1</manvolnum>
20 <refname>busctl
</refname>
21 <refpurpose>Introspect the bus
</refpurpose>
26 <command>busctl
</command>
27 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
28 <arg choice=
"opt">COMMAND
</arg>
29 <arg choice=
"opt" rep=
"repeat"><replaceable>NAME
</replaceable></arg>
34 <title>Description
</title>
36 <para><command>busctl
</command> may be used to
37 introspect and monitor the D-Bus bus.
</para>
41 <title>Options
</title>
43 <para>The following options are understood:
</para>
47 <term><option>--address=
<replaceable>ADDRESS
</replaceable></option></term>
49 <listitem><para>Connect to the bus specified by
50 <replaceable>ADDRESS
</replaceable> instead of using suitable
51 defaults for either the system or user bus (see
52 <option>--system
</option> and
<option>--user
</option>
53 options).
</para></listitem>
57 <term><option>--show-machine
</option></term>
59 <listitem><para>When showing the list of peers, show a
60 column containing the names of containers they belong to.
62 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
67 <term><option>--unique
</option></term>
69 <listitem><para>When showing the list of peers, show only
70 "unique" names (of the form
71 <literal>:
<replaceable>number
</replaceable>.
<replaceable>number
</replaceable></literal>).
76 <term><option>--acquired
</option></term>
78 <listitem><para>The opposite of
<option>--unique
</option> —
79 only
"well-known" names will be shown.
</para></listitem>
83 <term><option>--activatable
</option></term>
85 <listitem><para>When showing the list of peers, show only
86 peers which have actually not been activated yet, but may be
87 started automatically if accessed.
</para>
92 <term><option>--match=
<replaceable>MATCH
</replaceable></option></term>
94 <listitem><para>When showing messages being exchanged, show only the
95 subset matching
<replaceable>MATCH
</replaceable>.
97 <citerefentry><refentrytitle>sd_bus_add_match
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
102 <term><option>--size=
</option></term>
105 <para>When used with the
<command>capture
</command> command,
106 specifies the maximum bus message size to capture
107 (
"snaplen"). Defaults to
4096 bytes.
</para>
112 <term><option>--list
</option></term>
115 <para>When used with the
<command>tree
</command> command, shows a
116 flat list of object paths instead of a tree.
</para>
121 <term><option>-q
</option></term>
122 <term><option>--quiet
</option></term>
125 <para>When used with the
<command>call
</command> command,
126 suppresses display of the response message payload. Note that even
127 if this option is specified, errors returned will still be
128 printed and the tool will indicate success or failure with
129 the process exit code.
</para>
134 <term><option>--verbose
</option></term>
137 <para>When used with the
<command>call
</command> or
138 <command>get-property
</command> command, shows output in a
139 more verbose format.
</para>
144 <term><option>--xml-interface
</option></term>
147 <para>When used with the
<command>introspect
</command> call, dump the XML description received from
148 the D-Bus
<constant>org.freedesktop.DBus.Introspectable.Introspect
</constant> call instead of the
149 normal output.
</para>
154 <term><option>--json=
</option><replaceable>MODE
</replaceable></term>
157 <para>When used with the
<command>call
</command> or
<command>get-property
</command> command, shows output
158 formatted as JSON. Expects one of
<literal>short
</literal> (for the shortest possible output without any
159 redundant whitespace or line breaks) or
<literal>pretty
</literal> (for a pretty version of the same, with
160 indentation and line breaks). Note that transformation from D-Bus marshalling to JSON is done in a loss-less
161 way, which means type information is embedded into the JSON object tree.
</para>
166 <term><option>-j
</option></term>
169 <para>Equivalent to
<option>--json=pretty
</option> when invoked interactively from a terminal. Otherwise
170 equivalent to
<option>--json=short
</option>, in particular when the output is piped to some other
176 <term><option>--expect-reply=
</option><replaceable>BOOL
</replaceable></term>
179 <para>When used with the
<command>call
</command> command,
180 specifies whether
<command>busctl
</command> shall wait for
181 completion of the method call, output the returned method
182 response data, and return success or failure via the process
183 exit code. If this is set to
<literal>no
</literal>, the
184 method call will be issued but no response is expected, the
185 tool terminates immediately, and thus no response can be
186 shown, and no success or failure is returned via the exit
187 code. To only suppress output of the reply message payload,
188 use
<option>--quiet
</option> above. Defaults to
189 <literal>yes
</literal>.
</para>
194 <term><option>--auto-start=
</option><replaceable>BOOL
</replaceable></term>
197 <para>When used with the
<command>call
</command> or
<command>emit
</command> command, specifies
198 whether the method call should implicitly activate the
199 called service, should it not be running yet but is
200 configured to be auto-started. Defaults to
201 <literal>yes
</literal>.
</para>
206 <term><option>--allow-interactive-authorization=
</option><replaceable>BOOL
</replaceable></term>
209 <para>When used with the
<command>call
</command> command,
210 specifies whether the services may enforce interactive
211 authorization while executing the operation, if the security
212 policy is configured for this. Defaults to
213 <literal>yes
</literal>.
</para>
218 <term><option>--timeout=
</option><replaceable>SECS
</replaceable></term>
221 <para>When used with the
<command>call
</command> command,
222 specifies the maximum time to wait for method call
223 completion. If no time unit is specified, assumes
224 seconds. The usual other units are understood, too (ms, us,
225 s, min, h, d, w, month, y). Note that this timeout does not
226 apply if
<option>--expect-reply=no
</option> is used, as the
227 tool does not wait for any reply message then. When not
228 specified or when set to
0, the default of
229 <literal>25s
</literal> is assumed.
</para>
234 <term><option>--augment-creds=
</option><replaceable>BOOL
</replaceable></term>
237 <para>Controls whether credential data reported by
238 <command>list
</command> or
<command>status
</command> shall
239 be augmented with data from
240 <filename>/proc
</filename>. When this is turned on, the data
241 shown is possibly inconsistent, as the data read from
242 <filename>/proc
</filename> might be more recent than the rest of
243 the credential information. Defaults to
<literal>yes
</literal>.
</para>
248 <term><option>--watch-bind=
</option><replaceable>BOOL
</replaceable></term>
251 <para>Controls whether to wait for the specified
<constant>AF_UNIX
</constant> bus socket to appear in the
252 file system before connecting to it. Defaults to off. When enabled, the tool will watch the file system until
253 the socket is created and then connect to it.
</para>
258 <term><option>--destination=
</option><replaceable>SERVICE
</replaceable></term>
261 <para>Takes a service name. When used with the
<command>emit
</command> command, a signal is
262 emitted to the specified service.
</para>
266 <xi:include href=
"user-system-options.xml" xpointer=
"user" />
267 <xi:include href=
"user-system-options.xml" xpointer=
"system" />
268 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
269 <xi:include href=
"user-system-options.xml" xpointer=
"machine" />
271 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
272 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
273 <xi:include href=
"standard-options.xml" xpointer=
"help" />
274 <xi:include href=
"standard-options.xml" xpointer=
"version" />
279 <title>Commands
</title>
281 <para>The following commands are understood:
</para>
285 <term><command>list
</command></term>
287 <listitem><para>Show all peers on the bus, by their service
288 names. By default, shows both unique and well-known names, but
289 this may be changed with the
<option>--unique
</option> and
290 <option>--acquired
</option> switches. This is the default
291 operation if no command is specified.
</para></listitem>
295 <term><command>status
</command> <arg choice=
"opt"><replaceable>SERVICE
</replaceable></arg></term>
297 <listitem><para>Show process information and credentials of a
298 bus service (if one is specified by its unique or well-known
299 name), a process (if one is specified by its numeric PID), or
300 the owner of the bus (if no parameter is
301 specified).
</para></listitem>
305 <term><command>monitor
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
307 <listitem><para>Dump messages being exchanged. If
308 <replaceable>SERVICE
</replaceable> is specified, show messages
309 to or from this peer, identified by its well-known or unique
310 name. Otherwise, show all messages on the bus. Use
311 <keycombo><keycap>Ctrl
</keycap><keycap>C
</keycap></keycombo>
312 to terminate the dump.
</para></listitem>
316 <term><command>capture
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
318 <listitem><para>Similar to
<command>monitor
</command> but
319 writes the output in pcap format (for details, see the
<ulink
320 url=
"https://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap
321 File Format
</ulink> description). Make sure to redirect
322 standard output to a file. Tools like
323 <citerefentry project='die-net'
><refentrytitle>wireshark
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
324 may be used to dissect and view the resulting
325 files.
</para></listitem>
329 <term><command>tree
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
331 <listitem><para>Shows an object tree of one or more
332 services. If
<replaceable>SERVICE
</replaceable> is specified,
333 show object tree of the specified services only. Otherwise,
334 show all object trees of all services on the bus that acquired
335 at least one well-known name.
</para></listitem>
339 <term><command>introspect
</command> <arg choice=
"plain"><replaceable>SERVICE
</replaceable></arg> <arg choice=
"plain"><replaceable>OBJECT
</replaceable></arg> <arg choice=
"opt"><replaceable>INTERFACE
</replaceable></arg></term>
341 <listitem><para>Show interfaces, methods, properties and
342 signals of the specified object (identified by its path) on
343 the specified service. If the interface argument is passed, the
344 output is limited to members of the specified
345 interface.
</para></listitem>
349 <term><command>call
</command> <arg choice=
"plain"><replaceable>SERVICE
</replaceable></arg> <arg choice=
"plain"><replaceable>OBJECT
</replaceable></arg> <arg choice=
"plain"><replaceable>INTERFACE
</replaceable></arg> <arg choice=
"plain"><replaceable>METHOD
</replaceable></arg> <arg choice=
"opt"><replaceable>SIGNATURE
</replaceable> <arg choice=
"opt" rep=
"repeat"><replaceable>ARGUMENT
</replaceable></arg></arg></term>
351 <listitem><para>Invoke a method and show the response. Takes a
352 service name, object path, interface name and method name. If
353 parameters shall be passed to the method call, a signature
354 string is required, followed by the arguments, individually
355 formatted as strings. For details on the formatting used, see
356 below. To suppress output of the returned data, use the
357 <option>--quiet
</option> option.
</para></listitem>
361 <term><command>emit
</command> <arg choice=
"plain"><replaceable>OBJECT
</replaceable></arg> <arg choice=
"plain"><replaceable>INTERFACE
</replaceable></arg> <arg choice=
"plain"><replaceable>SIGNAL
</replaceable></arg> <arg choice=
"opt"><replaceable>SIGNATURE
</replaceable> <arg choice=
"opt" rep=
"repeat"><replaceable>ARGUMENT
</replaceable></arg></arg></term>
363 <listitem><para>Emit a signal. Takes a object path, interface name and method name. If parameters
364 shall be passed, a signature string is required, followed by the arguments, individually formatted as
365 strings. For details on the formatting used, see below. To specify the destination of the signal,
366 use the
<option>--destination=
</option> option.
</para></listitem>
370 <term><command>get-property
</command> <arg choice=
"plain"><replaceable>SERVICE
</replaceable></arg> <arg choice=
"plain"><replaceable>OBJECT
</replaceable></arg> <arg choice=
"plain"><replaceable>INTERFACE
</replaceable></arg> <arg choice=
"plain" rep=
"repeat"><replaceable>PROPERTY
</replaceable></arg></term>
372 <listitem><para>Retrieve the current value of one or more
373 object properties. Takes a service name, object path,
374 interface name and property name. Multiple properties may be
375 specified at once, in which case their values will be shown one
376 after the other, separated by newlines. The output is, by
377 default, in terse format. Use
<option>--verbose
</option> for a
378 more elaborate output format.
</para></listitem>
382 <term><command>set-property
</command> <arg choice=
"plain"><replaceable>SERVICE
</replaceable></arg> <arg choice=
"plain"><replaceable>OBJECT
</replaceable></arg> <arg choice=
"plain"><replaceable>INTERFACE
</replaceable></arg> <arg choice=
"plain"><replaceable>PROPERTY
</replaceable></arg> <arg choice=
"plain"><replaceable>SIGNATURE
</replaceable></arg> <arg choice=
"plain" rep=
"repeat"><replaceable>ARGUMENT
</replaceable></arg></term>
384 <listitem><para>Set the current value of an object
385 property. Takes a service name, object path, interface name,
386 property name, property signature, followed by a list of
387 parameters formatted as strings.
</para></listitem>
391 <term><command>help
</command></term>
393 <listitem><para>Show command syntax help.
</para></listitem>
399 <title>Parameter Formatting
</title>
401 <para>The
<command>call
</command> and
402 <command>set-property
</command> commands take a signature string
403 followed by a list of parameters formatted as string (for details
404 on D-Bus signature strings, see the
<ulink
405 url=
"http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">Type
406 system chapter of the D-Bus specification
</ulink>). For simple
407 types, each parameter following the signature should simply be the
408 parameter's value formatted as string. Positive boolean values may
409 be formatted as
<literal>true
</literal>,
<literal>yes
</literal>,
410 <literal>on
</literal>, or
<literal>1</literal>; negative boolean
411 values may be specified as
<literal>false
</literal>,
412 <literal>no
</literal>,
<literal>off
</literal>, or
413 <literal>0</literal>. For arrays, a numeric argument for the
414 number of entries followed by the entries shall be specified. For
415 variants, the signature of the contents shall be specified,
416 followed by the contents. For dictionaries and structs, the
417 contents of them shall be directly specified.
</para>
420 <programlisting>s jawoll
</programlisting> is the formatting
421 of a single string
<literal>jawoll
</literal>.
</para>
424 <programlisting>as
3 hello world foobar
</programlisting>
425 is the formatting of a string array with three entries,
426 <literal>hello
</literal>,
<literal>world
</literal> and
427 <literal>foobar
</literal>.
</para>
430 <programlisting>a{sv}
3 One s Eins Two u
2 Yes b true
</programlisting>
431 is the formatting of a dictionary
432 array that maps strings to variants, consisting of three
433 entries. The string
<literal>One
</literal> is assigned the
434 string
<literal>Eins
</literal>. The string
435 <literal>Two
</literal> is assigned the
32-bit unsigned
436 integer
2. The string
<literal>Yes
</literal> is assigned a
437 positive boolean.
</para>
439 <para>Note that the
<command>call
</command>,
440 <command>get-property
</command>,
<command>introspect
</command>
441 commands will also generate output in this format for the returned
442 data. Since this format is sometimes too terse to be easily
443 understood, the
<command>call
</command> and
444 <command>get-property
</command> commands may generate a more
445 verbose, multi-line output when passed the
446 <option>--verbose
</option> option.
</para>
450 <title>Examples
</title>
453 <title>Write and Read a Property
</title>
455 <para>The following two commands first write a property and then
456 read it back. The property is found on the
457 <literal>/org/freedesktop/systemd1
</literal> object of the
458 <literal>org.freedesktop.systemd1
</literal> service. The name of
459 the property is
<literal>LogLevel
</literal> on the
460 <literal>org.freedesktop.systemd1.Manager
</literal>
461 interface. The property contains a single string:
</para>
463 <programlisting># busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
464 # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
465 s
"debug"</programlisting>
470 <title>Terse and Verbose Output
</title>
472 <para>The following two commands read a property that contains
473 an array of strings, and first show it in terse format, followed
474 by verbose format:
</para>
476 <programlisting>$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
477 as
2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
478 $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
480 STRING
"LANG=en_US.UTF-8";
481 STRING
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
486 <title>Invoking a Method
</title>
488 <para>The following command invokes the
489 <literal>StartUnit
</literal> method on the
490 <literal>org.freedesktop.systemd1.Manager
</literal>
492 <literal>/org/freedesktop/systemd1
</literal> object
493 of the
<literal>org.freedesktop.systemd1
</literal>
494 service, and passes it two strings
495 <literal>cups.service
</literal> and
496 <literal>replace
</literal>. As a result of the method
497 call, a single object path parameter is received and
500 <programlisting># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss
"cups.service" "replace"
501 o
"/org/freedesktop/systemd1/job/42684"</programlisting>
506 <title>See Also
</title>
509 <citerefentry project='dbus'
><refentrytitle>dbus-daemon
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
510 <ulink url=
"https://www.freedesktop.org/wiki/Software/dbus">D-Bus
</ulink>,
511 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
512 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
513 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
514 <citerefentry project='die-net'
><refentrytitle>wireshark
</refentrytitle><manvolnum>1</manvolnum></citerefentry>