mirror of
https://github.com/systemd/systemd
synced 2024-07-05 17:39:42 +00:00
da213bb5c0
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.
367 lines
14 KiB
XML
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>
|