Ubuntu Manpage: varlinkctl - Varlink-Diensten untersuchen und aufrufen

bezeichnung
übersicht
beschreibung
befehle
optionen
beispiele
siehe auch
anmerkungen
übersetzung

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…] 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, 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-Objekt nach Stdout geschrieben.

Hinzugefügt in Version 255.

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.

--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 äquivalent zu
--json=short, insbesondere wenn die Ausgabe mittels 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.

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

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:/usr/bin/systemd-creds org.varlink.service.GetInfo '{}'

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