man/varlinkctl.xml

   1 <?xml version='1.0'?>
   2 <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   3   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
   4 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
   5
   6 <refentry id="varlinkctl"
   7           xmlns:xi="http://www.w3.org/2001/XInclude">
   8
   9   <refentryinfo>
  10     <title>varlinkctl</title>
  11     <productname>systemd</productname>
  12   </refentryinfo>
  13
  14   <refmeta>
  15     <refentrytitle>varlinkctl</refentrytitle>
  16     <manvolnum>1</manvolnum>
  17   </refmeta>
  18
  19   <refnamediv>
  20     <refname>varlinkctl</refname>
  21     <refpurpose>Introspect with and invoke Varlink services</refpurpose>
  22   </refnamediv>
  23
  24   <refsynopsisdiv>
  25     <cmdsynopsis>
  26       <command>varlinkctl</command>
  27       <arg choice="opt" rep="repeat">OPTIONS</arg>
  28       <arg choice="plain">info</arg>
  29       <arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
  30     </cmdsynopsis>
  31
  32     <cmdsynopsis>
  33       <command>varlinkctl</command>
  34       <arg choice="opt" rep="repeat">OPTIONS</arg>
  35       <arg choice="plain">list-interfaces</arg>
  36       <arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
  37     </cmdsynopsis>
  38
  39     <cmdsynopsis>
  40       <command>varlinkctl</command>
  41       <arg choice="opt" rep="repeat">OPTIONS</arg>
  42       <arg choice="plain">introspect</arg>
  43       <arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
  44       <arg choice="plain"><replaceable>INTERFACE</replaceable></arg>
  45     </cmdsynopsis>
  46
  47     <cmdsynopsis>
  48       <command>varlinkctl</command>
  49       <arg choice="opt" rep="repeat">OPTIONS</arg>
  50       <arg choice="plain">call</arg>
  51       <arg choice="plain"><replaceable>ADDRESS</replaceable></arg>
  52       <arg choice="plain"><replaceable>METHOD</replaceable></arg>
  53       <arg choice="opt"><replaceable>PARAMETERS</replaceable></arg>
  54     </cmdsynopsis>
  55
  56     <cmdsynopsis>
  57       <command>varlinkctl</command>
  58       <arg choice="opt" rep="repeat">OPTIONS</arg>
  59       <arg choice="plain">validate-idl</arg>
  60       <arg choice="opt"><replaceable>FILE</replaceable></arg>
  61     </cmdsynopsis>
  62   </refsynopsisdiv>
  63
  64   <refsect1>
  65     <title>Description</title>
  66
  67     <para><command>varlinkctl</command> may be used to introspect and invoke <ulink
  68     url="https://varlink.org/">Varlink</ulink> services.</para>
  69
  70     <para>Services are referenced by one of the following:</para>
  71
  72     <itemizedlist>
  73       <listitem><para>A Varlink service reference starting with the <literal>unix:</literal> string, followed
  74       by an absolute <constant>AF_UNIX</constant> path, or by <literal>@</literal> and an arbitrary string
  75       (the latter for referencing sockets in the abstract namespace).</para></listitem>
  76
  77       <listitem><para>A Varlink service reference starting with the <literal>exec:</literal> string, followed
  78       by an absolute path of a binary to execute.</para></listitem>
  79     </itemizedlist>
  80
  81     <para>For convenience these two simpler (redundant) service address syntaxes are also supported:</para>
  82
  83     <itemizedlist>
  84       <listitem><para>A file system path to an <constant>AF_UNIX</constant> socket, either absolute
  85       (i.e. begins with <literal>/</literal>) or relative (in which case it must begin with
  86       <literal>./</literal>).</para></listitem>
  87
  88       <listitem><para>A file system path to an executable, either absolute or relative (as above, must begin
  89       with <literal>/</literal>, resp. <literal>./</literal>).</para></listitem>
  90     </itemizedlist>
  91   </refsect1>
  92
  93   <refsect1>
  94     <title>Commands</title>
  95
  96     <para>The following commands are understood:</para>
  97
  98     <variablelist>
  99       <varlistentry>
 100         <term><command>info</command> <replaceable>ADDRESS</replaceable></term>
 101
 102         <listitem><para>Show brief information about the specified service, including vendor name and list of
 103         implemented interfaces. Expects a service address in the formats described above.</para>
 104
 105         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 106       </varlistentry>
 107
 108       <varlistentry>
 109         <term><command>list-interfaces</command> <replaceable>ADDRESS</replaceable></term>
 110
 111         <listitem><para>Show list of interfaces implemented by the specified service. Expects a service
 112         address in the formats described above.</para>
 113
 114         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 115       </varlistentry>
 116
 117       <varlistentry>
 118         <term><command>introspect</command> <replaceable>ADDRESS</replaceable> <replaceable>INTERFACE</replaceable></term>
 119
 120         <listitem><para>Show interface definition of the specified interface provided by the specified
 121         service. Expects a service address in the formats described above and a Varlink interface
 122         name.</para>
 123
 124         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 125       </varlistentry>
 126
 127       <varlistentry>
 128         <term><command>call</command> <replaceable>ADDRESS</replaceable> <replaceable>METHOD</replaceable> [<replaceable>ARGUMENTS</replaceable>]</term>
 129
 130         <listitem><para>Call the specified method of the specified service. Expects a service address in the
 131         format described above, a fully qualified Varlink method name, and a JSON arguments object. If the
 132         arguments object is not specified, it is read from STDIN instead. To pass an empty list of
 133         parameters, specify the empty object <literal>{}</literal>.</para>
 134
 135         <para>The reply parameters are written as JSON object to STDOUT.</para>
 136
 137         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 138       </varlistentry>
 139
 140       <varlistentry>
 141         <term><command>validate-idl</command> [<replaceable>FILE</replaceable>]</term>
 142
 143         <listitem><para>Reads a Varlink interface definition file, parses and validates it, then outputs it
 144         with syntax highlighting. This checks for syntax and internal consistency of the interface. Expects a
 145         file name to read the interface definition from. If omitted reads the interface definition from
 146         STDIN.</para>
 147
 148         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 149       </varlistentry>
 150
 151       <varlistentry>
 152         <term><command>help</command></term>
 153
 154         <listitem><para>Show command syntax help.</para>
 155
 156         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 157       </varlistentry>
 158     </variablelist>
 159   </refsect1>
 160
 161   <refsect1>
 162     <title>Options</title>
 163
 164     <para>The following options are understood:</para>
 165
 166     <variablelist>
 167       <varlistentry>
 168         <term><option>--more</option></term>
 169
 170         <listitem><para>When used with <command>call</command>: expect multiple method replies. If this flag is
 171         set the method call is sent with the <constant>more</constant> flag set, which tells the service to
 172         generate multiple replies, if needed. The command remains running until the service sends a reply
 173         message that indicates it is the last in the series. This flag should be set only for method calls
 174         that support this mechanism.</para>
 175
 176         <para>If this mode is enabled output is automatically switched to JSON-SEQ mode, so that individual
 177         reply objects can be easily discerned.</para>
 178
 179         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 180       </varlistentry>
 181
 182       <varlistentry>
 183         <term><option>--oneway</option></term>
 184
 185         <listitem><para>When used with <command>call</command>: do not expect a method reply. If this flag
 186         is set the method call is sent with the <constant>oneway</constant> flag set (the command exits
 187         immediately after), which tells the service not to generate a reply.</para>
 188
 189         <xi:include href="version-info.xml" xpointer="v255"/></listitem>
 190       </varlistentry>
 191
 192       <varlistentry>
 193         <term><option>--json=</option><replaceable>MODE</replaceable></term>
 194
 195         <listitem>
 196           <para>Selects the JSON output formatting, one of <literal>pretty</literal> (for nicely indented,
 197           colorized output) or <literal>short</literal> (for terse output with minimal whitespace and no
 198           newlines), defaults to <literal>short</literal>.</para>
 199
 200         <xi:include href="version-info.xml" xpointer="v255"/>
 201         </listitem>
 202       </varlistentry>
 203
 204       <varlistentry>
 205         <term><option>-j</option></term>
 206
 207         <listitem>
 208           <para>Equivalent to <option>--json=pretty</option> when invoked interactively from a terminal. Otherwise
 209           equivalent to <option>--json=short</option>, in particular when the output is piped to some other
 210           program.</para>
 211
 212         <xi:include href="version-info.xml" xpointer="v255"/>
 213         </listitem>
 214       </varlistentry>
 215
 216       <xi:include href="standard-options.xml" xpointer="no-pager" />
 217       <xi:include href="standard-options.xml" xpointer="help" />
 218       <xi:include href="standard-options.xml" xpointer="version" />
 219     </variablelist>
 220   </refsect1>
 221
 222   <refsect1>
 223     <title>Examples</title>
 224
 225     <example>
 226       <title>Investigating a Service</title>
 227
 228       <para>The following three commands inspect the <literal>io.systemd.Resolve</literal> service
 229       implemented by
 230       <citerefentry><refentrytitle>systemd-resolved.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>,
 231       listing general service information and implemented interfaces, and then displaying the interface
 232       definition of its primary interface:</para>
 233
 234       <programlisting>$ varlinkctl info /run/systemd/resolve/io.systemd.Resolve
 235     Vendor: The systemd Project
 236    Product: systemd (systemd-resolved)
 237    Version: 254 (254-1522-g4790521^)
 238        URL: https://systemd.io/
 239 Interfaces: io.systemd
 240             io.systemd.Resolve
 241             org.varlink.service
 242 $ varlinkctl list-interfaces /run/systemd/resolve/io.systemd.Resolve
 243 io.systemd
 244 io.systemd.Resolve
 245 org.varlink.service
 246 $ varlinkctl introspect /run/systemd/resolve/io.systemd.Resolve io.systemd.Resolve
 247 interface io.systemd.Resolve
 248 type ResolvedAddress(
 249         ifindex: ?int,
 250         …</programlisting>
 251
 252     <para>(Interface definition has been truncated in the example above, in the interest of brevity.)</para>
 253     </example>
 254
 255     <example>
 256       <title>Invoking a Method</title>
 257
 258       <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>
 259
 260       <programlisting>$ varlinkctl call /run/systemd/resolve/io.systemd.Resolve io.systemd.Resolve.ResolveHostname '{"name":"systemd.io","family":2}' -j
 261 {
 262         "addresses" : [
 263                 {
 264                         "ifindex" : 2,
 265                         "family" : 2,
 266                         "address" : [
 267                                 185,
 268                                 199,
 269                                 111,
 270                                 153
 271                         ]
 272                 }
 273         ],
 274         "name" : "systemd.io",
 275         "flags" : 1048577
 276 }</programlisting>
 277     </example>
 278
 279     <example>
 280       <title>Investigating a Service Executable</title>
 281
 282       <para>The following command inspects the <filename>/usr/lib/systemd/systemd-pcrextend</filename>
 283       executable and the IPC APIs it provides. It then invokes a method on it:</para>
 284
 285       <programlisting># varlinkctl info /usr/lib/systemd/systemd-pcrextend
 286     Vendor: The systemd Project
 287    Product: systemd (systemd-pcrextend)
 288    Version: 254 (254-1536-g97734fb)
 289        URL: https://systemd.io/
 290 Interfaces: io.systemd
 291             io.systemd.PCRExtend
 292             org.varlink.service
 293 # varlinkctl introspect /usr/lib/systemd/systemd-pcrextend io.systemd.PCRExtend
 294 interface io.systemd.PCRExtend
 295
 296 method Extend(
 297         pcr: int,
 298         text: ?string,
 299         data: ?string
 300 ) -> ()
 301 # varlinkctl call /usr/lib/systemd/systemd-pcrextend io.systemd.PCRExtend.Extend '{"pcr":15,"text":"foobar"}'
 302 {}</programlisting>
 303     </example>
 304
 305   </refsect1>
 306
 307   <refsect1>
 308     <title>See Also</title>
 309
 310     <para><simplelist type="inline">
 311       <member><citerefentry><refentrytitle>busctl</refentrytitle><manvolnum>1</manvolnum></citerefentry></member>
 312       <member><ulink url="https://varlink.org/">Varlink</ulink></member>
 313     </simplelist></para>
 314   </refsect1>
 315 </refentry>