org.freedesktop.import1(5) — Linux manual page

NAME | INTRODUCTION | THE MANAGER OBJECT | THE TRANSFER OBJECT | EXAMPLES | VERSIONING | NOTES | COLOPHON

ORG.FREEDESKTOP.IMPORT1(5) org.freedesktop.import1ORG.FREEDESKTOP.IMPORT1(5)

NAME         top

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

INTRODUCTION         top

       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         top

       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         top

           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         top

       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         top

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

NOTES         top

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

COLOPHON         top

       This page is part of the systemd (systemd system and service manager)
       project.  Information about the project can be found at 
       ⟨http://www.freedesktop.org/wiki/Software/systemd⟩.  If you have a bug
       report for this manual page, see
       ⟨http://www.freedesktop.org/wiki/Software/systemd/#bugreports⟩.  This
       page was obtained from the project's upstream Git repository
       ⟨https://github.com/systemd/systemd.git⟩ on 2020-11-01.  (At that
       time, the date of the most recent commit that was found in the repos‐
       itory was 2020-11-01.)  If you discover any rendering problems in
       this HTML version of the page, or you believe there is a better or
       more up-to-date source for the page, or you have corrections or im‐
       provements to the information in this COLOPHON (which is not part of
       the original manual page), send a mail to man-pages@man7.org

systemd 247                                       ORG.FREEDESKTOP.IMPORT1(5)

Pages that refer to this page: 30-systemd-environment-d-generator(7)systemd.directives(7)systemd.index(7)systemd-importd(8)systemd-importd.service(8)