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>--json=</option><replaceable>MODE</replaceable></term>
 148
 149         <listitem>
 150           <para>When used with the <command>call</command> or <command>get-property</command> command, shows output
 151           formatted as JSON. Expects one of <literal>short</literal> (for the shortest possible output without any
 152           redundant whitespace or line breaks) or <literal>pretty</literal> (for a pretty version of the same, with
 153           indentation and line breaks). Note that transformation from D-Bus marshalling to JSON is done in a loss-less
 154           way, which means type information is embedded into the JSON object tree.</para>
 155         </listitem>
 156       </varlistentry>
 157
 158       <varlistentry>
 159         <term><option>-j</option></term>
 160
 161         <listitem>
 162           <para>Equivalent to <option>--json=pretty</option> when invoked interactively from a terminal. Otherwise
 163           equivalent to <option>--json=short</option>, in particular when the output is piped to some other
 164           program.</para>
 165         </listitem>
 166       </varlistentry>
 167
 168       <varlistentry>
 169         <term><option>--expect-reply=</option><replaceable>BOOL</replaceable></term>
 170
 171         <listitem>
 172           <para>When used with the <command>call</command> command,
 173           specifies whether <command>busctl</command> shall wait for
 174           completion of the method call, output the returned method
 175           response data, and return success or failure via the process
 176           exit code. If this is set to <literal>no</literal>, the
 177           method call will be issued but no response is expected, the
 178           tool terminates immediately, and thus no response can be
 179           shown, and no success or failure is returned via the exit
 180           code. To only suppress output of the reply message payload,
 181           use <option>--quiet</option> above. Defaults to
 182           <literal>yes</literal>.</para>
 183         </listitem>
 184       </varlistentry>
 185
 186       <varlistentry>
 187         <term><option>--auto-start=</option><replaceable>BOOL</replaceable></term>
 188
 189         <listitem>
 190           <para>When used with the <command>call</command> command, specifies
 191           whether the method call should implicitly activate the
 192           called service, should it not be running yet but is
 193           configured to be auto-started. Defaults to
 194           <literal>yes</literal>.</para>
 195         </listitem>
 196       </varlistentry>
 197
 198       <varlistentry>
 199         <term><option>--allow-interactive-authorization=</option><replaceable>BOOL</replaceable></term>
 200
 201         <listitem>
 202           <para>When used with the <command>call</command> command,
 203           specifies whether the services may enforce interactive
 204           authorization while executing the operation, if the security
 205           policy is configured for this. Defaults to
 206           <literal>yes</literal>.</para>
 207         </listitem>
 208       </varlistentry>
 209
 210       <varlistentry>
 211         <term><option>--timeout=</option><replaceable>SECS</replaceable></term>
 212
 213         <listitem>
 214           <para>When used with the <command>call</command> command,
 215           specifies the maximum time to wait for method call
 216           completion. If no time unit is specified, assumes
 217           seconds. The usual other units are understood, too (ms, us,
 218           s, min, h, d, w, month, y). Note that this timeout does not
 219           apply if <option>--expect-reply=no</option> is used, as the
 220           tool does not wait for any reply message then. When not
 221           specified or when set to 0, the default of
 222           <literal>25s</literal> is assumed.</para>
 223         </listitem>
 224       </varlistentry>
 225
 226       <varlistentry>
 227         <term><option>--augment-creds=</option><replaceable>BOOL</replaceable></term>
 228
 229         <listitem>
 230           <para>Controls whether credential data reported by
 231           <command>list</command> or <command>status</command> shall
 232           be augmented with data from
 233           <filename>/proc</filename>. When this is turned on, the data
 234           shown is possibly inconsistent, as the data read from
 235           <filename>/proc</filename> might be more recent than the rest of
 236           the credential information. Defaults to <literal>yes</literal>.</para>
 237         </listitem>
 238       </varlistentry>
 239
 240       <varlistentry>
 241         <term><option>--watch-bind=</option><replaceable>BOOL</replaceable></term>
 242
 243         <listitem>
 244           <para>Controls whether to wait for the specified <constant>AF_UNIX</constant> bus socket to appear in the
 245           file system before connecting to it. Defaults to off. When enabled, the tool will watch the file system until
 246           the socket is created and then connect to it.</para>
 247         </listitem>
 248       </varlistentry>
 249
 250       <xi:include href="user-system-options.xml" xpointer="user" />
 251       <xi:include href="user-system-options.xml" xpointer="system" />
 252       <xi:include href="user-system-options.xml" xpointer="host" />
 253       <xi:include href="user-system-options.xml" xpointer="machine" />
 254
 255       <xi:include href="standard-options.xml" xpointer="no-pager" />
 256       <xi:include href="standard-options.xml" xpointer="no-legend" />
 257       <xi:include href="standard-options.xml" xpointer="help" />
 258       <xi:include href="standard-options.xml" xpointer="version" />
 259     </variablelist>
 260   </refsect1>
 261
 262   <refsect1>
 263     <title>Commands</title>
 264
 265     <para>The following commands are understood:</para>
 266
 267     <variablelist>
 268       <varlistentry>
 269         <term><command>list</command></term>
 270
 271         <listitem><para>Show all peers on the bus, by their service
 272         names. By default, shows both unique and well-known names, but
 273         this may be changed with the <option>--unique</option> and
 274         <option>--acquired</option> switches. This is the default
 275         operation if no command is specified.</para></listitem>
 276       </varlistentry>
 277
 278       <varlistentry>
 279         <term><command>status</command> <arg choice="opt"><replaceable>SERVICE</replaceable></arg></term>
 280
 281         <listitem><para>Show process information and credentials of a
 282         bus service (if one is specified by its unique or well-known
 283         name), a process (if one is specified by its numeric PID), or
 284         the owner of the bus (if no parameter is
 285         specified).</para></listitem>
 286       </varlistentry>
 287
 288       <varlistentry>
 289         <term><command>monitor</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
 290
 291         <listitem><para>Dump messages being exchanged. If
 292         <replaceable>SERVICE</replaceable> is specified, show messages
 293         to or from this peer, identified by its well-known or unique
 294         name. Otherwise, show all messages on the bus. Use
 295         <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo>
 296         to terminate the dump.</para></listitem>
 297       </varlistentry>
 298
 299       <varlistentry>
 300         <term><command>capture</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
 301
 302         <listitem><para>Similar to <command>monitor</command> but
 303         writes the output in pcap format (for details, see the <ulink
 304         url="https://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap
 305         File Format</ulink> description). Make sure to redirect
 306         standard output to a file. Tools like
 307         <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 308         may be used to dissect and view the resulting
 309         files.</para></listitem>
 310       </varlistentry>
 311
 312       <varlistentry>
 313         <term><command>tree</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
 314
 315         <listitem><para>Shows an object tree of one or more
 316         services. If <replaceable>SERVICE</replaceable> is specified,
 317         show object tree of the specified services only. Otherwise,
 318         show all object trees of all services on the bus that acquired
 319         at least one well-known name.</para></listitem>
 320       </varlistentry>
 321
 322       <varlistentry>
 323         <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>
 324
 325         <listitem><para>Show interfaces, methods, properties and
 326         signals of the specified object (identified by its path) on
 327         the specified service. If the interface argument is passed, the
 328         output is limited to members of the specified
 329         interface.</para></listitem>
 330       </varlistentry>
 331
 332       <varlistentry>
 333         <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>
 334
 335         <listitem><para>Invoke a method and show the response. Takes a
 336         service name, object path, interface name and method name. If
 337         parameters shall be passed to the method call, a signature
 338         string is required, followed by the arguments, individually
 339         formatted as strings. For details on the formatting used, see
 340         below. To suppress output of the returned data, use the
 341         <option>--quiet</option> option.</para></listitem>
 342       </varlistentry>
 343
 344       <varlistentry>
 345         <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>
 346
 347         <listitem><para>Retrieve the current value of one or more
 348         object properties. Takes a service name, object path,
 349         interface name and property name. Multiple properties may be
 350         specified at once, in which case their values will be shown one
 351         after the other, separated by newlines. The output is, by
 352         default, in terse format. Use <option>--verbose</option> for a
 353         more elaborate output format.</para></listitem>
 354       </varlistentry>
 355
 356       <varlistentry>
 357         <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>
 358
 359         <listitem><para>Set the current value of an object
 360         property. Takes a service name, object path, interface name,
 361         property name, property signature, followed by a list of
 362         parameters formatted as strings.</para></listitem>
 363       </varlistentry>
 364
 365       <varlistentry>
 366         <term><command>help</command></term>
 367
 368         <listitem><para>Show command syntax help.</para></listitem>
 369       </varlistentry>
 370     </variablelist>
 371   </refsect1>
 372
 373   <refsect1>
 374     <title>Parameter Formatting</title>
 375
 376     <para>The <command>call</command> and
 377     <command>set-property</command> commands take a signature string
 378     followed by a list of parameters formatted as string (for details
 379     on D-Bus signature strings, see the <ulink
 380     url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">Type
 381     system chapter of the D-Bus specification</ulink>). For simple
 382     types, each parameter following the signature should simply be the
 383     parameter's value formatted as string. Positive boolean values may
 384     be formatted as <literal>true</literal>, <literal>yes</literal>,
 385     <literal>on</literal>, or <literal>1</literal>; negative boolean
 386     values may be specified as <literal>false</literal>,
 387     <literal>no</literal>, <literal>off</literal>, or
 388     <literal>0</literal>. For arrays, a numeric argument for the
 389     number of entries followed by the entries shall be specified. For
 390     variants, the signature of the contents shall be specified,
 391     followed by the contents. For dictionaries and structs, the
 392     contents of them shall be directly specified.</para>
 393
 394     <para>For example,
 395     <programlisting>s jawoll</programlisting> is the formatting
 396     of a single string <literal>jawoll</literal>.</para>
 397
 398     <para>
 399     <programlisting>as 3 hello world foobar</programlisting>
 400     is the formatting of a string array with three entries,
 401     <literal>hello</literal>, <literal>world</literal> and
 402     <literal>foobar</literal>.</para>
 403
 404     <para>
 405     <programlisting>a{sv} 3 One s Eins Two u 2 Yes b true</programlisting>
 406     is the formatting of a dictionary
 407     array that maps strings to variants, consisting of three
 408     entries. The string <literal>One</literal> is assigned the
 409     string <literal>Eins</literal>. The string
 410     <literal>Two</literal> is assigned the 32-bit unsigned
 411     integer 2. The string <literal>Yes</literal> is assigned a
 412     positive boolean.</para>
 413
 414     <para>Note that the <command>call</command>,
 415     <command>get-property</command>, <command>introspect</command>
 416     commands will also generate output in this format for the returned
 417     data. Since this format is sometimes too terse to be easily
 418     understood, the <command>call</command> and
 419     <command>get-property</command> commands may generate a more
 420     verbose, multi-line output when passed the
 421     <option>--verbose</option> option.</para>
 422   </refsect1>
 423
 424   <refsect1>
 425     <title>Examples</title>
 426
 427     <example>
 428       <title>Write and Read a Property</title>
 429
 430       <para>The following two commands first write a property and then
 431       read it back. The property is found on the
 432       <literal>/org/freedesktop/systemd1</literal> object of the
 433       <literal>org.freedesktop.systemd1</literal> service. The name of
 434       the property is <literal>LogLevel</literal> on the
 435       <literal>org.freedesktop.systemd1.Manager</literal>
 436       interface. The property contains a single string:</para>
 437
 438       <programlisting># busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
 439 # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
 440 s "debug"</programlisting>
 441
 442     </example>
 443
 444     <example>
 445       <title>Terse and Verbose Output</title>
 446
 447       <para>The following two commands read a property that contains
 448       an array of strings, and first show it in terse format, followed
 449       by verbose format:</para>
 450
 451       <programlisting>$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
 452 as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
 453 $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
 454 ARRAY "s" {
 455         STRING "LANG=en_US.UTF-8";
 456         STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
 457 };</programlisting>
 458     </example>
 459
 460     <example>
 461       <title>Invoking a Method</title>
 462
 463       <para>The following command invokes the
 464       <literal>StartUnit</literal> method on the
 465       <literal>org.freedesktop.systemd1.Manager</literal>
 466       interface of the
 467       <literal>/org/freedesktop/systemd1</literal> object
 468       of the <literal>org.freedesktop.systemd1</literal>
 469       service, and passes it two strings
 470       <literal>cups.service</literal> and
 471       <literal>replace</literal>. As a result of the method
 472       call, a single object path parameter is received and
 473       shown:</para>
 474
 475       <programlisting># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
 476 o "/org/freedesktop/systemd1/job/42684"</programlisting>
 477     </example>
 478   </refsect1>
 479
 480   <refsect1>
 481     <title>See Also</title>
 482
 483     <para>
 484       <citerefentry project='dbus'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 485       <ulink url="https://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
 486       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 487       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 488       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 489       <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 490     </para>
 491   </refsect1>
 492 </refentry>