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