systemd/man/varlinkctl.xml
2024-04-15 10:40:11 +02:00

330 lines
13 KiB
XML

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