1:255.16-alt1
[systemd_ALT.git] / man / busctl.xml
blobcc404529ae041f76be9d483081d3e2427da2e0bf
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 -->
6 <refentry id="busctl"
7           xmlns:xi="http://www.w3.org/2001/XInclude">
9   <refentryinfo>
10     <title>busctl</title>
11     <productname>systemd</productname>
12   </refentryinfo>
14   <refmeta>
15     <refentrytitle>busctl</refentrytitle>
16     <manvolnum>1</manvolnum>
17   </refmeta>
19   <refnamediv>
20     <refname>busctl</refname>
21     <refpurpose>Introspect the bus</refpurpose>
22   </refnamediv>
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>
33   <refsect1>
34     <title>Description</title>
36     <para><command>busctl</command> may be used to
37     introspect and monitor the D-Bus bus.</para>
38   </refsect1>
40   <refsect1>
41     <title>Commands</title>
43     <para>The following commands are understood:</para>
45     <variablelist>
46       <varlistentry>
47         <term><command>list</command></term>
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>
55         <xi:include href="version-info.xml" xpointer="v209"/></listitem>
56       </varlistentry>
58       <varlistentry>
59         <term><command>status</command> <arg choice="opt"><replaceable>SERVICE</replaceable></arg></term>
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>
67         <xi:include href="version-info.xml" xpointer="v209"/></listitem>
68       </varlistentry>
70       <varlistentry>
71         <term><command>monitor</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
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>
80         <xi:include href="version-info.xml" xpointer="v209"/></listitem>
81       </varlistentry>
83       <varlistentry>
84         <term><command>capture</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
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>
95         <xi:include href="version-info.xml" xpointer="v218"/></listitem>
96       </varlistentry>
98       <varlistentry>
99         <term><command>tree</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
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>
107         <xi:include href="version-info.xml" xpointer="v218"/></listitem>
108       </varlistentry>
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>
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>
119         <xi:include href="version-info.xml" xpointer="v218"/></listitem>
120       </varlistentry>
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>
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>
133         <xi:include href="version-info.xml" xpointer="v218"/></listitem>
134       </varlistentry>
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>
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>
144         <xi:include href="version-info.xml" xpointer="v242"/></listitem>
145       </varlistentry>
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>
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>
158         <xi:include href="version-info.xml" xpointer="v218"/></listitem>
159       </varlistentry>
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>
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>
169         <xi:include href="version-info.xml" xpointer="v218"/></listitem>
170       </varlistentry>
172       <varlistentry>
173         <term><command>help</command></term>
175         <listitem><para>Show command syntax help.</para>
177         <xi:include href="version-info.xml" xpointer="v209"/></listitem>
178       </varlistentry>
179     </variablelist>
180   </refsect1>
182   <refsect1>
183     <title>Options</title>
185     <para>The following options are understood:</para>
187     <variablelist>
188       <varlistentry>
189           <term><option>--address=<replaceable>ADDRESS</replaceable></option></term>
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>
197           <xi:include href="version-info.xml" xpointer="v209"/></listitem>
198       </varlistentry>
200       <varlistentry>
201           <term><option>--show-machine</option></term>
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>
209           <xi:include href="version-info.xml" xpointer="v209"/></listitem>
210       </varlistentry>
212       <varlistentry>
213           <term><option>--unique</option></term>
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>
220           <xi:include href="version-info.xml" xpointer="v209"/></listitem>
221       </varlistentry>
223       <varlistentry>
224           <term><option>--acquired</option></term>
226           <listitem><para>The opposite of <option>--unique</option> —
227           only "well-known" names will be shown.</para>
229           <xi:include href="version-info.xml" xpointer="v209"/></listitem>
230       </varlistentry>
232       <varlistentry>
233           <term><option>--activatable</option></term>
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>
239           <xi:include href="version-info.xml" xpointer="v209"/>
240           </listitem>
241       </varlistentry>
243       <varlistentry>
244           <term><option>--match=<replaceable>MATCH</replaceable></option></term>
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>
252           <xi:include href="version-info.xml" xpointer="v209"/></listitem>
253       </varlistentry>
255       <varlistentry>
256         <term><option>--size=</option></term>
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>
263         <xi:include href="version-info.xml" xpointer="v218"/>
264         </listitem>
265       </varlistentry>
267       <varlistentry>
268         <term><option>--list</option></term>
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>
274         <xi:include href="version-info.xml" xpointer="v218"/>
275         </listitem>
276       </varlistentry>
278       <varlistentry>
279         <term><option>-q</option></term>
280         <term><option>--quiet</option></term>
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>
289         <xi:include href="version-info.xml" xpointer="v218"/>
290         </listitem>
291       </varlistentry>
293       <varlistentry>
294         <term><option>--verbose</option></term>
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>
301         <xi:include href="version-info.xml" xpointer="v218"/>
302         </listitem>
303       </varlistentry>
305       <varlistentry>
306         <term><option>--xml-interface</option></term>
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>
313         <xi:include href="version-info.xml" xpointer="v243"/>
314         </listitem>
315       </varlistentry>
317       <varlistentry>
318         <term><option>--json=</option><replaceable>MODE</replaceable></term>
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>
327         <xi:include href="version-info.xml" xpointer="v240"/>
328         </listitem>
329       </varlistentry>
331       <varlistentry>
332         <term><option>-j</option></term>
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>
339         <xi:include href="version-info.xml" xpointer="v240"/>
340         </listitem>
341       </varlistentry>
343       <varlistentry>
344         <term><option>--expect-reply=</option><replaceable>BOOL</replaceable></term>
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>
359         <xi:include href="version-info.xml" xpointer="v218"/>
360         </listitem>
361       </varlistentry>
363       <varlistentry>
364         <term><option>--auto-start=</option><replaceable>BOOL</replaceable></term>
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>
373         <xi:include href="version-info.xml" xpointer="v218"/>
374         </listitem>
375       </varlistentry>
377       <varlistentry>
378         <term><option>--allow-interactive-authorization=</option><replaceable>BOOL</replaceable></term>
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>
387         <xi:include href="version-info.xml" xpointer="v218"/>
388         </listitem>
389       </varlistentry>
391       <varlistentry>
392         <term><option>--timeout=</option><replaceable>SECS</replaceable></term>
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>
405         <xi:include href="version-info.xml" xpointer="v218"/>
406         </listitem>
407       </varlistentry>
409       <varlistentry>
410         <term><option>--augment-creds=</option><replaceable>BOOL</replaceable></term>
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>
421           <xi:include href="version-info.xml" xpointer="v218"/>
422         </listitem>
423       </varlistentry>
425       <varlistentry>
426         <term><option>--watch-bind=</option><replaceable>BOOL</replaceable></term>
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>
433         <xi:include href="version-info.xml" xpointer="v237"/>
434         </listitem>
435       </varlistentry>
437       <varlistentry>
438         <term><option>--destination=</option><replaceable>SERVICE</replaceable></term>
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>
444         <xi:include href="version-info.xml" xpointer="v242"/>
445         </listitem>
446       </varlistentry>
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" />
453       <varlistentry>
454         <term><option>-l</option></term>
455         <term><option>--full</option></term>
457         <listitem>
458           <para>Do not ellipsize the output in <command>list</command> command.</para>
460         <xi:include href="version-info.xml" xpointer="v245"/>
461         </listitem>
462       </varlistentry>
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>
471   <refsect1>
472     <title>Parameter Formatting</title>
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>
492     <para>For example,
493     <programlisting>s jawoll</programlisting> is the formatting
494     of a single string <literal>jawoll</literal>.</para>
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>
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>
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>
522   <refsect1>
523     <title>Examples</title>
525     <example>
526       <title>Write and Read a Property</title>
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>
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>
540     </example>
542     <example>
543       <title>Terse and Verbose Output</title>
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>
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>
558     <example>
559       <title>Invoking a Method</title>
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>
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>
578   <refsect1>
579     <title>See Also</title>
581     <para>
582       <citerefentry project='dbus'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
583       <ulink url="https://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
584       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
585       <citerefentry><refentrytitle>varlinkctl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
586       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
587       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
588       <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>
589     </para>
590   </refsect1>
591 </refentry>