1BUSCTL(1)                           busctl                           BUSCTL(1)
2
3
4

NAME

6       busctl - Introspect the bus
7

SYNOPSIS

9       busctl [OPTIONS...] [COMMAND] [NAME...]
10

DESCRIPTION

12       busctl may be used to introspect and monitor the D-Bus bus.
13

OPTIONS

15       The following options are understood:
16
17       --address=ADDRESS
18           Connect to the bus specified by ADDRESS instead of using suitable
19           defaults for either the system or user bus (see --system and --user
20           options).
21
22       --show-machine
23           When showing the list of peers, show a column containing the names
24           of containers they belong to. See systemd-machined.service(8).
25
26       --unique
27           When showing the list of peers, show only "unique" names (of the
28           form ":number.number").
29
30       --acquired
31           The opposite of --unique — only "well-known" names will be shown.
32
33       --activatable
34           When showing the list of peers, show only peers which have actually
35           not been activated yet, but may be started automatically if
36           accessed.
37
38       --match=MATCH
39           When showing messages being exchanged, show only the subset
40           matching MATCH. See sd_bus_add_match(3).
41
42       --size=
43           When used with the capture command, specifies the maximum bus
44           message size to capture ("snaplen"). Defaults to 4096 bytes.
45
46       --list
47           When used with the tree command, shows a flat list of object paths
48           instead of a tree.
49
50       -q, --quiet
51           When used with the call command, suppresses display of the response
52           message payload. Note that even if this option is specified, errors
53           returned will still be printed and the tool will indicate success
54           or failure with the process exit code.
55
56       --verbose
57           When used with the call or get-property command, shows output in a
58           more verbose format.
59
60       --expect-reply=BOOL
61           When used with the call command, specifies whether busctl shall
62           wait for completion of the method call, output the returned method
63           response data, and return success or failure via the process exit
64           code. If this is set to "no", the method call will be issued but no
65           response is expected, the tool terminates immediately, and thus no
66           response can be shown, and no success or failure is returned via
67           the exit code. To only suppress output of the reply message
68           payload, use --quiet above. Defaults to "yes".
69
70       --auto-start=BOOL
71           When used with the call command, specifies whether the method call
72           should implicitly activate the called service, should it not be
73           running yet but is configured to be auto-started. Defaults to
74           "yes".
75
76       --allow-interactive-authorization=BOOL
77           When used with the call command, specifies whether the services may
78           enforce interactive authorization while executing the operation, if
79           the security policy is configured for this. Defaults to "yes".
80
81       --timeout=SECS
82           When used with the call command, specifies the maximum time to wait
83           for method call completion. If no time unit is specified, assumes
84           seconds. The usual other units are understood, too (ms, us, s, min,
85           h, d, w, month, y). Note that this timeout does not apply if
86           --expect-reply=no is used, as the tool does not wait for any reply
87           message then. When not specified or when set to 0, the default of
88           "25s" is assumed.
89
90       --augment-creds=BOOL
91           Controls whether credential data reported by list or status shall
92           be augmented with data from /proc. When this is turned on, the data
93           shown is possibly inconsistent, as the data read from /proc might
94           be more recent than the rest of the credential information.
95           Defaults to "yes".
96
97       --watch-bind=BOOL
98           Controls whether to wait for the specified AF_UNIX bus socket to
99           appear in the file system before connecting to it. Defaults to off.
100           When enabled, the tool will watch the file system until the socket
101           is created and then connect to it.
102
103       --user
104           Talk to the service manager of the calling user, rather than the
105           service manager of the system.
106
107       --system
108           Talk to the service manager of the system. This is the implied
109           default.
110
111       -H, --host=
112           Execute the operation remotely. Specify a hostname, or a username
113           and hostname separated by "@", to connect to. The hostname may
114           optionally be suffixed by a container name, separated by ":", which
115           connects directly to a specific container on the specified host.
116           This will use SSH to talk to the remote machine manager instance.
117           Container names may be enumerated with machinectl -H HOST.
118
119       -M, --machine=
120           Execute operation on a local container. Specify a container name to
121           connect to.
122
123       --no-pager
124           Do not pipe output into a pager.
125
126       --no-legend
127           Do not print the legend, i.e. column headers and the footer with
128           hints.
129
130       -h, --help
131           Print a short help text and exit.
132
133       --version
134           Print a short version string and exit.
135

COMMANDS

