Provided by: systemd-container_256.5-2ubuntu3_amd64 bug

NAME

       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 disk 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 importctl pull-raw, importctl
       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);
                 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 { ... };
           };

   Methods
       ImportTar()/ImportTarEx() and ImportRaw()/ImportRawEx() import a disk image and place it
       into the image directory. 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()/ImportTarEx() 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()/ImportRawEx() 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 the image directory under the specified name with no suffix appended. A raw import
       is placed as a file in the image directory with the .raw suffix appended. In case of
       ImportTar()/ImportRaw(), 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. The read_only argument controls whether to create
       a writable or read-only image. In case of ImportTarEx()/ImportRawEx() these boolean flags
       are provided via a 64bit flags parameter instead, with bit 0 mapping to the force
       parameter, and bit 1 mapping to read_only. The class parameter specifies the image class,
       and takes one of "machine", "portable", "sysext", "confext". All four 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()/ExportTarEx() and ExportRaw()/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()/ExportTarEx() or a raw disk image in case of
       ExportRaw()/ExportRawEx(). 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,
       similarly to ImportTar()/ImportTarEx() or ImportRaw()/ImportRawEx() as described above.
       ExportTarEx()/ExportRawEx() expect the image class as additional parameter, as well as a
       64bit flags parameter that currently must be specified as zero.

       PullTar()/PullTarEx() and PullRaw()/PullRawEx() may be used to download, verify and import
       a system image from a URL. They take a 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,
       similarly to the matching argument of the ImportTar()/ImportTarEx() and
       ImportRaw()/ImportRawEx() 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. In case of PullTar()/PullRaw() 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"). In case of PullTarEx()/PullRawEx() the last argument is a 64bit flags parameter,
       where bit 0 controls the "force" flag, bit 1 is a "read_only" flag that controls whether
       the created image shall be marked read-only, and bit 2 is a "keep_download" flag that
       indicates whether a pristine, read-only copy of the downloaded image shell be kept, in
       addition for the local copy of the image. The ..._Ex() variants also expect an image class
       string (as above). Like the import and export calls above, these calls return a pair of
       transfer identifier and object path for the ongoing download.

       ImportFileSystem()/ImportFileSystemEx() are similar to ImportTar()/ImportTarEx() but
       import a directory tree. The first argument must refer to a directory file descriptor for
       the source hierarchy to import.

       ListTransfers()/ListTransfersEx() return a list of ongoing import, export or download
       operations as created with the six calls described above. They return 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, the image class
       (only in case of ListTransfersEx(); one of "machine", "portable", "sysext", "confext"), 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.

       ListImages() returns a list of currently installed images. It takes a image class string
       and a flags parameter. The image class is either the empty string or specifies one of the
       four image classes, by which it will then filter. The flags parameter must be zero at this
       time. It returns an array of items, each describing one image. The item fields are in
       order: the image class, the local image name, the image type, the image path, the
       read-only flag, the creation and modification times (in microseconds since the UNIX
       epoch), as well as the current disk usage in bytes (both overall, and exclusive), as well
       as any size limit in bytes set on the image (both overall and exclusive).

   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);
                 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 { ... };
           };

   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.

   Signals
       The LogMessage() signal is emitted for log messages generated by a transfer. It carries a
       pair of syslog log level integer and log string.

       The ProgressUpdate() signal is emitted in regular intervals when new download progress
       information is available for a transfer. It carries a double precision floating pointer
       number between 0.0 and 1.0 indicating the transfer progress.

EXAMPLES

       Example 1. Introspect org.freedesktop.import1.Manager on the bus

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

       Example 2. 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[1].

HISTORY

   The Manager Object
       ImportTarEx(), ImportRawEx(), ImportFileSystemEx(), ExportTarEx(), ExportRawEx(),
       PullTarEx(), PullRawEx(), ListTransfersEx(), ListImages() were added in version 256.

   Transfer Objects
       ProgressUpdate() was added in version 256.

NOTES

        1. the usual interface versioning guidelines
           https://0pointer.de/blog/projects/versioning-dbus.html