1 <?xml version='1.0'?> <!--*-nxml-*-->
2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
6 This file is part of systemd.
8 Copyright 2014 Zbigniew Jędrzejewski-Szmek
10 systemd is free software; you can redistribute it and/or modify it
11 under the terms of the GNU Lesser General Public License as published by
12 the Free Software Foundation; either version 2.1 of the License, or
13 (at your option) any later version.
15 systemd is distributed in the hope that it will be useful, but
16 WITHOUT ANY WARRANTY; without even the implied warranty of
17 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
18 Lesser General Public License for more details.
20 You should have received a copy of the GNU Lesser General Public License
21 along with systemd; If not, see <http://www.gnu.org/licenses/>.
25 xmlns:xi="http://www.w3.org/2001/XInclude">
29 <productname>systemd</productname>
33 <contrib>A monkey with a typewriter</contrib>
34 <firstname>Zbigniew</firstname>
35 <surname>Jędrzejewski-Szmek</surname>
36 <email>zbyszek@in.waw.pl</email>
42 <refentrytitle>busctl</refentrytitle>
43 <manvolnum>1</manvolnum>
47 <refname>busctl</refname>
48 <refpurpose>Introspect the bus</refpurpose>
53 <command>busctl</command>
54 <arg choice="opt" rep="repeat">OPTIONS</arg>
55 <arg choice="opt">COMMAND</arg>
56 <arg choice="opt" rep="repeat"><replaceable>NAME</replaceable></arg>
61 <title>Description</title>
63 <para><command>busctl</command> may be used to
64 introspect and monitor the D-Bus bus.</para>
68 <title>Options</title>
70 <para>The following options are understood:</para>
74 <term><option>--address=<replaceable>ADDRESS</replaceable></option></term>
76 <listitem><para>Connect to the bus specified by
77 <replaceable>ADDRESS</replaceable> instead of using suitable
78 defaults for either the system or user bus (see
79 <option>--system</option> and <option>--user</option>
80 options).</para></listitem>
84 <term><option>--show-machine</option></term>
86 <listitem><para>When showing the list of endpoints, show a
87 column containing the names of containers they belong to.
89 <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>.
94 <term><option>--unique</option></term>
96 <listitem><para>When showing the list of endpoints, show
97 only "unique" names (of the form
98 <literal>:<replaceable>number</replaceable>.<replaceable>number</replaceable></literal>).
103 <term><option>--acquired</option></term>
105 <listitem><para>The opposite of <option>--unique</option> —
106 only "well-known" names will be shown.</para></listitem>
110 <term><option>--activatable</option></term>
112 <listitem><para>When showing the list of endpoints, show
113 only endpoints which have actually not been activated yet,
114 but may be started automatically if accessed.</para>
119 <term><option>--match=<replaceable>MATCH</replaceable></option></term>
121 <listitem><para>When showing messages being exchanged, show only the
122 subset matching <replaceable>MATCH</replaceable>.</para></listitem>
123 <!-- TODO: link to sd_bus_add_match when it is written? -->
127 <term><option>--no-legend</option></term>
130 <para>Do not print the legend,
131 i.e. the column headers and the
137 <term><option>--size=</option></term>
140 <para>When used with the <command>capture</command> command
141 specifies the maximum bus message size to capture
142 ("snaplen"). Defaults to 4096 bytes.</para>
147 <term><option>--list</option></term>
150 <para>When used with the <command>tree</command> command shows a
151 flat list of object paths instead of a tree.</para>
156 <term><option>--quiet</option></term>
159 <para>When used with the <command>call</command> command suppresses
160 display of the response message.</para>
166 <term><option>--verbose</option></term>
169 <para>When used with the <command>call</command> or
170 <command>get-property</command> command shows output in a
171 more verbose format.</para>
175 <xi:include href="user-system-options.xml" xpointer="user" />
176 <xi:include href="user-system-options.xml" xpointer="system" />
177 <xi:include href="user-system-options.xml" xpointer="host" />
178 <xi:include href="user-system-options.xml" xpointer="machine" />
180 <xi:include href="standard-options.xml" xpointer="help" />
181 <xi:include href="standard-options.xml" xpointer="version" />
182 <xi:include href="standard-options.xml" xpointer="no-pager" />
187 <title>Commands</title>
189 <para>The following commands are understood:</para>
193 <term><command>list</command></term>
195 <listitem><para>Show service names on the bus. This is the
196 default if no command is specified.</para></listitem>
200 <term><command>status</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg></term>
202 <listitem><para>Show process information and credentials of a
203 bus service.</para></listitem>
207 <term><command>monitor</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
209 <listitem><para>Dump messages being exchanged. If
210 <replaceable>SERVICE</replaceable> is specified, show messages
211 to or from this endpoint. Otherwise, show all messages on the
212 bus. Use Ctrl-C to terminate dump.</para></listitem>
216 <term><command>capture</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
218 <listitem><para>Similar to <command>monitor</command> but
219 writes the output in pcap format (for details see the <ulink
220 url="http://wiki.wireshark.org/Development/LibpcapFileFormat">Libpcap
221 File Format</ulink> description. Make sure to redirect the
222 output to STDOUT to a file. Tools like
223 <citerefentry><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>
224 may be used to dissect and view the generated
225 files.</para></listitem>
229 <term><command>tree</command> <arg choice="opt" rep="repeat"><replaceable>SERVICE</replaceable></arg></term>
231 <listitem><para>Shows an object tree of one or more
232 services. If <replaceable>SERVICE</replaceable> is specified,
233 show object tree of the specified services only. Otherwise,
234 show all object trees of all services on the bus that acquired
235 at least one well-known name.</para></listitem>
239 <term><command>introspect</command> <arg choice="plain"><replaceable>SERVICE</replaceable></arg> <arg choice="plain"><replaceable>OBJECT</replaceable></arg></term>
241 <listitem><para>Show interfaces, methods, properties and
242 signals of the specified object (identified by its path) on
243 the specified service.</para></listitem>
247 <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>
249 <listitem><para>Invoke a method and show the response. Takes a
250 service name, object path, interface name and method name. If
251 parameters shall be passed to the method call a signature
252 string is required, followed by the arguments, individually
253 formatted as strings. For details on the formatting used, see
254 below. To suppress output of the returned data use the
255 <option>--quiet</option> option.</para></listitem>
259 <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>
261 <listitem><para>Retrieve the current value of one or more
262 object properties. Takes a service name, object path,
263 interface name and property name. Multiple properties may be
264 specified at once in which case their values will be shown one
265 after the other, separated by newlines. The output is by
266 default in terse format. Use <option>--verbose</option> for a
267 more elaborate output format.</para></listitem>
271 <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>
273 <listitem><para>Set the current value an object
274 property. Takes a service name, object path, interface name,
275 property name, property signature, followed by a list of
276 parameters formatted as strings.</para></listitem>
280 <term><command>help</command></term>
282 <listitem><para>Show command syntax help.</para></listitem>
288 <title>Parameter Formatting</title>
290 <para>The <command>call</command> and
291 <command>set-property</command> commands take a signature
292 string followed by a list of parameters formatted as string
293 (for details on D-Bus signature strings see the <ulink
294 url="http://dbus.freedesktop.org/doc/dbus-specification.html#type-system">Type
295 system chapter of the D-Bus specification</ulink>). For
296 simple types each parameter following the signature should
297 simply be the parameter's value formatted as
298 string. Positive boolean values may be formatted as
299 <literal>true</literal>, <literal>yes</literal>,
300 <literal>on</literal>, <literal>1</literal>; negative
301 boolean values may be specified as <literal>false</literal>,
302 <literal>no</literal>, <literal>off</literal>,
303 <literal>0</literal>. For arrays, a numeric argument for the
304 number of entries followed by the entries shall be
305 specified. For variants the signature of the contents shall
306 be specified, followed by the contents. For dictionaries and
307 structs the contents of them shall be directly
311 <programlisting>s jawoll</programlisting> is the formatting
312 of a single string <literal>jawoll</literal>.</para>
315 <programlisting>as 3 hello world foobar</programlisting>
316 is the formatting of a string array with three entries,
317 <literal>hello</literal>, <literal>world</literal> and
318 <literal>foobar</literal>.</para>
321 <programlisting>a{sv} 3 One s Eins Two u 2 Yes b true</programlisting>
322 is the formatting of a dictionary
323 array that maps strings to variants, consisting of three
324 entries. The string <literal>One</literal> is assigned the
325 string <literal>Eins</literal>. The string
326 <literal>Two</literal> is assigned the 32bit unsigned
327 integer 2. The string <literal>Yes</literal> is assigned a
328 positive boolean.</para>
330 <para>Note that the <command>call</command>,
331 <command>get-property</command>,
332 <command>introspect</command> commands will also generate
333 output in this format for the returned data. Since this
334 format is sometimes too terse to be easily understood, the
335 <command>call</command> and <command>get-property</command>
336 commands may generate a more verbose, multi-line output when
337 passed the <option>--verbose</option> option.</para>
341 <title>Examples</title>
344 <title>Write and Read a Property</title>
346 <para>The following two commands first write a
347 property and then read it back. The property is
349 <literal>/org/freedesktop/systemd1</literal> object
350 of the <literal>org.freedesktop.systemd1</literal>
351 service. The name of the property is
352 <literal>LogLevel</literal> on the
353 <literal>org.freedesktop.systemd1.Manager</literal>
354 interface. The property contains a single
357 <programlisting># busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
358 # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
359 s "debug"</programlisting>
364 <title>Terse and Verbose Output</title>
366 <para>The following two commands read a property that
367 contains an array of strings, and first show it in
368 terse format, followed by verbose format:</para>
370 <programlisting>$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
371 as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
372 $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
374 STRING "LANG=en_US.UTF-8";
375 STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
380 <title>Invoking a Method</title>
382 <para>The following command invokes a the
383 <literal>StartUnit</literal> method on the
384 <literal>org.freedesktop.systemd1.Manager</literal>
386 <literal>/org/freedesktop/systemd1</literal> object
387 of the <literal>org.freedesktop.systemd1</literal>
388 service, and passes it two strings
389 <literal>cups.service</literal> and
390 <literal>replace</literal>. As result of the method
391 call a single object path parameter is received and
394 <programlisting># busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
395 o "/org/freedesktop/systemd1/job/42684"</programlisting>
400 <title>See Also</title>
403 <citerefentry><refentrytitle>dbus-daemon</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
404 <ulink url="http://freedesktop.org/wiki/Software/dbus">D-Bus</ulink>,
405 <ulink url="https://code.google.com/p/d-bus/">kdbus</ulink>,
406 <citerefentry><refentrytitle>sd-bus</refentrytitle><manvolnum>3</manvolnum></citerefentry>,
407 <citerefentry><refentrytitle>systemd</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
408 <citerefentry><refentrytitle>systemd-bus-proxyd</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
409 <citerefentry><refentrytitle>machinectl</refentrytitle><manvolnum>1</manvolnum></citerefentry>,
410 <citerefentry><refentrytitle>wireshark</refentrytitle><manvolnum>1</manvolnum></citerefentry>