Debian Codegraph @

upstream/debian-trixie/man1/busctl.1

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