Methoden¶

ImportTar() und ImportRaw() importieren ein Systemabbild und legen es in /var/lib/machines/ ab. Das erste Argument sollte ein Dateideskripter (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() 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() 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 von /var/lib/machines/ unter dem festgelegten Namen ohne zusätzliche Erweiterung abgelegt. Ein roher Import wird als eine Datei in /var/lib/machines/ mit angehängter Endung .raw abgelegt. 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 schließlich, ob ein schreibbares oder schreibgeschütztes Abbild erstellt wird. Beide 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() und 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() eine Tar-Datei oder im Falle von ExportRaw() 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() oder ImportRaw().

PullTar() und PullRaw() 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() und ImportRaw() 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. Das letzte Argument kennzeichnet, ob ein möglicherweise bereits existierendes Abbild mit dem gleichen lokalen Namen ersetzt wird (falls »true«) oder ob ein Fehlschlag erfolgt (falls »false«). Wie die oben beschriebenen Import- und Exportaufrufe liefern diese Aufrufe ein Paar an Übertragungskennzeichner und Objektpfad für die laufenden Herunterladungen zurück.

ListTransfers() liefert eine Liste der laufenden Importe, Exporte oder Herunterlade-Aktionen, wie sie mit den sechs oben beschriebenen Aufrufen erstellt werden, zurück. Sie liefert 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, 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.

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

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