varlinkctl(1) - BetterMan

—

Options · 1

Varlink

NAME

varlinkctl - Introspect with and invoke Varlink services

SYNOPSIS

varlinkctl [OPTIONS...] info ADDRESS

varlinkctl [OPTIONS...] list-interfaces ADDRESS

varlinkctl [OPTIONS...] list-methods ADDRESS [INTERFACE...]

varlinkctl [OPTIONS...] introspect ADDRESS [INTERFACE...]

varlinkctl [OPTIONS...] call ADDRESSMETHOD [ARGUMENTS]

varlinkctl [OPTIONS...] validate-idl [FILE]

DESCRIPTION

varlinkctl may be used to introspect and invoke Varlink[1] services.

Services are referenced by one of the following:

For convenience, these two simpler (redundant) service address syntaxes are also supported:

COMMANDS

The following commands are understood:

infoADDRESS

Added in version 255.

list-interfacesADDRESS

Added in version 255.

list-methodsADDRESS [INTERFACE...]

Added in version 257.

introspectADDRESS [INTERFACE...]

Added in version 255.

callADDRESSMETHOD [ARGUMENTS]

The reply parameters are written as JSON object to STDOUT.

Added in version 255.

validate-idl [FILE]

Added in version 255.

help

Added in version 255.

OPTIONS

The following options are understood:

--more

If this mode is enabled output is automatically switched to JSON-SEQ mode, so that individual reply objects can be easily discerned.

This switch has no effect on the method call timeout applied by default: regardless if --more is specified or not, the default timeout will be 45s. Use --timeout= (see below) to change or disable the timeout. When invoking a method call that continuously returns updates it is typically desirable to disable the timeout with --timeout=infinity. On the other hand, when invoking a --more method call for the purpose of enumerating objects (which likely will complete quickly) it is typically beneficial to leave the timeout logic enabled, for robustness reasons.

Added in version 255.

-E

Added in version 257.

--collect

Added in version 256.

--oneway

Added in version 255.

--json=MODE

Added in version 255.

-j

Added in version 255.

--quiet, -q

Added in version 257.

--graceful=

Added in version 257.

--timeout=

Added in version 257.

--no-pager

-h, --help

--version

EXAMPLES

Example 1. Investigating a Service

The following three commands inspect the "io.systemd.Resolve" service implemented by systemd-resolved.service(8), listing general service information and implemented interfaces, and then displaying the interface definition of its primary interface:

bash

$ varlinkctl info /run/systemd/resolve/io.systemd.Resolve
\n
    Vendor: The systemd Project
\n
   Product: systemd (systemd-resolved)
\n
   Version: 254 (254-1522-g4790521^)
\n
       URL: https://systemd.io/
Interfaces: io.systemd
\n
            io.systemd.Resolve
\n
            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(
\n
        ifindex: ?int,
\n
        ...

(Interface definition has been truncated in the example above, in the interest of brevity.)

Example 2. Invoking a Method

The following command resolves a hostname via systemd-resolved.service(8)'s ResolveHostname method call.

bash

$ varlinkctl call /run/systemd/resolve/io.systemd.Resolve io.systemd.Resolve.ResolveHostname '{"name":"systemd.io","family":2}' -j
{
\n
        "addresses" : [
\n
                {
\n
                        "ifindex" : 2,
\n
                        "family" : 2,
\n
                        "address" : [
\n
                                185,
\n
                                199,
\n
                                111,
\n
                                153
\n
                        ]
\n
                }
\n
        ],
\n
        "name" : "systemd.io",
\n
        "flags" : 1048577
}

Example 3. Investigating a Service Executable

The following command inspects the /usr/lib/systemd/systemd-pcrextend executable and the IPC APIs it provides. It then invokes a method on it:

bash

# varlinkctl info /usr/lib/systemd/systemd-pcrextend
\n
    Vendor: The systemd Project
\n
   Product: systemd (systemd-pcrextend)
\n
   Version: 254 (254-1536-g97734fb)
\n
       URL: https://systemd.io/
Interfaces: io.systemd
\n
            io.systemd.PCRExtend
\n
            org.varlink.service
# varlinkctl introspect /usr/lib/systemd/systemd-pcrextend io.systemd.PCRExtend
interface io.systemd.PCRExtend
method Extend(
\n
        pcr: int,
\n
        text: ?string,
\n
        data: ?string
) -> ()
# varlinkctl call /usr/lib/systemd/systemd-pcrextend io.systemd.PCRExtend.Extend '{"pcr":15,"text":"foobar"}'
{}

Example 4. Invoking a method remotely via SSH

The following command acquires a report about the identity of a remote host "somehost" from systemd-hostnamed.service(8) by connecting via SSH to the AF_UNIX socket the service listens on:

bash

# varlinkctl call ssh-unix:somehost:/run/systemd/io.systemd.Hostname io.systemd.Hostname.Describe '{}'

To invoke a Varlink service binary directly on the remote host, rather than talking to a service via AF_UNIX can be done like this:

bash

# varlinkctl call ssh-exec:somehost:/usr/bin/systemd-creds org.varlink.service.GetInfo '{}'

NOTES

1.: Varlink