mirror of
https://github.com/systemd/systemd
synced 2024-07-09 04:26:06 +00:00
a1bb30de7f
This uses openssh 9.4's -W support for AF_UNIX. Unfortunately older versions
don't work with this, and I couldn#t figure a way that would work for
older versions too, would not be racy and where we'd still could keep
track of the forked off ssh process.
Unfortunately, on older versions -W will just hang (because it tries to
resolve the AF_UNIX path as regular host name), which sucks, but hopefully this
issue will go away sooner or later on its own, as distributions update.
Fedora is still stuck at 9.3 at the time of posting this (even on
Fedora), even though 9.4, 9.5, 9.6 have all already been released by
now.
Example:
varlinkctl call -j ssh:root@somehost:/run/systemd/io.systemd.Credentials io.systemd.Credentials.Encrypt '{"text":"foobar"}'
321 lines
12 KiB
XML
321 lines
12 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>PARAMETERS</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 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 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 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>--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=</option><replaceable>MODE</replaceable></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>
|