# org.freedesktop.import1

## 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), **zstd**(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, zstd,
           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", "gzip"
           or "zstd", 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, gzip or zstd. 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].


## NOTES



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


* * *