varlinkctl(1) — Linux manual page

NAME | SYNOPSIS | DESCRIPTION | COMMANDS | OPTIONS | EXAMPLES | SEE ALSO | NOTES | COLOPHON

VARLINKCTL(1)                  varlinkctl                  VARLINKCTL(1)

NAME         top

       varlinkctl - Introspect with and invoke Varlink services

SYNOPSIS         top


       varlinkctl [OPTIONS...] info ADDRESS

       varlinkctl [OPTIONS...] list-interfaces ADDRESS

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

       varlinkctl [OPTIONS...] call ADDRESS METHOD [ARGUMENTS]

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

DESCRIPTION         top

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

       Services are referenced by one of the following:

       •   A Varlink service reference starting with the "unix:" string,
           followed by an absolute AF_UNIX socket path, or by "@" and an
           arbitrary string (the latter for referencing sockets in the
           abstract namespace).

       •   A Varlink service reference starting with the "exec:" string,
           followed by an absolute path of a binary to execute.

       •   A Varlink service reference starting with the "ssh:" string,
           followed by an SSH host specification, followed by ":",
           followed by an absolute AF_UNIX socket path. (This requires
           OpenSSH 9.4 or newer on the server side, abstract namespace
           sockets are not supported.)

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

       •   A file system path to an AF_UNIX socket, either absolute
           (i.e. begins with "/") or relative (in which case it must
           begin with "./").

       •   A file system path to an executable, either absolute or
           relative (as above, must begin with "/", resp.  "./").

COMMANDS         top

       The following commands are understood:

       info ADDRESS
           Show brief information about the specified service, including
           vendor name and list of implemented interfaces. Expects a
           service address in one of the formats described above.

           Added in version 255.

       list-interfaces ADDRESS
           Show list of interfaces implemented by the specified service.
           Expects a service address in one of the formats described
           above.

           Added in version 255.

       list-methods ADDRESS [INTERFACE...]
           Show list of methods implemented by the specified service.
           Expects a service address in one of the formats described
           above as well as one or more interface names. If no interface
           name is specified, lists all methods of all interfaces
           implemented by the service, otherwise just the methods in the
           specified services.

           Added in version 257.

       introspect ADDRESS [INTERFACE...]
           Show the interface definitions of the specified interfaces
           provided by the specified service. Expects a service address
           in one of the formats described above and optionally one or
           more Varlink interface names. If no interface names are
           specified, shows all provided interfaces by the service.

           Added in version 255.

       call ADDRESS METHOD [ARGUMENTS]
           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 "{}".

           The reply parameters are written as JSON object to STDOUT.

           Added in version 255.

       validate-idl [FILE]
           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.

           Added in version 255.

       help
           Show command syntax help.

           Added in version 255.

OPTIONS         top

       The following options are understood:

       --more
           When used with call: expect multiple method replies. If this
           flag is set the method call is sent with the more 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.

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

           Added in version 255.

       --collect
           This is similar to --more but collects all responses in a
           JSON array, and prints it, rather than in JSON_SEQ mode.

           Added in version 256.

       --oneway
           When used with call: do not expect a method reply. If this
           flag is set the method call is sent with the oneway flag set
           (the command exits immediately after), which tells the
           service not to generate a reply.

           Added in version 255.

       --json=MODE
           Selects the JSON output formatting, one of "pretty" (for
           nicely indented, colorized output) or "short" (for terse
           output with minimal whitespace and no newlines), defaults to
           "short".

           Added in version 255.

       -j
           Equivalent to --json=pretty when invoked interactively from a
           terminal. Otherwise equivalent to --json=short, in particular
           when the output is piped to some other program.

           Added in version 255.

       --quiet, -q
           Suppress output of method call replies.

           Added in version 257.

       --no-pager
           Do not pipe output into a pager.

       -h, --help
           Print a short help text and exit.

       --version
           Print a short version string and exit.

EXAMPLES         top

       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"}'
           {}

SEE ALSO         top

       busctl(1), Varlink[1]

NOTES         top

        1. Varlink
           https://varlink.org/

COLOPHON         top

       This page is part of the systemd (systemd system and service
       manager) project.  Information about the project can be found at
       ⟨http://www.freedesktop.org/wiki/Software/systemd⟩.  If you have
       a bug report for this manual page, see
       ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.
       This page was obtained from the project's upstream Git repository
       ⟨https://github.com/systemd/systemd.git⟩ on 2024-06-14.  (At that
       time, the date of the most recent commit that was found in the
       repository was 2024-06-13.)  If you discover any rendering
       problems in this HTML version of the page, or you believe there
       is a better or more up-to-date source for the page, or you have
       corrections or improvements to the information in this COLOPHON
       (which is not part of the original manual page), send a mail to
       [email protected]

systemd 257~devel                                          VARLINKCTL(1)

Pages that refer to this page: busctl(1)systemd.directives(7)systemd.index(7)