org.freedesktop.import1

systemd
org.freedesktop.import1 5
org.freedesktop.import1 The D-Bus interface of systemd-importd

## Introduction

systemd-importd.service 8 is a system service which may be used to import, export and download additional system images. These images can be used by tools such as systemd-nspawn 1 to run local containers. The service is used as the backend for `machinectl pull-raw`, `machinectl pull-tar` and related commands. This page describes the D-Bus interface.

Note that systemd-importd.service 8 is mostly a small companion service for systemd-machined.service 8. Many operations to manipulate local container and VM images are hence available via the `systemd-machined` D-Bus API, c.f. org.freedesktop.machine1 5.

## 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);
          ImportFileSystem(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) transfers);
          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 a file on disk, a pipe or a socket. When `ImportTar()` is used the file descriptor should refer to a tar file, optionally compressed with gzip 1, bzip2 1, or xz 1. `systemd-importd` will detect the used compression scheme (if any) 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 a file descriptor on disk, progress information is generated for the import operation (as in that case we know the total size on disk). If a socket or pipe is specified, progress information 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 a directory tree or a btrfs 8 subvolume below `/var/lib/machines/` under the specified name with no suffix appended. A raw import is placed as a file in `/var/lib/machines/` with the `.raw` suffix appended. If the `force` argument is true, any pre-existing image with the same name is removed before starting the operation. Otherwise, the operation fails if an image with the same name already exists. Finally, the `read_only` argument controls whether to create a writable or read-only image. Both methods return immediately after starting the import, 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 to 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 in 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 their 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. This restriction might be lifted eventually. The method returns a transfer identifier and object path for cancelling or tracking the export operation, similar to `ImportTar()` or `ImportRaw()` as described above.

`PullTar()` and `PullRaw()` may be used to download, verify and import a system image from a URL. They take an URL argument which should point to 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 a hostname, similar to the matching argument of the `ImportTar()` and `ImportRaw()` methods above. The third argument indicates the verification mode for the image. It may be one of `no`, `checksum`, `signature`. `no` turns off 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 against the image; `signature` does the same but also tries to authenticate the `SHA256SUM` file via gpg 8 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 the ongoing operation.

### Signals

The `TransferNew` signal is generated each time a new transfer is started with the import, export or download calls described above. It carries the transfer ID and object path that have just been created.

The `TransferRemoved` signal is sent each time a transfer finishes, is canceled or fails. 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

    node /org/freedesktop/import1/transfer/_1 {
      interface org.freedesktop.import1.Transfer {
        methods:
          Cancel();
        signals:
          LogMessage(u priority,
                     s line);
        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 { ... };
    };

### Methods

The `Cancel()` method may be used to cancel the transfer. It takes no parameters. This method is pretty much equivalent to the `CancelTransfer()` method on the Manager interface (see above), but is exposed on the Transfer object itself instead of taking a transfer ID.

### Properties

The `Id` property exposes the numeric transfer ID of the transfer object.

The `Local`, `Remote` and `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()` method 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 we recommend to query this value in regular intervals, for example every 500 ms or so.

## Examples

Introspect org.freedesktop.import1.Manager on the bus

    $ gdbus introspect --system \
      --dest org.freedesktop.import1 \
      --object-path /org/freedesktop/import1

Introspect org.freedesktop.import1.Transfer on the bus

    $ gdbus introspect --system \
      --dest org.freedesktop.import1 \
      --object-path /org/freedesktop/import1/transfer/_1

## Versioning

These D-Bus interfaces follow the usual interface versioning guidelines.