iTechGuides is reader-supported. When you buy through links on our site, we may earn an affiliate commission. As an Amazon Associate I earn from qualifying purchases. Learn more
Use varlinkctl to discover what a Varlink service actually exposes before calling it: identify its socket or executable address, list its interfaces, inspect the interface definition, and then send a fully qualified method name with JSON arguments. The exact commands and options depend on the installed systemd version, and a documented socket path is not proof that the socket exists on your host.
What varlinkctl does
varlinkctl is a command-line client for inspecting and invoking Varlink services. Its documented commands cover service information, interface discovery, interface introspection, method calls, and validation of interface definition language (IDL) files. The Debian trixie varlinkctl(1) manual documents these operations and their address formats.
The reliable workflow is to inspect the service first, then build a call from the method signature you find. A method name or argument guessed from a service’s purpose may be wrong; the live interface definition is the useful reference for its actual API.
Quick wins for a faster PC:
Fix the driver behind crashes, sound loss and screen glitchesFind Drivers →Repair Windows errors before they cause bigger problemsFix Now →How to find a systemd Varlink service address
The address tells varlinkctl how to reach the service. It can identify a local Unix socket, a local executable to start, or a remote endpoint reached through SSH. These are documented address forms, not confirmation that a particular service or socket is installed or enabled on your machine.
#1 Best Overall
| Address form | What it targets | Where and how it runs |
|---|---|---|
unix:/absolute/path/to/socket |
A filesystem Unix socket | Local connection to the named socket |
unix:@name |
An abstract-namespace Unix socket | Local connection to the named abstract socket |
exec:/absolute/path/to/program |
A local executable | Starts the program and passes it a connected stream socket |
ssh-unix:host:/absolute/path/to/socket |
A remote Unix socket | Connects over SSH; the server requires OpenSSH 9.4 or newer, and abstract-namespace sockets are unsupported in this mode |
ssh-exec:host:/path/to/command |
A remote command | Invokes the program over SSH and speaks Varlink over its standard input and output |
/path/to/socket or /path/to/program |
A socket or executable filesystem path | Direct path form accepted by the tool |
For a local service, check the service’s documentation and host configuration for its actual socket address. For a remote service, choose between forwarding to a socket with ssh-unix: and running a command with ssh-exec:; the service deployment determines which form is appropriate.
How to inspect a Varlink interface
The Debian trixie manual uses systemd-resolved to demonstrate a discovery sequence. Run these commands only if that service is available at the documented path on your host:
varlinkctl info /run/systemd/resolve/io.systemd.Resolve
varlinkctl list-interfaces /run/systemd/resolve/io.systemd.Resolve
varlinkctl introspect /run/systemd/resolve/io.systemd.Resolve io.systemd.Resolve- Get service metadata:
inforeports basic information about the service and the interfaces it implements. - List interfaces:
list-interfacesshows the service’s available interfaces. - Read an interface definition:
introspectdisplays the selected interface’s definition, including its methods and signatures. Use the method’s declared parameters and types to prepare a call.
list-methods is also documented, but its availability is version-dependent: the manual marks it as added in systemd 257. Use it only if it appears in the man page for your installed version.
What’s actually slowing this PC down?
Pick the symptom - the matching free tool is one click away.
Rank #2
How to call a Varlink method with JSON
A call takes a service address, a fully qualified method name, and a JSON object containing the method’s arguments. The manual’s local executable example is:
varlinkctl call /usr/lib/systemd/systemd-pcrextend
io.systemd.PCRExtend.Extend
'{"pcr":15,"text":"foobar"}'This illustrates the syntax; it is not a claim that the executable exists or that the call has been run on your system. The method is io.systemd.PCRExtend.Extend, and the final argument is a JSON object matching its parameters. If you omit the argument object, call reads JSON from standard input. Use {} when the method takes no parameters. Reply parameters are written as JSON to standard output.
- Copy the fully qualified method name from the interface definition rather than inferring it from the service name.
- Match JSON property names and value types to the declared signature.
- Check the service’s deployment and permissions separately; introspection describes the interface but does not establish that your caller is authorized to invoke it.
How to handle methods that return multiple replies
Some Varlink methods return a series of replies. The manual distinguishes streaming-style output from collecting those replies into one JSON value.
| Option | Output behavior | Use when |
|---|---|---|
--more |
Sets the Varlink more flag and writes replies as JSON-SEQ, separating multiple replies | The method supports multiple replies and the consumer can process a separated stream |
--collect |
Collects replies into a JSON array | The method supports multiple replies and the consumer needs one array |
Choose based on the method’s behavior and what the receiving program expects. The manual documents a 45-second default call timeout. For a continuous update stream, it says --timeout=infinity is typically desirable; for an enumeration expected to finish promptly, a timeout can help prevent an indefinite wait. An infinite timeout is inappropriate if you need a bounded operation.
Do these 3 things before closing this tab:
1Fix the driver behind crashes, sound loss and screen glitches2Repair Windows errors before they cause bigger problems3Scan for outdated or missing drivers - takes under a minuteThese options have version requirements in the manual: --more was added in systemd 255 and --collect in systemd 256. They only apply when the method supports the relevant multiple-reply behavior.
How to use varlinkctl over SSH
Use ssh-unix:host:/absolute/path/to/socket when the remote service is exposed as a Unix socket; the documented server requirement is OpenSSH 9.4 or newer. This mode does not support abstract-namespace sockets. Use ssh-exec:host:/path/to/command when the remote endpoint should be a program invoked over SSH, with Varlink carried on its standard input and output.
SSH address syntax does not guarantee that the remote path or command exists. Confirm the remote service’s configured endpoint and use an account that can access it. Then apply the same inspection-first sequence—service information, interface listing, and introspection—using the remote address in place of a local one.
What validate-idl checks—and what it does not
varlinkctl validate-idl [FILE] parses and checks a Varlink interface definition for syntax and internal consistency. If no file is supplied, it reads the definition from standard input. This is a local definition check: it does not establish that a running service implements the file, authorize a caller, or certify that invoking a method is safe.
Check your installed systemd version
The Debian trixie manual records upstream introduction versions for documented features: the core commands info, list-interfaces, introspect, call, and validate-idl are marked as added in systemd 255; --collect in 256; and list-methods and --quiet in 257. These are upstream feature notes, not a guarantee of the package version installed by a distribution.
Check varlinkctl --version and the local varlinkctl man page before using a newer command or option. A distribution may ship a different systemd version, and host service configuration may differ from a manual example.
Why inspect a service API: systemd-nsresourced
The systemd-nsresourced.service manual says that systemd-nsresourced exposes the io.systemd.NamespaceResource Varlink interface for registering user namespaces and assigning mounts, cgroups, and network interfaces. That establishes the API’s documented scope, but does not specify a verified socket address or a method-call command. Discover the live interface definition on the host rather than assuming an endpoint or inventing a call.
Quick Recap
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
