systemd/man/varlinkctl.xml
Lennart Poettering da213bb5c0 varlinkctl: add --graceful= option for optionally marking some errors as successes
This is generally useful, but in some cases particularly: when
implementing enumeration calls that use the "more" flag to return
multiple replies then for the first reply we need to return an error in
case the list of objects to enumerate is empty, usually so form of
"NoSuchXYZ" error. In many cases this shouldn't really be treated as
error, as an empty list probably more than not is as valid as a list
with one, two or more entries.
2024-06-20 18:20:09 +02:00

367 lines
14 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="opt"><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>list-methods</command> <replaceable>ADDRESS</replaceable> [<replaceable>INTERFACE…</replaceable>]</term>
<listitem><para>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 services.</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>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.</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>
<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>
<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>