This page has been obsoleted and replaced: https://www.freedesktop.org/software/systemd/man/org.freedesktop.import1.html.
importd
systemd 219 and newer include the systemd-importd service which may be used to import, export and download additional system images, for running them as local containers using tools such as systemd-nspawn. The service is used as backend for machinectl pull-raw and machinectl pull-tar and related commands.
Note that systemd-importd is mostly a small companion service for systemd-machined. Many operations to manipulate local container and VM images are hence available via the systemd-machined bus API instead.
See systemd-importd(8).service for more information.
The Manager Object
The service exposes the following interfaces on the Manager object on the bus:
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);
ImportRaw(in h fd,
in s local_name,
in b force,
in b read_only,
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);
ExportRaw(in s local_name,
in h fd,
in s format,
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);
PullRaw(in s url,
in s local_name,
in s verify_mode,
in b force,
out u transfer_id,
out o transfer_path);
ListTransfers(out a(usssdo) list);
CancelTransfer(in u transfer_id);
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 {
};
};
Methods
ImportTar() and ImportRaw() import a system image and place it into /var/lib/machines/. The first argument should be a file descriptor (opened for reading) referring to the tar or raw file to import. It should reference either a file on disk or a pipe/socket. When ImportTar() is used the file descriptor should refer to a tar file, optionally compressed with gzip, bzip2 or xz. systemd-importd will detect the used compression scheme (or whether any is used at all) automatically. When ImportRaw() is used the file descriptor should refer to a raw or qcow2 disk image containing an MBR or GPT disk label, also optionally compressed with gzip, bzip2 or xz. In either case, if the file is specified as file descriptor on disk, progress information is generated for the import operation (since the size on disk is known then), if a socket or pipe is specified this is not available. The file descriptor argument is followed by a local name for the image. This should be a name suitable as a hostname and will be used to name the imported image below /var/lib/machines. A tar import is placed as directory tree or btrfs subvolume below /var/lib/machines/, under the name specified with no suffix appended. A raw import is placed as file in /var/lib/machines/ with the .raw suffix appended. The force argument controls whether any pre-existing image with the same name shall be removed for the operation. If true, it is removed, if false the operation fails on a name conflict. Finally, the read_only argument controls whether to create a writable or read-only image. The two calls return immediately after invocation, with the import transfer ongoing. They return a pair of transfer identifier and object path, which may be used to retrieve progress information about the transfer, or cancel it. The transfer identifier is a simple numeric identifier, the object path references an org.freedesktop.import1.Transfer object, see below. Listen for a TransferRemoved signal for the transfer ID it order to detect when a transfer is complete. The returned transfer object is useful to determine the current progress or log output of the ongoing import operation.
ExportTar() and ExportRaw() implement the reverse operation, and may be used to export a system image in order to place it in a tar or raw image. They take the machine name to export as first parameter, followed by a file descriptor (opened for writing) where the tar or raw file will be written. It may either reference a file on disk or a pipe/socket. The third argument specifies in which compression format to write the image. It takes one of uncompressed, xz, bzip2 or gzip, depending on which compression scheme is required. The image written to the specified file descriptor will be a tar file in case of ExportTar() or a raw disk image in case of ExportRaw(). Note that currently raw disk images may not be exported as tar files, and vice versa, however this restriction might be lifted eventually. The call returns a transfer identifier and object path for cancelling or tracking the export operation, similar to ImportTar() or ImportRaw() described above.
PullTar() and PullRaw() may be used to download, verify and import a system image from a web site. They take an URL argument, that should reference a tar or raw file on the http:// or https:// protocols, possibly compressed with xz, bzip2 or gzip. The second argument is a local name for the image. It should be suitable as hostname, similar to the matching argument of the ImportTar() and ImportRaw() calls above. The third argument indicates the verification mode for the image. It may be one of no, checksum, signature. no turns of any kind of verification of the image; checksum looks for a SHA256SUM file next to the downloaded image, and verifies any SHA256 hash value in that file again the image; signature does the same but also tries to authenticate the SHA256SUM file via gpg first. The last argument indicates whether to replace a possibly pre-existing image with the same local name (if true), or whether to fail (if false). Like the import and export calls above these calls return a pair of transfer identifier and object path for the ongoing download.
ListTransfers() returns a list of ongoing import, export or download operations, as created with the six calls described above. It returns an array of structures, which consist of the numeric transfer identifier, a string indicating the operation (one of import-tar, import-raw, export-tar, export-raw, pull-tar or pull-raw), a string describing the remote file (in case of download operations this is the source URL, in case of import/export operations this is a short string describing the file descriptor passed in), a string with the local machine image name, a progress value between 0.0 (for 0%) and 1.0 (for 100%), as well as the transfer object path.
CancelTransfer() may be used to cancel an ongoing import, export or download operation. Simply specify the transfer identifier to cancel.
Signals
The TransferNew signal is generated each time a new transfer is added with the import, export or download calls described above. It carries the transfer ID and object path just created.
The TransferRemoved signal is sent each time a transfer was completed, cancelled or failed. It also carries the transfer ID and object path, followed by a string indicating the result of the operation, which is one of done (on success), canceled or failed.
The Transfer Object
Each ongoing transfer is exposed on the bus via an org.freedesktop.import1.Transfer object. The object path to the transfer is returned by the various calls that create an import, export or download operation (see above), as well as by ListTransfer(). It is also included in the TransferNew and TransferRemoved signals that notify clients about added or removed transfers.
node /org/freedesktop/import1/transfer/_1 {
interface org.freedesktop.import1.Transfer {
methods:
Cancel();
signals:
LogMessage(u priority,
s line);
properties:
readonly u Id = 1;
readonly s Local = 'xenial-server-cloudimg-amd64-root';
readonly s Remote = 'https://cloud-images.ubuntu.com/xenial/current/xenial-server-cloudimg-amd64-root.tar.gz';
readonly s Type = 'pull-tar';
readonly s Verify = 'signature';
readonly d Progress = 0.253;
};
interface org.freedesktop.DBus.Peer {
};
interface org.freedesktop.DBus.Introspectable {
};
interface org.freedesktop.DBus.Properties {
};
};
Methods
The Cancel() method may be used to cancel the transfer. It takes no parameters. This call is pretty much equivalent to the CancelTransfer() call on the Manager interface (see above), but is exposed on the Transfer object itself instead of taking a transfer ID.
Signals
The LogMessage signal is sent from each transfer object for each log message generated by the transfer operation. It contains a syslog-compatible log priority level (i.e. LOG_DEBUG, LOG_INFO, LOG_NOTICE, LOG_ERR, as defined in syslog.h) as well as the log line. Use this signal in UIs to display status information about individual transfers. In order to determine why a transfer failed it's a good idea to look for log messages with high priority levels (such as LOG_ERR and above).
Properties
The Id property exposes the numeric transfer ID of the transfer object.
The Local, Remote, Type properties expose the local container name of this transfer, the remote source (in case of download: the URL, in case of import/export a string describing the file descriptor passed in), and the type of operation (see the Manager's ListTransfer() call above for an explanation of the possible values).
The Verify property exposes the selected verification setting, and is only defined for download operations (see above).
The Progress property exposes the current progress of the transfer, as a value between 0.0 and 1.0. To show a progress bar on screen it recommend to query this value in regular intervals, for example every 500ms or so.