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>--expect-reply=
</option><replaceable>BOOL
</replaceable></term>
150 <para>When used with the
<command>call
</command> command,
151 specifies whether
<command>busctl
</command> shall wait for
152 completion of the method call, output the returned method
153 response data, and return success or failure via the process
154 exit code. If this is set to
<literal>no
</literal>, the
155 method call will be issued but no response is expected, the
156 tool terminates immediately, and thus no response can be
157 shown, and no success or failure is returned via the exit
158 code. To only suppress output of the reply message payload,
159 use
<option>--quiet
</option> above. Defaults to
160 <literal>yes
</literal>.
</para>
165 <term><option>--auto-start=
</option><replaceable>BOOL
</replaceable></term>
168 <para>When used with the
<command>call
</command> command, specifies
169 whether the method call should implicitly activate the
170 called service, should it not be running yet but is
171 configured to be auto-started. Defaults to
172 <literal>yes
</literal>.
</para>
177 <term><option>--allow-interactive-authorization=
</option><replaceable>BOOL
</replaceable></term>
180 <para>When used with the
<command>call
</command> command,
181 specifies whether the services may enforce interactive
182 authorization while executing the operation, if the security
183 policy is configured for this. Defaults to
184 <literal>yes
</literal>.
</para>
189 <term><option>--timeout=
</option><replaceable>SECS
</replaceable></term>
192 <para>When used with the
<command>call
</command> command,
193 specifies the maximum time to wait for method call
194 completion. If no time unit is specified, assumes
195 seconds. The usual other units are understood, too (ms, us,
196 s, min, h, d, w, month, y). Note that this timeout does not
197 apply if
<option>--expect-reply=no
</option> is used, as the
198 tool does not wait for any reply message then. When not
199 specified or when set to
0, the default of
200 <literal>25s
</literal> is assumed.
</para>
205 <term><option>--augment-creds=
</option><replaceable>BOOL
</replaceable></term>
208 <para>Controls whether credential data reported by
209 <command>list
</command> or
<command>status
</command> shall
210 be augmented with data from
211 <filename>/proc
</filename>. When this is turned on, the data
212 shown is possibly inconsistent, as the data read from
213 <filename>/proc
</filename> might be more recent than the rest of
214 the credential information. Defaults to
<literal>yes
</literal>.
</para>
219 <term><option>--watch-bind=
</option><replaceable>BOOL
</replaceable></term>
222 <para>Controls whether to wait for the specified
<constant>AF_UNIX
</constant> bus socket to appear in the
223 file system before connecting to it. Defaults to off. When enabled, the tool will watch the file system until
224 the socket is created and then connect to it.
</para>
228 <xi:include href=
"user-system-options.xml" xpointer=
"user" />
229 <xi:include href=
"user-system-options.xml" xpointer=
"system" />
230 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
231 <xi:include href=
"user-system-options.xml" xpointer=
"machine" />
233 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
234 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
235 <xi:include href=
"standard-options.xml" xpointer=
"help" />
236 <xi:include href=
"standard-options.xml" xpointer=
"version" />
241 <title>Commands
</title>
243 <para>The following commands are understood:
</para>
247 <term><command>list
</command></term>
249 <listitem><para>Show all peers on the bus, by their service
250 names. By default, shows both unique and well-known names, but
251 this may be changed with the
<option>--unique
</option> and
252 <option>--acquired
</option> switches. This is the default
253 operation if no command is specified.
</para></listitem>
257 <term><command>status
</command> <arg choice=
"opt"><replaceable>SERVICE
</replaceable></arg></term>
259 <listitem><para>Show process information and credentials of a
260 bus service (if one is specified by its unique or well-known
261 name), a process (if one is specified by its numeric PID), or
262 the owner of the bus (if no parameter is
263 specified).
</para></listitem>
267 <term><command>monitor
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
269 <listitem><para>Dump messages being exchanged. If
270 <replaceable>SERVICE
</replaceable> is specified, show messages
271 to or from this peer, identified by its well-known or unique
272 name. Otherwise, show all messages on the bus. Use Ctrl-C to
273 terminate the dump.
</para></listitem>
277 <term><command>capture
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
279 <listitem><para>Similar to
<command>monitor
</command> but
280 writes the output in pcap format (for details, see the
<ulink
281 url=
"https://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap
282 File Format
</ulink> description). Make sure to redirect
283 standard output to a file. Tools like
284 <citerefentry project='die-net'
><refentrytitle>wireshark
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
285 may be used to dissect and view the resulting
286 files.
</para></listitem>
290 <term><command>tree
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
292 <listitem><para>Shows an object tree of one or more
293 services. If
<replaceable>SERVICE
</replaceable> is specified,
294 show object tree of the specified services only. Otherwise,
295 show all object trees of all services on the bus that acquired
296 at least one well-known name.
</para></listitem>
300 <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>
302 <listitem><para>Show interfaces, methods, properties and
303 signals of the specified object (identified by its path) on
304 the specified service. If the interface argument is passed, the
305 output is limited to members of the specified
306 interface.
</para></listitem>
310 <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>
312 <listitem><para>Invoke a method and show the response. Takes a
313 service name, object path, interface name and method name. If
314 parameters shall be passed to the method call, a signature
315 string is required, followed by the arguments, individually
316 formatted as strings. For details on the formatting used, see
317 below. To suppress output of the returned data, use the
318 <option>--quiet
</option> option.
</para></listitem>
322 <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>
324 <listitem><para>Retrieve the current value of one or more
325 object properties. Takes a service name, object path,
326 interface name and property name. Multiple properties may be
327 specified at once, in which case their values will be shown one
328 after the other, separated by newlines. The output is, by
329 default, in terse format. Use
<option>--verbose
</option> for a
330 more elaborate output format.
</para></listitem>
334 <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>
336 <listitem><para>Set the current value of an object
337 property. Takes a service name, object path, interface name,
338 property name, property signature, followed by a list of
339 parameters formatted as strings.
</para></listitem>
343 <term><command>help
</command></term>
345 <listitem><para>Show command syntax help.
</para></listitem>
351 <title>Parameter Formatting
</title>
353 <para>The
<command>call
</command> and
354 <command>set-property
</command> commands take a signature string
355 followed by a list of parameters formatted as string (for details
356 on D-Bus signature strings, see the
<ulink
357 url=
"http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">Type
358 system chapter of the D-Bus specification
</ulink>). For simple
359 types, each parameter following the signature should simply be the
360 parameter's value formatted as string. Positive boolean values may
361 be formatted as
<literal>true
</literal>,
<literal>yes
</literal>,
362 <literal>on
</literal>, or
<literal>1</literal>; negative boolean
363 values may be specified as
<literal>false
</literal>,
364 <literal>no
</literal>,
<literal>off
</literal>, or
365 <literal>0</literal>. For arrays, a numeric argument for the
366 number of entries followed by the entries shall be specified. For
367 variants, the signature of the contents shall be specified,
368 followed by the contents. For dictionaries and structs, the
369 contents of them shall be directly specified.
</para>
372 <programlisting>s jawoll
</programlisting> is the formatting
373 of a single string
<literal>jawoll
</literal>.
</para>
376 <programlisting>as
3 hello world foobar
</programlisting>
377 is the formatting of a string array with three entries,
378 <literal>hello
</literal>,
<literal>world
</literal> and
379 <literal>foobar
</literal>.
</para>
382 <programlisting>a{sv}
3 One s Eins Two u
2 Yes b true
</programlisting>
383 is the formatting of a dictionary
384 array that maps strings to variants, consisting of three
385 entries. The string
<literal>One
</literal> is assigned the
386 string
<literal>Eins
</literal>. The string
387 <literal>Two
</literal> is assigned the
32-bit unsigned
388 integer
2. The string
<literal>Yes
</literal> is assigned a
389 positive boolean.
</para>
391 <para>Note that the
<command>call
</command>,
392 <command>get-property
</command>,
<command>introspect
</command>
393 commands will also generate output in this format for the returned
394 data. Since this format is sometimes too terse to be easily
395 understood, the
<command>call
</command> and
396 <command>get-property
</command> commands may generate a more
397 verbose, multi-line output when passed the
398 <option>--verbose
</option> option.
</para>
402 <title>Examples
</title>
405 <title>Write and Read a Property
</title>
407 <para>The following two commands first write a property and then
408 read it back. The property is found on the
409 <literal>/org/freedesktop/systemd1
</literal> object of the
410 <literal>org.freedesktop.systemd1
</literal> service. The name of
411 the property is
<literal>LogLevel
</literal> on the
412 <literal>org.freedesktop.systemd1.Manager
</literal>
413 interface. The property contains a single string:
</para>
415 <programlisting># busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
416 # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
417 s
"debug"</programlisting>
422 <title>Terse and Verbose Output
</title>
424 <para>The following two commands read a property that contains
425 an array of strings, and first show it in terse format, followed
426 by verbose format:
</para>
428 <programlisting>$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
429 as
2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
430 $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
432 STRING
"LANG=en_US.UTF-8";
433 STRING
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
438 <title>Invoking a Method
</title>
440 <para>The following command invokes the
441 <literal>StartUnit
</literal> method on the
442 <literal>org.freedesktop.systemd1.Manager
</literal>
444 <literal>/org/freedesktop/systemd1
</literal> object
445 of the
<literal>org.freedesktop.systemd1
</literal>
446 service, and passes it two strings
447 <literal>cups.service
</literal> and
448 <literal>replace
</literal>. As a result of the method
449 call, a single object path parameter is received and
452 <programlisting># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss
"cups.service" "replace"
453 o
"/org/freedesktop/systemd1/job/42684"</programlisting>
458 <title>See Also
</title>
461 <citerefentry project='dbus'
><refentrytitle>dbus-daemon
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
462 <ulink url=
"https://www.freedesktop.org/wiki/Software/dbus">D-Bus
</ulink>,
463 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
464 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
465 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
466 <citerefentry project='die-net'
><refentrytitle>wireshark
</refentrytitle><manvolnum>1</manvolnum></citerefentry>