BEFEHLE¶
Die folgenden Befehle werden verstanden:
list
Zeigt alle Peers (Gegenstellen) durch ihren Dienstenamen
auf dem Bus. Standardmäßig werden sowohl eindeutige als auch gut
bekannte Namen angezeigt, dies kann aber mit den Schaltern
--unique und
--acquired geändert werden. Dies ist die Vorgabeaktion, falls
kein Befehl angegeben ist.
Hinzugefügt in Version 209.
status [DIENST]
Zeigt Prozessinformationen und Berechtigungsnachweise
eines Bus-Dienstes (falls einer durch seinen eindeutigen oder gut bekannten
Namen angegeben ist), eines Prozesses (falls einer durch seine numerische PID
angegeben ist) oder des Eigentümers des Busses (falls kein Parameter
angegeben ist).
Hinzugefügt in Version 209.
monitor [DIENST…]
Schreibt die ausgetauschten Nachrichten raus. Falls
DIENST angegeben ist, werden die Nachrichten von und an diesen Peer
(Gegenstelle), der durch seinen gut bekannten oder eindeutigen Namen
identifiziert ist, angezeigt. Andernfalls werden alle Nachrichten auf dem Bus
angezeigt. Verwenden Sie Strg+C, um die Ausgabe abzubrechen.
Hinzugefügt in Version 209.
capture [DIENST…]
Ähnlich zu
monitor, schreibt die Ausgabe
aber im Pcap-Format (für Details siehe
Dateierfassungsformat PCAP
Nächste Generation (pcapng)). Stellen Sie sicher, dass die die
Standardausgabe in eine Datei oder Pipe umgelenkt ist. Werkzeuge wie
wireshark(1) können zum Analysieren und Anschauen der
entstehenden Dateien verwandt werden.
Hinzugefügt in Version 218.
tree [DIENST…]
Zeigt einen Objektbaum von einem oder mehreren Diensten.
Falls
DIENST angegeben ist, wird nur der Objektbaum des angegebenen
Dienstes gezeigt. Andernfalls werden alle Objektbäume aller Dienste auf
dem Bus, der mindestens einen gut bekannten Namen erlangte, angezeigt.
Hinzugefügt in Version 218.
introspect DIENST OBJEKT
[SCHNITTSTELLE]
Zeigt Schnittstellen, Methoden, Eigenschaften und Signale
der angegebenen Objekte (identifiziert durch ihren Pfad) auf dem angegebenen
Dienst. Falls das Schnittstellenargument übergeben wurde, wird die
Ausgabe auf die Elemente auf der angegebenen Schnittstelle beschränkt.
Hinzugefügt in Version 218.
call DIENST OBJEKT SCHNITTSTELLE
METHODE [SIGNATUR [ARGUMENT…]]
Ruft eine Methode auf und zeigt die Antwort. Akzeptiert
einen Dienstenamen, einen Objektpfad, Schnittstellennamen und Methodennamen.
Falls Parameter an den Methodenaufruf übergeben werden sollen, wird
eine Signaturzeichenkette, gefolgt von den Argumenten, die individuell als
Zeichenketten formatiert sind, benötigt. Für Details über
die verwandte Formatierung siehe unten. Um die Ausgabe der
zurückgelieferten Daten zu unterdrücken, verwenden Sie die
Option
--quiet.
Hinzugefügt in Version 218.
emit OBJEKT SCHNITTSTELLE SIGNAL
[SIGNATURE [ARGUMENT…]]
Sendet ein Signal. Akzeptiert einen Objektpfad,
Schnittstellennamen und Methodennamen. Falls Parameter übergeben werden
sollen, wird eine Signaturzeichenkette, gefolgt von den Argumenten, die
individuell als Zeichenketten formatiert sind, benötigt. Für
Details über die verwandte Formatierung siehe unten. Um das Ziel des
Signals anzugeben, verwenden Sie die Option
--destination=.
Hinzugefügt in Version 242.
get-property DIENST OBJEKT
SCHNITTSTELLE EIGENSCHAFT…
Ruft den aktuellen Wert einer oder mehrerer
Objekteigenschaften ab. Akzeptiert einen Dienstenamen, einen Objektpfad, einen
Schnittstellennamen und einen Eigenschaftennamen. Mehrere Eigenschaften
können auf einmal, getrennt durch Zeilenumbrüche, angegeben
werden. In diesem Falle werden ihre Werte einer nach dem anderen angezeigt.
Die Ausgabe ist standardmäßig im knappen Format. Verwenden Sie
--verbose für ein ausführlicheres Ausgabeformat.
Hinzugefügt in Version 218.
set-property DIENST OBJEKT
SCHNITTSTELLE EIGENSCHAFT SIGNATUR
ARGUMENT…
Setzt den aktuellen Wert einer Objekteigenschaft.
Akzeptiert einen Dienstenamen, Objektpfad, Schnittstellennamen,
Eigenschaftsnamen, Eigenschaftssignatur, gefolgt von einer Liste von
Parametern, die als Zeichenketten formatiert sind.
Hinzugefügt in Version 218.
help
Zeigt die Hilfe zur Befehlssyntax.
Hinzugefügt in Version 209.
OPTIONEN¶
Die folgenden Optionen werden verstanden:
--address=ADRESSE
Verbindet mit dem durch
ADRESSE angegebenen Bus,
anstatt geeignete Vorgaben für entweder den System- oder den
Benutzerbus zu verwenden (siehe die Optionen
--system und
--user).
Hinzugefügt in Version 209.
--show-machine
Zeigt bei der Anzeige der Liste der Peers (Gegenstellen)
eine Spalte mit den Namen der Container an, zu denen sie gehören. Siehe
systemd-machined.service(8).
Hinzugefügt in Version 209.
--unique
Zeigt bei der Anzeige der Liste der Peers (Gegenstellen)
nur »eindeutige« Namen (der Form
»:
Zahl.
Zahl«) an.
Hinzugefügt in Version 209.
--acquired
Das Gegenteil von
--unique — zeigt nur
»gut bekannte« Namen an.
Hinzugefügt in Version 209.
--activatable
Zeigt bei der Anzeige der Liste der Peers (Gegenstellen)
nur jene an, die tatsächlich noch nicht aktiviert wurden, aber beim
Zugriff darauf automatisch gestartet werden könnten.
Hinzugefügt in Version 209.
--match=TREFFER
Zeigt bei der Anzeige der ausgetauschten Nachrichten nur
die auf
TREFFER passende Teilmenge an. Siehe
sd_bus_add_match(3).
Hinzugefügt in Version 209.
--size=
Gibt bei der Verwendung mit dem Befehl
capture die
maximale Busnachrichtengröße an, die aufgenommen
(»snaplen«) werden soll. Standardmäßig 4096 Byte.
Hinzugefügt in Version 218.
--list
Zeigt bei der Verwendung mit dem Befehl
tree eine
flache Liste von Objektpfaden statt eines Baumes an.
Hinzugefügt in Version 218.
-q, --quiet
Unterdrückt bei der Verwendung mit dem Befehl
call die Anzeige der Antwortnachrichtennutzlast. Beachten Sie, dass
zurückgelieferte Fehler weiterhin ausgegeben und das Werkzeug den
Erfolg oder Misserfolg durch den Exit-Code des Prozesses angeben wird, selbst
wenn diese Option angegeben ist.
Hinzugefügt in Version 218.
--verbose
Zeigt bei der Verwendung mit dem Befehl
call oder
get-property die Ausgabe in einem ausführlicheren Format an.
Hinzugefügt in Version 218.
--xml-interface
Gibt die vom D-Bus-Aufruf
org.freedesktop.DBus.Introspectable.Introspect empfangene
XML-Beschreibung statt der normalen Ausgabe aus, falls mit dem Aufur
introspect verwandt.
Hinzugefügt in Version 243.
--json=MODUS
Zeigt die Ausgabe im JSON-Format an, wenn dies mit dem
Befehl
call oder
get-property verwandt wird. Erwartet entweder
»short« (für die kürzest mögliche Ausgabe
ohne redundanten Leerraum oder Zeilenumbrüche) oder
»pretty« (für eine schöne Version des gleichen,
mit Einrückungen und Zeilenumbrüchen). Beachten Sie, dass die
Umwandlung von der D-Bus-Anordnung nach JSON auf eine verlustfreie Art
erfolgt, was bedeutet, dass Typinformationen in den JSON-Objektbaum
eingebettet sind.
Hinzugefügt in Version 240.
-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 240.
--expect-reply=LOGISCH
Gitbt bei der Verwendung mit dem Befehl
call an,
ob
busctl auf den Abschluss des Methodenaufrufs warten, die Ausgabe der
zurückgelieferten Methodenantwortdaten ausgeben und Erfolg oder Fehler
mittels des Prozess-Exit-Codes zurückliefern soll. Falls dies auf
»no« gesetzt ist, wird der Methodenaufruf durchgeführt,
aber es wird keine Antwort erwartet, das Werkzeug beendet sich sofort und
daher kann keine Antwort angezeigt und kein Erfolg oder Misserfolg über
den Exit-Code zurückgeliefert werden. Um nur die Ausgabe der
Antwortnachrichtennutzlast zu unterdrücken, verwenden Sie
--quiet oben. Standardmäßig »yes«.
Hinzugefügt in Version 218.
--auto-start=LOGISCH
Gibt bei der Verwendung mit dem Befehl
call oder
emit an, ob der Methodenaufruf implizit den aufgerufenen Dienst
aktivieren soll, falls er noch nicht laufen sollte, aber für
automatisches Starten konfiguriert ist. Standardmäßig
»yes«.
Hinzugefügt in Version 218.
--allow-interactive-authorization=LOGISCH
Gibt bei der Verwendung mit dem Befehl
call an, ob
der Dienst interaktive Autorisierung während der Ausführung
einer Aktion erzwingen darf, falls die Sicherheitsrichtlinie dafür
konfiguriert ist. Standardmäßig »yes«.
Hinzugefügt in Version 218.
--timeout=SEK
Gibt bei der Verwendung mit dem Befehl
call die
maximale Zeit, die auf den Abschluss eines Methodenaufrufs gewartet werden
soll, an. Falls keine Zeiteinheit angegeben ist, wird Sekunden angenommen. Die
normalen anderen Einheiten werden auch verstanden (ms, us, s, min, h, d, w,
month, y). Beachten Sie, dass diese Zeitüberschreitung nicht angewandt
wird, falls
--expect-reply=no verwandt wird, da das Werkzeug dann nicht
auf eine Antwortnachricht wartet. Falls nicht angegeben oder auf 0 gesetzt,
wird die Vorgabe von »25s« angenommen.
Hinzugefügt in Version 218.
--augment-creds=LOGISCH
Steuert, ob das Berichten der Berechtigungsnachweise
durch
list oder
status mit Daten aus /proc/ ergänzt
werden soll. Wenn dies eingeschaltet ist, sind die dargestellten Daten
möglicherweise inkonsistent, da die aus /proc/ gelesenen Daten neuer
als der Rest der Berechtigungsnachweisinformationen sein könnten.
Standardmäßig »yes«.
Hinzugefügt in Version 218.
--watch-bind=LOGISCH
Steuert, ob auf das Auftauchen des angegebenen
AF_UNIX-Bus-Sockets im Dateisystem gewartet werden soll, bevor damit
verbunden wird. Standardmäßig aus. Falls aktiviert, wird das
Werkzeug das Dateisystem beobachten, bis das Socket erstellt ist und sich dann
mit ihm verbinden.
Hinzugefügt in Version 237.
--destination=DIENST
Akzeptiert einen Dienstenamen. Bei der Verwendung mit dem
Befehl
emit wird ein Signal an den angegebenen Dienst ausgesandt.
Hinzugefügt in Version 242.
--user
Kommuniziert mit dem Diensteverwalter des aufrufenden
Benutzers statt mit dem Diensteverwalter des Systems.
--system
Kommuniziert mit dem Diensteverwalter des Systems. Dies
ist die implizite Vorgabe.
-H, --host=
Führt die Aktion aus der Ferne aus. Geben Sie den
Rechnernamen oder einen Benutzernamen und Rechnernamen (getrennt durch
»@«) an, zu dem verbunden werden soll. Dem Rechnernamen darf
optional ein Port, auf dem SSH auf Anfragen wartet, getrennt durch
»:« und dann ein Container auf dem angegebenen Host
angehängt werden, womit direkt zu einem bestimmten Container auf dem
angegebenen Rechner verbunden wird. Dies verwendet SSH, um mit der
Maschinen-Verwalterinstanz auf dem Rechner in der Ferne zu kommunizieren.
Container-Namen dürfen mit machinectl -H RECHNER
aufgezählt werden. Stellen Sie IPv6-Adressen in Klammern.
-M, --machine=
Führt die Aktion in einem lokalen Container aus.
Geben Sie den Namen des Containers an, zu dem verbunden werden soll. Optional
kann diesem ein Benutzername, abgetrennt durch ein »@«-Zeichen,
als der verbunden werden soll, vorangestellt werden. Falls die besondere
Zeichenkette ».host« anstelle des Container-Names verwandt wird,
wird eine Verbindung zu dem lokalen System aufgebaut (das ist nützlich,
um sich zu dem Benutzerbus eines bestimmten Benutzers zu verbinden:
»--user --machine=lennart@.host«. Falls die
»@«-Syntax nicht verwandt wird, wird die Verbindung als Benutzer
»root« vorgenommen. Falls die »@«-Syntax verwandt
wird, kann entweder die linke oder die rechte Seite fortgelassen werden (aber
nicht beide). In diesem Fall wird der lokale Benutzername und
».host« angenommen.
-l, --full
Verkürzt die Ausgabe im Befehl
list nicht.
Hinzugefügt in Version 245.
--no-pager
Leitet die Ausgabe nicht an ein Textanzeigeprogramm
weiter.
--no-legend
Gibt die Legende nicht aus, d.h. die Spaltenköpfe
und die Fußzeile mit Hinweisen.
-h, --help
Zeigt einen kurzen Hilfetext an und beendet das
Programm.
--version
Zeigt eine kurze Versionszeichenkette an und beendet das
Programm.
Die Befehle call und set-property akzeptieren eine
Signaturzeichenkette, gefolgt von einer Liste von als Zeichenketten
formatierten Parametern (für Details über
D-Bus-Signaturzeichenketten siehe das Typesystemkapitel der
D-Bus-Spezifikation[2]). Für einfache Typen sollte jeder der
Signatur folgenden Parameter einfach der als Zeichenkette formatierte
Parameter sein. Positive logische Werte können als
»true«, yes«, »on« oder
»1«, negative logische Werte können als
»false«, »no«, »off« oder
»0« angegeben sein. Für Felder soll ein numerisches
Argument für die Anzahl der Einträge gefolgt von den
Einträgen angegeben werden. Für Varianten soll die Signatur
der Einträge, gefolgt von den Inhalten, angegeben werden. Für
Wörterbücher und Strukturen sollen die Einträge direkt
angegeben werden.
Beispielsweise ist
die Formatierung einer einzelnen Zeichenkette
»jawoll«.
ist die Formatierung eines Zeichenkettenfeldes mit den drei
Einträgen »Hallo«, »Welt« und
»foobar«.
a{sv} 3 Eins s One Zwei u 2 Ja b true
ist die Formatierung eines Wörterbuchfeldes, das
Zeichenketten auf Varianten abbildet und aus drei Einträgen besteht.
Der Zeichenkette »Eins« wird »One« zugeordnet.
Der Zeichenkette »Zwei« wird die vorzeichenfreie
32-Bit-Ganzzahl 2 zugeordnet. Der Zeichenkette »Ja« wird ein
positiver logischer Wert zugeordnet.
Beachten Sie, dass die Befehle call, get-property,
introspect auch Ausgaben für die zurückgelieferten
Daten in diesem Format erstellen. Da dieses Format manchmal zu knapp und
daher nicht immer leicht verständlich ist, können die Befehle
call und get-property eine ausführlichere, mehrzeilige
Ausgabe, wenn die Option --verbose übergeben wird,
erzeugen.
BEISPIELE¶
Beispiel 1. Eine Eigenschaft lesen und
schreiben
Die folgenden zwei Befehle schreiben zuerst eine Eigenschaft und
lesen sie dann zurück. Die Eigenschaft wird im Objekt
»/org/freedesktop/systemd1« des Dienstes
»org.freedesktop.systemd1« gefunden. Der Name der Eigenschaft
ist »LogLevel« auf der Schnittstelle
»org.freedesktop.systemd1.Manager«. Die Eigenschaft
enthält eine einzelne Zeichenkette:
# busctl set-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel s debug
# busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager LogLevel
s "debug"
Beispiel 2. Knappe und ausführliche
Ausgabe
Die folgenden zwei Befehle lesen eine Eigenschaft, die ein Feld
von Zeichenketten enthält, und zeigen sie zuerst in einem knappen,
gefolgt von einem ausführlichen Format:
$ busctl get-property org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
as 2 "LANG=en_US.UTF-8" "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin"
$ busctl get-property --verbose org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager Environment
ARRAY "s" {
STRING "LANG=en_US.UTF-8";
STRING "PATH=/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin";
};
Beispiel 3. Eine Methode aufrufen
Die folgenden Befehle rufen die Methode »StartUnit«
auf der Schnittstelle »org.freedesktop.systemd1.Manager« des
Objektes »/org/freedesktop/systemd1« des Dienstes
»org.freedesktop.systemd1« auf und übergeben ihr zwei
Zeichenketten »cups.service« und »replace«. Als
Ergebnis des Methodenaufrufs wird ein einzelnes Pfadparameterobjekt
empfangen und angezeigt:
# busctl call org.freedesktop.systemd1 /org/freedesktop/systemd1 org.freedesktop.systemd1.Manager StartUnit ss "cups.service" "replace"
o "/org/freedesktop/systemd1/job/42684"