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> 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>
250 <xi:include href=
"user-system-options.xml" xpointer=
"user" />
251 <xi:include href=
"user-system-options.xml" xpointer=
"system" />
252 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
253 <xi:include href=
"user-system-options.xml" xpointer=
"machine" />
255 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
256 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
257 <xi:include href=
"standard-options.xml" xpointer=
"help" />
258 <xi:include href=
"standard-options.xml" xpointer=
"version" />
263 <title>Commands
</title>
265 <para>The following commands are understood:
</para>
269 <term><command>list
</command></term>
271 <listitem><para>Show all peers on the bus, by their service
272 names. By default, shows both unique and well-known names, but
273 this may be changed with the
<option>--unique
</option> and
274 <option>--acquired
</option> switches. This is the default
275 operation if no command is specified.
</para></listitem>
279 <term><command>status
</command> <arg choice=
"opt"><replaceable>SERVICE
</replaceable></arg></term>
281 <listitem><para>Show process information and credentials of a
282 bus service (if one is specified by its unique or well-known
283 name), a process (if one is specified by its numeric PID), or
284 the owner of the bus (if no parameter is
285 specified).
</para></listitem>
289 <term><command>monitor
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
291 <listitem><para>Dump messages being exchanged. If
292 <replaceable>SERVICE
</replaceable> is specified, show messages
293 to or from this peer, identified by its well-known or unique
294 name. Otherwise, show all messages on the bus. Use Ctrl-C to
295 terminate the dump.
</para></listitem>
299 <term><command>capture
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
301 <listitem><para>Similar to
<command>monitor
</command> but
302 writes the output in pcap format (for details, see the
<ulink
303 url=
"https://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap
304 File Format
</ulink> description). Make sure to redirect
305 standard output to a file. Tools like
306 <citerefentry project='die-net'
><refentrytitle>wireshark
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
307 may be used to dissect and view the resulting
308 files.
</para></listitem>
312 <term><command>tree
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
314 <listitem><para>Shows an object tree of one or more
315 services. If
<replaceable>SERVICE
</replaceable> is specified,
316 show object tree of the specified services only. Otherwise,
317 show all object trees of all services on the bus that acquired
318 at least one well-known name.
</para></listitem>
322 <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>
324 <listitem><para>Show interfaces, methods, properties and
325 signals of the specified object (identified by its path) on
326 the specified service. If the interface argument is passed, the
327 output is limited to members of the specified
328 interface.
</para></listitem>
332 <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>
334 <listitem><para>Invoke a method and show the response. Takes a
335 service name, object path, interface name and method name. If
336 parameters shall be passed to the method call, a signature
337 string is required, followed by the arguments, individually
338 formatted as strings. For details on the formatting used, see
339 below. To suppress output of the returned data, use the
340 <option>--quiet
</option> option.
</para></listitem>
344 <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>
346 <listitem><para>Retrieve the current value of one or more
347 object properties. Takes a service name, object path,
348 interface name and property name. Multiple properties may be
349 specified at once, in which case their values will be shown one
350 after the other, separated by newlines. The output is, by
351 default, in terse format. Use
<option>--verbose
</option> for a
352 more elaborate output format.
</para></listitem>
356 <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>
358 <listitem><para>Set the current value of an object
359 property. Takes a service name, object path, interface name,
360 property name, property signature, followed by a list of
361 parameters formatted as strings.
</para></listitem>
365 <term><command>help
</command></term>
367 <listitem><para>Show command syntax help.
</para></listitem>
373 <title>Parameter Formatting
</title>
375 <para>The
<command>call
</command> and
376 <command>set-property
</command> commands take a signature string
377 followed by a list of parameters formatted as string (for details
378 on D-Bus signature strings, see the
<ulink
379 url=
"http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">Type
380 system chapter of the D-Bus specification
</ulink>). For simple
381 types, each parameter following the signature should simply be the
382 parameter's value formatted as string. Positive boolean values may
383 be formatted as
<literal>true
</literal>,
<literal>yes
</literal>,
384 <literal>on
</literal>, or
<literal>1</literal>; negative boolean
385 values may be specified as
<literal>false
</literal>,
386 <literal>no
</literal>,
<literal>off
</literal>, or
387 <literal>0</literal>. For arrays, a numeric argument for the
388 number of entries followed by the entries shall be specified. For
389 variants, the signature of the contents shall be specified,
390 followed by the contents. For dictionaries and structs, the
391 contents of them shall be directly specified.
</para>
394 <programlisting>s jawoll
</programlisting> is the formatting
395 of a single string
<literal>jawoll
</literal>.
</para>
398 <programlisting>as
3 hello world foobar
</programlisting>
399 is the formatting of a string array with three entries,
400 <literal>hello
</literal>,
<literal>world
</literal> and
401 <literal>foobar
</literal>.
</para>
404 <programlisting>a{sv}
3 One s Eins Two u
2 Yes b true
</programlisting>
405 is the formatting of a dictionary
406 array that maps strings to variants, consisting of three
407 entries. The string
<literal>One
</literal> is assigned the
408 string
<literal>Eins
</literal>. The string
409 <literal>Two
</literal> is assigned the
32-bit unsigned
410 integer
2. The string
<literal>Yes
</literal> is assigned a
411 positive boolean.
</para>
413 <para>Note that the
<command>call
</command>,
414 <command>get-property
</command>,
<command>introspect
</command>
415 commands will also generate output in this format for the returned
416 data. Since this format is sometimes too terse to be easily
417 understood, the
<command>call
</command> and
418 <command>get-property
</command> commands may generate a more
419 verbose, multi-line output when passed the
420 <option>--verbose
</option> option.
</para>
424 <title>Examples
</title>
427 <title>Write and Read a Property
</title>
429 <para>The following two commands first write a property and then
430 read it back. The property is found on the
431 <literal>/org/freedesktop/systemd1
</literal> object of the
432 <literal>org.freedesktop.systemd1
</literal> service. The name of
433 the property is
<literal>LogLevel
</literal> on the
434 <literal>org.freedesktop.systemd1.Manager
</literal>
435 interface. The property contains a single string:
</para>
437 <programlisting># busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
438 # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
439 s
"debug"</programlisting>
444 <title>Terse and Verbose Output
</title>
446 <para>The following two commands read a property that contains
447 an array of strings, and first show it in terse format, followed
448 by verbose format:
</para>
450 <programlisting>$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
451 as
2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
452 $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
454 STRING
"LANG=en_US.UTF-8";
455 STRING
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
460 <title>Invoking a Method
</title>
462 <para>The following command invokes the
463 <literal>StartUnit
</literal> method on the
464 <literal>org.freedesktop.systemd1.Manager
</literal>
466 <literal>/org/freedesktop/systemd1
</literal> object
467 of the
<literal>org.freedesktop.systemd1
</literal>
468 service, and passes it two strings
469 <literal>cups.service
</literal> and
470 <literal>replace
</literal>. As a result of the method
471 call, a single object path parameter is received and
474 <programlisting># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss
"cups.service" "replace"
475 o
"/org/freedesktop/systemd1/job/42684"</programlisting>
480 <title>See Also
</title>
483 <citerefentry project='dbus'
><refentrytitle>dbus-daemon
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
484 <ulink url=
"https://www.freedesktop.org/wiki/Software/dbus">D-Bus
</ulink>,
485 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
486 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
487 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
488 <citerefentry project='die-net'
><refentrytitle>wireshark
</refentrytitle><manvolnum>1</manvolnum></citerefentry>