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-or-later -->
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>Commands</title>
43 <para>The following commands are understood:</para>
47 <term><command>list</command></term>
49 <listitem><para>Show all peers on the bus, by their service
50 names. By default, shows both unique and well-known names, but
51 this may be changed with the <option>--unique</option> and
52 <option>--acquired</option> switches. This is the default
53 operation if no command is specified.</para>
55 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
59 <term><command>status</command> <arg choice="opt"><replaceable>SERVICE</replaceable></arg></term>
61 <listitem><para>Show process information and credentials of a
62 bus service (if one is specified by its unique or well-known
63 name), a process (if one is specified by its numeric PID), or
64 the owner of the bus (if no parameter is
67 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
71 <term><command>monitor</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
73 <listitem><para>Dump messages being exchanged. If
74 <replaceable>SERVICE</replaceable> is specified, show messages
75 to or from this peer, identified by its well-known or unique
76 name. Otherwise, show all messages on the bus. Use
77 <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
78 to terminate the dump.</para>
80 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
84 <term><command>capture</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
86 <listitem><para>Similar to <command>monitor</command> but
87 writes the output in pcapng format (for details, see
88 <ulink url="https://github.com/pcapng/pcapng/">
89 PCAP Next Generation (pcapng) Capture File Format</ulink>).
90 Make sure to redirect standard output to a file or pipe. Tools like
91 <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>
92 may be used to dissect and view the resulting
95 <xi:include href="version-info.xml" xpointer="v218"/></listitem>
99 <term><command>tree</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
101 <listitem><para>Shows an object tree of one or more
102 services. If <replaceable>SERVICE</replaceable> is specified,
103 show object tree of the specified services only. Otherwise,
104 show all object trees of all services on the bus that acquired
105 at least one well-known name.</para>
107 <xi:include href="version-info.xml" xpointer="v218"/></listitem>
111 <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>
113 <listitem><para>Show interfaces, methods, properties and
114 signals of the specified object (identified by its path) on
115 the specified service. If the interface argument is passed, the
116 output is limited to members of the specified
119 <xi:include href="version-info.xml" xpointer="v218"/></listitem>
123 <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>
125 <listitem><para>Invoke a method and show the response. Takes a
126 service name, object path, interface name and method name. If
127 parameters shall be passed to the method call, a signature
128 string is required, followed by the arguments, individually
129 formatted as strings. For details on the formatting used, see
130 below. To suppress output of the returned data, use the
131 <option>--quiet</option> option.</para>
133 <xi:include href="version-info.xml" xpointer="v218"/></listitem>
137 <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>
139 <listitem><para>Emit a signal. Takes an object path, interface name and method name. If parameters
140 shall be passed, a signature string is required, followed by the arguments, individually formatted as
141 strings. For details on the formatting used, see below. To specify the destination of the signal,
142 use the <option>--destination=</option> option.</para>
144 <xi:include href="version-info.xml" xpointer="v242"/></listitem>
148 <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>
150 <listitem><para>Retrieve the current value of one or more
151 object properties. Takes a service name, object path,
152 interface name and property name. Multiple properties may be
153 specified at once, in which case their values will be shown one
154 after the other, separated by newlines. The output is, by
155 default, in terse format. Use <option>--verbose</option> for a
156 more elaborate output format.</para>
158 <xi:include href="version-info.xml" xpointer="v218"/></listitem>
162 <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>
164 <listitem><para>Set the current value of an object
165 property. Takes a service name, object path, interface name,
166 property name, property signature, followed by a list of
167 parameters formatted as strings.</para>
169 <xi:include href="version-info.xml" xpointer="v218"/></listitem>
173 <term><command>help</command></term>
175 <listitem><para>Show command syntax help.</para>
177 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
183 <title>Options</title>
185 <para>The following options are understood:</para>
189 <term><option>--address=<replaceable>ADDRESS</replaceable></option></term>
191 <listitem><para>Connect to the bus specified by
192 <replaceable>ADDRESS</replaceable> instead of using suitable
193 defaults for either the system or user bus (see
194 <option>--system</option> and <option>--user</option>
197 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
201 <term><option>--show-machine</option></term>
203 <listitem><para>When showing the list of peers, show a
204 column containing the names of containers they belong to.
206 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
209 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
213 <term><option>--unique</option></term>
215 <listitem><para>When showing the list of peers, show only
216 "unique" names (of the form
217 <literal>:<replaceable>number</replaceable>.<replaceable>number</replaceable></literal>).
220 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
224 <term><option>--acquired</option></term>
226 <listitem><para>The opposite of <option>--unique</option> —
227 only "well-known" names will be shown.</para>
229 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
233 <term><option>--activatable</option></term>
235 <listitem><para>When showing the list of peers, show only
236 peers which have actually not been activated yet, but may be
237 started automatically if accessed.</para>
239 <xi:include href="version-info.xml" xpointer="v209"/>
244 <term><option>--match=<replaceable>MATCH</replaceable></option></term>
246 <listitem><para>When showing messages being exchanged, show only the
247 subset matching <replaceable>MATCH</replaceable>.
249 <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
252 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
256 <term><option>--size=</option></term>
259 <para>When used with the <command>capture</command> command,
260 specifies the maximum bus message size to capture
261 ("snaplen"). Defaults to 4096 bytes.</para>
263 <xi:include href="version-info.xml" xpointer="v218"/>
268 <term><option>--list</option></term>
271 <para>When used with the <command>tree</command> command, shows a
272 flat list of object paths instead of a tree.</para>
274 <xi:include href="version-info.xml" xpointer="v218"/>
279 <term><option>-q</option></term>
280 <term><option>--quiet</option></term>
283 <para>When used with the <command>call</command> command,
284 suppresses display of the response message payload. Note that even
285 if this option is specified, errors returned will still be
286 printed and the tool will indicate success or failure with
287 the process exit code.</para>
289 <xi:include href="version-info.xml" xpointer="v218"/>
294 <term><option>--verbose</option></term>
297 <para>When used with the <command>call</command> or
298 <command>get-property</command> command, shows output in a
299 more verbose format.</para>
301 <xi:include href="version-info.xml" xpointer="v218"/>
306 <term><option>--xml-interface</option></term>
309 <para>When used with the <command>introspect</command> call, dump the XML description received from
310 the D-Bus <constant>org.freedesktop.DBus.Introspectable.Introspect</constant> call instead of the
311 normal output.</para>
313 <xi:include href="version-info.xml" xpointer="v243"/>
318 <term><option>--json=</option><replaceable>MODE</replaceable></term>
321 <para>When used with the <command>call</command> or <command>get-property</command> command, shows output
322 formatted as JSON. Expects one of <literal>short</literal> (for the shortest possible output without any
323 redundant whitespace or line breaks) or <literal>pretty</literal> (for a pretty version of the same, with
324 indentation and line breaks). Note that transformation from D-Bus marshalling to JSON is done in a loss-less
325 way, which means type information is embedded into the JSON object tree.</para>
327 <xi:include href="version-info.xml" xpointer="v240"/>
332 <term><option>-j</option></term>
335 <para>Equivalent to <option>--json=pretty</option> when invoked interactively from a terminal. Otherwise
336 equivalent to <option>--json=short</option>, in particular when the output is piped to some other
339 <xi:include href="version-info.xml" xpointer="v240"/>
344 <term><option>--expect-reply=</option><replaceable>BOOL</replaceable></term>
347 <para>When used with the <command>call</command> command,
348 specifies whether <command>busctl</command> shall wait for
349 completion of the method call, output the returned method
350 response data, and return success or failure via the process
351 exit code. If this is set to <literal>no</literal>, the
352 method call will be issued but no response is expected, the
353 tool terminates immediately, and thus no response can be
354 shown, and no success or failure is returned via the exit
355 code. To only suppress output of the reply message payload,
356 use <option>--quiet</option> above. Defaults to
357 <literal>yes</literal>.</para>
359 <xi:include href="version-info.xml" xpointer="v218"/>
364 <term><option>--auto-start=</option><replaceable>BOOL</replaceable></term>
367 <para>When used with the <command>call</command> or <command>emit</command> command, specifies
368 whether the method call should implicitly activate the
369 called service, should it not be running yet but is
370 configured to be auto-started. Defaults to
371 <literal>yes</literal>.</para>
373 <xi:include href="version-info.xml" xpointer="v218"/>
378 <term><option>--allow-interactive-authorization=</option><replaceable>BOOL</replaceable></term>
381 <para>When used with the <command>call</command> command,
382 specifies whether the services may enforce interactive
383 authorization while executing the operation, if the security
384 policy is configured for this. Defaults to
385 <literal>yes</literal>.</para>
387 <xi:include href="version-info.xml" xpointer="v218"/>
392 <term><option>--timeout=</option><replaceable>SECS</replaceable></term>
395 <para>When used with the <command>call</command> command,
396 specifies the maximum time to wait for method call
397 completion. If no time unit is specified, assumes
398 seconds. The usual other units are understood, too (ms, us,
399 s, min, h, d, w, month, y). Note that this timeout does not
400 apply if <option>--expect-reply=no</option> is used, as the
401 tool does not wait for any reply message then. When not
402 specified or when set to 0, the default of
403 <literal>25s</literal> is assumed.</para>
405 <xi:include href="version-info.xml" xpointer="v218"/>
410 <term><option>--augment-creds=</option><replaceable>BOOL</replaceable></term>
413 <para>Controls whether credential data reported by
414 <command>list</command> or <command>status</command> shall
415 be augmented with data from
416 <filename>/proc/</filename>. When this is turned on, the data
417 shown is possibly inconsistent, as the data read from
418 <filename>/proc/</filename> might be more recent than the rest of
419 the credential information. Defaults to <literal>yes</literal>.</para>
421 <xi:include href="version-info.xml" xpointer="v218"/>
426 <term><option>--watch-bind=</option><replaceable>BOOL</replaceable></term>
429 <para>Controls whether to wait for the specified <constant>AF_UNIX</constant> bus socket to appear in the
430 file system before connecting to it. Defaults to off. When enabled, the tool will watch the file system until
431 the socket is created and then connect to it.</para>
433 <xi:include href="version-info.xml" xpointer="v237"/>
438 <term><option>--destination=</option><replaceable>SERVICE</replaceable></term>
441 <para>Takes a service name. When used with the <command>emit</command> command, a signal is
442 emitted to the specified service.</para>
444 <xi:include href="version-info.xml" xpointer="v242"/>
448 <xi:include href="user-system-options.xml" xpointer="user" />
449 <xi:include href="user-system-options.xml" xpointer="system" />
450 <xi:include href="user-system-options.xml" xpointer="host" />
451 <xi:include href="user-system-options.xml" xpointer="machine" />
454 <term><option>-l</option></term>
455 <term><option>--full</option></term>
458 <para>Do not ellipsize the output in <command>list</command> command.</para>
460 <xi:include href="version-info.xml" xpointer="v245"/>
464 <xi:include href="standard-options.xml" xpointer="no-pager" />
465 <xi:include href="standard-options.xml" xpointer="no-legend" />
466 <xi:include href="standard-options.xml" xpointer="help" />
467 <xi:include href="standard-options.xml" xpointer="version" />
472 <title>Parameter Formatting</title>
474 <para>The <command>call</command> and
475 <command>set-property</command> commands take a signature string
476 followed by a list of parameters formatted as string (for details
477 on D-Bus signature strings, see the <ulink
478 url="https://dbus.freedesktop.org/doc/dbus-specification.html#type-system">Type
479 system chapter of the D-Bus specification</ulink>). For simple
480 types, each parameter following the signature should simply be the
481 parameter's value formatted as string. Positive boolean values may
482 be formatted as <literal>true</literal>, <literal>yes</literal>,
483 <literal>on</literal>, or <literal>1</literal>; negative boolean
484 values may be specified as <literal>false</literal>,
485 <literal>no</literal>, <literal>off</literal>, or
486 <literal>0</literal>. For arrays, a numeric argument for the
487 number of entries followed by the entries shall be specified. For
488 variants, the signature of the contents shall be specified,
489 followed by the contents. For dictionaries and structs, the
490 contents of them shall be directly specified.</para>
493 <programlisting>s jawoll</programlisting> is the formatting
494 of a single string <literal>jawoll</literal>.</para>
497 <programlisting>as 3 hello world foobar</programlisting>
498 is the formatting of a string array with three entries,
499 <literal>hello</literal>, <literal>world</literal> and
500 <literal>foobar</literal>.</para>
503 <programlisting>a{sv} 3 One s Eins Two u 2 Yes b true</programlisting>
504 is the formatting of a dictionary
505 array that maps strings to variants, consisting of three
506 entries. The string <literal>One</literal> is assigned the
507 string <literal>Eins</literal>. The string
508 <literal>Two</literal> is assigned the 32-bit unsigned
509 integer 2. The string <literal>Yes</literal> is assigned a
510 positive boolean.</para>
512 <para>Note that the <command>call</command>,
513 <command>get-property</command>, <command>introspect</command>
514 commands will also generate output in this format for the returned
515 data. Since this format is sometimes too terse to be easily
516 understood, the <command>call</command> and
517 <command>get-property</command> commands may generate a more
518 verbose, multi-line output when passed the
519 <option>--verbose</option> option.</para>
523 <title>Examples</title>
526 <title>Write and Read a Property</title>
528 <para>The following two commands first write a property and then
529 read it back. The property is found on the
530 <literal>/org/freedesktop/systemd1</literal> object of the
531 <literal>org.freedesktop.systemd1</literal> service. The name of
532 the property is <literal>LogLevel</literal> on the
533 <literal>org.freedesktop.systemd1.Manager</literal>
534 interface. The property contains a single string:</para>
536 <programlisting># busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
537 # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
538 s "debug"</programlisting>
543 <title>Terse and Verbose Output</title>
545 <para>The following two commands read a property that contains
546 an array of strings, and first show it in terse format, followed
547 by verbose format:</para>
549 <programlisting>$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
550 as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
551 $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
553 STRING "LANG=en_US.UTF-8";
554 STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
559 <title>Invoking a Method</title>
561 <para>The following command invokes the
562 <literal>StartUnit</literal> method on the
563 <literal>org.freedesktop.systemd1.Manager</literal>
565 <literal>/org/freedesktop/systemd1</literal> object
566 of the <literal>org.freedesktop.systemd1</literal>
567 service, and passes it two strings
568 <literal>cups.service</literal> and
569 <literal>replace</literal>. As a result of the method
570 call, a single object path parameter is received and
573 <programlisting># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
574 o "/org/freedesktop/systemd1/job/42684"</programlisting>
579 <title>See Also</title>
582 <citerefentry project='dbus'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
583 <ulink url="https://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
584 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
585 <citerefentry><refentrytitle>varlinkctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
586 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
587 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
588 <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>