man/busctl.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
   3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
   4
   5 <!--
   6   SPDX-License-Identifier: LGPL-2.1+
   7 -->
   8
   9 <refentry id="busctl"
  10           xmlns:xi="http://www.w3.org/2001/XInclude">
  11
  12   <refentryinfo>
  13     <title>busctl</title>
  14     <productname>systemd</productname>
  15   </refentryinfo>
  16
  17   <refmeta>
  18     <refentrytitle>busctl</refentrytitle>
  19     <manvolnum>1</manvolnum>
  20   </refmeta>
  21
  22   <refnamediv>
  23     <refname>busctl</refname>
  24     <refpurpose>Introspect the bus</refpurpose>
  25   </refnamediv>
  26
  27   <refsynopsisdiv>
  28     <cmdsynopsis>
  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>
  33     </cmdsynopsis>
  34   </refsynopsisdiv>
  35
  36   <refsect1>
  37     <title>Description</title>
  38
  39     <para><command>busctl</command> may be used to
  40     introspect and monitor the D-Bus bus.</para>
  41   </refsect1>
  42
  43   <refsect1>
  44     <title>Options</title>
  45
  46     <para>The following options are understood:</para>
  47
  48     <variablelist>
  49       <varlistentry>
  50           <term><option>--address=<replaceable>ADDRESS</replaceable></option></term>
  51
  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>
  57       </varlistentry>
  58
  59       <varlistentry>
  60           <term><option>--show-machine</option></term>
  61
  62           <listitem><para>When showing the list of peers, show a
  63           column containing the names of containers they belong to.
  64           See
  65           <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
  66           </para></listitem>
  67       </varlistentry>
  68
  69       <varlistentry>
  70           <term><option>--unique</option></term>
  71
  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>).
  75           </para></listitem>
  76       </varlistentry>
  77
  78       <varlistentry>
  79           <term><option>--acquired</option></term>
  80
  81           <listitem><para>The opposite of <option>--unique</option> —
  82           only "well-known" names will be shown.</para></listitem>
  83       </varlistentry>
  84
  85       <varlistentry>
  86           <term><option>--activatable</option></term>
  87
  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>
  91           </listitem>
  92       </varlistentry>
  93
  94       <varlistentry>
  95           <term><option>--match=<replaceable>MATCH</replaceable></option></term>
  96
  97           <listitem><para>When showing messages being exchanged, show only the
  98           subset matching <replaceable>MATCH</replaceable>.
  99           See
 100           <citerefentry><refentrytitle>sd_bus_add_match</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
 101           </para></listitem>
 102       </varlistentry>
 103
 104       <varlistentry>
 105         <term><option>--size=</option></term>
 106
 107         <listitem>
 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>
 111         </listitem>
 112       </varlistentry>
 113
 114       <varlistentry>
 115         <term><option>--list</option></term>
 116
 117         <listitem>
 118           <para>When used with the <command>tree</command> command, shows a
 119           flat list of object paths instead of a tree.</para>
 120         </listitem>
 121       </varlistentry>
 122
 123       <varlistentry>
 124         <term><option>-q</option></term>
 125         <term><option>--quiet</option></term>
 126
 127         <listitem>
 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>
 133         </listitem>
 134       </varlistentry>
 135
 136       <varlistentry>
 137         <term><option>--verbose</option></term>
 138
 139         <listitem>
 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>
 143         </listitem>
 144       </varlistentry>
 145
 146       <varlistentry>
 147         <term><option>--expect-reply=</option><replaceable>BOOL</replaceable></term>
 148
 149         <listitem>
 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>
 161         </listitem>
 162       </varlistentry>
 163
 164       <varlistentry>
 165         <term><option>--auto-start=</option><replaceable>BOOL</replaceable></term>
 166
 167         <listitem>
 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>
 173         </listitem>
 174       </varlistentry>
 175
 176       <varlistentry>
 177         <term><option>--allow-interactive-authorization=</option><replaceable>BOOL</replaceable></term>
 178
 179         <listitem>
 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>
 185         </listitem>
 186       </varlistentry>
 187
 188       <varlistentry>
 189         <term><option>--timeout=</option><replaceable>SECS</replaceable></term>
 190
 191         <listitem>
 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>
 201         </listitem>
 202       </varlistentry>
 203
 204       <varlistentry>
 205         <term><option>--augment-creds=</option><replaceable>BOOL</replaceable></term>
 206
 207         <listitem>
 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>
 215         </listitem>
 216       </varlistentry>
 217
 218       <varlistentry>
 219         <term><option>--watch-bind=</option><replaceable>BOOL</replaceable></term>
 220
 221         <listitem>
 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>
 225         </listitem>
 226       </varlistentry>
 227
 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" />
 232
 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" />
 237     </variablelist>
 238   </refsect1>
 239
 240   <refsect1>
 241     <title>Commands</title>
 242
 243     <para>The following commands are understood:</para>
 244
 245     <variablelist>
 246       <varlistentry>
 247         <term><command>list</command></term>
 248
 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>
 254       </varlistentry>
 255
 256       <varlistentry>
 257         <term><command>status</command> <arg choice="opt"><replaceable>SERVICE</replaceable></arg></term>
 258
 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>
 264       </varlistentry>
 265
 266       <varlistentry>
 267         <term><command>monitor</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
 268
 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>
 274       </varlistentry>
 275
 276       <varlistentry>
 277         <term><command>capture</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
 278
 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>
 287       </varlistentry>
 288
 289       <varlistentry>
 290         <term><command>tree</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
 291
 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>
 297       </varlistentry>
 298
 299       <varlistentry>
 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>
 301
 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>
 307       </varlistentry>
 308
 309       <varlistentry>
 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>
 311
 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>
 319       </varlistentry>
 320
 321       <varlistentry>
 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>
 323
 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>
 331       </varlistentry>
 332
 333       <varlistentry>
 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>
 335
 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>
 340       </varlistentry>
 341
 342       <varlistentry>
 343         <term><command>help</command></term>
 344
 345         <listitem><para>Show command syntax help.</para></listitem>
 346       </varlistentry>
 347     </variablelist>
 348   </refsect1>
 349
 350   <refsect1>
 351     <title>Parameter Formatting</title>
 352
 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>
 370
 371     <para>For example,
 372     <programlisting>s jawoll</programlisting> is the formatting
 373     of a single string <literal>jawoll</literal>.</para>
 374
 375     <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>
 380
 381     <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>
 390
 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>
 399   </refsect1>
 400
 401   <refsect1>
 402     <title>Examples</title>
 403
 404     <example>
 405       <title>Write and Read a Property</title>
 406
 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>
 414
 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>
 418
 419     </example>
 420
 421     <example>
 422       <title>Terse and Verbose Output</title>
 423
 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>
 427
 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
 431 ARRAY "s" {
 432         STRING "LANG=en_US.UTF-8";
 433         STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
 434 };</programlisting>
 435     </example>
 436
 437     <example>
 438       <title>Invoking a Method</title>
 439
 440       <para>The following command invokes the
 441       <literal>StartUnit</literal> method on the
 442       <literal>org.freedesktop.systemd1.Manager</literal>
 443       interface of the
 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
 450       shown:</para>
 451
 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>
 454     </example>
 455   </refsect1>
 456
 457   <refsect1>
 458     <title>See Also</title>
 459
 460     <para>
 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>
 467     </para>
 468   </refsect1>
 469 </refentry>