VARLINKCTL(1) | varlinkctl | VARLINKCTL(1) |
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 ADDRESS METHOD [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:
info ADDRESS
Added in version 255.
list-interfaces ADDRESS
Added in version 255.
list-methods ADDRESS [INTERFACE...]
Added in version 257.
introspect ADDRESS [INTERFACE...]
Added in version 255.
call ADDRESS METHOD [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
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,
...
(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 {
"addresses" : [
{
"ifindex" : 2,
"family" : 2,
"address" : [
185,
199,
111,
153
]
}
],
"name" : "systemd.io",
"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
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"}' {}
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
systemd 257~rc3 |