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