Debian Codegraph @

upstream/opensuse-tumbleweed/man1/varlinkctl.1

raw
1 '\" t
2 .TH "VARLINKCTL" "1" "" "systemd 260.1" "varlinkctl"
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 varlinkctl \- Introspect with and invoke Varlink services
24 .SH "SYNOPSIS"
25 .HP \w'\fBvarlinkctl\fR\ 'u
26 \fBvarlinkctl\fR [OPTIONS...] info \fIADDRESS\fR
27 .HP \w'\fBvarlinkctl\fR\ 'u
28 \fBvarlinkctl\fR [OPTIONS...] list\-interfaces \fIADDRESS\fR
29 .HP \w'\fBvarlinkctl\fR\ 'u
30 \fBvarlinkctl\fR [OPTIONS...] list\-methods \fIADDRESS\fR [\fIINTERFACE\fR...]
31 .HP \w'\fBvarlinkctl\fR\ 'u
32 \fBvarlinkctl\fR [OPTIONS...] introspect \fIADDRESS\fR [\fIINTERFACE\fR...]
33 .HP \w'\fBvarlinkctl\fR\ 'u
34 \fBvarlinkctl\fR [OPTIONS...] call \fIADDRESS\fR \fIMETHOD\fR [\fIARGUMENTS\fR]
35 .HP \w'\fBvarlinkctl\fR\ 'u
36 \fBvarlinkctl\fR [OPTIONS...] \-\-exec\ call call \fIADDRESS\fR \fIMETHOD\fR \fIARGUMENTS\fR \-\- \fICMDLINE\fR
37 .HP \w'\fBvarlinkctl\fR\ 'u
38 \fBvarlinkctl\fR [OPTIONS...] validate\-idl [\fIFILE\fR]
39 .SH "DESCRIPTION"
40 .PP
41 \fBvarlinkctl\fR
42 may be used to introspect and invoke
43 \m[blue]\fBVarlink\fR\m[]\&\s-2\u[1]\d\s+2
44 services\&.
45 .PP
46 Services are referenced by one of the following:
47 .sp
48 .RS 4
49 .ie n \{\
50 \h'-04'\(bu\h'+03'\c
51 .\}
52 .el \{\
53 .sp -1
54 .IP \(bu 2.3
55 .\}
56 A Varlink service reference starting with the
57 "unix:"
58 string, followed by an absolute
59 \fBAF_UNIX\fR
60 socket path, or by
61 "@"
62 and an arbitrary string (the latter for referencing sockets in the abstract namespace)\&. In this case, a stream socket connection is made to the specified socket\&.
63 .RE
64 .sp
65 .RS 4
66 .ie n \{\
67 \h'-04'\(bu\h'+03'\c
68 .\}
69 .el \{\
70 .sp -1
71 .IP \(bu 2.3
72 .\}
73 A Varlink service reference starting with the
74 "exec:"
75 string, followed by an absolute path of a binary to execute\&. In this case, the specified process is forked off locally, with a connected stream socket passed in\&.
76 .RE
77 .sp
78 .RS 4
79 .ie n \{\
80 \h'-04'\(bu\h'+03'\c
81 .\}
82 .el \{\
83 .sp -1
84 .IP \(bu 2.3
85 .\}
86 A Varlink service reference starting with the
87 "ssh\-unix:"
88 string, followed by an SSH host specification, followed by
89 ":", followed by an absolute
90 \fBAF_UNIX\fR
91 socket path\&. (This requires OpenSSH 9\&.4 or newer on the server side, and abstract namespace sockets are not supported\&.)
92 .RE
93 .sp
94 .RS 4
95 .ie n \{\
96 \h'-04'\(bu\h'+03'\c
97 .\}
98 .el \{\
99 .sp -1
100 .IP \(bu 2.3
101 .\}
102 A Varlink service reference starting with the
103 "ssh\-exec:"
104 string, followed by an SSH host specification, followed by
105 ":", followed by a command line\&. In this case, the command is invoked and the Varlink protocol is spoken on the standard input and output of the invoked command\&.
106 .RE
107 .PP
108 For convenience, these two simpler (redundant) service address syntaxes are also supported:
109 .sp
110 .RS 4
111 .ie n \{\
112 \h'-04'\(bu\h'+03'\c
113 .\}
114 .el \{\
115 .sp -1
116 .IP \(bu 2.3
117 .\}
118 A file system path to an
119 \fBAF_UNIX\fR
120 socket, either absolute (i\&.e\&. begins with
121 "/") or relative (in which case it must begin with
122 "\&./")\&.
123 .RE
124 .sp
125 .RS 4
126 .ie n \{\
127 \h'-04'\(bu\h'+03'\c
128 .\}
129 .el \{\
130 .sp -1
131 .IP \(bu 2.3
132 .\}
133 A file system path to an executable, either absolute or relative (as above, must begin with
134 "/"
135 or
136 "\&./", respectively)\&.
137 .RE
138 .SH "COMMANDS"
139 .PP
140 The following commands are understood:
141 .PP
142 \fBinfo\fR \fIADDRESS\fR
143 .RS 4
144 Shows brief information about the specified service, including vendor name and list of implemented interfaces\&. Expects a service address in one of the formats described above\&.
145 .sp
146 Added in version 255\&.
147 .RE
148 .PP
149 \fBlist\-interfaces\fR \fIADDRESS\fR
150 .RS 4
151 Shows a list of interfaces implemented by the specified service\&. Expects a service address in one of the formats described above\&.
152 .sp
153 Added in version 255\&.
154 .RE
155 .PP
156 \fBlist\-methods\fR \fIADDRESS\fR [\fIINTERFACE\&...\fR]
157 .RS 4
158 Shows a list of methods implemented by the specified service\&. Expects a service address in one of the formats described above as well as one or more interface names\&. If no interface name is specified, lists all methods of all interfaces implemented by the service, otherwise just the methods in the specified interfaces\&.
159 .sp
160 Added in version 257\&.
161 .RE
162 .PP
163 \fBintrospect\fR \fIADDRESS\fR [\fIINTERFACE\&...\fR]
164 .RS 4
165 Shows the interface definitions of the specified interfaces provided by the specified service\&. Expects a service address in one of the formats described above and optionally one or more Varlink interface names\&. If no interface names are specified, shows all provided interfaces by the service\&.
166 .sp
167 Added in version 255\&.
168 .RE
169 .PP
170 \fBcall\fR \fIADDRESS\fR \fIMETHOD\fR [\fIARGUMENTS\fR]
171 .RS 4
172 Calls the specified method of the specified service\&. Expects a service address in the format described above, a fully qualified Varlink method name, and a JSON arguments object\&. If the arguments object is not specified, it is read from STDIN instead\&. To pass an empty list of parameters, specify the empty object
173 "{}"\&.
174 .sp
175 The reply parameters are written as JSON objects to STDOUT\&.
176 .sp
177 Added in version 255\&.
178 .RE
179 .PP
180 \fBlist\-registry\fR
181 .RS 4
182 Shows a list of Varlink services currently registered in the service registry, plus their entrypoint sockets\&. (Currently, this simply enumerates the sockets and symlinked sockets in
183 /run/varlink/registry/, see below\&.)
184 .sp
185 Added in version 260\&.
186 .RE
187 .PP
188 \fBvalidate\-idl\fR [\fIFILE\fR]
189 .RS 4
190 Reads a Varlink interface definition file, parses and validates it, then outputs it with syntax highlighting\&. This checks for syntax and internal consistency of the interface\&. Expects a file name to read the interface definition from\&. If omitted, reads the interface definition from STDIN\&.
191 .sp
192 Added in version 255\&.
193 .RE
194 .PP
195 \fBhelp\fR
196 .RS 4
197 Shows command syntax help\&.
198 .sp
199 Added in version 255\&.
200 .RE
201 .SH "OPTIONS"
202 .PP
203 The following options are understood:
204 .PP
205 \fB\-\-more\fR
206 .RS 4
207 When used with
208 \fBcall\fR: expect multiple method replies\&. If this flag is set, the method call is sent with the
209 \fBmore\fR
210 flag set, which tells the service to generate multiple replies, if needed\&. The command remains running until the service sends a reply message that indicates it is the last in the series (or if the configured timeout is reached, see below)\&. This flag should be set only for method calls that support this mechanism\&.
211 .sp
212 If this mode is enabled, output is automatically switched to JSON\-SEQ mode, so that individual reply objects can be easily discerned\&.
213 .sp
214 This switch has no effect on the method call timeout applied by default\&. Regardless of whether
215 \fB\-\-more\fR
216 is specified or not, the default timeout will be 45s\&. Use
217 \fB\-\-timeout=\fR
218 (see below) to change or disable the timeout\&. When invoking a method call that continuously returns updates, it is typically desirable to disable the timeout with
219 \fB\-\-timeout=infinity\fR\&. On the other hand, when invoking a
220 \fB\-\-more\fR
221 method call for the purpose of enumerating objects (which likely will complete quickly), it is typically beneficial to leave the timeout logic enabled, for robustness reasons\&.
222 .sp
223 Added in version 255\&.
224 .RE
225 .PP
226 \fB\-E\fR
227 .RS 4
228 A shortcut for
229 \fB\-\-more \-\-timeout=infinity\fR\&. This switch is useful for method calls that implement subscription to a continuous stream of updates\&.
230 .sp
231 Added in version 257\&.
232 .RE
233 .PP
234 \fB\-\-collect\fR
235 .RS 4
236 This is similar to
237 \fB\-\-more\fR, but collects all responses in a JSON array, and prints it, rather than in JSON\-SEQ mode\&.
238 .sp
239 Added in version 256\&.
240 .RE
241 .PP
242 \fB\-\-oneway\fR
243 .RS 4
244 When used with
245 \fBcall\fR: do not expect a method reply\&. If this flag is set, the method call is sent with the
246 \fBoneway\fR
247 flag set (the command exits immediately after), which tells the service not to generate a reply\&.
248 .sp
249 Added in version 255\&.
250 .RE
251 .PP
252 \fB\-\-json=\fR\fB\fIMODE\fR\fR
253 .RS 4
254 Selects the JSON output formatting, either
255 "pretty"
256 for nicely indented, colorized output, or
257 "short"
258 for terse output with minimal whitespace and no newlines\&. Defaults to
259 "short"\&.
260 .sp
261 Added in version 255\&.
262 .RE
263 .PP
264 \fB\-j\fR
265 .RS 4
266 Equivalent to
267 \fB\-\-json=pretty\fR
268 when invoked interactively from a terminal\&. Otherwise, it is equivalent to
269 \fB\-\-json=short\fR, in particular when the output is piped to some other program\&.
270 .sp
271 Added in version 255\&.
272 .RE
273 .PP
274 \fB\-\-quiet\fR, \fB\-q\fR
275 .RS 4
276 Suppress output of method call replies\&.
277 .sp
278 Added in version 257\&.
279 .RE
280 .PP
281 \fB\-\-graceful=\fR
282 .RS 4
283 Takes a qualified Varlink error name, i\&.e\&. an interface name, suffixed by an error name, separated by a dot, e\&.g\&.
284 "org\&.varlink\&.service\&.InvalidParameter"\&. Ensures that, if a method call fails with the specified error, this will be treated as success, i\&.e\&. will cause the
285 \fBvarlinkctl\fR
286 invocation to exit with a zero exit status\&. This option may be used more than once in order to treat multiple different errors as successes\&.
287 .sp
288 Added in version 257\&.
289 .RE
290 .PP
291 \fB\-\-timeout=\fR
292 .RS 4
293 Expects a timeout in seconds as parameter\&. By default, a timeout of 45s is enforced\&. To turn off the timeout, specify
294 "infinity"
295 or an empty string\&.
296 .sp
297 Added in version 257\&.
298 .RE
299 .PP
300 \fB\-\-exec\fR
301 .RS 4
302 Once the method call issued via
303 \fBcall\fR
304 completed successfully, chainload the specified command line, with the method call output parameters serialized to JSON passed into standard input (and standard output and standard error inherited from the invoking process)\&. Moreover any file descriptors passed back on the underlying communication socket are passed to the invoked process via the usual
305 \fI$LISTEN_FDS\fR
306 protocol\&. This functionality may be used to consume replies that come with associated file descriptors in a reasonable way\&.
307 .sp
308 Now that if
309 \fB\-\-exec\fR
310 is specified the the third parameter to
311 \fBcall\fR
312 is not optional (i\&.e\&. the method call parameters)\&.
313 .sp
314 Added in version 258\&.
315 .RE
316 .PP
317 \fB\-\-push\-fd=\fR
318 .RS 4
319 Takes a numeric file descriptor number as parameter\&. May be used to pass a file descriptor along with the method call, if the underlying transport supports this\&. May be used multiple times to pass multiple file descriptors, retaining the order in which they are specified\&. The specified file descriptors must be passed to the
320 \fBvarlinkctl\fR
321 invocation\&. Optionally, in place of a numeric file descriptor number an absolute or relative file system path (the latter must be prefixed with
322 "\&./") may be specified, which is opened in read\-only mode\&.
323 .sp
324 Added in version 258\&.
325 .RE
326 .PP
327 \fB\-\-system\fR, \fB\-\-user\fR
328 .RS 4
329 Determines whether to query to the per\-system or per\-user registry when using the
330 \fBlist\-registry\fR
331 command\&. By default, the per\-system registry is queried\&.
332 .PP
333 Added in version 260\&.
334 .RE
335 .PP
336 \fB\-\-no\-ask\-password\fR
337 .RS 4
338 Do not query the user for authentication for privileged operations\&.
339 .RE
340 .PP
341 \fB\-\-no\-pager\fR
342 .RS 4
343 Do not pipe output into a pager\&.
344 .RE
345 .PP
346 \fB\-h\fR, \fB\-\-help\fR
347 .RS 4
348 Print a short help text and exit\&.
349 .RE
350 .PP
351 \fB\-\-version\fR
352 .RS 4
353 Print a short version string and exit\&.
354 .RE
355 .SH "FILES & DIRECTORIES"
356 .PP
357 /run/varlink/registry/
358 .RS 4
359 Directory containing
360 \fBAF_UNIX\fR
361 entrypoint socket inodes (or symlinks to them) of well\-known, public Varlink interfaces on the local system\&. They are named after the Varlink interface they implement\&.
362 .sp
363 Use
364 \fBvarlinkctl list\-registry\fR
365 to show the contents of this directory\&.
366 .sp
367 (Inodes that neither qualify as socket inodes nor as symlinks to them shall be ignored\&. A future extension might introduce regular files and directories to enhance the registry functionality\&.)
368 .sp
369 Added in version 260\&.
370 .RE
371 .SH "EXAMPLES"
372 .PP
373 \fBExample\ \&1.\ \&Investigating a Service\fR
374 .PP
375 The following three commands inspect the
376 "io\&.systemd\&.Resolve"
377 service implemented by
378 \fBsystemd-resolved.service\fR(8), listing general service information and implemented interfaces, and then displaying the interface definition of its primary interface:
379 .sp
380 .if n \{\
381 .RS 4
382 .\}
383 .nf
384 $ varlinkctl info /run/systemd/resolve/io\&.systemd\&.Resolve
385 Vendor: The systemd Project
386 Product: systemd (systemd\-resolved)
387 Version: 254 (254\-1522\-g4790521^)
388 URL: https://systemd\&.io/
389 Interfaces: io\&.systemd
390 io\&.systemd\&.Resolve
391 org\&.varlink\&.service
392 $ varlinkctl list\-interfaces /run/systemd/resolve/io\&.systemd\&.Resolve
393 io\&.systemd
394 io\&.systemd\&.Resolve
395 org\&.varlink\&.service
396 $ varlinkctl introspect /run/systemd/resolve/io\&.systemd\&.Resolve io\&.systemd\&.Resolve
397 interface io\&.systemd\&.Resolve
398 type ResolvedAddress(
399 ifindex: ?int,
400 \&...
401 .fi
402 .if n \{\
403 .RE
404 .\}
405 .PP
406 (Interface definition has been truncated in the example above, in the interest of brevity\&.)
407 .PP
408 \fBExample\ \&2.\ \&Invoking a Method\fR
409 .PP
410 The following command resolves a hostname via
411 \fBsystemd-resolved.service\fR(8)\*(Aqs
412 \fBResolveHostname\fR
413 method call\&.
414 .sp
415 .if n \{\
416 .RS 4
417 .\}
418 .nf
419 $ varlinkctl call /run/systemd/resolve/io\&.systemd\&.Resolve io\&.systemd\&.Resolve\&.ResolveHostname \*(Aq{"name":"systemd\&.io","family":2}\*(Aq \-j
420 {
421 "addresses" : [
422 {
423 "ifindex" : 2,
424 "family" : 2,
425 "address" : [
426 185,
427 199,
428 111,
429 153
430 ]
431 }
432 ],
433 "name" : "systemd\&.io",
434 "flags" : 1048577
435 }
436 .fi
437 .if n \{\
438 .RE
439 .\}
440 .PP
441 \fBExample\ \&3.\ \&Investigating a Service Executable\fR
442 .PP
443 The following command inspects the
444 /usr/lib/systemd/systemd\-pcrextend
445 executable and the IPC APIs it provides\&. It then invokes a method on it:
446 .sp
447 .if n \{\
448 .RS 4
449 .\}
450 .nf
451 # varlinkctl info /usr/lib/systemd/systemd\-pcrextend
452 Vendor: The systemd Project
453 Product: systemd (systemd\-pcrextend)
454 Version: 254 (254\-1536\-g97734fb)
455 URL: https://systemd\&.io/
456 Interfaces: io\&.systemd
457 io\&.systemd\&.PCRExtend
458 org\&.varlink\&.service
459 # varlinkctl introspect /usr/lib/systemd/systemd\-pcrextend io\&.systemd\&.PCRExtend
460 interface io\&.systemd\&.PCRExtend
461
462 method Extend(
463 pcr: int,
464 text: ?string,
465 data: ?string
466 ) \-> ()
467 # varlinkctl call /usr/lib/systemd/systemd\-pcrextend io\&.systemd\&.PCRExtend\&.Extend \*(Aq{"pcr":15,"text":"foobar"}\*(Aq
468 {}
469 .fi
470 .if n \{\
471 .RE
472 .\}
473 .PP
474 \fBExample\ \&4.\ \&Invoking a method remotely via SSH\fR
475 .PP
476 The following command acquires a report about the identity of a remote host
477 "somehost"
478 from
479 \fBsystemd-hostnamed.service\fR(8)
480 by connecting via SSH to the
481 \fBAF_UNIX\fR
482 socket the service listens on:
483 .sp
484 .if n \{\
485 .RS 4
486 .\}
487 .nf
488 # varlinkctl call ssh\-unix:somehost:/run/systemd/io\&.systemd\&.Hostname io\&.systemd\&.Hostname\&.Describe \*(Aq{}\*(Aq
489 .fi
490 .if n \{\
491 .RE
492 .\}
493 .PP
494 To invoke a Varlink service binary directly on the remote host, rather than talking to a service via
495 \fBAF_UNIX\fR
496 can be done like this:
497 .sp
498 .if n \{\
499 .RS 4
500 .\}
501 .nf
502 # varlinkctl call ssh\-exec:somehost:systemd\-creds org\&.varlink\&.service\&.GetInfo \*(Aq{}\*(Aq
503 .fi
504 .if n \{\
505 .RE
506 .\}
507 .SH "SEE ALSO"
508 .PP
509 \fBbusctl\fR(1), \m[blue]\fBVarlink\fR\m[]\&\s-2\u[1]\d\s+2
510 .SH "NOTES"
511 .IP " 1." 4
512 Varlink
513 .RS 4
514 \%https://varlink.org/
515 .RE