ORG.FREEDESKTOP.IMPORT1(5) org.freedesktop.import1 ORG.FREEDESKTOP.IMPORT1(5) BEZEICHNUNG org.freedesktop.import1 - Die D-Bus-Schnittstelle von systemd-importd EINFUHRUNG systemd-importd.service(8) ist ein Systemdienst, der zum Import, Export und Herunterladen von Plattenabbildern verwandt werden kann. Diese Plattenabbilder konnen von Werkzeugen wie systemd-nspawn(1) verwandt werden, um lokale Container auszufuhren. Der Dienst wird als Backend fur importctl pull-raw, importctl pull-tar und ahnliche Befehle verwandt. Diese Seite beschreibt die D-Bus-Schnittstelle. Beachten Sie, dass systemd-importd.service(8) grosstenteils ein kleiner Begleitdienst fur 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) verfugbar, 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 Dateideskripter (zum Lesen geoffnet) 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 Fallen wird Fortschrittsinformation fur die Importaktion erstellt, falls die Datei als Dateideskriptor auf Platte festgelegt ist (da dann die Gesamtgrosse auf Platte bekannt ist). Falls ein Socket oder eine Pipe festgelegt ist, ist keine Fortschrittsinformation verfugbar. Dem Dateideskriptorargument folgt ein lokaler Name fur das Abbild. Dieser Name sollte fur 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)-Teildatentrager unterhalb des Abbild-Verzeichnisses unter dem festgelegten Namen ohne zusatzliche Erweiterung abgelegt. Ein roher Import wird als eine Datei im Abbildverzeichnis mit angehangter 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 schlagt die Aktion fehl, falls ein Abbild mit dem gleichen Namen bereits existiert. Das Argument read_only steuert, ob ein schreibbares oder schreibgeschutztes 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 zuruck, wahrend die Importubertragung lauft. Sie liefern ein Paar von Ubertragungskennzeichner und Objektpfad zuruck, die zum Ermitteln von Fortschrittsinformationen uber die Ubertragung und zum Abbruch der Ubertragung verwandt werden konnen. Der Ubertragungskennzeichner ist ein einfacher numerischer Kennzeichner, der Objektpfad referenziert das Objekt org.freedesktop.import1.Transfer, siehe unten. Warten Sie auf ein Signal TransferRemoved() fur die Ubertragungskennung um zu erkennen, wenn eine Ubertragung abgeschlossen ist. Das zuruckgelieferte Ubertragungsobjekt ist zur Bestimmung des aktuellen Fortschrittes oder zur Protokollausgabe der laufenden Importaktion nutzlich. ExportTar()/ExportTarEx() und ExportRaw()/ExportRaw() implementieren die umgekehrte Aktion und konnen 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 geoffneten) 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<<, abhangig vom benotigten 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 konnen. Diese Einschrankung konnte irgendwann aufgehoben werden. Die Methode liefert einen Ubertragungs-Kennzeichner und einen Objektpfad zum Abbruch oder zum Nachverfolgen der Export-Aktion, ahnlich wie bei den oben beschriebenen ImportTar()/ImportTarEx() oder ImportRaw()/ImportRawEx(). ExportTarEx()/ExportRawEx() erwarten die Abbildklasse als zusatzlichen Parameter, sowie einen 64-bit-Schalterparameter, der derzeit als Null festgelegt sein muss. PullTar()/PullTarEx() und PullRaw()/PullRawEx() konnen zum herunterladen, uberprufen 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 moglicherweise mit gzip(1), bzip2(1) oder xz(1) komprimiert ist. Das zweite Argument ist ein lokaler Name fur das Abbild. Es sollte als Rechnername, ahnlich wie bei dem entsprechenden Argument wie bei den oben beschriebenen Methoden ImportTar()/ImportTarEx() und ImportRaw()/ImportRawEx() geeignet sein. Das dritte Argument kennzeichnet die Uberprufungsmethode fur das Abbild. Es kann entweder >>no<<, >>checksum<< oder >>signature<< sein. >>no<< schaltet jede Art von Uberprufung des Abbildes aus; >>checksum<< sucht nach einer SHA256SUM-Datei neben dem heruntergeladenen Abbild und uberpruft 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 moglicherweise 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 schreibgeschutzt markiert werden soll und Bit 2 ist ein >>keep_download<<-Schalter, der kennzeichnet, ob eine unverfalschte, schreibgeschutzte Kopie des heruntergeladenen Abbildes zusatzlich 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 Ubertragungskennzeichner und Objektpfad fur die laufende Herunterladungen zuruck. ImportFileSystem()/ImportFileSystemEx() sind ahnlich zu ImportTar()/ImportTarEx(), importieren aber ein Verzeichnisbaum. Das erste Argument muss sich auf ein Verzeichnisdateideskriptor fur 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, zuruck. Sie liefern ein Feld von Strukturen zuruck, das aus dem numerischen Ubertragungskennzeichner, 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 (fur 0%) und 1.0 (fur 100%) sowie den Ubertragungsobjektpfad besteht. CancelTransfer() kann zum Abbruch einer laufenden Import-, Export- oder Herunterladeaktion verwandt werden. Es reicht die einfache Angabe des Ubertragungskennzeichners, um die laufende Aktion abzubrechen. ListImages() liefert eine Liste der derzeit installierten Abbilder zuruck. 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 Eintragen, 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 Veranderungszeiten (in Mikrosekunden seit der UNIX-Epoch) sowie der derzeitige Plattenverbrauch in Byte (sowohl gesamt als auch exklusiv), sowie alle Grossenbegrenzungen in Byte, die fur das Abbild gesetzt sind (sowohl gesamt als auch exklusiv). Signale Das Signal TransferNew() wird fur jedes Auftreten des Starts einer neuen Ubertragung mit den oben beschriebenen Import-, Export oder Herunterlade-Aufrufen erstellt. Es transportiert den frisch erstellten Ubertragungskennzeichner und Objektpfad. Das Signal TransferRemoved() wird fur jedes Auftreten des Beendens, Abbruchs oder Fehlschlags einer Ubertragung gesandt. Es transportiert auch den Ubertragungskennzeichner 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 Ubertragung verwandt werden. Sie akzeptiert keine Parameter. Diese Methode ist ziemlich ahnlich der Methode CancelTransfer() auf der Manager-Schnittstelle (siehe oben), wird aber auf dem Transfer-Objekt selbst offengelegt, anstatt eine Ubertragungskennzeichnung zu akzeptieren. Eigenschaften Die Eigenschaft Id legt die numerische Ubertragungskennzeichnung des Transfer-Objekts offen. Die Eigenschaften Local, Remote und Type legen den lokalen Container-Namen dieser Ubertragung 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 fur eine Erklarung der moglichen Werte). Die Eigenschaft Verify legt die ausgewahlte Uberprufungseinstellung offen und ist nur fur die Herunterladeaktionen definiert (siehe oben). Die Eingenschaft Progress legt den aktuellen Fortschritt der Ubertragung als Wert zwischen 0.0 und 1.0 offen. Um einen Fortschrittsbalken auf dem Bildschirm darzustellen, wird die Abfrage des Wertes in regelmassigen Abstanden empfohlen, beispielsweise alle 500 ms oder so. Signale Das Signal LogMessage() wird fur Protokollmeldungen ausgesandt, die durch eine Ubertragung erstellt werden. Es transportiert ein Paar aus Syslog-Protokollstufen-Ganzzahl und Protokoll-Zeichenkette. Das Signal ProgressUpdate() wird in regelmassigen Abstanden ausgesandt, wenn neue Herunterlade-Fortschrittsinformationen fur eine Ubertragung verfugbar sind. Es transportiert eine doppelt-genaue Fliesskommazahl zwischen 0.0 und 1.0, die den Ubertragungsfortschritt 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 hinzugefugt. Ubertragungsobjekte ProgressUpdate() wurde in Version 256 hinzugefugt. SIEHE AUCH systemd(1), systemd-importd.service(8), importctl(1) ANMERKUNGEN 1. die normalen Schnittstellenversionierungsrichtlinien https://0pointer.de/blog/projects/versioning-dbus.html UBERSETZUNG Die deutsche Ubersetzung dieser Handbuchseite wurde von Helge Kreutzmann erstellt. Diese Ubersetzung ist Freie Dokumentation; lesen Sie die GNU General Public License Version 3 oder neuer bezuglich der Copyright-Bedingungen. Es wird KEINE HAFTUNG ubernommen. Wenn Sie Fehler in der Ubersetzung dieser Handbuchseite finden, schicken Sie bitte eine E-Mail an die Mailingliste der Ubersetzer . systemd 257 ORG.FREEDESKTOP.IMPORT1(5)