From 55944e5e40b1be2afc4855d8d2baf4b73d1876b5 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 10 Apr 2024 22:49:52 +0200 Subject: Adding upstream version 255.4. Signed-off-by: Daniel Baumann --- man/varlinkctl.xml | 315 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 315 insertions(+) create mode 100644 man/varlinkctl.xml (limited to 'man/varlinkctl.xml') diff --git a/man/varlinkctl.xml b/man/varlinkctl.xml new file mode 100644 index 0000000..7dec54c --- /dev/null +++ b/man/varlinkctl.xml @@ -0,0 +1,315 @@ + + + + + + + + varlinkctl + systemd + + + + varlinkctl + 1 + + + + varlinkctl + Introspect with and invoke Varlink services + + + + + varlinkctl + OPTIONS + info + ADDRESS + + + + varlinkctl + OPTIONS + list-interfaces + ADDRESS + + + + varlinkctl + OPTIONS + introspect + ADDRESS + INTERFACE + + + + varlinkctl + OPTIONS + call + ADDRESS + METHOD + PARAMETERS + + + + varlinkctl + OPTIONS + validate-idl + FILE + + + + + Description + + varlinkctl may be used to introspect and invoke Varlink services. + + Services are referenced by one of the following: + + + A Varlink service reference starting with the unix: string, followed + by an absolute AF_UNIX 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. + + + 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 + + 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 the formats described above. + + + + + + list-interfaces ADDRESS + + Show list of interfaces implemented by the specified service. Expects a service + address in the formats described above. + + + + + + introspect ADDRESS INTERFACE + + Show interface definition of the specified interface provided by the specified + service. Expects a service address in the formats described above and a Varlink interface + name. + + + + + + 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. + + + + + + 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. + + + + + + help + + Show command syntax help. + + + + + + + + Options + + The following options are understood: + + + + + + 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. + + + + + + + + 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. + + + + + + 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. + + + + + + + + + + Equivalent to when invoked interactively from a terminal. Otherwise + equivalent to , in particular when the output is piped to some other + program. + + + + + + + + + + + + + Examples + + + Investigating a Service + + The following three commands inspect the io.systemd.Resolve service + implemented by + systemd-resolved.service8, + 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.) + + + + Invoking a Method + + The following command resolves a hostname via systemd-resolved.service8'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 +} + + + + 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 + + + busctl1, + Varlink + + + -- cgit v1.2.3