man/busctl.xml

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