Adding upstream version 4.22.0.upstream/4.22.0

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 347 insertions, 0 deletions

diff --git a/upstream/opensuse-leap-15-6/man5/org.freedesktop.import1.5 b/upstream/opensuse-leap-15-6/man5/org.freedesktop.import1.5
new file mode 100644
index 00000000..ec7b2da9
--- /dev/null
+++ b/upstream/opensuse-leap-15-6/man5/org.freedesktop.import1.5
@@ -0,0 +1,347 @@
+'\" t
+.TH "ORG\&.FREEDESKTOP\&.IMPORT1" "5" "" "systemd 254" "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