2 <!DOCTYPE refentry PUBLIC
"-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 SPDX-License-Identifier: LGPL-2.1+
10 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
14 <productname>systemd
</productname>
18 <refentrytitle>busctl
</refentrytitle>
19 <manvolnum>1</manvolnum>
23 <refname>busctl
</refname>
24 <refpurpose>Introspect the bus
</refpurpose>
29 <command>busctl
</command>
30 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
31 <arg choice=
"opt">COMMAND
</arg>
32 <arg choice=
"opt" rep=
"repeat"><replaceable>NAME
</replaceable></arg>
37 <title>Description
</title>
39 <para><command>busctl
</command> may be used to
40 introspect and monitor the D-Bus bus.
</para>
44 <title>Options
</title>
46 <para>The following options are understood:
</para>
50 <term><option>--address=
<replaceable>ADDRESS
</replaceable></option></term>
52 <listitem><para>Connect to the bus specified by
53 <replaceable>ADDRESS
</replaceable> instead of using suitable
54 defaults for either the system or user bus (see
55 <option>--system
</option> and
<option>--user
</option>
56 options).
</para></listitem>
60 <term><option>--show-machine
</option></term>
62 <listitem><para>When showing the list of peers, show a
63 column containing the names of containers they belong to.
65 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
70 <term><option>--unique
</option></term>
72 <listitem><para>When showing the list of peers, show only
73 "unique" names (of the form
74 <literal>:
<replaceable>number
</replaceable>.
<replaceable>number
</replaceable></literal>).
79 <term><option>--acquired
</option></term>
81 <listitem><para>The opposite of
<option>--unique
</option> —
82 only
"well-known" names will be shown.
</para></listitem>
86 <term><option>--activatable
</option></term>
88 <listitem><para>When showing the list of peers, show only
89 peers which have actually not been activated yet, but may be
90 started automatically if accessed.
</para>
95 <term><option>--match=
<replaceable>MATCH
</replaceable></option></term>
97 <listitem><para>When showing messages being exchanged, show only the
98 subset matching
<replaceable>MATCH
</replaceable>.
100 <citerefentry><refentrytitle>sd_bus_add_match
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
105 <term><option>--size=
</option></term>
108 <para>When used with the
<command>capture
</command> command,
109 specifies the maximum bus message size to capture
110 (
"snaplen"). Defaults to
4096 bytes.
</para>
115 <term><option>--list
</option></term>
118 <para>When used with the
<command>tree
</command> command, shows a
119 flat list of object paths instead of a tree.
</para>
124 <term><option>-q
</option></term>
125 <term><option>--quiet
</option></term>
128 <para>When used with the
<command>call
</command> command,
129 suppresses display of the response message payload. Note that even
130 if this option is specified, errors returned will still be
131 printed and the tool will indicate success or failure with
132 the process exit code.
</para>
137 <term><option>--verbose
</option></term>
140 <para>When used with the
<command>call
</command> or
141 <command>get-property
</command> command, shows output in a
142 more verbose format.
</para>
147 <term><option>--json=
</option><replaceable>MODE
</replaceable></term>
150 <para>When used with the
<command>call
</command> or
<command>get-property
</command> command, shows output
151 formatted as JSON. Expects one of
<literal>short
</literal> (for the shortest possible output without any
152 redundant whitespace or line breaks) or
<literal>pretty
</literal> (for a pretty version of the same, with
153 indentation and line breaks). Note that transformation from D-Bus marshalling to JSON is done in a loss-less
154 way, which means type information is embedded into the JSON object tree.
</para>
159 <term><option>-j
</option></term>
162 <para>Equivalent to
<option>--json=pretty
</option> when invoked interactively from a terminal. Otherwise
163 equivalent to
<option>--json=short
</option>, in particular when the output is piped to some other
169 <term><option>--expect-reply=
</option><replaceable>BOOL
</replaceable></term>
172 <para>When used with the
<command>call
</command> command,
173 specifies whether
<command>busctl
</command> shall wait for
174 completion of the method call, output the returned method
175 response data, and return success or failure via the process
176 exit code. If this is set to
<literal>no
</literal>, the
177 method call will be issued but no response is expected, the
178 tool terminates immediately, and thus no response can be
179 shown, and no success or failure is returned via the exit
180 code. To only suppress output of the reply message payload,
181 use
<option>--quiet
</option> above. Defaults to
182 <literal>yes
</literal>.
</para>
187 <term><option>--auto-start=
</option><replaceable>BOOL
</replaceable></term>
190 <para>When used with the
<command>call
</command> or
<command>emit
</command> command, specifies
191 whether the method call should implicitly activate the
192 called service, should it not be running yet but is
193 configured to be auto-started. Defaults to
194 <literal>yes
</literal>.
</para>
199 <term><option>--allow-interactive-authorization=
</option><replaceable>BOOL
</replaceable></term>
202 <para>When used with the
<command>call
</command> command,
203 specifies whether the services may enforce interactive
204 authorization while executing the operation, if the security
205 policy is configured for this. Defaults to
206 <literal>yes
</literal>.
</para>
211 <term><option>--timeout=
</option><replaceable>SECS
</replaceable></term>
214 <para>When used with the
<command>call
</command> command,
215 specifies the maximum time to wait for method call
216 completion. If no time unit is specified, assumes
217 seconds. The usual other units are understood, too (ms, us,
218 s, min, h, d, w, month, y). Note that this timeout does not
219 apply if
<option>--expect-reply=no
</option> is used, as the
220 tool does not wait for any reply message then. When not
221 specified or when set to
0, the default of
222 <literal>25s
</literal> is assumed.
</para>
227 <term><option>--augment-creds=
</option><replaceable>BOOL
</replaceable></term>
230 <para>Controls whether credential data reported by
231 <command>list
</command> or
<command>status
</command> shall
232 be augmented with data from
233 <filename>/proc
</filename>. When this is turned on, the data
234 shown is possibly inconsistent, as the data read from
235 <filename>/proc
</filename> might be more recent than the rest of
236 the credential information. Defaults to
<literal>yes
</literal>.
</para>
241 <term><option>--watch-bind=
</option><replaceable>BOOL
</replaceable></term>
244 <para>Controls whether to wait for the specified
<constant>AF_UNIX
</constant> bus socket to appear in the
245 file system before connecting to it. Defaults to off. When enabled, the tool will watch the file system until
246 the socket is created and then connect to it.
</para>
251 <term><option>--destination=
</option><replaceable>SERVICE
</replaceable></term>
254 <para>Takes a service name. When used with the
<command>emit
</command> command, a signal is
255 emitted to the specified service.
</para>
259 <xi:include href=
"user-system-options.xml" xpointer=
"user" />
260 <xi:include href=
"user-system-options.xml" xpointer=
"system" />
261 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
262 <xi:include href=
"user-system-options.xml" xpointer=
"machine" />
264 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
265 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
266 <xi:include href=
"standard-options.xml" xpointer=
"help" />
267 <xi:include href=
"standard-options.xml" xpointer=
"version" />
272 <title>Commands
</title>
274 <para>The following commands are understood:
</para>
278 <term><command>list
</command></term>
280 <listitem><para>Show all peers on the bus, by their service
281 names. By default, shows both unique and well-known names, but
282 this may be changed with the
<option>--unique
</option> and
283 <option>--acquired
</option> switches. This is the default
284 operation if no command is specified.
</para></listitem>
288 <term><command>status
</command> <arg choice=
"opt"><replaceable>SERVICE
</replaceable></arg></term>
290 <listitem><para>Show process information and credentials of a
291 bus service (if one is specified by its unique or well-known
292 name), a process (if one is specified by its numeric PID), or
293 the owner of the bus (if no parameter is
294 specified).
</para></listitem>
298 <term><command>monitor
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
300 <listitem><para>Dump messages being exchanged. If
301 <replaceable>SERVICE
</replaceable> is specified, show messages
302 to or from this peer, identified by its well-known or unique
303 name. Otherwise, show all messages on the bus. Use
304 <keycombo><keycap>Ctrl
</keycap><keycap>C
</keycap></keycombo>
305 to terminate the dump.
</para></listitem>
309 <term><command>capture
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
311 <listitem><para>Similar to
<command>monitor
</command> but
312 writes the output in pcap format (for details, see the
<ulink
313 url=
"https://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap
314 File Format
</ulink> description). Make sure to redirect
315 standard output to a file. Tools like
316 <citerefentry project='die-net'
><refentrytitle>wireshark
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
317 may be used to dissect and view the resulting
318 files.
</para></listitem>
322 <term><command>tree
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
324 <listitem><para>Shows an object tree of one or more
325 services. If
<replaceable>SERVICE
</replaceable> is specified,
326 show object tree of the specified services only. Otherwise,
327 show all object trees of all services on the bus that acquired
328 at least one well-known name.
</para></listitem>
332 <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>
334 <listitem><para>Show interfaces, methods, properties and
335 signals of the specified object (identified by its path) on
336 the specified service. If the interface argument is passed, the
337 output is limited to members of the specified
338 interface.
</para></listitem>
342 <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>
344 <listitem><para>Invoke a method and show the response. Takes a
345 service name, object path, interface name and method name. If
346 parameters shall be passed to the method call, a signature
347 string is required, followed by the arguments, individually
348 formatted as strings. For details on the formatting used, see
349 below. To suppress output of the returned data, use the
350 <option>--quiet
</option> option.
</para></listitem>
354 <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>
356 <listitem><para>Emit a signal. Takes a object path, interface name and method name. If parameters
357 shall be passed, a signature string is required, followed by the arguments, individually formatted as
358 strings. For details on the formatting used, see below. To specify the destination of the signal,
359 use the
<option>--destination=
</option> option.
</para></listitem>
363 <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>
365 <listitem><para>Retrieve the current value of one or more
366 object properties. Takes a service name, object path,
367 interface name and property name. Multiple properties may be
368 specified at once, in which case their values will be shown one
369 after the other, separated by newlines. The output is, by
370 default, in terse format. Use
<option>--verbose
</option> for a
371 more elaborate output format.
</para></listitem>
375 <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>
377 <listitem><para>Set the current value of an object
378 property. Takes a service name, object path, interface name,
379 property name, property signature, followed by a list of
380 parameters formatted as strings.
</para></listitem>
384 <term><command>help
</command></term>
386 <listitem><para>Show command syntax help.
</para></listitem>
392 <title>Parameter Formatting
</title>
394 <para>The
<command>call
</command> and
395 <command>set-property
</command> commands take a signature string
396 followed by a list of parameters formatted as string (for details
397 on D-Bus signature strings, see the
<ulink
398 url=
"http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">Type
399 system chapter of the D-Bus specification
</ulink>). For simple
400 types, each parameter following the signature should simply be the
401 parameter's value formatted as string. Positive boolean values may
402 be formatted as
<literal>true
</literal>,
<literal>yes
</literal>,
403 <literal>on
</literal>, or
<literal>1</literal>; negative boolean
404 values may be specified as
<literal>false
</literal>,
405 <literal>no
</literal>,
<literal>off
</literal>, or
406 <literal>0</literal>. For arrays, a numeric argument for the
407 number of entries followed by the entries shall be specified. For
408 variants, the signature of the contents shall be specified,
409 followed by the contents. For dictionaries and structs, the
410 contents of them shall be directly specified.
</para>
413 <programlisting>s jawoll
</programlisting> is the formatting
414 of a single string
<literal>jawoll
</literal>.
</para>
417 <programlisting>as
3 hello world foobar
</programlisting>
418 is the formatting of a string array with three entries,
419 <literal>hello
</literal>,
<literal>world
</literal> and
420 <literal>foobar
</literal>.
</para>
423 <programlisting>a{sv}
3 One s Eins Two u
2 Yes b true
</programlisting>
424 is the formatting of a dictionary
425 array that maps strings to variants, consisting of three
426 entries. The string
<literal>One
</literal> is assigned the
427 string
<literal>Eins
</literal>. The string
428 <literal>Two
</literal> is assigned the
32-bit unsigned
429 integer
2. The string
<literal>Yes
</literal> is assigned a
430 positive boolean.
</para>
432 <para>Note that the
<command>call
</command>,
433 <command>get-property
</command>,
<command>introspect
</command>
434 commands will also generate output in this format for the returned
435 data. Since this format is sometimes too terse to be easily
436 understood, the
<command>call
</command> and
437 <command>get-property
</command> commands may generate a more
438 verbose, multi-line output when passed the
439 <option>--verbose
</option> option.
</para>
443 <title>Examples
</title>
446 <title>Write and Read a Property
</title>
448 <para>The following two commands first write a property and then
449 read it back. The property is found on the
450 <literal>/org/freedesktop/systemd1
</literal> object of the
451 <literal>org.freedesktop.systemd1
</literal> service. The name of
452 the property is
<literal>LogLevel
</literal> on the
453 <literal>org.freedesktop.systemd1.Manager
</literal>
454 interface. The property contains a single string:
</para>
456 <programlisting># busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
457 # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
458 s
"debug"</programlisting>
463 <title>Terse and Verbose Output
</title>
465 <para>The following two commands read a property that contains
466 an array of strings, and first show it in terse format, followed
467 by verbose format:
</para>
469 <programlisting>$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
470 as
2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
471 $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
473 STRING
"LANG=en_US.UTF-8";
474 STRING
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
479 <title>Invoking a Method
</title>
481 <para>The following command invokes the
482 <literal>StartUnit
</literal> method on the
483 <literal>org.freedesktop.systemd1.Manager
</literal>
485 <literal>/org/freedesktop/systemd1
</literal> object
486 of the
<literal>org.freedesktop.systemd1
</literal>
487 service, and passes it two strings
488 <literal>cups.service
</literal> and
489 <literal>replace
</literal>. As a result of the method
490 call, a single object path parameter is received and
493 <programlisting># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss
"cups.service" "replace"
494 o
"/org/freedesktop/systemd1/job/42684"</programlisting>
499 <title>See Also
</title>
502 <citerefentry project='dbus'
><refentrytitle>dbus-daemon
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
503 <ulink url=
"https://www.freedesktop.org/wiki/Software/dbus">D-Bus
</ulink>,
504 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
505 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
506 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
507 <citerefentry project='die-net'
><refentrytitle>wireshark
</refentrytitle><manvolnum>1</manvolnum></citerefentry>