•Eine Varlink-Referenz, die mit der Zeichenkette »unix:« beginnt, gefolgt von einem absoluten AF_UNIX-Socket-Pfad, oder durch »@« und eine beliebige Zeichenkette (letzteres für die Referenzierung von Sockets in dem abstrakten Namensraum). In diesem Fall erfolgt eine Datenstrom-Socket-Verbindung mit dem angegebenen Socket.

•Eine Varlink-Referenz, die mit der Zeichenkette »exec:« beginnt, gefolgt von einem absoluten Pfad zum auszuführenden Programm. In diesem Fall wird der angegebene Prozess lokal gestartet, wobei ein verbundener Datenstrom-Socket hereingereicht wird.

•Eine Varlink-Referenz, die mit der Zeichenkette »ssh-unix:« beginnt, gefolgt von einer SSH-Rechnerangabe, gefolgt von »:«, gefolgt von einem absoluten AF_UNIX-Socket-Pfad. (Dies benötigt OpenSSH 9.4 oder neuer auf der Server-Seite und abstrakte Namensräume werden nicht unterstützt.)

•Eine Varlink-Referenz, die mit der Zeichenkette »ssh-exec:« beginnt, gefolgt von einer SSH-Rechnerangabe, gefolgt von »:«, gefolgt von einer Befehlszeile. In diesem Fall wird der Befehl aufgerufen und das Varlink-Protokoll auf der Standardeingabe und der Standardausgabe des aufgerufenen Befehls gesprochen.

•Ein Dateisystempfad zu einem AF_UNIX-Socket, entweder absolut (d.h. mit »/« beginnend) oder relativ (dann muss er mit »./« anfangen).

•Ein Dateisystempfad zu einem Programm, entweder absolut oder relativ (wie oben, muss mit »/« bzw. »./« beginnen).

Zeigt eine kurze Information über den angegebenen Dienst, einschließlich des Lieferantennamens und einer Liste der implementierten Schnittstellen. Erwartet eine Dienstadresse in einem der oben beschriebenen Formate.

Hinzugefügt in Version 255.

Zeigt eine Liste von durch den Dienst implementierten Schnittstellen. Erwartet eine Dienstadresse in einem der oben beschriebenen Formate.

Hinzugefügt in Version 255.

Zeigt eine Liste der durch den angegebenen Dienst implementierten Methoden. Erwartet eine Diensteadresse in einem der oben beschriebenen Formate sowie einen oder mehrere Schnittstellennamen. Falls kein Schnittstellenname angegeben ist, werden alle durch den Dienst implementierten Methoden auf allen Schnittstellen aufgelistet, andernfalls nur die Methoden an der angegebenen Schnittstelle.

Hinzugefügt in Version 257.

Zeigt die Schnittstellendefinitionen der angegebenen Schnittstellen, die durch den angegebenen Dienst bereitgestellt wird. Erwartet eine Dienstadresse in einem der oben beschriebenen Formate und optional einen oder mehrere Varlink-Schnittstellennamen. Falls keine Schnittstellennamen angegeben sind, werden alle durch den Dienst bereitgestellten Schnittstellen angezeigt.

Hinzugefügt in Version 255.

Ruft die angegebene Methode des angegebenen Dienstes auf. Erwartet eine Dienstadresse in den oben beschriebenen Formaten, einen vollständig qualifizierten Varlink-Methodennamen und ein JSON-Argumentenobjekt. Falls das Argumentenobjekt nicht angegeben ist, wird es stattdessen von Stdin gelesen. Um eine leere Parameterliste zu übergeben, geben Sie das leere Objekt »{}« an.

Die Antwortparameter werden als JSON-Objekte nach Stdout geschrieben.

Hinzugefügt in Version 255.

Run a Varlink server that accepts protocol upgrade requests for the specified method and connects the upgraded connection to the standard input and output of the specified command. This can act as a server-side counterpart to call --upgrade.

The listening socket must be passed via socket activation (i.e. the $LISTEN_FDS protocol), making this command suitable for use in socket-activated service units. When a client calls the specified method with the upgrade flag, the server sends a reply confirming the upgrade, then forks and executes the given command line with the upgraded connection on its standard input and output.

This effectively turns any command that speaks a protocol over standard input/output into a Varlink service, discoverable via the service registry and authenticated via socket credentials. Because each connection is handled by a forked child process, the service unit can apply systemd's sandboxing options (such as ProtectSystem=, etc.) and does not operate in the caller's environment.

Hinzugefügt in Version 261.

Zeigt eine Liste der derzeit in der Diensteregistrierung registrierten Varlink-Dienste zusammen mit ihren Eintrittspunkt-Sockets an. (Derzeit zählt dies einfach die Sockets und mittels Symlinks verbundene Sockets in /run/varlink/registry/ auf, wie nachfolgend beschrieben.)

Hinzugefügt in Version 260.