137       The following commands are understood:
138
139       list
140           Show all peers on the bus, by their service names. By default,
141           shows both unique and well-known names, but this may be changed
142           with the --unique and --acquired switches. This is the default
143           operation if no command is specified.
144
145       status [SERVICE]
146           Show process information and credentials of a bus service (if one
147           is specified by its unique or well-known name), a process (if one
148           is specified by its numeric PID), or the owner of the bus (if no
149           parameter is specified).
150
151       monitor [SERVICE...]
152           Dump messages being exchanged. If SERVICE is specified, show
153           messages to or from this peer, identified by its well-known or
154           unique name. Otherwise, show all messages on the bus. Use Ctrl-C to
155           terminate the dump.
156
157       capture [SERVICE...]
158           Similar to monitor but writes the output in pcap format (for
159           details, see the Libpcap File Format[1] description). Make sure to
160           redirect standard output to a file. Tools like wireshark(1) may be
161           used to dissect and view the resulting files.
162
163       tree [SERVICE...]
164           Shows an object tree of one or more services. If SERVICE is
165           specified, show object tree of the specified services only.
166           Otherwise, show all object trees of all services on the bus that
167           acquired at least one well-known name.
168
169       introspect SERVICE OBJECT [INTERFACE]
170           Show interfaces, methods, properties and signals of the specified
171           object (identified by its path) on the specified service. If the
172           interface argument is passed, the output is limited to members of
173           the specified interface.
174
175       call SERVICE OBJECT INTERFACE METHOD [SIGNATURE [ARGUMENT...]]
176           Invoke a method and show the response. Takes a service name, object
177           path, interface name and method name. If parameters shall be passed
178           to the method call, a signature string is required, followed by the
179           arguments, individually formatted as strings. For details on the
180           formatting used, see below. To suppress output of the returned
181           data, use the --quiet option.
182
183       get-property SERVICE OBJECT INTERFACE PROPERTY...
184           Retrieve the current value of one or more object properties. Takes
185           a service name, object path, interface name and property name.
186           Multiple properties may be specified at once, in which case their
187           values will be shown one after the other, separated by newlines.
188           The output is, by default, in terse format. Use --verbose for a
189           more elaborate output format.
190
191       set-property SERVICE OBJECT INTERFACE PROPERTY SIGNATURE ARGUMENT...
192           Set the current value of an object property. Takes a service name,
193           object path, interface name, property name, property signature,
194           followed by a list of parameters formatted as strings.
195
196       help
197           Show command syntax help.
198

PARAMETER FORMATTING

200       The call and set-property commands take a signature string followed by
201       a list of parameters formatted as string (for details on D-Bus
202       signature strings, see the Type system chapter of the D-Bus
203       specification[2]). For simple types, each parameter following the
204       signature should simply be the parameter's value formatted as string.
205       Positive boolean values may be formatted as "true", "yes", "on", or
206       "1"; negative boolean values may be specified as "false", "no", "off",
207       or "0". For arrays, a numeric argument for the number of entries
208       followed by the entries shall be specified. For variants, the signature
209       of the contents shall be specified, followed by the contents. For
210       dictionaries and structs, the contents of them shall be directly
211       specified.
212
213       For example,
214
215           s jawoll
216
217       is the formatting of a single string "jawoll".
218
219           as 3 hello world foobar
220
221       is the formatting of a string array with three entries, "hello",
222       "world" and "foobar".
223
224           a{sv} 3 One s Eins Two u 2 Yes b true
225
226       is the formatting of a dictionary array that maps strings to variants,
227       consisting of three entries. The string "One" is assigned the string
228       "Eins". The string "Two" is assigned the 32-bit unsigned integer 2. The
229       string "Yes" is assigned a positive boolean.
230
231       Note that the call, get-property, introspect commands will also
232       generate output in this format for the returned data. Since this format
233       is sometimes too terse to be easily understood, the call and
234       get-property commands may generate a more verbose, multi-line output
235       when passed the --verbose option.
236

EXAMPLES

238       Example 1. Write and Read a Property
239
240       The following two commands first write a property and then read it
241       back. The property is found on the "/org/freedesktop/systemd1" object
242       of the "org.freedesktop.systemd1" service. The name of the property is
243       "LogLevel" on the "org.freedesktop.systemd1.Manager" interface. The
244       property contains a single string:
245
246           # busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
247           # busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
248           s "debug"
249
250       Example 2. Terse and Verbose Output
251
252       The following two commands read a property that contains an array of
253       strings, and first show it in terse format, followed by verbose format:
254
255           $ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
256           as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
257           $ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
258           ARRAY "s" {
259                   STRING "LANG=en_US.UTF-8";
260                   STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
261           };
262
263       Example 3. Invoking a Method
264
265       The following command invokes the "StartUnit" method on the
266       "org.freedesktop.systemd1.Manager" interface of the
267       "/org/freedesktop/systemd1" object of the "org.freedesktop.systemd1"
268       service, and passes it two strings "cups.service" and "replace". As a
269       result of the method call, a single object path parameter is received
270       and shown:
271
272           # busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
273           o "/org/freedesktop/systemd1/job/42684"
274

SEE ALSO

276       dbus-daemon(1), D-Bus[3], sd-bus(3), systemd(1), machinectl(1),
277       wireshark(1)
278

NOTES

280        1. Libpcap File Format
281           https://wiki.wireshark.org/Development/LibpcapFileFormat
282
283        2. Type system chapter of the D-Bus specification
284           http://dbus.freedesktop.org/doc/dbus-specification.html#type-system
285
286        3. D-Bus
287           https://www.freedesktop.org/wiki/Software/dbus
288
289
290
291systemd 239                                                          BUSCTL(1)
Impressum