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>--json=
</option><replaceable>MODE
</replaceable></term>
147 <para>When used with the
<command>call
</command> or
<command>get-property
</command> command, shows output
148 formatted as JSON. Expects one of
<literal>short
</literal> (for the shortest possible output without any
149 redundant whitespace or line breaks) or
<literal>pretty
</literal> (for a pretty version of the same, with
150 indentation and line breaks). Note that transformation from D-Bus marshalling to JSON is done in a loss-less
151 way, which means type information is embedded into the JSON object tree.
</para>
156 <term><option>-j
</option></term>
159 <para>Equivalent to
<option>--json=pretty
</option> when invoked interactively from a terminal. Otherwise
160 equivalent to
<option>--json=short
</option>, in particular when the output is piped to some other
166 <term><option>--expect-reply=
</option><replaceable>BOOL
</replaceable></term>
169 <para>When used with the
<command>call
</command> command,
170 specifies whether
<command>busctl
</command> shall wait for
171 completion of the method call, output the returned method
172 response data, and return success or failure via the process
173 exit code. If this is set to
<literal>no
</literal>, the
174 method call will be issued but no response is expected, the
175 tool terminates immediately, and thus no response can be
176 shown, and no success or failure is returned via the exit
177 code. To only suppress output of the reply message payload,
178 use
<option>--quiet
</option> above. Defaults to
179 <literal>yes
</literal>.
</para>
184 <term><option>--auto-start=
</option><replaceable>BOOL
</replaceable></term>
187 <para>When used with the
<command>call
</command> or
<command>emit
</command> command, specifies
188 whether the method call should implicitly activate the
189 called service, should it not be running yet but is
190 configured to be auto-started. Defaults to
191 <literal>yes
</literal>.
</para>
196 <term><option>--allow-interactive-authorization=
</option><replaceable>BOOL
</replaceable></term>
199 <para>When used with the
<command>call
</command> command,
200 specifies whether the services may enforce interactive
201 authorization while executing the operation, if the security
202 policy is configured for this. Defaults to
203 <literal>yes
</literal>.
</para>
208 <term><option>--timeout=
</option><replaceable>SECS
</replaceable></term>
211 <para>When used with the
<command>call
</command> command,
212 specifies the maximum time to wait for method call
213 completion. If no time unit is specified, assumes
214 seconds. The usual other units are understood, too (ms, us,
215 s, min, h, d, w, month, y). Note that this timeout does not
216 apply if
<option>--expect-reply=no
</option> is used, as the
217 tool does not wait for any reply message then. When not
218 specified or when set to
0, the default of
219 <literal>25s
</literal> is assumed.
</para>
224 <term><option>--augment-creds=
</option><replaceable>BOOL
</replaceable></term>
227 <para>Controls whether credential data reported by
228 <command>list
</command> or
<command>status
</command> shall
229 be augmented with data from
230 <filename>/proc
</filename>. When this is turned on, the data
231 shown is possibly inconsistent, as the data read from
232 <filename>/proc
</filename> might be more recent than the rest of
233 the credential information. Defaults to
<literal>yes
</literal>.
</para>
238 <term><option>--watch-bind=
</option><replaceable>BOOL
</replaceable></term>
241 <para>Controls whether to wait for the specified
<constant>AF_UNIX
</constant> bus socket to appear in the
242 file system before connecting to it. Defaults to off. When enabled, the tool will watch the file system until
243 the socket is created and then connect to it.
</para>
248 <term><option>--destination=
</option><replaceable>SERVICE
</replaceable></term>
251 <para>Takes a service name. When used with the
<command>emit
</command> command, a signal is
252 emitted to the specified service.
</para>
256 <xi:include href=
"user-system-options.xml" xpointer=
"user" />
257 <xi:include href=
"user-system-options.xml" xpointer=
"system" />
258 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
259 <xi:include href=
"user-system-options.xml" xpointer=
"machine" />
261 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
262 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
263 <xi:include href=
"standard-options.xml" xpointer=
"help" />
264 <xi:include href=
"standard-options.xml" xpointer=
"version" />
269 <title>Commands
</title>
271 <para>The following commands are understood:
</para>
275 <term><command>list
</command></term>
277 <listitem><para>Show all peers on the bus, by their service
278 names. By default, shows both unique and well-known names, but
279 this may be changed with the
<option>--unique
</option> and
280 <option>--acquired
</option> switches. This is the default
281 operation if no command is specified.
</para></listitem>
285 <term><command>status
</command> <arg choice=
"opt"><replaceable>SERVICE
</replaceable></arg></term>
287 <listitem><para>Show process information and credentials of a
288 bus service (if one is specified by its unique or well-known
289 name), a process (if one is specified by its numeric PID), or
290 the owner of the bus (if no parameter is
291 specified).
</para></listitem>
295 <term><command>monitor
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
297 <listitem><para>Dump messages being exchanged. If
298 <replaceable>SERVICE
</replaceable> is specified, show messages
299 to or from this peer, identified by its well-known or unique
300 name. Otherwise, show all messages on the bus. Use
301 <keycombo><keycap>Ctrl
</keycap><keycap>C
</keycap></keycombo>
302 to terminate the dump.
</para></listitem>
306 <term><command>capture
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
308 <listitem><para>Similar to
<command>monitor
</command> but
309 writes the output in pcap format (for details, see the
<ulink
310 url=
"https://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap
311 File Format
</ulink> description). Make sure to redirect
312 standard output to a file. Tools like
313 <citerefentry project='die-net'
><refentrytitle>wireshark
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
314 may be used to dissect and view the resulting
315 files.
</para></listitem>
319 <term><command>tree
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
321 <listitem><para>Shows an object tree of one or more
322 services. If
<replaceable>SERVICE
</replaceable> is specified,
323 show object tree of the specified services only. Otherwise,
324 show all object trees of all services on the bus that acquired
325 at least one well-known name.
</para></listitem>
329 <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>
331 <listitem><para>Show interfaces, methods, properties and
332 signals of the specified object (identified by its path) on
333 the specified service. If the interface argument is passed, the
334 output is limited to members of the specified
335 interface.
</para></listitem>
339 <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>
341 <listitem><para>Invoke a method and show the response. Takes a
342 service name, object path, interface name and method name. If
343 parameters shall be passed to the method call, a signature
344 string is required, followed by the arguments, individually
345 formatted as strings. For details on the formatting used, see
346 below. To suppress output of the returned data, use the
347 <option>--quiet
</option> option.
</para></listitem>
351 <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>
353 <listitem><para>Emit a signal. Takes a object path, interface name and method name. If parameters
354 shall be passed, a signature string is required, followed by the arguments, individually formatted as
355 strings. For details on the formatting used, see below. To specify the destination of the signal,
356 use the
<option>--destination=
</option> option.
</para></listitem>
360 <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>
362 <listitem><para>Retrieve the current value of one or more
363 object properties. Takes a service name, object path,
364 interface name and property name. Multiple properties may be
365 specified at once, in which case their values will be shown one
366 after the other, separated by newlines. The output is, by
367 default, in terse format. Use
<option>--verbose
</option> for a
368 more elaborate output format.
</para></listitem>
372 <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>
374 <listitem><para>Set the current value of an object
375 property. Takes a service name, object path, interface name,
376 property name, property signature, followed by a list of
377 parameters formatted as strings.
</para></listitem>
381 <term><command>help
</command></term>
383 <listitem><para>Show command syntax help.
</para></listitem>
389 <title>Parameter Formatting
</title>
391 <para>The
<command>call
</command> and
392 <command>set-property
</command> commands take a signature string
393 followed by a list of parameters formatted as string (for details
394 on D-Bus signature strings, see the
<ulink
395 url=
"http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">Type
396 system chapter of the D-Bus specification
</ulink>). For simple
397 types, each parameter following the signature should simply be the
398 parameter's value formatted as string. Positive boolean values may
399 be formatted as
<literal>true
</literal>,
<literal>yes
</literal>,
400 <literal>on
</literal>, or
<literal>1</literal>; negative boolean
401 values may be specified as
<literal>false
</literal>,
402 <literal>no
</literal>,
<literal>off
</literal>, or
403 <literal>0</literal>. For arrays, a numeric argument for the
404 number of entries followed by the entries shall be specified. For
405 variants, the signature of the contents shall be specified,
406 followed by the contents. For dictionaries and structs, the
407 contents of them shall be directly specified.
</para>
410 <programlisting>s jawoll
</programlisting> is the formatting
411 of a single string
<literal>jawoll
</literal>.
</para>
414 <programlisting>as
3 hello world foobar
</programlisting>
415 is the formatting of a string array with three entries,
416 <literal>hello
</literal>,
<literal>world
</literal> and
417 <literal>foobar
</literal>.
</para>
420 <programlisting>a{sv}
3 One s Eins Two u
2 Yes b true
</programlisting>
421 is the formatting of a dictionary
422 array that maps strings to variants, consisting of three
423 entries. The string
<literal>One
</literal> is assigned the
424 string
<literal>Eins
</literal>. The string
425 <literal>Two
</literal> is assigned the
32-bit unsigned
426 integer
2. The string
<literal>Yes
</literal> is assigned a
427 positive boolean.
</para>
429 <para>Note that the
<command>call
</command>,
430 <command>get-property
</command>,
<command>introspect
</command>
431 commands will also generate output in this format for the returned
432 data. Since this format is sometimes too terse to be easily
433 understood, the
<command>call
</command> and
434 <command>get-property
</command> commands may generate a more
435 verbose, multi-line output when passed the
436 <option>--verbose
</option> option.
</para>
440 <title>Examples
</title>
443 <title>Write and Read a Property
</title>
445 <para>The following two commands first write a property and then
446 read it back. The property is found on the
447 <literal>/org/freedesktop/systemd1
</literal> object of the
448 <literal>org.freedesktop.systemd1
</literal> service. The name of
449 the property is
<literal>LogLevel
</literal> on the
450 <literal>org.freedesktop.systemd1.Manager
</literal>
451 interface. The property contains a single string:
</para>
453 <programlisting># busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
454 # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
455 s
"debug"</programlisting>
460 <title>Terse and Verbose Output
</title>
462 <para>The following two commands read a property that contains
463 an array of strings, and first show it in terse format, followed
464 by verbose format:
</para>
466 <programlisting>$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
467 as
2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
468 $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
470 STRING
"LANG=en_US.UTF-8";
471 STRING
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
476 <title>Invoking a Method
</title>
478 <para>The following command invokes the
479 <literal>StartUnit
</literal> method on the
480 <literal>org.freedesktop.systemd1.Manager
</literal>
482 <literal>/org/freedesktop/systemd1
</literal> object
483 of the
<literal>org.freedesktop.systemd1
</literal>
484 service, and passes it two strings
485 <literal>cups.service
</literal> and
486 <literal>replace
</literal>. As a result of the method
487 call, a single object path parameter is received and
490 <programlisting># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss
"cups.service" "replace"
491 o
"/org/freedesktop/systemd1/job/42684"</programlisting>
496 <title>See Also
</title>
499 <citerefentry project='dbus'
><refentrytitle>dbus-daemon
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
500 <ulink url=
"https://www.freedesktop.org/wiki/Software/dbus">D-Bus
</ulink>,
501 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
502 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
503 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
504 <citerefentry project='die-net'
><refentrytitle>wireshark
</refentrytitle><manvolnum>1</manvolnum></citerefentry>