1 <?xml version='
1.0'
?> <!--*- Mode: nxml; nxml-child-indent: 2; indent-tabs-mode: nil -*-->
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+
8 This file is part of systemd.
10 Copyright 2014 Zbigniew Jędrzejewski-Szmek
12 systemd is free software; you can redistribute it and/or modify it
13 under the terms of the GNU Lesser General Public License as published by
14 the Free Software Foundation; either version 2.1 of the License, or
15 (at your option) any later version.
17 systemd is distributed in the hope that it will be useful, but
18 WITHOUT ANY WARRANTY; without even the implied warranty of
19 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
20 Lesser General Public License for more details.
22 You should have received a copy of the GNU Lesser General Public License
23 along with systemd; If not, see <http://www.gnu.org/licenses/>.
27 xmlns:
xi=
"http://www.w3.org/2001/XInclude">
31 <productname>systemd
</productname>
35 <contrib>A monkey with a typewriter
</contrib>
36 <firstname>Zbigniew
</firstname>
37 <surname>Jędrzejewski-Szmek
</surname>
38 <email>zbyszek@in.waw.pl
</email>
44 <refentrytitle>busctl
</refentrytitle>
45 <manvolnum>1</manvolnum>
49 <refname>busctl
</refname>
50 <refpurpose>Introspect the bus
</refpurpose>
55 <command>busctl
</command>
56 <arg choice=
"opt" rep=
"repeat">OPTIONS
</arg>
57 <arg choice=
"opt">COMMAND
</arg>
58 <arg choice=
"opt" rep=
"repeat"><replaceable>NAME
</replaceable></arg>
63 <title>Description
</title>
65 <para><command>busctl
</command> may be used to
66 introspect and monitor the D-Bus bus.
</para>
70 <title>Options
</title>
72 <para>The following options are understood:
</para>
76 <term><option>--address=
<replaceable>ADDRESS
</replaceable></option></term>
78 <listitem><para>Connect to the bus specified by
79 <replaceable>ADDRESS
</replaceable> instead of using suitable
80 defaults for either the system or user bus (see
81 <option>--system
</option> and
<option>--user
</option>
82 options).
</para></listitem>
86 <term><option>--show-machine
</option></term>
88 <listitem><para>When showing the list of peers, show a
89 column containing the names of containers they belong to.
91 <citerefentry><refentrytitle>systemd-machined.service
</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
96 <term><option>--unique
</option></term>
98 <listitem><para>When showing the list of peers, show only
99 "unique" names (of the form
100 <literal>:
<replaceable>number
</replaceable>.
<replaceable>number
</replaceable></literal>).
105 <term><option>--acquired
</option></term>
107 <listitem><para>The opposite of
<option>--unique
</option> —
108 only
"well-known" names will be shown.
</para></listitem>
112 <term><option>--activatable
</option></term>
114 <listitem><para>When showing the list of peers, show only
115 peers which have actually not been activated yet, but may be
116 started automatically if accessed.
</para>
121 <term><option>--match=
<replaceable>MATCH
</replaceable></option></term>
123 <listitem><para>When showing messages being exchanged, show only the
124 subset matching
<replaceable>MATCH
</replaceable>.
126 <citerefentry><refentrytitle>sd_bus_add_match
</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
131 <term><option>--size=
</option></term>
134 <para>When used with the
<command>capture
</command> command,
135 specifies the maximum bus message size to capture
136 (
"snaplen"). Defaults to
4096 bytes.
</para>
141 <term><option>--list
</option></term>
144 <para>When used with the
<command>tree
</command> command, shows a
145 flat list of object paths instead of a tree.
</para>
150 <term><option>--quiet
</option></term>
153 <para>When used with the
<command>call
</command> command,
154 suppresses display of the response message payload. Note that even
155 if this option is specified, errors returned will still be
156 printed and the tool will indicate success or failure with
157 the process exit code.
</para>
162 <term><option>--verbose
</option></term>
165 <para>When used with the
<command>call
</command> or
166 <command>get-property
</command> command, shows output in a
167 more verbose format.
</para>
172 <term><option>--expect-reply=
</option><replaceable>BOOL
</replaceable></term>
175 <para>When used with the
<command>call
</command> command,
176 specifies whether
<command>busctl
</command> shall wait for
177 completion of the method call, output the returned method
178 response data, and return success or failure via the process
179 exit code. If this is set to
<literal>no
</literal>, the
180 method call will be issued but no response is expected, the
181 tool terminates immediately, and thus no response can be
182 shown, and no success or failure is returned via the exit
183 code. To only suppress output of the reply message payload,
184 use
<option>--quiet
</option> above. Defaults to
185 <literal>yes
</literal>.
</para>
190 <term><option>--auto-start=
</option><replaceable>BOOL
</replaceable></term>
193 <para>When used with the
<command>call
</command> command, specifies
194 whether the method call should implicitly activate the
195 called service, should it not be running yet but is
196 configured to be auto-started. Defaults to
197 <literal>yes
</literal>.
</para>
202 <term><option>--allow-interactive-authorization=
</option><replaceable>BOOL
</replaceable></term>
205 <para>When used with the
<command>call
</command> command,
206 specifies whether the services may enforce interactive
207 authorization while executing the operation, if the security
208 policy is configured for this. Defaults to
209 <literal>yes
</literal>.
</para>
214 <term><option>--timeout=
</option><replaceable>SECS
</replaceable></term>
217 <para>When used with the
<command>call
</command> command,
218 specifies the maximum time to wait for method call
219 completion. If no time unit is specified, assumes
220 seconds. The usual other units are understood, too (ms, us,
221 s, min, h, d, w, month, y). Note that this timeout does not
222 apply if
<option>--expect-reply=no
</option> is used, as the
223 tool does not wait for any reply message then. When not
224 specified or when set to
0, the default of
225 <literal>25s
</literal> is assumed.
</para>
230 <term><option>--augment-creds=
</option><replaceable>BOOL
</replaceable></term>
233 <para>Controls whether credential data reported by
234 <command>list
</command> or
<command>status
</command> shall
235 be augmented with data from
236 <filename>/proc
</filename>. When this is turned on, the data
237 shown is possibly inconsistent, as the data read from
238 <filename>/proc
</filename> might be more recent than the rest of
239 the credential information. Defaults to
<literal>yes
</literal>.
</para>
243 <xi:include href=
"user-system-options.xml" xpointer=
"user" />
244 <xi:include href=
"user-system-options.xml" xpointer=
"system" />
245 <xi:include href=
"user-system-options.xml" xpointer=
"host" />
246 <xi:include href=
"user-system-options.xml" xpointer=
"machine" />
248 <xi:include href=
"standard-options.xml" xpointer=
"no-pager" />
249 <xi:include href=
"standard-options.xml" xpointer=
"no-legend" />
250 <xi:include href=
"standard-options.xml" xpointer=
"help" />
251 <xi:include href=
"standard-options.xml" xpointer=
"version" />
256 <title>Commands
</title>
258 <para>The following commands are understood:
</para>
262 <term><command>list
</command></term>
264 <listitem><para>Show all peers on the bus, by their service
265 names. By default, shows both unique and well-known names, but
266 this may be changed with the
<option>--unique
</option> and
267 <option>--acquired
</option> switches. This is the default
268 operation if no command is specified.
</para></listitem>
272 <term><command>status
</command> <arg choice=
"opt"><replaceable>SERVICE
</replaceable></arg></term>
274 <listitem><para>Show process information and credentials of a
275 bus service (if one is specified by its unique or well-known
276 name), a process (if one is specified by its numeric PID), or
277 the owner of the bus (if no parameter is
278 specified).
</para></listitem>
282 <term><command>monitor
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
284 <listitem><para>Dump messages being exchanged. If
285 <replaceable>SERVICE
</replaceable> is specified, show messages
286 to or from this peer, identified by its well-known or unique
287 name. Otherwise, show all messages on the bus. Use Ctrl-C to
288 terminate the dump.
</para></listitem>
292 <term><command>capture
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
294 <listitem><para>Similar to
<command>monitor
</command> but
295 writes the output in pcap format (for details, see the
<ulink
296 url=
"https://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap
297 File Format
</ulink> description). Make sure to redirect
298 standard output to a file. Tools like
299 <citerefentry project='die-net'
><refentrytitle>wireshark
</refentrytitle><manvolnum>1</manvolnum></citerefentry>
300 may be used to dissect and view the resulting
301 files.
</para></listitem>
305 <term><command>tree
</command> <arg choice=
"opt" rep=
"repeat"><replaceable>SERVICE
</replaceable></arg></term>
307 <listitem><para>Shows an object tree of one or more
308 services. If
<replaceable>SERVICE
</replaceable> is specified,
309 show object tree of the specified services only. Otherwise,
310 show all object trees of all services on the bus that acquired
311 at least one well-known name.
</para></listitem>
315 <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>
317 <listitem><para>Show interfaces, methods, properties and
318 signals of the specified object (identified by its path) on
319 the specified service. If the interface argument is passed, the
320 output is limited to members of the specified
321 interface.
</para></listitem>
325 <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>
327 <listitem><para>Invoke a method and show the response. Takes a
328 service name, object path, interface name and method name. If
329 parameters shall be passed to the method call, a signature
330 string is required, followed by the arguments, individually
331 formatted as strings. For details on the formatting used, see
332 below. To suppress output of the returned data, use the
333 <option>--quiet
</option> option.
</para></listitem>
337 <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>
339 <listitem><para>Retrieve the current value of one or more
340 object properties. Takes a service name, object path,
341 interface name and property name. Multiple properties may be
342 specified at once, in which case their values will be shown one
343 after the other, separated by newlines. The output is, by
344 default, in terse format. Use
<option>--verbose
</option> for a
345 more elaborate output format.
</para></listitem>
349 <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>
351 <listitem><para>Set the current value of an object
352 property. Takes a service name, object path, interface name,
353 property name, property signature, followed by a list of
354 parameters formatted as strings.
</para></listitem>
358 <term><command>help
</command></term>
360 <listitem><para>Show command syntax help.
</para></listitem>
366 <title>Parameter Formatting
</title>
368 <para>The
<command>call
</command> and
369 <command>set-property
</command> commands take a signature string
370 followed by a list of parameters formatted as string (for details
371 on D-Bus signature strings, see the
<ulink
372 url=
"http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">Type
373 system chapter of the D-Bus specification
</ulink>). For simple
374 types, each parameter following the signature should simply be the
375 parameter's value formatted as string. Positive boolean values may
376 be formatted as
<literal>true
</literal>,
<literal>yes
</literal>,
377 <literal>on
</literal>, or
<literal>1</literal>; negative boolean
378 values may be specified as
<literal>false
</literal>,
379 <literal>no
</literal>,
<literal>off
</literal>, or
380 <literal>0</literal>. For arrays, a numeric argument for the
381 number of entries followed by the entries shall be specified. For
382 variants, the signature of the contents shall be specified,
383 followed by the contents. For dictionaries and structs, the
384 contents of them shall be directly specified.
</para>
387 <programlisting>s jawoll
</programlisting> is the formatting
388 of a single string
<literal>jawoll
</literal>.
</para>
391 <programlisting>as
3 hello world foobar
</programlisting>
392 is the formatting of a string array with three entries,
393 <literal>hello
</literal>,
<literal>world
</literal> and
394 <literal>foobar
</literal>.
</para>
397 <programlisting>a{sv}
3 One s Eins Two u
2 Yes b true
</programlisting>
398 is the formatting of a dictionary
399 array that maps strings to variants, consisting of three
400 entries. The string
<literal>One
</literal> is assigned the
401 string
<literal>Eins
</literal>. The string
402 <literal>Two
</literal> is assigned the
32-bit unsigned
403 integer
2. The string
<literal>Yes
</literal> is assigned a
404 positive boolean.
</para>
406 <para>Note that the
<command>call
</command>,
407 <command>get-property
</command>,
<command>introspect
</command>
408 commands will also generate output in this format for the returned
409 data. Since this format is sometimes too terse to be easily
410 understood, the
<command>call
</command> and
411 <command>get-property
</command> commands may generate a more
412 verbose, multi-line output when passed the
413 <option>--verbose
</option> option.
</para>
417 <title>Examples
</title>
420 <title>Write and Read a Property
</title>
422 <para>The following two commands first write a property and then
423 read it back. The property is found on the
424 <literal>/org/freedesktop/systemd1
</literal> object of the
425 <literal>org.freedesktop.systemd1
</literal> service. The name of
426 the property is
<literal>LogLevel
</literal> on the
427 <literal>org.freedesktop.systemd1.Manager
</literal>
428 interface. The property contains a single string:
</para>
430 <programlisting># busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
431 # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
432 s
"debug"</programlisting>
437 <title>Terse and Verbose Output
</title>
439 <para>The following two commands read a property that contains
440 an array of strings, and first show it in terse format, followed
441 by verbose format:
</para>
443 <programlisting>$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
444 as
2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
445 $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
447 STRING
"LANG=en_US.UTF-8";
448 STRING
"PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
453 <title>Invoking a Method
</title>
455 <para>The following command invokes the
456 <literal>StartUnit
</literal> method on the
457 <literal>org.freedesktop.systemd1.Manager
</literal>
459 <literal>/org/freedesktop/systemd1
</literal> object
460 of the
<literal>org.freedesktop.systemd1
</literal>
461 service, and passes it two strings
462 <literal>cups.service
</literal> and
463 <literal>replace
</literal>. As a result of the method
464 call, a single object path parameter is received and
467 <programlisting># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss
"cups.service" "replace"
468 o
"/org/freedesktop/systemd1/job/42684"</programlisting>
473 <title>See Also
</title>
476 <citerefentry project='dbus'
><refentrytitle>dbus-daemon
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
477 <ulink url=
"https://www.freedesktop.org/wiki/Software/dbus">D-Bus
</ulink>,
478 <citerefentry><refentrytitle>sd-bus
</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
479 <citerefentry><refentrytitle>systemd
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
480 <citerefentry><refentrytitle>machinectl
</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
481 <citerefentry project='die-net'
><refentrytitle>wireshark
</refentrytitle><manvolnum>1</manvolnum></citerefentry>