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 Ctrl-C to
 295         terminate the dump.</para></listitem>
 296       </varlistentry>
 297
 298       <varlistentry>
 299         <term><command>capture</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
 300
 301         <listitem><para>Similar to <command>monitor</command> but
 302         writes the output in pcap format (for details, see the <ulink
 303         url="https://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap
 304         File Format</ulink> description). Make sure to redirect
 305         standard output to a file. Tools like
 306         <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 307         may be used to dissect and view the resulting
 308         files.</para></listitem>
 309       </varlistentry>
 310
 311       <varlistentry>
 312         <term><command>tree</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
 313
 314         <listitem><para>Shows an object tree of one or more
 315         services. If <replaceable>SERVICE</replaceable> is specified,
 316         show object tree of the specified services only. Otherwise,
 317         show all object trees of all services on the bus that acquired
 318         at least one well-known name.</para></listitem>
 319       </varlistentry>
 320
 321       <varlistentry>
 322         <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>
 323
 324         <listitem><para>Show interfaces, methods, properties and
 325         signals of the specified object (identified by its path) on
 326         the specified service. If the interface argument is passed, the
 327         output is limited to members of the specified
 328         interface.</para></listitem>
 329       </varlistentry>
 330
 331       <varlistentry>
 332         <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>
 333
 334         <listitem><para>Invoke a method and show the response. Takes a
 335         service name, object path, interface name and method name. If
 336         parameters shall be passed to the method call, a signature
 337         string is required, followed by the arguments, individually
 338         formatted as strings. For details on the formatting used, see
 339         below. To suppress output of the returned data, use the
 340         <option>--quiet</option> option.</para></listitem>
 341       </varlistentry>
 342
 343       <varlistentry>
 344         <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>
 345
 346         <listitem><para>Retrieve the current value of one or more
 347         object properties. Takes a service name, object path,
 348         interface name and property name. Multiple properties may be
 349         specified at once, in which case their values will be shown one
 350         after the other, separated by newlines. The output is, by
 351         default, in terse format. Use <option>--verbose</option> for a
 352         more elaborate output format.</para></listitem>
 353       </varlistentry>
 354
 355       <varlistentry>
 356         <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>
 357
 358         <listitem><para>Set the current value of an object
 359         property. Takes a service name, object path, interface name,
 360         property name, property signature, followed by a list of
 361         parameters formatted as strings.</para></listitem>
 362       </varlistentry>
 363
 364       <varlistentry>
 365         <term><command>help</command></term>
 366
 367         <listitem><para>Show command syntax help.</para></listitem>
 368       </varlistentry>
 369     </variablelist>
 370   </refsect1>
 371
 372   <refsect1>
 373     <title>Parameter Formatting</title>
 374
 375     <para>The <command>call</command> and
 376     <command>set-property</command> commands take a signature string
 377     followed by a list of parameters formatted as string (for details
 378     on D-Bus signature strings, see the <ulink
 379     url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">Type
 380     system chapter of the D-Bus specification</ulink>). For simple
 381     types, each parameter following the signature should simply be the
 382     parameter's value formatted as string. Positive boolean values may
 383     be formatted as <literal>true</literal>, <literal>yes</literal>,
 384     <literal>on</literal>, or <literal>1</literal>; negative boolean
 385     values may be specified as <literal>false</literal>,
 386     <literal>no</literal>, <literal>off</literal>, or
 387     <literal>0</literal>. For arrays, a numeric argument for the
 388     number of entries followed by the entries shall be specified. For
 389     variants, the signature of the contents shall be specified,
 390     followed by the contents. For dictionaries and structs, the
 391     contents of them shall be directly specified.</para>
 392
 393     <para>For example,
 394     <programlisting>s jawoll</programlisting> is the formatting
 395     of a single string <literal>jawoll</literal>.</para>
 396
 397     <para>
 398     <programlisting>as 3 hello world foobar</programlisting>
 399     is the formatting of a string array with three entries,
 400     <literal>hello</literal>, <literal>world</literal> and
 401     <literal>foobar</literal>.</para>
 402
 403     <para>
 404     <programlisting>a{sv} 3 One s Eins Two u 2 Yes b true</programlisting>
 405     is the formatting of a dictionary
 406     array that maps strings to variants, consisting of three
 407     entries. The string <literal>One</literal> is assigned the
 408     string <literal>Eins</literal>. The string
 409     <literal>Two</literal> is assigned the 32-bit unsigned
 410     integer 2. The string <literal>Yes</literal> is assigned a
 411     positive boolean.</para>
 412
 413     <para>Note that the <command>call</command>,
 414     <command>get-property</command>, <command>introspect</command>
 415     commands will also generate output in this format for the returned
 416     data. Since this format is sometimes too terse to be easily
 417     understood, the <command>call</command> and
 418     <command>get-property</command> commands may generate a more
 419     verbose, multi-line output when passed the
 420     <option>--verbose</option> option.</para>
 421   </refsect1>
 422
 423   <refsect1>
 424     <title>Examples</title>
 425
 426     <example>
 427       <title>Write and Read a Property</title>
 428
 429       <para>The following two commands first write a property and then
 430       read it back. The property is found on the
 431       <literal>/org/freedesktop/systemd1</literal> object of the
 432       <literal>org.freedesktop.systemd1</literal> service. The name of
 433       the property is <literal>LogLevel</literal> on the
 434       <literal>org.freedesktop.systemd1.Manager</literal>
 435       interface. The property contains a single string:</para>
 436
 437       <programlisting># busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
 438 # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
 439 s "debug"</programlisting>
 440
 441     </example>
 442
 443     <example>
 444       <title>Terse and Verbose Output</title>
 445
 446       <para>The following two commands read a property that contains
 447       an array of strings, and first show it in terse format, followed
 448       by verbose format:</para>
 449
 450       <programlisting>$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
 451 as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
 452 $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
 453 ARRAY "s" {
 454         STRING "LANG=en_US.UTF-8";
 455         STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
 456 };</programlisting>
 457     </example>
 458
 459     <example>
 460       <title>Invoking a Method</title>
 461
 462       <para>The following command invokes the
 463       <literal>StartUnit</literal> method on the
 464       <literal>org.freedesktop.systemd1.Manager</literal>
 465       interface of the
 466       <literal>/org/freedesktop/systemd1</literal> object
 467       of the <literal>org.freedesktop.systemd1</literal>
 468       service, and passes it two strings
 469       <literal>cups.service</literal> and
 470       <literal>replace</literal>. As a result of the method
 471       call, a single object path parameter is received and
 472       shown:</para>
 473
 474       <programlisting># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
 475 o "/org/freedesktop/systemd1/job/42684"</programlisting>
 476     </example>
 477   </refsect1>
 478
 479   <refsect1>
 480     <title>See Also</title>
 481
 482     <para>
 483       <citerefentry project='dbus'><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 484       <ulink url="https://www.freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
 485       <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
 486       <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 487       <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
 488       <citerefentry project='die-net'><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>
 489     </para>
 490   </refsect1>
 491 </refentry>