Liest eine Varlink-Schnittstellendefinitionsdatei, wertet sie aus, validiert sie und gibt sie mit Syntaxhervorhebung aus. Dies prüft auf Syntax und interne Konsistenz der Schnittstelle. Erwartet einen Dateinamen, aus dem die Schnittstellendefinition gelesen werden soll. Falls dieser fehlt, wird die Schnittstellendefinition von Stdin gelesen.

Hinzugefügt in Version 255.

Zeigt die Hilfe zur Befehlssyntax.

Hinzugefügt in Version 255.

Bei der Verwendung mit call: Erwartet mehrere Methodenantworten. Falls dieser Schalter gesetzt ist, wird der Methodenaufruf mit gesetztem Schalter more gesandt. Dies teilt dem Dienst mit, falls notwendig, mehrere Antworten zu generieren. Der Befehl läuft, bis der Dienst eine Antwortnachricht sendet, die anzeigt, dass sie die letzte in der Serie ist (oder falls die konfigurierte Zeitüberschreitung erreicht wird, siehe unten). Dieser Schalter sollte nur für Methodenaufrufe gesetzt werden, die diesen Mechanismus unterstützten.

Falls dieser Modus aktiviert ist, wird die Ausgabe automatisch auf den JSON-SEQ-Modus umgeschaltet, so dass einzelne Antwortobjekte leicht unterschieden werden können.

Dieser Schalter hat keine Auswirkung auf die standardmäßig angewandte Methodenaufruf-Zeitüberschreitung. Unabhängig davon, ob --more angegeben ist, wird die Standardzeitüberschreitung 45 s sein. Verwenden Sie den (nachfolgend beschriebenen) --timeout=, um die Zeitüberschreitung zu ändern oder zu deaktivieren. Beim Aufruf eines Methodenaufrufs, der kontinuierlich Aktualisierungen zurückliefert, ist es typischerweise wünschenswert, die Zeitüberschreitung mit --timeout=infinity zu deaktivieren. Andererseits ist es typischerweise von Vorteil, beim Aufruf des Methodenaufrufs --more zum Zwecke der Aufzählung von Objekten (was wahrscheinlich sehr schnell abgeschlossen ist), die Zeitüberschreitungslogik aus Zwecken der Robustheit aktiviert zu lassen.

Hinzugefügt in Version 255.

Eine Abkürzung für --more --timeout=infinity. Dieser Schalter ist für Methodenaufrufe nützlich, die ein Abonnement für einen dauerhaften Datenstrom von Aktualisierungen implementieren.

Hinzugefügt in Version 257.

Dies ist ähnlich zu --more, sammelt aber alle Antworten in einem JSON-Feld und gibt sie aus, anders als im Modus JSON-SEQ.

Hinzugefügt in Version 256.

Bei der Verwendung mit call wird keine Methodenantwort erwartet. Falls dieser Schalter gesetzt ist, wird der Methodenaufruf mit gesetztem Schalter oneway gesandt (der Befehl beendet sich direkt danach). Dies teilt dem Dienst mit, keine Antwort zu erstellen.

Hinzugefügt in Version 255.

When used with call: request a protocol upgrade. The method call is sent with the upgrade flag set. The service is expected to send a single reply confirming the upgrade. After the reply, the Varlink protocol is no longer in effect on the connection.

If --exec is not specified, varlinkctl acts as a bidirectional proxy: data read from standard input is forwarded to the upgraded connection, and data received from the connection is written to standard output.

If --exec is specified, the upgraded connection socket is placed on both standard input and standard output of the invoked process. This is similar to the regular --exec behavior (without --upgrade), which places the method call reply on standard input. The invoked process can thus simply read from and write to stdin/stdout to communicate over the upgraded protocol.

This option may not be combined with --more, --oneway, --collect, --graceful=, or --push-fd=.

Hinzugefügt in Version 261.

Wählt die JSON-Ausgabeformatierung. Entweder »pretty« (für schön eingerückte, gefärbte Ausgabe) oder »short« (für knappe Ausgabe mit minimalem Leerraum und keinen Zeilenumbrüchen). Die Vorgabe ist »short«.

Hinzugefügt in Version 255.

Bei dem interaktiven Aufruf vom Terminal äquivalent zu --json=pretty. Andernfalls ist es zu --json=short äquivalent, insbesondere wenn die Ausgabe mittels einer Pipe an ein anderes Programm weitergeleitet wird.

Hinzugefügt in Version 255.

Untderdrückt die Ausgabe der Antworten von Methodenaufrufen.

Hinzugefügt in Version 257.

Akzeptiert einen qualifizierten Varlink-Fehlernamen, d.h. einen Schnittstellenanmen mit angehängtem Fehlernamen, getrennt durch einen Punkt, z.B. »org.varlink.service.InvalidParameter«. Dies stellt sicher, dasss beim Fehlschlag eines Methodenaufrufs mit dem angegebenen Fehler dies als Erfolg behandelt wird, d.h. dazu führt, dass der Aufruf von varlinkctl mit einem Exit-Status Null beendet wird. Diese Option kann mehr als einmal verwandt werden, um mehrere verschiedene Fehler als Erfolg zu behandeln.

