path: root/upstream/fedora-rawhide/man5/org.freedesktop.import1.5

'\" t
.TH "ORG\&.FREEDESKTOP\&.IMPORT1" "5" "" "systemd 255" "org.freedesktop.import1"
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
org.freedesktop.import1 \- The D\-Bus interface of systemd\-importd
.SH "INTRODUCTION"
.PP
\fBsystemd-importd.service\fR(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
\fBsystemd-nspawn\fR(1)
to run local containers\&. The service is used as the backend for
\fBmachinectl pull\-raw\fR,
\fBmachinectl pull\-tar\fR
and related commands\&. This page describes the D\-Bus interface\&.
.PP
Note that
\fBsystemd-importd.service\fR(8)
is mostly a small companion service for
\fBsystemd-machined.service\fR(8)\&. Many operations to manipulate local container and VM images are hence available via the
\fBsystemd\-machined\fR
D\-Bus API, c\&.f\&.
\fBorg.freedesktop.machine1\fR(5)\&.
.SH "THE MANAGER OBJECT"
.PP
The service exposes the following interfaces on the Manager object on the bus:
.sp
.if n \{\
.RS 4
.\}
.nf
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 { \&.\&.\&. };
};
    
.fi
.if n \{\
.RE
.\}












.SS "Methods"
.PP
\fBImportTar()\fR
and
\fBImportRaw()\fR
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
\fBImportTar()\fR
is used the file descriptor should refer to a tar file, optionally compressed with
\fBgzip\fR(1),
\fBbzip2\fR(1), or
\fBxz\fR(1)\&.
\fBsystemd\-importd\fR
will detect the used compression scheme (if any) automatically\&. When
\fBImportRaw()\fR
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
\fBbtrfs\fR(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
\fBforce\fR
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
\fBread_only\fR
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
\fBTransferRemoved\fR
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\&.
.PP
\fBExportTar()\fR
and
\fBExportRaw()\fR
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
\fBExportTar()\fR
or a raw disk image in case of
\fBExportRaw()\fR\&. 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
\fBImportTar()\fR
or
\fBImportRaw()\fR
as described above\&.
.PP
\fBPullTar()\fR
and
\fBPullRaw()\fR
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
\fBImportTar()\fR
and
\fBImportRaw()\fR
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
\fBgpg\fR(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\&.
.PP
\fBListTransfers()\fR
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\&.
.PP
\fBCancelTransfer()\fR
may be used to cancel an ongoing import, export or download operation\&. Simply specify the transfer identifier to cancel the ongoing operation\&.
.SS "Signals"
.PP
The
\fBTransferNew\fR
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\&.
.PP
The
\fBTransferRemoved\fR
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"\&.
.SH "THE TRANSFER OBJECT"
.sp
.if n \{\
.RS 4
.\}
.nf
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 = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s Remote = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s Type = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
      readonly s Verify = \*(Aq\&.\&.\&.\*(Aq;
      @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
      readonly d Progress = \&.\&.\&.;
  };
  interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
  interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
  interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
};
    
.fi
.if n \{\
.RE
.\}









.SS "Methods"
.PP
The
\fBCancel()\fR
method may be used to cancel the transfer\&. It takes no parameters\&. This method is pretty much equivalent to the
\fBCancelTransfer()\fR
method on the
Manager
interface (see above), but is exposed on the
Transfer
object itself instead of taking a transfer ID\&.
.SS "Properties"
.PP
The
\fIId\fR
property exposes the numeric transfer ID of the transfer object\&.
.PP
The
\fILocal\fR,
\fIRemote\fR
and
\fIType\fR
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\*(Aqs
\fBListTransfer()\fR
method above for an explanation of the possible values)\&.
.PP
The
\fIVerify\fR
property exposes the selected verification setting and is only defined for download operations (see above)\&.
.PP
The
\fIProgress\fR
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\&.
.SH "EXAMPLES"
.PP
\fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.import1\&.Manager on the bus\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ gdbus introspect \-\-system \e
  \-\-dest org\&.freedesktop\&.import1 \e
  \-\-object\-path /org/freedesktop/import1
      
.fi
.if n \{\
.RE
.\}
.PP
\fBExample\ \&2.\ \&Introspect org\&.freedesktop\&.import1\&.Transfer on the bus\fR
.sp
.if n \{\
.RS 4
.\}
.nf
$ gdbus introspect \-\-system \e
  \-\-dest org\&.freedesktop\&.import1 \e
  \-\-object\-path /org/freedesktop/import1/transfer/_1
      
.fi
.if n \{\
.RE
.\}
.SH "VERSIONING"
.PP
These D\-Bus interfaces follow
\m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[1]\d\s+2\&.
.SH "NOTES"
.IP " 1." 4
the usual interface versioning guidelines
.RS 4
\%https://0pointer.de/blog/projects/versioning-dbus.html
.RE