| 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:
$ 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.
$ 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:
# 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:
# 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:
# varlinkctl call ssh-exec:somehost:/usr/bin/systemd-creds org.varlink.service.GetInfo '{}'SEE ALSO
busctl(1), Varlink[1]
NOTES
- 1.
Varlink