Debian Codegraph @

upstream/debian-trixie/man1/varlinkctl.1

raw
1 '\" t
2 .TH "VARLINKCTL" "1" "" "systemd 257.13" "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...] validate\-idl [\fIFILE\fR]
37 .SH "DESCRIPTION"
38 .PP
39 \fBvarlinkctl\fR
40 may be used to introspect and invoke
41 \m[blue]\fBVarlink\fR\m[]\&\s-2\u[1]\d\s+2
42 services\&.
43 .PP
44 Services are referenced by one of the following:
45 .sp
46 .RS 4
47 .ie n \{\
48 \h'-04'\(bu\h'+03'\c
49 .\}
50 .el \{\
51 .sp -1
52 .IP \(bu 2.3
53 .\}
54 A Varlink service reference starting with the
55 "unix:"
56 string, followed by an absolute
57 \fBAF_UNIX\fR
58 socket path, or by
59 "@"
60 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\&.
61 .RE
62 .sp
63 .RS 4
64 .ie n \{\
65 \h'-04'\(bu\h'+03'\c
66 .\}
67 .el \{\
68 .sp -1
69 .IP \(bu 2.3
70 .\}
71 A Varlink service reference starting with the
72 "exec:"
73 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\&.
74 .RE
75 .sp
76 .RS 4
77 .ie n \{\
78 \h'-04'\(bu\h'+03'\c
79 .\}
80 .el \{\
81 .sp -1
82 .IP \(bu 2.3
83 .\}
84 A Varlink service reference starting with the
85 "ssh\-unix:"
86 string, followed by an SSH host specification, followed by
87 ":", followed by an absolute
88 \fBAF_UNIX\fR
89 socket path\&. (This requires OpenSSH 9\&.4 or newer on the server side, abstract namespace sockets are not supported\&.)
90 .RE
91 .sp
92 .RS 4
93 .ie n \{\
94 \h'-04'\(bu\h'+03'\c
95 .\}
96 .el \{\
97 .sp -1
98 .IP \(bu 2.3
99 .\}
100 A Varlink service reference starting with the
101 "ssh\-exec:"
102 string, followed by an SSH host specification, followed by
103 ":", 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\&.
104 .RE
105 .PP
106 For convenience, these two simpler (redundant) service address syntaxes are also supported:
107 .sp
108 .RS 4
109 .ie n \{\
110 \h'-04'\(bu\h'+03'\c
111 .\}
112 .el \{\
113 .sp -1
114 .IP \(bu 2.3
115 .\}
116 A file system path to an
117 \fBAF_UNIX\fR
118 socket, either absolute (i\&.e\&. begins with
119 "/") or relative (in which case it must begin with
120 "\&./")\&.
121 .RE
122 .sp
123 .RS 4
124 .ie n \{\
125 \h'-04'\(bu\h'+03'\c
126 .\}
127 .el \{\
128 .sp -1
129 .IP \(bu 2.3
130 .\}
131 A file system path to an executable, either absolute or relative (as above, must begin with
132 "/", resp\&.
133 "\&./")\&.
134 .RE
135 .SH "COMMANDS"
136 .PP
137 The following commands are understood:
138 .PP
139 \fBinfo\fR \fIADDRESS\fR
140 .RS 4
141 Show 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\&.
142 .sp
143 Added in version 255\&.
144 .RE
145 .PP
146 \fBlist\-interfaces\fR \fIADDRESS\fR
147 .RS 4
148 Show list of interfaces implemented by the specified service\&. Expects a service address in one of the formats described above\&.
149 .sp
150 Added in version 255\&.
151 .RE
152 .PP
153 \fBlist\-methods\fR \fIADDRESS\fR [\fIINTERFACE\&...\fR]
154 .RS 4
155 Show 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\&.
156 .sp
157 Added in version 257\&.
158 .RE
159 .PP
160 \fBintrospect\fR \fIADDRESS\fR [\fIINTERFACE\&...\fR]
161 .RS 4
162 Show 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\&.
163 .sp
164 Added in version 255\&.
165 .RE
166 .PP
167 \fBcall\fR \fIADDRESS\fR \fIMETHOD\fR [\fIARGUMENTS\fR]
168 .RS 4
169 Call 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
170 "{}"\&.
171 .sp
172 The reply parameters are written as JSON object to STDOUT\&.
173 .sp
174 Added in version 255\&.
175 .RE
176 .PP
177 \fBvalidate\-idl\fR [\fIFILE\fR]
178 .RS 4
179 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\&.
180 .sp
181 Added in version 255\&.
182 .RE
183 .PP
184 \fBhelp\fR
185 .RS 4
186 Show command syntax help\&.
187 .sp
188 Added in version 255\&.
189 .RE
190 .SH "OPTIONS"
191 .PP
192 The following options are understood:
193 .PP
194 \fB\-\-more\fR
195 .RS 4
196 When used with
197 \fBcall\fR: expect multiple method replies\&. If this flag is set the method call is sent with the
198 \fBmore\fR
199 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\&.
200 .sp
201 If this mode is enabled output is automatically switched to JSON\-SEQ mode, so that individual reply objects can be easily discerned\&.
202 .sp
203 This switch has no effect on the method call timeout applied by default: regardless if
204 \fB\-\-more\fR
205 is specified or not, the default timeout will be 45s\&. Use
206 \fB\-\-timeout=\fR
207 (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
208 \fB\-\-timeout=infinity\fR\&. On the other hand, when invoking a
209 \fB\-\-more\fR
210 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\&.
211 .sp
212 Added in version 255\&.
213 .RE
214 .PP
215 \fB\-E\fR
216 .RS 4
217 A shortcut for
218 \fB\-\-more \-\-timeout=infinity\fR\&. This switch is useful for method calls that implement subscription to a continuous stream of updates\&.
219 .sp
220 Added in version 257\&.
221 .RE
222 .PP
223 \fB\-\-collect\fR
224 .RS 4
225 This is similar to
226 \fB\-\-more\fR
227 but collects all responses in a JSON array, and prints it, rather than in JSON_SEQ mode\&.
228 .sp
229 Added in version 256\&.
230 .RE
231 .PP
232 \fB\-\-oneway\fR
233 .RS 4
234 When used with
235 \fBcall\fR: do not expect a method reply\&. If this flag is set the method call is sent with the
236 \fBoneway\fR
237 flag set (the command exits immediately after), which tells the service not to generate a reply\&.
238 .sp
239 Added in version 255\&.
240 .RE
241 .PP
242 \fB\-\-json=\fR\fB\fIMODE\fR\fR
243 .RS 4
244 Selects the JSON output formatting, one of
245 "pretty"
246 (for nicely indented, colorized output) or
247 "short"
248 (for terse output with minimal whitespace and no newlines), defaults to
249 "short"\&.
250 .sp
251 Added in version 255\&.
252 .RE
253 .PP
254 \fB\-j\fR
255 .RS 4
256 Equivalent to
257 \fB\-\-json=pretty\fR
258 when invoked interactively from a terminal\&. Otherwise equivalent to
259 \fB\-\-json=short\fR, in particular when the output is piped to some other program\&.
260 .sp
261 Added in version 255\&.
262 .RE
263 .PP
264 \fB\-\-quiet\fR, \fB\-q\fR
265 .RS 4
266 Suppress output of method call replies\&.
267 .sp
268 Added in version 257\&.
269 .RE
270 .PP
271 \fB\-\-graceful=\fR
272 .RS 4
273 Takes a qualified Varlink error name (i\&.e\&. an interface name, suffixed by an error name, separated by a dot; e\&.g\&.
274 "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
275 \fBvarlinkctl\fR
276 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\&.
277 .sp
278 Added in version 257\&.
279 .RE
280 .PP
281 \fB\-\-timeout=\fR
282 .RS 4
283 Expects a timeout in seconds as parameter\&. By default, a timeout of 45s is enforced\&. To turn off the timeout specify
284 "infinity"
285 or an empty string\&.
286 .sp
287 Added in version 257\&.
288 .RE
289 .PP
290 \fB\-\-no\-pager\fR
291 .RS 4
292 Do not pipe output into a pager\&.
293 .RE
294 .PP
295 \fB\-h\fR, \fB\-\-help\fR
296 .RS 4
297 Print a short help text and exit\&.
298 .RE
299 .PP
300 \fB\-\-version\fR
301 .RS 4
302 Print a short version string and exit\&.
303 .RE
304 .SH "EXAMPLES"
305 .PP
306 \fBExample\ \&1.\ \&Investigating a Service\fR
307 .PP
308 The following three commands inspect the
309 "io\&.systemd\&.Resolve"
310 service implemented by
311 \fBsystemd-resolved.service\fR(8), listing general service information and implemented interfaces, and then displaying the interface definition of its primary interface:
312 .sp
313 .if n \{\
314 .RS 4
315 .\}
316 .nf
317 $ varlinkctl info /run/systemd/resolve/io\&.systemd\&.Resolve
318 Vendor: The systemd Project
319 Product: systemd (systemd\-resolved)
320 Version: 254 (254\-1522\-g4790521^)
321 URL: https://systemd\&.io/
322 Interfaces: io\&.systemd
323 io\&.systemd\&.Resolve
324 org\&.varlink\&.service
325 $ varlinkctl list\-interfaces /run/systemd/resolve/io\&.systemd\&.Resolve
326 io\&.systemd
327 io\&.systemd\&.Resolve
328 org\&.varlink\&.service
329 $ varlinkctl introspect /run/systemd/resolve/io\&.systemd\&.Resolve io\&.systemd\&.Resolve
330 interface io\&.systemd\&.Resolve
331 type ResolvedAddress(
332 ifindex: ?int,
333 \&...
334 .fi
335 .if n \{\
336 .RE
337 .\}
338 .PP
339 (Interface definition has been truncated in the example above, in the interest of brevity\&.)
340 .PP
341 \fBExample\ \&2.\ \&Invoking a Method\fR
342 .PP
343 The following command resolves a hostname via
344 \fBsystemd-resolved.service\fR(8)\*(Aqs
345 \fBResolveHostname\fR
346 method call\&.
347 .sp
348 .if n \{\
349 .RS 4
350 .\}
351 .nf
352 $ varlinkctl call /run/systemd/resolve/io\&.systemd\&.Resolve io\&.systemd\&.Resolve\&.ResolveHostname \*(Aq{"name":"systemd\&.io","family":2}\*(Aq \-j
353 {
354 "addresses" : [
355 {
356 "ifindex" : 2,
357 "family" : 2,
358 "address" : [
359 185,
360 199,
361 111,
362 153
363 ]
364 }
365 ],
366 "name" : "systemd\&.io",
367 "flags" : 1048577
368 }
369 .fi
370 .if n \{\
371 .RE
372 .\}
373 .PP
374 \fBExample\ \&3.\ \&Investigating a Service Executable\fR
375 .PP
376 The following command inspects the
377 /usr/lib/systemd/systemd\-pcrextend
378 executable and the IPC APIs it provides\&. It then invokes a method on it:
379 .sp
380 .if n \{\
381 .RS 4
382 .\}
383 .nf
384 # varlinkctl info /usr/lib/systemd/systemd\-pcrextend
385 Vendor: The systemd Project
386 Product: systemd (systemd\-pcrextend)
387 Version: 254 (254\-1536\-g97734fb)
388 URL: https://systemd\&.io/
389 Interfaces: io\&.systemd
390 io\&.systemd\&.PCRExtend
391 org\&.varlink\&.service
392 # varlinkctl introspect /usr/lib/systemd/systemd\-pcrextend io\&.systemd\&.PCRExtend
393 interface io\&.systemd\&.PCRExtend
394
395 method Extend(
396 pcr: int,
397 text: ?string,
398 data: ?string
399 ) \-> ()
400 # varlinkctl call /usr/lib/systemd/systemd\-pcrextend io\&.systemd\&.PCRExtend\&.Extend \*(Aq{"pcr":15,"text":"foobar"}\*(Aq
401 {}
402 .fi
403 .if n \{\
404 .RE
405 .\}
406 .PP
407 \fBExample\ \&4.\ \&Invoking a method remotely via SSH\fR
408 .PP
409 The following command acquires a report about the identity of a remote host
410 "somehost"
411 from
412 \fBsystemd-hostnamed.service\fR(8)
413 by connecting via SSH to the
414 \fBAF_UNIX\fR
415 socket the service listens on:
416 .sp
417 .if n \{\
418 .RS 4
419 .\}
420 .nf
421 # varlinkctl call ssh\-unix:somehost:/run/systemd/io\&.systemd\&.Hostname io\&.systemd\&.Hostname\&.Describe \*(Aq{}\*(Aq
422 .fi
423 .if n \{\
424 .RE
425 .\}
426 .PP
427 To invoke a Varlink service binary directly on the remote host, rather than talking to a service via
428 \fBAF_UNIX\fR
429 can be done like this:
430 .sp
431 .if n \{\
432 .RS 4
433 .\}
434 .nf
435 # varlinkctl call ssh\-exec:somehost:/usr/bin/systemd\-creds org\&.varlink\&.service\&.GetInfo \*(Aq{}\*(Aq
436 .fi
437 .if n \{\
438 .RE
439 .\}
440 .SH "SEE ALSO"
441 .PP
442 \fBbusctl\fR(1), \m[blue]\fBVarlink\fR\m[]\&\s-2\u[1]\d\s+2
443 .SH "NOTES"
444 .IP " 1." 4
445 Varlink
446 .RS 4
447 \%https://varlink.org/
448 .RE