Provided by: manpages-de_4.27.0-1_all 
BEZEICHNUNG
org.freedesktop.import1 - Die D-Bus-Schnittstelle von systemd-importd
EINFÜHRUNG
systemd-importd.service(8) ist ein Systemdienst, der zum Import, Export und Herunterladen von
Plattenabbildern verwandt werden kann. Diese Plattenabbilder können von Werkzeugen wie systemd-nspawn(1)
verwandt werden, um lokale Container auszuführen. Der Dienst wird als Backend für importctl pull-raw,
importctl pull-tar und ähnliche Befehle verwandt. Diese Seite beschreibt die D-Bus-Schnittstelle.
Beachten Sie, dass systemd-importd.service(8) größtenteils ein kleiner Begleitdienst für
systemd-machined.service(8) ist. Viele Aktionen, um lokale Container und VM-Abbilder zu bearbeiten, sind
daher mittels des D-Bus-APIs von systemd-machined(8) verfügbar, siehe org.freedesktop.machine1(5).
DAS OBJEKT »MANAGER«
Der Dienst legt die folgenden Schnittstellen des Objekts »Manager« auf dem Bus offen:
node /org/freedesktop/import1 {
interface org.freedesktop.import1.Manager {
methods:
ImportTar(in h fd,
in s local_name,
in b force,
in b read_only,
out u transfer_id,
out o transfer_path);
ImportTarEx(in h fd,
in s local_name,
in s class,
in t flags,
out u transfer_id,
out o transfer_path);
ImportRaw(in h fd,
in s local_name,
in b force,
in b read_only,
out u transfer_id,
out o transfer_path);
ImportRawEx(in h fd,
in s local_name,
in s class,
in t flags,
out u transfer_id,
out o transfer_path);
ImportFileSystem(in h fd,
in s local_name,
in b force,
in b read_only,
out u transfer_id,
out o transfer_path);
ImportFileSystemEx(in h fd,
in s local_name,
in s class,
in t flags,
out u transfer_id,
out o transfer_path);
ExportTar(in s local_name,
in h fd,
in s format,
out u transfer_id,
out o transfer_path);
ExportTarEx(in s local_name,
in s class,
in h fd,
in s format,
in t flags,
out u transfer_id,
out o transfer_path);
ExportRaw(in s local_name,
in h fd,
in s format,
out u transfer_id,
out o transfer_path);
ExportRawEx(in s local_name,
in s class,
in h fd,
in s format,
in t flags,
out u transfer_id,
out o transfer_path);
PullTar(in s url,
in s local_name,
in s verify_mode,
in b force,
out u transfer_id,
out o transfer_path);
PullTarEx(in s url,
in s local_name,
in s class,
in s verify_mode,
in t flags,
out u transfer_id,
out o transfer_path);
PullRaw(in s url,
in s local_name,
in s verify_mode,
in b force,
out u transfer_id,
out o transfer_path);
PullRawEx(in s url,
in s local_name,
in s class,
in s verify_mode,
in t flags,
out u transfer_id,
out o transfer_path);
ListTransfers(out a(usssdo) transfers);
ListTransfersEx(in s class,
in t flags,
out a(ussssdo) transfers);
CancelTransfer(in u transfer_id);
ListImages(in s class,
in t flags,
out a(ssssbtttttt) images);
signals:
TransferNew(u transfer_id,
o transfer_path);
TransferRemoved(u transfer_id,
o transfer_path,
s result);
};
interface org.freedesktop.DBus.Peer { … };
interface org.freedesktop.DBus.Introspectable { … };
interface org.freedesktop.DBus.Properties { … };
};
Methoden
ImportTar()/ImportTarEx() und ImportRaw()/ImportRawEx() importieren ein Plattenabbild und legen es im
Abbildverzeichnis ab. Das erste Argument sollte ein Dateideskriptor (zum Lesen geöffnet) sein, der sich
auf die zu importierende Tar- oder rohe Datei bezieht. Es sollte eine Datei auf der Platte, eine Pipe
oder ein Socket referenzieren. Wenn ImportTar()/ImportTarEx() verwandt wird, sollte sich der
Dateideskriptor auf eine Tar-Datei, die optional mit gzip(1), bzip2(1) oder xz(1) komprimiert ist,
beziehen. systemd-importd(8) wird automatisch das verwandte Komprimierungsschema (falls vorhanden)
erkennen. Wenn ImportRaw()/ImportRawEx() verwandt wird, sollte sich der Dateideskriptor auf ein rohes
oder qcow2-Plattenabbild beziehen, das optional mit gzip(1), bzip2(1) oder xz(1) komprimiert ist. In
beiden Fällen wird Fortschrittsinformation für die Importaktion erstellt, falls die Datei als
Dateideskriptor auf Platte festgelegt ist (da dann die Gesamtgröße auf Platte bekannt ist). Falls ein
Socket oder eine Pipe festgelegt ist, ist keine Fortschrittsinformation verfügbar. Dem
Dateideskriptorargument folgt ein lokaler Name für das Abbild. Dieser Name sollte für einen Rechnernamen
geeignet sein und wird zur Benennung des importierten Abbildes unterhalb von /var/lib/machines/ verwandt.
Ein Tar-Import wird als Verzeichnisbaum oder als ein btrfs(8)-Teildatenträger unterhalb des
Abbild-Verzeichnisses unter dem festgelegten Namen ohne zusätzliche Erweiterung abgelegt. Ein roher
Import wird als eine Datei im Abbildverzeichnis mit angehängter Endung .raw abgelegt. Im Falle von
ImportTar()/ImportRaw() und falls das Argument force true ist, werden alle vorher bestehenden Abbilder
mit dem gleichen Namen entfernt, bevor die Aktion gestartet wird. Andernfalls schlägt die Aktion fehl,
falls ein Abbild mit dem gleichen Namen bereits existiert. Das Argument read_only steuert, ob ein
schreibbares oder schreibgeschütztes Abbild erstellt wird. Im Falle von ImportTarEx()/ImportRawEx()
werden diese logischen Schalter stattdessen mittels eines 64-bit-Schalterparameters bereitgestellt, wobei
Bit 0 auf den Parameter force und Bit 1 auf read_only abgebildet ist. Der Parameter class legt die
Abbildklasse fest und akzeptiert entweder »machine«, »portable«, »sysext« oder »confext«. Alle vier
Methoden kehren direkt nach Start des Imports zurück, während die Importübertragung läuft. Sie liefern
ein Paar von Übertragungskennzeichner und Objektpfad zurück, die zum Ermitteln von
Fortschrittsinformationen über die Übertragung und zum Abbruch der Übertragung verwandt werden können.
Der Übertragungskennzeichner ist ein einfacher numerischer Kennzeichner, der Objektpfad referenziert das
Objekt org.freedesktop.import1.Transfer, siehe unten. Warten Sie auf ein Signal TransferRemoved() für die
Übertragungskennung um zu erkennen, wenn eine Übertragung abgeschlossen ist. Das zurückgelieferte
Übertragungsobjekt ist zur Bestimmung des aktuellen Fortschrittes oder zur Protokollausgabe der laufenden
Importaktion nützlich.
ExportTar()/ExportTarEx() und ExportRaw()/ExportRaw() implementieren die umgekehrte Aktion und können zum
Exportieren eines Systemabbildes verwandt werden, um es in ein Tar- oder rohes Abbild abzulegen. Sie
akzeptieren den zu exportierenden Maschinennamen als ersten Parameter, gefolgt von einem (zum schreiben
geöffneten) Dateideskriptor, wohin die Tar- oder rohe Datei geschrieben wird. Er kann entweder eine Datei
auf der Platte oder eine Pipe/ein Socket referenzieren. Das dritte Argument legt das zu verwendende
Kompressionsformat des Abbildes fest. Es akzeptiert entweder »uncompressed«, »xz«, »bzip2« oder »gzip«,
abhängig vom benötigten Komprimierungsschema. Das in den angegebenen Dateideskriptor geschriebene Abbild
wird im Falle von ExportTar()/ExportTarEx() eine Tar-Datei oder im Falle von ExportRaw()/ExportRawEx()
eine rohe Datei sein. Beachten Sie, dass derzeit rohe Plattenabbilder nicht als Tar-Dateien (und
umgekehrt) exportiert werden können. Diese Einschränkung könnte irgendwann aufgehoben werden. Die Methode
liefert einen Übertragungs-Kennzeichner und einen Objektpfad zum Abbruch oder zum Nachverfolgen der
Export-Aktion, ähnlich wie bei den oben beschriebenen ImportTar()/ImportTarEx() oder
ImportRaw()/ImportRawEx(). ExportTarEx()/ExportRawEx() erwarten die Abbildklasse als zusätzlichen
Parameter, sowie einen 64-bit-Schalterparameter, der derzeit als Null festgelegt sein muss.
PullTar()/PullTarEx() und PullRaw()/PullRawEx() können zum herunterladen, überprüfen und importieren
eines Systemabbildes von einer URL verwandt werden. Sie akzeptieren ein URL-Argument, das auf eine Tar-
oder rohe Datei unter dem Protokoll »http://« oder »https://« zeigen soll und möglicherweise mit gzip(1),
bzip2(1) oder xz(1) komprimiert ist. Das zweite Argument ist ein lokaler Name für das Abbild. Es sollte
als Rechnername, ähnlich wie bei dem entsprechenden Argument wie bei den oben beschriebenen Methoden
ImportTar()/ImportTarEx() und ImportRaw()/ImportRawEx() geeignet sein. Das dritte Argument kennzeichnet
die Überprüfungsmethode für das Abbild. Es kann entweder »no«, »checksum« oder »signature« sein. »no«
schaltet jede Art von Überprüfung des Abbildes aus; »checksum« sucht nach einer SHA256SUM-Datei neben dem
heruntergeladenen Abbild und überprüft jeden SHA256-Hash-Wert in dieser Datei gegen das Abbild;
»signature« macht das Gleiche, versucht aber auch zuerst die SHA256SUM mittels gpg(8) zu
authentifizieren. Im Falle von PullTar()/PullRaw() kennzeichnet das letzte Argument, ob ein
möglicherweise bereits existierendes Abbild mit dem gleichen lokalen Namen ersetzt wird (falls »true«)
oder ob ein Fehlschlag erfolgt (falls »false«). Im Falle von PullTarEx()/PullRawEx() ist das letzte
Argument ein 64-bit-Schalter-Parameter, wobei Bit 0 den Schalter »force« steuert, Bit 1 ist ein
»read_only«-Schalter, der steuert, ob das erstellte Abbild als schreibgeschützt markiert werden soll und
Bit 2 ist ein »keep_download«-Schalter, der kennzeichnet, ob eine unverfälschte, schreibgeschützte Kopie
des heruntergeladenen Abbildes zusätzlich zu der lokalen Kopie des Abbildes beibehalten werden soll. Die
Varianten …_Ex() erwarten auch eine Abbildklassenzeichenkette (wie oben). Wie die oben beschriebenen
Import- und Exportaufrufe liefern diese Aufrufe ein Paar an Übertragungskennzeichner und Objektpfad für
die laufende Herunterladung zurück.
ImportFileSystem()/ImportFileSystemEx() sind ähnlich zu ImportTar()/ImportTarEx(), importieren aber ein
Verzeichnisbaum. Das erste Argument muss sich auf ein Verzeichnisdateideskriptor für die zu importierende
Quell-Hierarchie beziehen.
ListTransfers()/ListTransfersEx() liefern eine Liste der laufenden Importe, Exporte oder
Herunterlade-Aktionen, wie sie mit den sechs oben beschriebenen Aufrufen erstellt werden, zurück. Sie
liefern ein Feld von Strukturen zurück, das aus dem numerischen Übertragungskennzeichner, einer
Zeichenkette, die die Aktion bezeichnet (entweder »import-tar«, »import-raw«, »export-tar«, »export-raw«,
»pull-tar« oder »pull-raw«), einer Zeichenkette, die die ferne Datei bezeichnet (im Falle von
Herunterladeaktionen ist dies die Quell-URL, im Falle von Import-/Export-Aktionen ist dies eine kurze
Zeichenkette, die den hereingereichten Dateideskriptor beschreibt), einer Zeichenkette mit dem lokalen
Maschinennamen, der Abbildklasse (nur im Falle von ListTransfersEx(); entweder »machine«, »portable«,
»sysext« oder »confext«), einem Fortschrittswert zwischen 0.0 (für 0%) und 1.0 (für 100%) sowie den
Übertragungsobjektpfad besteht.
CancelTransfer() kann zum Abbruch einer laufenden Import-, Export- oder Herunterladeaktion verwandt
werden. Es reicht die einfache Angabe des Übertragungskennzeichners, um die laufende Aktion abzubrechen.
ListImages() liefert eine Liste der derzeit installierten Abbilder zurück. Sie akzeptiert eine
Abbildklassenzeichenkette und einen Schalter-Parameter. Die Abbildklasse ist entweder die leere
Zeichenkette oder sie legt eine der vier Abbildklassen fest, nach der dann gefiltert wird. Der
Schalter-Parameter muss derzeit Null sein. Sie liefert ein Feld von Einträgen, wobei jeder ein Abbild
beschreibt. Die Eintragsfelder sind der Reihe nach: die Abbildklasse, der lokale Abbildname, der
Abbildtyp, der Abbildpfad, der Schreibschutz-Schalter, die Erstellungs- und Veränderungszeiten (in
Mikrosekunden seit der UNIX-Epoch) sowie der derzeitige Plattenverbrauch in Byte (sowohl gesamt als auch
exklusiv), sowie alle Größenbegrenzungen in Byte, die für das Abbild gesetzt sind (sowohl gesamt als auch
exklusiv).
Signale
Das Signal TransferNew() wird für jedes Auftreten des Starts einer neuen Übertragung mit den oben
beschriebenen Import-, Export oder Herunterlade-Aufrufen erstellt. Es transportiert den frisch erstellten
Übertragungskennzeichner und Objektpfad.
Das Signal TransferRemoved() wird für jedes Auftreten des Beendens, Abbruchs oder Fehlschlags einer
Übertragung gesandt. Es transportiert auch den Übertragungskennzeichner und Objektpfad, gefolgt von einer
Zeichenkette, die das Ergebnis der Aktion anzeigt. Diese ist entweder »done« (im Erfolgsfall), »canceled«
(abgebrochen) oder »failed« (fehlgeschlagen).
DAS OBJEKT »TRANSFER«
node /org/freedesktop/import1/transfer/_1 {
interface org.freedesktop.import1.Transfer {
methods:
Cancel();
signals:
LogMessage(u priority,
s line);
ProgressUpdate(d progress);
properties:
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u Id = …;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Local = '…';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Remote = '…';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Type = '…';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Verify = '…';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly d Progress = …;
};
interface org.freedesktop.DBus.Peer { … };
interface org.freedesktop.DBus.Introspectable { … };
interface org.freedesktop.DBus.Properties { … };
};
Methoden
Die Methode Cancel() kann zum Abbruch der Übertragung verwandt werden. Sie akzeptiert keine Parameter.
Diese Methode ist ziemlich ähnlich der Methode CancelTransfer() auf der Manager-Schnittstelle (siehe
oben), wird aber auf dem Transfer-Objekt selbst offengelegt, anstatt eine Übertragungskennzeichnung zu
akzeptieren.
Eigenschaften
Die Eigenschaft Id legt die numerische Übertragungskennzeichnung des Transfer-Objekts offen.
Die Eigenschaften Local, Remote und Type legen den lokalen Container-Namen dieser Übertragung offen, die
ferne Quelle (im Falle vom Herunterladen: die URL, im Falle vom Im-/Export: eine Zeichenkette, die den
hereingereichten Dateideskriptor beschreibt) und die Art der Aktion (siehe die obige Methode
ListTransfer() des Managers für eine Erklärung der möglichen Werte).
Die Eigenschaft Verify legt die ausgewählte Überprüfungseinstellung offen und ist nur für die
Herunterladeaktionen definiert (siehe oben).
Die Eigenschaft Progress legt den aktuellen Fortschritt der Übertragung als Wert zwischen 0.0 und 1.0
offen. Um einen Fortschrittsbalken auf dem Bildschirm darzustellen, wird die Abfrage des Wertes in
regelmäßigen Abständen empfohlen, beispielsweise alle 500 ms oder so.
Signale
Das Signal LogMessage() wird für Protokollmeldungen ausgesandt, die durch eine Übertragung erstellt
werden. Es transportiert ein Paar aus Syslog-Protokollstufen-Ganzzahl und Protokoll-Zeichenkette.
Das Signal ProgressUpdate() wird in regelmäßigen Abständen ausgesandt, wenn neue
Herunterlade-Fortschrittsinformationen für eine Übertragung verfügbar sind. Es transportiert eine
doppelt-genaue Fließkommazahl zwischen 0.0 und 1.0, die den Übertragungsfortschritt anzeigt.
BEISPIELE
Beispiel 1. Untersuchung von org.freedesktop.import1.Manager auf dem Bus
$ gdbus introspect --system \
--dest org.freedesktop.import1 \
--object-path /org/freedesktop/import1
Beispiel 2. Untersuchung von org.freedesktop.import1.Transfer auf dem Bus
$ gdbus introspect --system \
--dest org.freedesktop.import1 \
--object-path /org/freedesktop/import1/transfer/_1
VERSIONIERUNG
Diese D-Bus-Schnittstellen folgen den normalen Schnittstellenversionierungsrichtlinien[1].
GESCHICHTE
Das Objekt »Manager«
ImportTarEx(), ImportRawEx(), ImportFileSystemEx(), ExportTarEx(), ExportRawEx(), PullTarEx(),
PullRawEx(), ListTransfersEx(), ListImages() wurden in Version 256 hinzugefügt.
Übertragungsobjekte
ProgressUpdate() wurde in Version 256 hinzugefügt.
SIEHE AUCH
systemd(1), systemd-importd.service(8), importctl(1)
ANMERKUNGEN
1. die normalen Schnittstellenversionierungsrichtlinien
https://0pointer.de/blog/projects/versioning-dbus.html
Ü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 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.
systemd 257.6 ORG.FREEDESKTOP.IMPORT1(5)