1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
|
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
<refentry id="varlinkctl"
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>varlinkctl</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>varlinkctl</refentrytitle>
<manvolnum>1</manvolnum>
</refmeta>
<refnamediv>
<refname>varlinkctl</refname>
<refpurpose>Introspect with and invoke Varlink services</refpurpose>
</refnamediv>
<refsynopsisdiv>
<cmdsynopsis>
<command>varlinkctl</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="plain">info</arg>
<arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>varlinkctl</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="plain">list-interfaces</arg>
<arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>varlinkctl</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="plain">list-methods</arg>
<arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>INTERFACE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>varlinkctl</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="plain">introspect</arg>
<arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
<arg choice="opt" rep="repeat"><replaceable>INTERFACE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>varlinkctl</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="plain">call</arg>
<arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
<arg choice="plain"><replaceable>METHOD</replaceable></arg>
<arg choice="opt"><replaceable>ARGUMENTS</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>varlinkctl</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="plain">--exec call</arg>
<arg choice="plain">call</arg>
<arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
<arg choice="plain"><replaceable>METHOD</replaceable></arg>
<arg choice="plain"><replaceable>ARGUMENTS</replaceable></arg>
<arg choice="plain">--</arg>
<arg choice="plain"><replaceable>CMDLINE</replaceable></arg>
</cmdsynopsis>
<cmdsynopsis>
<command>varlinkctl</command>
<arg choice="opt" rep="repeat">OPTIONS</arg>
<arg choice="plain">validate-idl</arg>
<arg choice="opt"><replaceable>FILE</replaceable></arg>
</cmdsynopsis>
</refsynopsisdiv>
<refsect1>
<title>Description</title>
<para><command>varlinkctl</command> may be used to introspect and invoke <ulink
url="https://varlink.org/">Varlink</ulink> services.</para>
<para>Services are referenced by one of the following:</para>
<itemizedlist>
<listitem><para>A Varlink service reference starting with the <literal>unix:</literal> string, followed
by an absolute <constant>AF_UNIX</constant> socket path, or by <literal>@</literal> 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.</para></listitem>
<listitem><para>A Varlink service reference starting with the <literal>exec:</literal> 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.</para></listitem>
<listitem><para>A Varlink service reference starting with the <literal>ssh-unix:</literal> string, followed
by an SSH host specification, followed by <literal>:</literal>, followed by an absolute
<constant>AF_UNIX</constant> socket path. (This requires OpenSSH 9.4 or newer on the server side,
and abstract namespace sockets are not supported.)</para></listitem>
<listitem><para>A Varlink service reference starting with the <literal>ssh-exec:</literal> string,
followed by an SSH host specification, followed by <literal>:</literal>, 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.</para></listitem>
</itemizedlist>
<para>For convenience, these two simpler (redundant) service address syntaxes are also supported:</para>
<itemizedlist>
<listitem><para>A file system path to an <constant>AF_UNIX</constant> socket, either absolute
(i.e. begins with <literal>/</literal>) or relative (in which case it must begin with
<literal>./</literal>).</para></listitem>
<listitem><para>A file system path to an executable, either absolute or relative (as above, must begin
with <literal>/</literal> or <literal>./</literal>, respectively).</para></listitem>
</itemizedlist>
</refsect1>
<refsect1>
<title>Commands</title>
<para>The following commands are understood:</para>
<variablelist>
<varlistentry>
<term><command>info</command> <replaceable>ADDRESS</replaceable></term>
<listitem><para>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.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><command>list-interfaces</command> <replaceable>ADDRESS</replaceable></term>
<listitem><para>Shows a list of interfaces implemented by the specified service. Expects a service
address in one of the formats described above.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><command>list-methods</command> <replaceable>ADDRESS</replaceable> [<replaceable>INTERFACE…</replaceable>]</term>
<listitem><para>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.</para>
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
</varlistentry>
<varlistentry>
<term><command>introspect</command> <replaceable>ADDRESS</replaceable> [<replaceable>INTERFACE…</replaceable>]</term>
<listitem><para>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.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><command>call</command> <replaceable>ADDRESS</replaceable> <replaceable>METHOD</replaceable> [<replaceable>ARGUMENTS</replaceable>]</term>
<listitem><para>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 <literal>{}</literal>.</para>
<para>The reply parameters are written as JSON objects to STDOUT.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><command>validate-idl</command> [<replaceable>FILE</replaceable>]</term>
<listitem><para>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.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><command>help</command></term>
<listitem><para>Shows command syntax help.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
</variablelist>
</refsect1>
<refsect1>
<title>Options</title>
<para>The following options are understood:</para>
<variablelist>
<varlistentry>
<term><option>--more</option></term>
<listitem><para>When used with <command>call</command>: expect multiple method replies. If this flag
is set, the method call is sent with the <constant>more</constant> 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.</para>
<para>If this mode is enabled, output is automatically switched to JSON-SEQ mode, so that individual
reply objects can be easily discerned.</para>
<para>This switch has no effect on the method call timeout applied by default. Regardless of
whether <option>--more</option> is specified or not, the default timeout will be 45s. Use
<option>--timeout=</option> (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
<option>--timeout=infinity</option>. On the other hand, when invoking a <option>--more</option>
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.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><option>-E</option></term>
<listitem><para>A shortcut for <option>--more --timeout=infinity</option>. This switch is
useful for method calls that implement subscription to a continuous stream of updates.</para>
<xi:include href="version-info.xml" xpointer="v257"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--collect</option></term>
<listitem><para>This is similar to <option>--more</option>, but collects all responses in a JSON
array, and prints it, rather than in JSON-SEQ mode.</para>
<xi:include href="version-info.xml" xpointer="v256"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--oneway</option></term>
<listitem><para>When used with <command>call</command>: do not expect a method reply. If this flag
is set, the method call is sent with the <constant>oneway</constant> flag set (the command exits
immediately after), which tells the service not to generate a reply.</para>
<xi:include href="version-info.xml" xpointer="v255"/></listitem>
</varlistentry>
<varlistentry>
<term><option>--json=<replaceable>MODE</replaceable></option></term>
<listitem>
<para>Selects the JSON output formatting, either <literal>pretty</literal> for nicely indented,
colorized output, or <literal>short</literal> for terse output with minimal whitespace and no
newlines. Defaults to <literal>short</literal>.</para>
<xi:include href="version-info.xml" xpointer="v255"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>-j</option></term>
<listitem>
<para>Equivalent to <option>--json=pretty</option> when invoked interactively from a terminal. Otherwise,
it is equivalent to <option>--json=short</option>, in particular when the output is piped to some other
program.</para>
<xi:include href="version-info.xml" xpointer="v255"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--quiet</option></term>
<term><option>-q</option></term>
<listitem>
<para>Suppress output of method call replies.</para>
<xi:include href="version-info.xml" xpointer="v257"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--graceful=</option></term>
<listitem>
<para>Takes a qualified Varlink error name, i.e. an interface name, suffixed by an error name,
separated by a dot, e.g. <literal>org.varlink.service.InvalidParameter</literal>. Ensures that, if
a method call fails with the specified error, this will be treated as success, i.e. will cause the
<command>varlinkctl</command> 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.</para>
<xi:include href="version-info.xml" xpointer="v257"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--timeout=</option></term>
<listitem>
<para>Expects a timeout in seconds as parameter. By default, a timeout of 45s is enforced. To turn
off the timeout, specify <literal>infinity</literal> or an empty string.</para>
<xi:include href="version-info.xml" xpointer="v257"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--exec</option></term>
<listitem>
<para>Once the method call issued via <command>call</command> 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 <varname>$LISTEN_FDS</varname> protocol. This
functionality may be used to consume replies that come with associated file descriptors in a
reasonable way.</para>
<para>Now that if <option>--exec</option> is specified the the third parameter to
<command>call</command> is not optional (i.e. the method call parameters).</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
<varlistentry>
<term><option>--push-fd=</option></term>
<listitem>
<para>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 <command>varlinkctl</command>
invocation. Optionally, in place of a numeric file descriptor number an absolute or relative file
system path (the latter must be prefixed with <literal>./</literal>) may be specified, which is
opened in read-only mode.</para>
<xi:include href="version-info.xml" xpointer="v258"/>
</listitem>
</varlistentry>
<xi:include href="standard-options.xml" xpointer="no-pager" />
<xi:include href="standard-options.xml" xpointer="help" />
<xi:include href="standard-options.xml" xpointer="version" />
</variablelist>
</refsect1>
<refsect1>
<title>Examples</title>
<example>
<title>Investigating a Service</title>
<para>The following three commands inspect the <literal>io.systemd.Resolve</literal> service
implemented by
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
listing general service information and implemented interfaces, and then displaying the interface
definition of its primary interface:</para>
<programlisting>$ varlinkctl info /run/systemd/resolve/io.systemd.Resolve
Vendor: The systemd Project
Product: systemd (systemd-resolved)
Version: 254 (254-1522-g4790521^)
URL: https://systemd.io/
Interfaces: io.systemd
io.systemd.Resolve
org.varlink.service
$ varlinkctl list-interfaces /run/systemd/resolve/io.systemd.Resolve
io.systemd
io.systemd.Resolve
org.varlink.service
$ varlinkctl introspect /run/systemd/resolve/io.systemd.Resolve io.systemd.Resolve
interface io.systemd.Resolve
type ResolvedAddress(
ifindex: ?int,
…</programlisting>
<para>(Interface definition has been truncated in the example above, in the interest of brevity.)</para>
</example>
<example>
<title>Invoking a Method</title>
<para>The following command resolves a hostname via
<citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>'s
<function>ResolveHostname</function> method call.</para>
<programlisting>$ varlinkctl call /run/systemd/resolve/io.systemd.Resolve io.systemd.Resolve.ResolveHostname '{"name":"systemd.io","family":2}' -j
{
"addresses" : [
{
"ifindex" : 2,
"family" : 2,
"address" : [
185,
199,
111,
153
]
}
],
"name" : "systemd.io",
"flags" : 1048577
}</programlisting>
</example>
<example>
<title>Investigating a Service Executable</title>
<para>The following command inspects the <filename>/usr/lib/systemd/systemd-pcrextend</filename>
executable and the IPC APIs it provides. It then invokes a method on it:</para>
<programlisting># varlinkctl info /usr/lib/systemd/systemd-pcrextend
Vendor: The systemd Project
Product: systemd (systemd-pcrextend)
Version: 254 (254-1536-g97734fb)
URL: https://systemd.io/
Interfaces: io.systemd
io.systemd.PCRExtend
org.varlink.service
# varlinkctl introspect /usr/lib/systemd/systemd-pcrextend io.systemd.PCRExtend
interface io.systemd.PCRExtend
method Extend(
pcr: int,
text: ?string,
data: ?string
) -> ()
# varlinkctl call /usr/lib/systemd/systemd-pcrextend io.systemd.PCRExtend.Extend '{"pcr":15,"text":"foobar"}'
{}</programlisting>
</example>
<example>
<title>Invoking a method remotely via SSH</title>
<para>The following command acquires a report about the identity of a remote host
<literal>somehost</literal> from
<citerefentry><refentrytitle>systemd-hostnamed.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
by connecting via SSH to the <constant>AF_UNIX</constant> socket the service listens on:</para>
<programlisting># varlinkctl call ssh-unix:somehost:/run/systemd/io.systemd.Hostname io.systemd.Hostname.Describe '{}'</programlisting>
<para>To invoke a Varlink service binary directly on the remote host, rather than talking to a service
via <constant>AF_UNIX</constant> can be done like this:</para>
<programlisting># varlinkctl call ssh-exec:somehost:systemd-creds org.varlink.service.GetInfo '{}'</programlisting>
</example>
</refsect1>
<refsect1>
<title>See Also</title>
<para><simplelist type="inline">
<member><citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
<member><ulink url="https://varlink.org/">Varlink</ulink></member>
</simplelist></para>
</refsect1>
</refentry>
|
