]> git.ipfire.org Git - thirdparty/systemd.git/blob - man/busctl.xml
man: use <simplelist> for 'See also' sections
[thirdparty/systemd.git] / man / busctl.xml
1 <?xml version='1.0'?>
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-or-later -->
5
6 <refentry id="busctl"
7 xmlns:xi="http://www.w3.org/2001/XInclude">
8
9 <refentryinfo>
10 <title>busctl</title>
11 <productname>systemd</productname>
12 </refentryinfo>
13
14 <refmeta>
15 <refentrytitle>busctl</refentrytitle>
16 <manvolnum>1</manvolnum>
17 </refmeta>
18
19 <refnamediv>
20 <refname>busctl</refname>
21 <refpurpose>Introspect the bus</refpurpose>
22 </refnamediv>
23
24 <refsynopsisdiv>
25 <cmdsynopsis>
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>
30 </cmdsynopsis>
31 </refsynopsisdiv>
32
33 <refsect1>
34 <title>Description</title>
35
36 <para><command>busctl</command> may be used to
37 introspect and monitor the D-Bus bus.</para>
38 </refsect1>
39
40 <refsect1>
41 <title>Commands</title>
42
43 <para>The following commands are understood:</para>
44
45 <variablelist>
46 <varlistentry>
47 <term><command>list</command></term>
48
49 <listitem><para>Show all peers on the bus, by their service
50 names. By default, shows both unique and well-known names, but
51 this may be changed with the <option>--unique</option> and
52 <option>--acquired</option> switches. This is the default
53 operation if no command is specified.</para>
54
55 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
56 </varlistentry>
57
58 <varlistentry>
59 <term><command>status</command> <arg choice="opt"><replaceable>SERVICE</replaceable></arg></term>
60
61 <listitem><para>Show process information and credentials of a
62 bus service (if one is specified by its unique or well-known
63 name), a process (if one is specified by its numeric PID), or
64 the owner of the bus (if no parameter is
65 specified).</para>
66
67 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
68 </varlistentry>
69
70 <varlistentry>
71 <term><command>monitor</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
72
73 <listitem><para>Dump messages being exchanged. If
74 <replaceable>SERVICE</replaceable> is specified, show messages
75 to or from this peer, identified by its well-known or unique
76 name. Otherwise, show all messages on the bus. Use
77 <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
78 to terminate the dump.</para>
79
80 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
81 </varlistentry>
82
83 <varlistentry>
84 <term><command>capture</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
85
86 <listitem><para>Similar to <command>monitor</command> but
87 writes the output in pcapng format (for details, see
88 <ulink url="https://github.com/pcapng/pcapng/">
89 PCAP Next Generation (pcapng) Capture File Format</ulink>).
90 Make sure to redirect standard output to a file or pipe. Tools like
91 <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>
92 may be used to dissect and view the resulting
93 files.</para>
94
95 <xi:include href="version-info.xml" xpointer="v218"/></listitem>
96 </varlistentry>
97
98 <varlistentry>
99 <term><command>tree</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
100
101 <listitem><para>Shows an object tree of one or more
102 services. If <replaceable>SERVICE</replaceable> is specified,
103 show object tree of the specified services only. Otherwise,
104 show all object trees of all services on the bus that acquired
105 at least one well-known name.</para>
106
107 <xi:include href="version-info.xml" xpointer="v218"/></listitem>
108 </varlistentry>
109
110 <varlistentry>
111 <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>
112
113 <listitem><para>Show interfaces, methods, properties and
114 signals of the specified object (identified by its path) on
115 the specified service. If the interface argument is passed, the
116 output is limited to members of the specified
117 interface.</para>
118
119 <xi:include href="version-info.xml" xpointer="v218"/></listitem>
120 </varlistentry>
121
122 <varlistentry>
123 <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>
124
125 <listitem><para>Invoke a method and show the response. Takes a
126 service name, object path, interface name and method name. If
127 parameters shall be passed to the method call, a signature
128 string is required, followed by the arguments, individually
129 formatted as strings. For details on the formatting used, see
130 below. To suppress output of the returned data, use the
131 <option>--quiet</option> option.</para>
132
133 <xi:include href="version-info.xml" xpointer="v218"/></listitem>
134 </varlistentry>
135
136 <varlistentry>
137 <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>
138
139 <listitem><para>Emit a signal. Takes an object path, interface name and method name. If parameters
140 shall be passed, a signature string is required, followed by the arguments, individually formatted as
141 strings. For details on the formatting used, see below. To specify the destination of the signal,
142 use the <option>--destination=</option> option.</para>
143
144 <xi:include href="version-info.xml" xpointer="v242"/></listitem>
145 </varlistentry>
146
147 <varlistentry>
148 <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>
149
150 <listitem><para>Retrieve the current value of one or more
151 object properties. Takes a service name, object path,
152 interface name and property name. Multiple properties may be
153 specified at once, in which case their values will be shown one
154 after the other, separated by newlines. The output is, by
155 default, in terse format. Use <option>--verbose</option> for a
156 more elaborate output format.</para>
157
158 <xi:include href="version-info.xml" xpointer="v218"/></listitem>
159 </varlistentry>
160
161 <varlistentry>
162 <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>
163
164 <listitem><para>Set the current value of an object
165 property. Takes a service name, object path, interface name,
166 property name, property signature, followed by a list of
167 parameters formatted as strings.</para>
168
169 <xi:include href="version-info.xml" xpointer="v218"/></listitem>
170 </varlistentry>
171
172 <varlistentry>
173 <term><command>help</command></term>
174
175 <listitem><para>Show command syntax help.</para>
176
177 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
178 </varlistentry>
179 </variablelist>
180 </refsect1>
181
182 <refsect1>
183 <title>Options</title>
184
185 <para>The following options are understood:</para>
186
187 <variablelist>
188 <varlistentry>
189 <term><option>--address=<replaceable>ADDRESS</replaceable></option></term>
190
191 <listitem><para>Connect to the bus specified by
192 <replaceable>ADDRESS</replaceable> instead of using suitable
193 defaults for either the system or user bus (see
194 <option>--system</option> and <option>--user</option>
195 options).</para>
196
197 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
198 </varlistentry>
199
200 <varlistentry>
201 <term><option>--show-machine</option></term>
202
203 <listitem><para>When showing the list of peers, show a
204 column containing the names of containers they belong to.
205 See
206 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
207 </para>
208
209 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
210 </varlistentry>
211
212 <varlistentry>
213 <term><option>--unique</option></term>
214
215 <listitem><para>When showing the list of peers, show only
216 "unique" names (of the form
217 <literal>:<replaceable>number</replaceable>.<replaceable>number</replaceable></literal>).
218 </para>
219
220 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
221 </varlistentry>
222
223 <varlistentry>
224 <term><option>--acquired</option></term>
225
226 <listitem><para>The opposite of <option>--unique</option> —
227 only "well-known" names will be shown.</para>
228
229 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
230 </varlistentry>
231
232 <varlistentry>
233 <term><option>--activatable</option></term>
234
235 <listitem><para>When showing the list of peers, show only
236 peers which have actually not been activated yet, but may be
237 started automatically if accessed.</para>
238
239 <xi:include href="version-info.xml" xpointer="v209"/>
240 </listitem>
241 </varlistentry>
242
243 <varlistentry>
244 <term><option>--match=<replaceable>MATCH</replaceable></option></term>
245
246 <listitem><para>When showing messages being exchanged, show only the
247 subset matching <replaceable>MATCH</replaceable>.
248 See
249 <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
250 </para>
251
252 <xi:include href="version-info.xml" xpointer="v209"/></listitem>
253 </varlistentry>
254
255 <varlistentry>
256 <term><option>--size=</option></term>
257
258 <listitem>
259 <para>When used with the <command>capture</command> command,
260 specifies the maximum bus message size to capture
261 ("snaplen"). Defaults to 4096 bytes.</para>
262
263 <xi:include href="version-info.xml" xpointer="v218"/>
264 </listitem>
265 </varlistentry>
266
267 <varlistentry>
268 <term><option>--list</option></term>
269
270 <listitem>
271 <para>When used with the <command>tree</command> command, shows a
272 flat list of object paths instead of a tree.</para>
273
274 <xi:include href="version-info.xml" xpointer="v218"/>
275 </listitem>
276 </varlistentry>
277
278 <varlistentry>
279 <term><option>-q</option></term>
280 <term><option>--quiet</option></term>
281
282 <listitem>
283 <para>When used with the <command>call</command> command,
284 suppresses display of the response message payload. Note that even
285 if this option is specified, errors returned will still be
286 printed and the tool will indicate success or failure with
287 the process exit code.</para>
288
289 <xi:include href="version-info.xml" xpointer="v218"/>
290 </listitem>
291 </varlistentry>
292
293 <varlistentry>
294 <term><option>--verbose</option></term>
295
296 <listitem>
297 <para>When used with the <command>call</command> or
298 <command>get-property</command> command, shows output in a
299 more verbose format.</para>
300
301 <xi:include href="version-info.xml" xpointer="v218"/>
302 </listitem>
303 </varlistentry>
304
305 <varlistentry>
306 <term><option>--xml-interface</option></term>
307
308 <listitem>
309 <para>When used with the <command>introspect</command> call, dump the XML description received from
310 the D-Bus <constant>org.freedesktop.DBus.Introspectable.Introspect</constant> call instead of the
311 normal output.</para>
312
313 <xi:include href="version-info.xml" xpointer="v243"/>
314 </listitem>
315 </varlistentry>
316
317 <varlistentry>
318 <term><option>--json=</option><replaceable>MODE</replaceable></term>
319
320 <listitem>
321 <para>When used with the <command>call</command> or <command>get-property</command> command, shows output
322 formatted as JSON. Expects one of <literal>short</literal> (for the shortest possible output without any
323 redundant whitespace or line breaks) or <literal>pretty</literal> (for a pretty version of the same, with
324 indentation and line breaks). Note that transformation from D-Bus marshalling to JSON is done in a loss-less
325 way, which means type information is embedded into the JSON object tree.</para>
326
327 <xi:include href="version-info.xml" xpointer="v240"/>
328 </listitem>
329 </varlistentry>
330
331 <varlistentry>
332 <term><option>-j</option></term>
333
334 <listitem>
335 <para>Equivalent to <option>--json=pretty</option> when invoked interactively from a terminal. Otherwise
336 equivalent to <option>--json=short</option>, in particular when the output is piped to some other
337 program.</para>
338
339 <xi:include href="version-info.xml" xpointer="v240"/>
340 </listitem>
341 </varlistentry>
342
343 <varlistentry>
344 <term><option>--expect-reply=</option><replaceable>BOOL</replaceable></term>
345
346 <listitem>
347 <para>When used with the <command>call</command> command,
348 specifies whether <command>busctl</command> shall wait for
349 completion of the method call, output the returned method
350 response data, and return success or failure via the process
351 exit code. If this is set to <literal>no</literal>, the
352 method call will be issued but no response is expected, the
353 tool terminates immediately, and thus no response can be
354 shown, and no success or failure is returned via the exit
355 code. To only suppress output of the reply message payload,
356 use <option>--quiet</option> above. Defaults to
357 <literal>yes</literal>.</para>
358
359 <xi:include href="version-info.xml" xpointer="v218"/>
360 </listitem>
361 </varlistentry>
362
363 <varlistentry>
364 <term><option>--auto-start=</option><replaceable>BOOL</replaceable></term>
365
366 <listitem>
367 <para>When used with the <command>call</command> or <command>emit</command> command, specifies
368 whether the method call should implicitly activate the
369 called service, should it not be running yet but is
370 configured to be auto-started. Defaults to
371 <literal>yes</literal>.</para>
372
373 <xi:include href="version-info.xml" xpointer="v218"/>
374 </listitem>
375 </varlistentry>
376
377 <varlistentry>
378 <term><option>--allow-interactive-authorization=</option><replaceable>BOOL</replaceable></term>
379
380 <listitem>
381 <para>When used with the <command>call</command> command,
382 specifies whether the services may enforce interactive
383 authorization while executing the operation, if the security
384 policy is configured for this. Defaults to
385 <literal>yes</literal>.</para>
386
387 <xi:include href="version-info.xml" xpointer="v218"/>
388 </listitem>
389 </varlistentry>
390
391 <varlistentry>
392 <term><option>--timeout=</option><replaceable>SECS</replaceable></term>
393
394 <listitem>
395 <para>When used with the <command>call</command> command,
396 specifies the maximum time to wait for method call
397 completion. If no time unit is specified, assumes
398 seconds. The usual other units are understood, too (ms, us,
399 s, min, h, d, w, month, y). Note that this timeout does not
400 apply if <option>--expect-reply=no</option> is used, as the
401 tool does not wait for any reply message then. When not
402 specified or when set to 0, the default of
403 <literal>25s</literal> is assumed.</para>
404
405 <xi:include href="version-info.xml" xpointer="v218"/>
406 </listitem>
407 </varlistentry>
408
409 <varlistentry>
410 <term><option>--augment-creds=</option><replaceable>BOOL</replaceable></term>
411
412 <listitem>
413 <para>Controls whether credential data reported by
414 <command>list</command> or <command>status</command> shall
415 be augmented with data from
416 <filename>/proc/</filename>. When this is turned on, the data
417 shown is possibly inconsistent, as the data read from
418 <filename>/proc/</filename> might be more recent than the rest of
419 the credential information. Defaults to <literal>yes</literal>.</para>
420
421 <xi:include href="version-info.xml" xpointer="v218"/>
422 </listitem>
423 </varlistentry>
424
425 <varlistentry>
426 <term><option>--watch-bind=</option><replaceable>BOOL</replaceable></term>
427
428 <listitem>
429 <para>Controls whether to wait for the specified <constant>AF_UNIX</constant> bus socket to appear in the
430 file system before connecting to it. Defaults to off. When enabled, the tool will watch the file system until
431 the socket is created and then connect to it.</para>
432
433 <xi:include href="version-info.xml" xpointer="v237"/>
434 </listitem>
435 </varlistentry>
436
437 <varlistentry>
438 <term><option>--destination=</option><replaceable>SERVICE</replaceable></term>
439
440 <listitem>
441 <para>Takes a service name. When used with the <command>emit</command> command, a signal is
442 emitted to the specified service.</para>
443
444 <xi:include href="version-info.xml" xpointer="v242"/>
445 </listitem>
446 </varlistentry>
447
448 <xi:include href="user-system-options.xml" xpointer="user" />
449 <xi:include href="user-system-options.xml" xpointer="system" />
450 <xi:include href="user-system-options.xml" xpointer="host" />
451 <xi:include href="user-system-options.xml" xpointer="machine" />
452
453 <varlistentry>
454 <term><option>-l</option></term>
455 <term><option>--full</option></term>
456
457 <listitem>
458 <para>Do not ellipsize the output in <command>list</command> command.</para>
459
460 <xi:include href="version-info.xml" xpointer="v245"/>
461 </listitem>
462 </varlistentry>
463
464 <xi:include href="standard-options.xml" xpointer="no-pager" />
465 <xi:include href="standard-options.xml" xpointer="no-legend" />
466 <xi:include href="standard-options.xml" xpointer="help" />
467 <xi:include href="standard-options.xml" xpointer="version" />
468 </variablelist>
469 </refsect1>
470
471 <refsect1>
472 <title>Parameter Formatting</title>
473
474 <para>The <command>call</command> and
475 <command>set-property</command> commands take a signature string
476 followed by a list of parameters formatted as string (for details
477 on D-Bus signature strings, see the <ulink
478 url="https://dbus.freedesktop.org/doc/dbus-specification.html#type-system">Type
479 system chapter of the D-Bus specification</ulink>). For simple
480 types, each parameter following the signature should simply be the
481 parameter's value formatted as string. Positive boolean values may
482 be formatted as <literal>true</literal>, <literal>yes</literal>,
483 <literal>on</literal>, or <literal>1</literal>; negative boolean
484 values may be specified as <literal>false</literal>,
485 <literal>no</literal>, <literal>off</literal>, or
486 <literal>0</literal>. For arrays, a numeric argument for the
487 number of entries followed by the entries shall be specified. For
488 variants, the signature of the contents shall be specified,
489 followed by the contents. For dictionaries and structs, the
490 contents of them shall be directly specified.</para>
491
492 <para>For example,
493 <programlisting>s jawoll</programlisting> is the formatting
494 of a single string <literal>jawoll</literal>.</para>
495
496 <para>
497 <programlisting>as 3 hello world foobar</programlisting>
498 is the formatting of a string array with three entries,
499 <literal>hello</literal>, <literal>world</literal> and
500 <literal>foobar</literal>.</para>
501
502 <para>
503 <programlisting>a{sv} 3 One s Eins Two u 2 Yes b true</programlisting>
504 is the formatting of a dictionary
505 array that maps strings to variants, consisting of three
506 entries. The string <literal>One</literal> is assigned the
507 string <literal>Eins</literal>. The string
508 <literal>Two</literal> is assigned the 32-bit unsigned
509 integer 2. The string <literal>Yes</literal> is assigned a
510 positive boolean.</para>
511
512 <para>Note that the <command>call</command>,
513 <command>get-property</command>, <command>introspect</command>
514 commands will also generate output in this format for the returned
515 data. Since this format is sometimes too terse to be easily
516 understood, the <command>call</command> and
517 <command>get-property</command> commands may generate a more
518 verbose, multi-line output when passed the
519 <option>--verbose</option> option.</para>
520 </refsect1>
521
522 <refsect1>
523 <title>Examples</title>
524
525 <example>
526 <title>Write and Read a Property</title>
527
528 <para>The following two commands first write a property and then
529 read it back. The property is found on the
530 <literal>/org/freedesktop/systemd1</literal> object of the
531 <literal>org.freedesktop.systemd1</literal> service. The name of
532 the property is <literal>LogLevel</literal> on the
533 <literal>org.freedesktop.systemd1.Manager</literal>
534 interface. The property contains a single string:</para>
535
536 <programlisting># busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
537 # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
538 s "debug"</programlisting>
539
540 </example>
541
542 <example>
543 <title>Terse and Verbose Output</title>
544
545 <para>The following two commands read a property that contains
546 an array of strings, and first show it in terse format, followed
547 by verbose format:</para>
548
549 <programlisting>$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
550 as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
551 $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
552 ARRAY "s" {
553 STRING "LANG=en_US.UTF-8";
554 STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
555 };</programlisting>
556 </example>
557
558 <example>
559 <title>Invoking a Method</title>
560
561 <para>The following command invokes the
562 <literal>StartUnit</literal> method on the
563 <literal>org.freedesktop.systemd1.Manager</literal>
564 interface of the
565 <literal>/org/freedesktop/systemd1</literal> object
566 of the <literal>org.freedesktop.systemd1</literal>
567 service, and passes it two strings
568 <literal>cups.service</literal> and
569 <literal>replace</literal>. As a result of the method
570 call, a single object path parameter is received and
571 shown:</para>
572
573 <programlisting># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
574 o "/org/freedesktop/systemd1/job/42684"</programlisting>
575 </example>
576 </refsect1>
577
578 <refsect1>
579 <title>See Also</title>
580
581 <para><simplelist type="inline">
582 <member><citerefentry project='dbus'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
583 <member><ulink url="https://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink></member>
584 <member><citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry></member>
585 <member><citerefentry><refentrytitle>varlinkctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
586 <member><citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
587 <member><citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
588 <member><citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
589 </simplelist></para>
590 </refsect1>
591 </refentry>