VARLINKCTL(1)

BEZEICHNUNG
varlinkctl - Varlink-Diensten untersuchen und aufrufen

ÜBERSICHT

varlinkctl [OPTIONEN…] info ADRESSE

varlinkctl [OPTIONEN…] list-interfaces ADRESSE

varlinkctl [OPTIONEN…] list-methods ADRESSE [SCHNITTSTELLE…]

varlinkctl [OPTIONEN…] introspect ADRESSE [SCHNITTSTELLE…]

varlinkctl [OPTIONEN…] call ADRESSE METHODE [ARGUMENTE]

varlinkctl [OPTIONEN…] --exec call ADRESSE METHODE ARGUMENTE -- BEFEHLSZEILE

varlinkctl [OPTIONEN…] serve METHODE {BEFEHLSZEILE…}

varlinkctl [OPTIONEN…] validate-idl [DATEI]

BESCHREIBUNG

varlinkctl kann zur Untersuchung und dem Aufruf von Varlink[1]-Diensten verwandt werden.

Dienste werden durch eines der Folgenden referenziert:

    • 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.

Für mehr Komfort werden diese zwei einfacheren (redundanten) Diensteadressyntaxen auch unterstützt:

    • 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).

BEFEHLE

Die folgenden Befehle werden verstanden:

info ADRESSE
    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.

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

    Hinzugefügt in Version 255.

list-methods ADRESSE [SCHNITTSTELLE…]
    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.

introspect ADRESSE [SCHNITTSTELLE…]
    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.

call ADRESSE METHODE [ARGUMENTE]
    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.

serve METHODE BEFEHLSZEILE…
    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.

list-registry
    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.

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

help
    Zeigt die Hilfe zur Befehlssyntax.

    Hinzugefügt in Version 255.

OPTIONEN

Die folgenden Optionen werden verstanden:

--more
    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.

-E
    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.

--collect
    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.

--oneway
    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.

--upgrade
    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.

--json=MODUS
    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.

-j
    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.

--quiet, -q
    Untderdrückt die Ausgabe der Antworten von Methodenaufrufen.

    Hinzugefügt in Version 257.

--graceful=
    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.

--timeout=
    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.

--exec
    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.

--push-fd=
    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.

--system, --user
    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.

--no-ask-password
    Befragt den Benutzer nicht für Authentifizierung für privilegierte Aktionen.

--no-pager
    Leitet die Ausgabe nicht an ein Textanzeigeprogramm weiter.

-h, --help
    Zeigt einen kurzen Hilfetext an und beendet das Programm.

--version
    Zeigt eine kurze Versionszeichenkette an und beendet das Programm.

DATEIEN UND VERZEICHNISSE

/run/varlink/registry/
    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.

BEISPIELE

Beispiel 1. Einen Dienst untersuchen

Die folgenden drei Befehle untersuchen den durch systemd-resolved.service(8) implementierten Dienst »io.systemd.Resolve«. Sie listen allgemeine Dienstinformationen und Implementierungsschnittstellen auf und zeigen dann die Schnittstellendefinitionen seiner primären Schnittstelle an:

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

(Im obigen Beispiel wurden die Schnittstellendefinitionen im Interesse einer kurzen Darstellung abgeschnitten.)

Beispiel 2. Aufruf einer Methode

Der folgende Befehl löst einen Rechnernamen mittels des Methodenaufrufs ResolveHostname von systemd-resolved.service(8) auf.

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

Beispiel 3. Untersuchung des Programms eines Dienstes

Der folgende Befehl untersucht das Programm /usr/lib/systemd/systemd-pcrextend und die von ihm bereitgestellten IPC-APIs. Dann ruft es eine Methode darauf aus:

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

Beispiel 4. Aufruf einer Methode aus der Ferne mittels SSH

Der folgende Befehl erlangt einen Bericht über die Identität des fernen Rechners »einemaschine« von systemd-hostnamed.service(8) durch Verbindung mittels SSH an das AF_UNIX-Socket, auf dem der Dienst auf Anfragen wartet:

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

Um das Varlink-Diensteprogramm direkt auf dem fernen Rechner aufzurufen, können Sie folgendes anstelle der Kommunikation mit dem Dienst über AF_UNIX durchführen:

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

Example 5. Serving a Sandboxed Decompressor via Protocol Upgrade

The following socket and service units expose xz decompression as a Varlink service. Clients connect and send compressed data over the upgraded connection, receiving decompressed output in return.

    # /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

A client can then decompress data through this service:

    $ echo "Hallo" | xz | varlinkctl call --upgrade \
            unix:/run/varlink/registry/com.example.Decompress.XZ \
            com.example.Decompress.XZ '{}'
    Hallo

For quick testing without unit files, systemd-socket-activate can be used to provide the listening socket:

    $ 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

SIEHE AUCH

busctl(1), Varlink[1]

ANMERKUNGEN

1.  Varlink
    https://varlink.org/

ÜBERSETZUNG
Die deutsche Übersetzung dieser Handbuchseite wurde von Helge Kreutzmann <debian@helgefjell.de> erstellt.

Diese Übersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 (https://www.gnu.org/licenses/gpl-3.0.html) oder neuer bezüglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG übernommen.

Wenn Sie Fehler in der Übersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die Mailingliste der Übersetzer (debian-l10n-german@lists.debian.org).