summaryrefslogtreecommitdiffstats
path: root/man/varlinkctl.xml
blob: eefc3d1de0eea2e11a46a772179a75b5f4bbddd4 (plain)
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
<?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">introspect</arg>
      <arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
      <arg choice="plain"><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">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).</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.</para></listitem>

      <listitem><para>A Varlink service reference starting with the <literal>ssh:</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,
      abstract namespace sockets are not supported.)</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>, resp. <literal>./</literal>).</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>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.</para>

        <xi:include href="version-info.xml" xpointer="v255"/></listitem>
      </varlistentry>

      <varlistentry>
        <term><command>list-interfaces</command> <replaceable>ADDRESS</replaceable></term>

        <listitem><para>Show 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>introspect</command> <replaceable>ADDRESS</replaceable> <replaceable>INTERFACE</replaceable></term>

        <listitem><para>Show interface definition of the specified interface provided by the specified
        service. Expects a service address in one of the formats described above and a Varlink interface
        name.</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>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 <literal>{}</literal>.</para>

        <para>The reply parameters are written as JSON object 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>Show 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. 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>

        <xi:include href="version-info.xml" xpointer="v255"/></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, one of <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
          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>

      <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>

  </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>