Debian Codegraph @

upstream/debian-unstable/man1/busctl.1

raw
1 '\" t
2 .TH "BUSCTL" "1" "" "systemd 261~rc3" "busctl"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 busctl \- Introspect the bus
24 .SH "SYNOPSIS"
25 .HP \w'\fBbusctl\fR\ 'u
26 \fBbusctl\fR [OPTIONS...] [COMMAND] [\fINAME\fR...]
27 .SH "DESCRIPTION"
28 .PP
29 \fBbusctl\fR
30 may be used to introspect and monitor the D\-Bus bus\&.
31 .SH "COMMANDS"
32 .PP
33 The following commands are understood:
34 .PP
35 \fBlist\fR
36 .RS 4
37 Show all peers on the bus, by their service names\&. By default, shows both unique and well\-known names, but this may be changed with the
38 \fB\-\-unique\fR
39 and
40 \fB\-\-acquired\fR
41 switches\&. This is the default operation if no command is specified\&.
42 .sp
43 Added in version 209\&.
44 .RE
45 .PP
46 \fBstatus\fR [\fISERVICE\fR]
47 .RS 4
48 Show process information and credentials of a bus service (if one is specified by its unique or well\-known name), a process (if one is specified by its numeric PID), or the owner of the bus (if no parameter is specified)\&.
49 .sp
50 Added in version 209\&.
51 .RE
52 .PP
53 \fBmonitor\fR [\fISERVICE\fR...]
54 .RS 4
55 Dump messages being exchanged\&. If
56 \fISERVICE\fR
57 is specified, show messages to or from this peer, identified by its well\-known or unique name\&. Otherwise, show all messages on the bus\&. Use
58 Ctrl+C
59 to terminate the dump or limit it with the
60 \fB\-\-limit\-messages=\fR
61 option\&.
62 .sp
63 Added in version 209\&.
64 .RE
65 .PP
66 \fBcapture\fR [\fISERVICE\fR...]
67 .RS 4
68 Similar to
69 \fBmonitor\fR
70 but writes the output in pcapng format (for details, see
71 \m[blue]\fBPCAP Next Generation (pcapng) Capture File Format\fR\m[]\&\s-2\u[1]\d\s+2)\&. Make sure to redirect standard output to a file or pipe\&. Tools like
72 \fBwireshark\fR(1)
73 may be used to dissect and view the resulting files\&.
74 .sp
75 Added in version 218\&.
76 .RE
77 .PP
78 \fBtree\fR [\fISERVICE\fR...]
79 .RS 4
80 Shows an object tree of one or more services\&. If
81 \fISERVICE\fR
82 is specified, show object tree of the specified services only\&. Otherwise, show all object trees of all services on the bus that acquired at least one well\-known name\&.
83 .sp
84 Added in version 218\&.
85 .RE
86 .PP
87 \fBintrospect\fR \fISERVICE\fR \fIOBJECT\fR [\fIINTERFACE\fR]
88 .RS 4
89 Show interfaces, methods, properties and signals of the specified object (identified by its path) on the specified service\&. If the interface argument is passed, the output is limited to members of the specified interface\&.
90 .sp
91 Added in version 218\&.
92 .RE
93 .PP
94 \fBcall\fR \fISERVICE\fR \fIOBJECT\fR \fIINTERFACE\fR \fIMETHOD\fR [\fISIGNATURE\fR\ [\fIARGUMENT\fR...]]
95 .RS 4
96 Invoke a method and show the response\&. Takes a service name, object path, interface name and method name\&. If parameters shall be passed to the method call, a signature string is required, followed by the arguments, individually formatted as strings\&. For details on the formatting used, see below\&. To suppress output of the returned data, use the
97 \fB\-\-quiet\fR
98 option\&.
99 .sp
100 Added in version 218\&.
101 .RE
102 .PP
103 \fBemit\fR \fIOBJECT\fR \fIINTERFACE\fR \fISIGNAL\fR [\fISIGNATURE\fR\ [\fIARGUMENT\fR...]]
104 .RS 4
105 Emit a signal\&. Takes an object path, interface name and method name\&. If parameters shall be passed, a signature string is required, followed by the arguments, individually formatted as strings\&. For details on the formatting used, see below\&. To specify the destination of the signal, use the
106 \fB\-\-destination=\fR
107 option\&.
108 .sp
109 Added in version 242\&.
110 .RE
111 .PP
112 \fBwait\fR [\fISERVICE\fR] \fIOBJECT\fR \fIINTERFACE\fR \fISIGNAL\fR
113 .RS 4
114 Wait for a signal\&. Takes an object path, interface name, and signal name\&. Use the
115 \fB\-\-limit\-messages=\fR
116 option to wait for more than just one signal before exiting\&. To suppress output of the returned data, use the
117 \fB\-\-quiet\fR
118 option\&. The service name may be omitted, in which case
119 \fBbusctl\fR
120 will match signals from any sender\&.
121 .sp
122 Added in version 257\&.
123 .RE
124 .PP
125 \fBget\-property\fR \fISERVICE\fR \fIOBJECT\fR \fIINTERFACE\fR \fIPROPERTY\fR...
126 .RS 4
127 Retrieve the current value of one or more object properties\&. Takes a service name, object path, interface name and property name\&. Multiple properties may be specified at once, in which case their values will be shown one after the other, separated by newlines\&. The output is, by default, in terse format\&. Use
128 \fB\-\-verbose\fR
129 for a more elaborate output format\&.
130 .sp
131 Added in version 218\&.
132 .RE
133 .PP
134 \fBset\-property\fR \fISERVICE\fR \fIOBJECT\fR \fIINTERFACE\fR \fIPROPERTY\fR \fISIGNATURE\fR \fIARGUMENT\fR...
135 .RS 4
136 Set the current value of an object property\&. Takes a service name, object path, interface name, property name, property signature, followed by a list of parameters formatted as strings\&.
137 .sp
138 Added in version 218\&.
139 .RE
140 .PP
141 \fBhelp\fR
142 .RS 4
143 Show command syntax help\&.
144 .sp
145 Added in version 209\&.
146 .RE
147 .SH "OPTIONS"
148 .PP
149 The following options are understood:
150 .PP
151 \fB\-\-address=\fR\fB\fIADDRESS\fR\fR
152 .RS 4
153 Connect to the bus specified by
154 \fIADDRESS\fR
155 instead of using suitable defaults for either the system or user bus (see
156 \fB\-\-system\fR
157 and
158 \fB\-\-user\fR
159 options)\&.
160 .sp
161 Added in version 209\&.
162 .RE
163 .PP
164 \fB\-\-show\-machine\fR
165 .RS 4
166 When showing the list of peers, show a column containing the names of containers they belong to\&. See
167 \fBsystemd-machined.service\fR(8)\&.
168 .sp
169 Added in version 209\&.
170 .RE
171 .PP
172 \fB\-\-unique\fR
173 .RS 4
174 When showing the list of peers, show only "unique" names (of the form
175 ":\fInumber\fR\&.\fInumber\fR")\&.
176 .sp
177 Added in version 209\&.
178 .RE
179 .PP
180 \fB\-\-acquired\fR
181 .RS 4
182 The opposite of
183 \fB\-\-unique\fR
184 \(em only "well\-known" names will be shown\&.
185 .sp
186 Added in version 209\&.
187 .RE
188 .PP
189 \fB\-\-activatable\fR
190 .RS 4
191 When showing the list of peers, show only peers which have actually not been activated yet, but may be started automatically if accessed\&.
192 .sp
193 Added in version 209\&.
194 .RE
195 .PP
196 \fB\-\-match=\fR\fB\fIMATCH\fR\fR
197 .RS 4
198 When showing messages being exchanged, show only the subset matching
199 \fIMATCH\fR\&. See
200 \fBsd_bus_add_match\fR(3)\&.
201 .sp
202 Added in version 209\&.
203 .RE
204 .PP
205 \fB\-\-size=\fR
206 .RS 4
207 When used with the
208 \fBcapture\fR
209 command, specifies the maximum bus message size to capture ("snaplen")\&. Defaults to 4096 bytes\&.
210 .sp
211 Added in version 218\&.
212 .RE
213 .PP
214 \fB\-\-list\fR
215 .RS 4
216 When used with the
217 \fBtree\fR
218 command, shows a flat list of object paths instead of a tree\&.
219 .sp
220 Added in version 218\&.
221 .RE
222 .PP
223 \fB\-q\fR, \fB\-\-quiet\fR
224 .RS 4
225 When used with the
226 \fBcall\fR
227 command, suppresses display of the response message payload\&. Note that even if this option is specified, errors returned will still be printed and the tool will indicate success or failure with the process exit code\&.
228 .sp
229 Added in version 218\&.
230 .RE
231 .PP
232 \fB\-\-verbose\fR
233 .RS 4
234 When used with the
235 \fBcall\fR
236 or
237 \fBget\-property\fR
238 command, shows output in a more verbose format\&.
239 .sp
240 Added in version 218\&.
241 .RE
242 .PP
243 \fB\-\-xml\-interface\fR
244 .RS 4
245 When used with the
246 \fBintrospect\fR
247 call, dump the XML description received from the D\-Bus
248 \fBorg\&.freedesktop\&.DBus\&.Introspectable\&.Introspect\fR
249 call instead of the normal output\&.
250 .sp
251 Added in version 243\&.
252 .RE
253 .PP
254 \fB\-\-expect\-reply=\fR\fB\fIBOOL\fR\fR
255 .RS 4
256 When used with the
257 \fBcall\fR
258 command, specifies whether
259 \fBbusctl\fR
260 shall wait for completion of the method call, output the returned method response data, and return success or failure via the process exit code\&. If this is set to
261 "no", the method call will be issued but no response is expected, the tool terminates immediately, and thus no response can be shown, and no success or failure is returned via the exit code\&. To only suppress output of the reply message payload, use
262 \fB\-\-quiet\fR
263 above\&. Defaults to
264 "yes"\&.
265 .sp
266 Added in version 218\&.
267 .RE
268 .PP
269 \fB\-\-auto\-start=\fR\fB\fIBOOL\fR\fR
270 .RS 4
271 When used with the
272 \fBcall\fR
273 or
274 \fBemit\fR
275 command, specifies whether the method call should implicitly activate the called service, should it not be running yet but is configured to be auto\-started\&. Defaults to
276 "yes"\&.
277 .sp
278 Added in version 218\&.
279 .RE
280 .PP
281 \fB\-\-allow\-interactive\-authorization=\fR\fB\fIBOOL\fR\fR
282 .RS 4
283 When used with the
284 \fBcall\fR
285 command, specifies whether the services may enforce interactive authorization while executing the operation, if the security policy is configured for this\&. Defaults to
286 "yes"\&.
287 .sp
288 Added in version 218\&.
289 .RE
290 .PP
291 \fB\-\-timeout=\fR\fB\fISECS\fR\fR
292 .RS 4
293 When used with the
294 \fBcall\fR
295 command, specifies the maximum time to wait for method call completion\&. When used with the
296 \fBmonitor\fR
297 command, since version v257, specifies the maximum time to wait for messages before automatically exiting\&. If no time unit is specified, assumes seconds\&. The usual other units are understood, too (ms, us, s, min, h, d, w, month, y)\&. Note that this timeout does not apply if
298 \fB\-\-expect\-reply=no\fR
299 is used, when combined with the
300 \fBcall\fR
301 command, as the tool does not wait for any reply message then\&. When not specified or when set to 0, the default of
302 "25s"
303 is assumed for the
304 \fBcall\fR
305 command, and it is disabled for the
306 \fBmonitor\fR
307 command\&.
308 .sp
309 Added in version 218\&.
310 .RE
311 .PP
312 \fB\-\-limit\-messages=\fR\fB\fINUMBER\fR\fR, \fB\-N \fR\fB\fINUMBER\fR\fR
313 .RS 4
314 When used with the
315 \fBmonitor\fR
316 command, if enabled will make
317 \fBbusctl\fR
318 exit when the specified number of messages have been received and printed\&. This is useful in combination with
319 \fB\-\-match=\fR, to wait for the specified number of occurrences of specific D\-Bus messages\&. While if not specified or is set to special value
320 "infinity", the default is to keep monitoring without limitations\&.
321 .sp
322 When used with the
323 \fBwait\fR
324 command, it will make
325 \fBbusctl\fR
326 exit when the specified number of DBus signals have been received and printed\&. Setting it to special value
327 "infinity"
328 will sustain
329 \fBbusctl\fR
330 to receive and print signals continuously without limitations\&. When nothing is specified, the default is to exit immediately after receiving and printing the first signal\&.
331 .sp
332 Added in version 257\&.
333 .RE
334 .PP
335 \fB\-\-augment\-creds=\fR\fB\fIBOOL\fR\fR
336 .RS 4
337 Controls whether credential data reported by
338 \fBlist\fR
339 or
340 \fBstatus\fR
341 shall be augmented with data from
342 /proc/\&. When this is turned on, the data shown is possibly inconsistent, as the data read from
343 /proc/
344 might be more recent than the rest of the credential information\&. Defaults to
345 "yes"\&.
346 .sp
347 Added in version 218\&.
348 .RE
349 .PP
350 \fB\-\-watch\-bind=\fR\fB\fIBOOL\fR\fR
351 .RS 4
352 Controls whether to wait for the specified
353 \fBAF_UNIX\fR
354 bus socket to appear in the file system before connecting to it\&. Defaults to off\&. When enabled, the tool will watch the file system until the socket is created and then connect to it\&.
355 .sp
356 Added in version 237\&.
357 .RE
358 .PP
359 \fB\-\-destination=\fR\fB\fISERVICE\fR\fR
360 .RS 4
361 Takes a service name\&. When used with the
362 \fBemit\fR
363 command, a signal is emitted to the specified service\&.
364 .sp
365 Added in version 242\&.
366 .RE
367 .PP
368 \fB\-\-user\fR
369 .RS 4
370 Talk to the service manager of the calling user, rather than the service manager of the system\&.
371 .RE
372 .PP
373 \fB\-\-system\fR
374 .RS 4
375 Talk to the service manager of the system\&. This is the implied default\&.
376 .RE
377 .PP
378 \fB\-H\fR, \fB\-\-host=\fR
379 .RS 4
380 Execute the operation remotely\&. Specify a hostname, or a username and hostname separated by
381 "@", to connect to\&. The hostname may optionally be suffixed by a port ssh is listening on, separated by
382 ":", and then a container name, separated by
383 "/", which connects directly to a specific container on the specified host\&. This will use SSH to talk to the remote machine manager instance\&. Container names may be enumerated with
384 \fBmachinectl \-H \fR\fB\fIHOST\fR\fR\&. Put IPv6 addresses in brackets\&.
385 .RE
386 .PP
387 \fB\-M\fR, \fB\-\-machine=\fR
388 .RS 4
389 Execute operation on a local container\&. Specify a container name to connect to, optionally prefixed by a user name to connect as and a separating
390 "@"
391 character\&. If the special string
392 "\&.host"
393 is used in place of the container name, a connection to the local system is made (which is useful to connect to a specific user\*(Aqs user bus:
394 "\-\-user \-\-machine=lennart@\&.host")\&. If the
395 "@"
396 syntax is not used, the connection is made as root user\&. If the
397 "@"
398 syntax is used either the left hand side or the right hand side may be omitted (but not both) in which case the local user name and
399 "\&.host"
400 are implied\&.
401 .RE
402 .PP
403 \fB\-C\fR, \fB\-\-capsule=\fR
404 .RS 4
405 Execute operation on a capsule\&. Specify a capsule name to connect to\&. See
406 \[email protected]\fR(5)
407 for details about capsules\&.
408 .sp
409 Added in version 256\&.
410 .RE
411 .PP
412 \fB\-l\fR, \fB\-\-full\fR
413 .RS 4
414 Do not ellipsize the output in
415 \fBlist\fR
416 command\&.
417 .sp
418 Added in version 245\&.
419 .RE
420 .PP
421 \fB\-\-json=\fR\fB\fIMODE\fR\fR
422 .RS 4
423 Shows output formatted as JSON\&. Expects one of
424 "short"
425 (for the shortest possible output without any redundant whitespace or line breaks),
426 "pretty"
427 (for a pretty version of the same, with indentation and line breaks) or
428 "off"
429 (to turn off JSON output, the default)\&.
430 .RE
431 .PP
432 \fB\-j\fR
433 .RS 4
434 Equivalent to
435 \fB\-\-json=pretty\fR
436 if running on a terminal, and
437 \fB\-\-json=short\fR
438 otherwise\&.
439 .RE
440 .PP
441 \fB\-\-no\-pager\fR
442 .RS 4
443 Do not pipe output into a pager\&.
444 .RE
445 .PP
446 \fB\-\-no\-legend\fR
447 .RS 4
448 Do not print the legend, i\&.e\&. column headers and the footer with hints\&.
449 .RE
450 .PP
451 \fB\-h\fR, \fB\-\-help\fR
452 .RS 4
453 Print a short help text and exit\&.
454 .RE
455 .PP
456 \fB\-\-version\fR
457 .RS 4
458 Print a short version string and exit\&.
459 .RE
460 .SH "PARAMETER FORMATTING"
461 .PP
462 The
463 \fBcall\fR
464 and
465 \fBset\-property\fR
466 commands take a signature string followed by a list of parameters formatted as string (for details on D\-Bus signature strings, see the
467 \m[blue]\fBType system chapter of the D\-Bus specification\fR\m[]\&\s-2\u[2]\d\s+2)\&. For simple types, each parameter following the signature should simply be the parameter\*(Aqs value formatted as string\&. Positive boolean values may be formatted as
468 "true",
469 "yes",
470 "on", or
471 "1"; negative boolean values may be specified as
472 "false",
473 "no",
474 "off", or
475 "0"\&. For arrays, a numeric argument for the number of entries followed by the entries shall be specified\&. For variants, the signature of the contents shall be specified, followed by the contents\&. For dictionaries and structs, the contents of them shall be directly specified\&.
476 .PP
477 For example,
478 .sp
479 .if n \{\
480 .RS 4
481 .\}
482 .nf
483 s jawoll
484 .fi
485 .if n \{\
486 .RE
487 .\}
488 .sp
489 is the formatting of a single string
490 "jawoll"\&.
491 .PP
492 .if n \{\
493 .RS 4
494 .\}
495 .nf
496 as 3 hello world foobar
497 .fi
498 .if n \{\
499 .RE
500 .\}
501 .sp
502 is the formatting of a string array with three entries,
503 "hello",
504 "world"
505 and
506 "foobar"\&.
507 .PP
508 .if n \{\
509 .RS 4
510 .\}
511 .nf
512 a{sv} 3 One s Eins Two u 2 Yes b true
513 .fi
514 .if n \{\
515 .RE
516 .\}
517 .sp
518 is the formatting of a dictionary array that maps strings to variants, consisting of three entries\&. The string
519 "One"
520 is assigned the string
521 "Eins"\&. The string
522 "Two"
523 is assigned the 32\-bit unsigned integer 2\&. The string
524 "Yes"
525 is assigned a positive boolean\&.
526 .PP
527 Note that the
528 \fBcall\fR,
529 \fBget\-property\fR,
530 \fBintrospect\fR
531 commands will also generate output in this format for the returned data\&. Since this format is sometimes too terse to be easily understood, the
532 \fBcall\fR
533 and
534 \fBget\-property\fR
535 commands may generate a more verbose, multi\-line output when passed the
536 \fB\-\-verbose\fR
537 option\&.
538 .SH "EXAMPLES"
539 .PP
540 \fBExample\ \&1.\ \&Write and Read a Property\fR
541 .PP
542 The following two commands first write a property and then read it back\&. The property is found on the
543 "/org/freedesktop/systemd1"
544 object of the
545 "org\&.freedesktop\&.systemd1"
546 service\&. The name of the property is
547 "LogLevel"
548 on the
549 "org\&.freedesktop\&.systemd1\&.Manager"
550 interface\&. The property contains a single string:
551 .sp
552 .if n \{\
553 .RS 4
554 .\}
555 .nf
556 # busctl set\-property org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager LogLevel s debug
557 # busctl get\-property org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager LogLevel
558 s "debug"
559 .fi
560 .if n \{\
561 .RE
562 .\}
563 .PP
564 \fBExample\ \&2.\ \&Terse and Verbose Output\fR
565 .PP
566 The following two commands read a property that contains an array of strings, and first show it in terse format, followed by verbose format:
567 .sp
568 .if n \{\
569 .RS 4
570 .\}
571 .nf
572 $ busctl get\-property org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager Environment
573 as 2 "LANG=en_US\&.UTF\-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
574 $ busctl get\-property \-\-verbose org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager Environment
575 ARRAY "s" {
576 STRING "LANG=en_US\&.UTF\-8";
577 STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
578 };
579 .fi
580 .if n \{\
581 .RE
582 .\}
583 .PP
584 \fBExample\ \&3.\ \&Invoking a Method\fR
585 .PP
586 The following command invokes the
587 "StartUnit"
588 method on the
589 "org\&.freedesktop\&.systemd1\&.Manager"
590 interface of the
591 "/org/freedesktop/systemd1"
592 object of the
593 "org\&.freedesktop\&.systemd1"
594 service, and passes it two strings
595 "cups\&.service"
596 and
597 "replace"\&. As a result of the method call, a single object path parameter is received and shown:
598 .sp
599 .if n \{\
600 .RS 4
601 .\}
602 .nf
603 # busctl call org\&.freedesktop\&.systemd1 /org/freedesktop/systemd1 org\&.freedesktop\&.systemd1\&.Manager StartUnit ss "cups\&.service" "replace"
604 o "/org/freedesktop/systemd1/job/42684"
605 .fi
606 .if n \{\
607 .RE
608 .\}
609 .SH "SEE ALSO"
610 .PP
611 \fBdbus-daemon\fR(1), \m[blue]\fBD\-Bus\fR\m[]\&\s-2\u[3]\d\s+2, \fBsd-bus\fR(3), \fBvarlinkctl\fR(1), \fBsystemd\fR(1), \fBmachinectl\fR(1), \fBwireshark\fR(1)
612 .SH "NOTES"
613 .IP " 1." 4
614 PCAP Next Generation (pcapng) Capture File Format
615 .RS 4
616 \%https://github.com/pcapng/pcapng/
617 .RE
618 .IP " 2." 4
619 Type system chapter of the D-Bus specification
620 .RS 4
621 \%https://dbus.freedesktop.org/doc/dbus-specification.html#type-system
622 .RE
623 .IP " 3." 4
624 D-Bus
625 .RS 4
626 \%https://www.freedesktop.org/wiki/Software/dbus
627 .RE