Hinzugefügt in Version 257.

Erwartet als Parameter eine Zeitüberschreitung in Sekunden. Standardmäßig wird eine Zeitüberschreitung von 45 s durchgesetzt. Um die Zeitüberschreitung auszuschalten, geben Sie »infinity« oder die leere Zeichenkette an.

Hinzugefügt in Version 257.

Sobald der mittels call aufgerufene Methodenaufruf erfolgreich abgeschlossen wurde, wird die angegebene Befehlszeile nachgeladen, wobei die Methodenaufruf-Ausgabeparameter, serialisiert nach JSON, in die Standardeingabe übergeben werden (und die Standardausgabe und die Standardfehlerausgabe vom aufrufenden Prozess geerbt werden). Desweiteren werden alle Dateideskriptoren, die auf dem zugrundeliegenden Kommunikations-Socket zurückgegeben werden, an den aufgerufenen Prozess mittels des gewöhnlichen Protokolls $LISTEN_FDS weitergegeben. Diese Funktionalität kann zum Verarbeiten von Antworten verwandt werden, die auf eine vernünftige Weise einem zugehörigen Dateideskriptor zugeordnet sind.

Beachten Sie, dass bei der Angabe von --exec der dritte Parameter für call nicht optional ist (d.h. die Methodenaufrufparameter).

Hinzugefügt in Version 258.

Akzeptiert eine numerische Dateideskriptorennummer als Parameter. Kann zur Übergabe eines Dateideskriptors zusammen mit einem Methodenaufruf verwandt werden, falls der zugrundeliegende Transport dies unterstützt. Kann mehrfach verwandt werden, um mehrere Dateideskriptoren zu übergeben, dabei bleibt die Reihenfolge der Angabe erhalten. Die angegebenen Dateideskriptoren müssen an den varlinkctl-Aufruf übergeben werden. Optional kann anstelle einer numerische Dateideskriptorennummer ein absoluter oder relativer Dateisystempfad übergeben werden (letzterem muss »./« vorangestellt werden), der dann schreibgeschützt geöffnet wird.

Hinzugefügt in Version 258.

Bestimmt, ob die systemweite oder benutzerbezogene Registratur abgefragt werden soll, wenn der Befehl list-registry verwandt wird. Standardmäßig wird die systemweite Registratur abgefragt.

Hinzugefügt in Version 260.

Befragt den Benutzer nicht für Authentifizierung für privilegierte Aktionen.

Leitet die Ausgabe nicht an ein Textanzeigeprogramm weiter.

Zeigt einen kurzen Hilfetext an und beendet das Programm.

Zeigt eine kurze Versionszeichenkette an und beendet das Programm.

Verzeichnis, das AF_UNIX-Eintrittspunkt-Socket-Inodes (oder Symlinks zu ihnen) von gut bekannten, öffentlichen Varlink-Schnittstellen auf dem lokalen System enthält. Sie sind nach ihrer Varlink-Schnittstelle, die sie implementieren, benannt.

Verwenden Sie varlinkctl list-registry, um den Inhalt dieses Verzeichnisses anzuzeigen.

(Inodes, die weder als Socket-Inodes noch als Symlinks auf sie befähigt sind, werden ignoriert. Eine zukünftige Erweiterung könnte reguläre Dateien und Verzeichnisse einführen, um die Registraturfunktionalität zu erweiteren.)

Hinzugefügt in Version 260.

$ 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,


        …

$ 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
}

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

# varlinkctl call ssh-unix:einemaschine:/run/systemd/io.systemd.Hostname io.systemd.Hostname.Describe '{}'

# varlinkctl call ssh-exec:einemaschine:systemd-creds org.varlink.service.GetInfo '{}'

# /etc/systemd/system/varlink-decompress-xz.socket
[Socket]
ListenStream=/run/varlink/registry/com.example.Decompress.XZ
[Install]
WantedBy=sockets.target
# /etc/systemd/system/varlink-decompress-xz.service
[Service]
ExecStart=varlinkctl serve com.example.Decompress.XZ xz -d
DynamicUser=yes
PrivateNetwork=yes
ProtectSystem=strict
ProtectHome=yes
NoNewPrivileges=yes
SystemCallFilter=~@privileged @resources
MemoryMax=256M

$ echo "Hallo" | xz | varlinkctl call --upgrade \


        unix:/run/varlink/registry/com.example.Decompress.XZ \


        com.example.Decompress.XZ '{}'
Hallo

$ systemd-socket-activate -l /tmp/decompress.sock -- varlinkctl serve com.example.Decompress.XZ xz -d &
$ echo "Hallo" | xz | varlinkctl call --upgrade unix:/tmp/decompress.sock com.example.Decompress.XZ '{}'
Hallo