Debian Codegraph @

upstream/debian-unstable/man5/org.freedesktop.import1.5

raw
1 '\" t
2 .TH "ORG\&.FREEDESKTOP\&.IMPORT1" "5" "" "systemd 261~rc3" "org.freedesktop.import1"
3 .\" -----------------------------------------------------------------
4 .\" * Define some portability stuff
5 .\" -----------------------------------------------------------------
6 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
7 .\" http://bugs.debian.org/507673
8 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
9 .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
10 .ie \n(.g .ds Aq \(aq
11 .el .ds Aq '
12 .\" -----------------------------------------------------------------
13 .\" * set default formatting
14 .\" -----------------------------------------------------------------
15 .\" disable hyphenation
16 .nh
17 .\" disable justification (adjust text to left margin only)
18 .ad l
19 .\" -----------------------------------------------------------------
20 .\" * MAIN CONTENT STARTS HERE *
21 .\" -----------------------------------------------------------------
22 .SH "NAME"
23 org.freedesktop.import1 \- The D\-Bus interface of systemd\-importd
24 .SH "INTRODUCTION"
25 .PP
26 \fBsystemd-importd.service\fR(8)
27 is a system service which may be used to import, export and download disk images\&. These images can be used by tools such as
28 \fBsystemd-nspawn\fR(1)
29 to run local containers\&. The service is used as the backend for
30 \fBimportctl pull\-raw\fR,
31 \fBimportctl pull\-tar\fR
32 and related commands\&. This page describes the D\-Bus interface\&.
33 .PP
34 Note that
35 \fBsystemd-importd.service\fR(8)
36 is mostly a small companion service for
37 \fBsystemd-machined.service\fR(8)\&. Many operations to manipulate local container and VM images are hence available via the
38 \fBsystemd\-machined\fR
39 D\-Bus API, c\&.f\&.
40 \fBorg.freedesktop.machine1\fR(5)\&.
41 .SH "THE MANAGER OBJECT"
42 .PP
43 The service exposes the following interfaces on the Manager object on the bus:
44 .sp
45 .if n \{\
46 .RS 4
47 .\}
48 .nf
49 node /org/freedesktop/import1 {
50 interface org\&.freedesktop\&.import1\&.Manager {
51 methods:
52 ImportTar(in h fd,
53 in s local_name,
54 in b force,
55 in b read_only,
56 out u transfer_id,
57 out o transfer_path);
58 ImportTarEx(in h fd,
59 in s local_name,
60 in s class,
61 in t flags,
62 out u transfer_id,
63 out o transfer_path);
64 ImportRaw(in h fd,
65 in s local_name,
66 in b force,
67 in b read_only,
68 out u transfer_id,
69 out o transfer_path);
70 ImportRawEx(in h fd,
71 in s local_name,
72 in s class,
73 in t flags,
74 out u transfer_id,
75 out o transfer_path);
76 ImportFileSystem(in h fd,
77 in s local_name,
78 in b force,
79 in b read_only,
80 out u transfer_id,
81 out o transfer_path);
82 ImportFileSystemEx(in h fd,
83 in s local_name,
84 in s class,
85 in t flags,
86 out u transfer_id,
87 out o transfer_path);
88 ExportTar(in s local_name,
89 in h fd,
90 in s format,
91 out u transfer_id,
92 out o transfer_path);
93 ExportTarEx(in s local_name,
94 in s class,
95 in h fd,
96 in s format,
97 in t flags,
98 out u transfer_id,
99 out o transfer_path);
100 ExportRaw(in s local_name,
101 in h fd,
102 in s format,
103 out u transfer_id,
104 out o transfer_path);
105 ExportRawEx(in s local_name,
106 in s class,
107 in h fd,
108 in s format,
109 in t flags,
110 out u transfer_id,
111 out o transfer_path);
112 PullTar(in s url,
113 in s local_name,
114 in s verify_mode,
115 in b force,
116 out u transfer_id,
117 out o transfer_path);
118 PullTarEx(in s url,
119 in s local_name,
120 in s class,
121 in s verify_mode,
122 in t flags,
123 out u transfer_id,
124 out o transfer_path);
125 PullRaw(in s url,
126 in s local_name,
127 in s verify_mode,
128 in b force,
129 out u transfer_id,
130 out o transfer_path);
131 PullRawEx(in s url,
132 in s local_name,
133 in s class,
134 in s verify_mode,
135 in t flags,
136 out u transfer_id,
137 out o transfer_path);
138 PullOci(in s ref,
139 in s local_name,
140 in s class,
141 in t flags,
142 out u transfer_id,
143 out o transfer_path);
144 ListTransfers(out a(usssdo) transfers);
145 ListTransfersEx(in s class,
146 in t flags,
147 out a(ussssdo) transfers);
148 CancelTransfer(in u transfer_id);
149 ListImages(in s class,
150 in t flags,
151 out a(ssssbtttttt) images);
152 signals:
153 TransferNew(u transfer_id,
154 o transfer_path);
155 TransferRemoved(u transfer_id,
156 o transfer_path,
157 s result);
158 };
159 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
160 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
161 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
162 };
163 .fi
164 .if n \{\
165 .RE
166 .\}
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189 .SS "Methods"
190 .PP
191 \fBImportTar()\fR/\fBImportTarEx()\fR
192 and
193 \fBImportRaw()\fR/\fBImportRawEx()\fR
194 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
195 \fBImportTar()\fR/\fBImportTarEx()\fR
196 is used the file descriptor should refer to a tar file, optionally compressed with
197 \fBgzip\fR(1),
198 \fBzstd\fR(1),
199 \fBbzip2\fR(1), or
200 \fBxz\fR(1)\&.
201 \fBsystemd\-importd\fR
202 will detect the used compression scheme (if any) automatically\&. When
203 \fBImportRaw()\fR/\fBImportRawEx()\fR
204 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
205 /var/lib/machines/\&. A tar import is placed as a directory tree or a
206 \fBbtrfs\fR(8)
207 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
208 \&.raw
209 suffix appended\&. In case of
210 \fBImportTar()\fR/\fBImportRaw()\fR, if the
211 \fBforce\fR
212 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
213 \fBread_only\fR
214 argument controls whether to create a writable or read\-only image\&. In case of
215 \fBImportTarEx()\fR/\fBImportRawEx()\fR
216 these boolean flags are provided via a 64bit flags parameter instead, with bit 0 mapping to the
217 \fBforce\fR
218 parameter, and bit 1 mapping to
219 \fBread_only\fR\&. The
220 \fBclass\fR
221 parameter specifies the image class, and takes one of
222 "machine",
223 "portable",
224 "sysext",
225 "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
226 org\&.freedesktop\&.import1\&.Transfer
227 object, see below\&. Listen for a
228 \fBTransferRemoved()\fR
229 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\&.
230 .PP
231 \fBExportTar()\fR/\fBExportTarEx()\fR
232 and
233 \fBExportRaw()\fR/\fBExportRaw()\fR
234 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
235 "uncompressed",
236 "xz",
237 "bzip2",
238 "gzip"
239 or
240 "zstd", depending on which compression scheme is required\&. The image written to the specified file descriptor will be a tar file in case of
241 \fBExportTar()\fR/\fBExportTarEx()\fR
242 or a raw disk image in case of
243 \fBExportRaw()\fR/\fBExportRawEx()\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
244 \fBImportTar()\fR/\fBImportTarEx()\fR
245 or
246 \fBImportRaw()\fR/\fBImportRawEx()\fR
247 as described above\&.
248 \fBExportTarEx()\fR/\fBExportRawEx()\fR
249 expect the image class as additional parameter, as well as a 64bit flags parameter that currently must be specified as zero\&.
250 .PP
251 \fBPullTar()\fR/\fBPullTarEx()\fR
252 and
253 \fBPullRaw()\fR/\fBPullRawEx()\fR
254 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
255 "http://"
256 or
257 "https://"
258 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
259 \fBImportTar()\fR/\fBImportTarEx()\fR
260 and
261 \fBImportRaw()\fR/\fBImportRawEx()\fR
262 methods above\&. The third argument indicates the verification mode for the image\&. It may be one of
263 "no",
264 "checksum",
265 "signature"\&.
266 "no"
267 turns off any kind of verification of the image;
268 "checksum"
269 looks for a
270 SHA256SUM
271 file next to the downloaded image and verifies any SHA256 hash value in that file against the image;
272 "signature"
273 does the same but also tries to authenticate the
274 SHA256SUM
275 file via
276 \fBgpg\fR(8)
277 first\&. In case of
278 \fBPullTar()\fR/\fBPullRaw()\fR
279 the last argument indicates whether to replace a possibly pre\-existing image with the same local name (if
280 "true"), or whether to fail (if
281 "false")\&. In case of
282 \fBPullTarEx()\fR/\fBPullRawEx()\fR
283 the last argument is a 64bit flags parameter, where bit 0 controls the
284 "force"
285 flag, bit 1 is a
286 "read_only"
287 flag that controls whether the created image shall be marked read\-only, and bit 2 is a
288 "keep_download"
289 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
290 \fB\&..._Ex()\fR
291 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\&.
292 .PP
293 \fBPullOci()\fR
294 is similar to
295 \fBPullTarEx()\fR
296 or
297 \fBPullRawEx()\fR
298 and may be used to download and import an OCI container image from an OCI registry\&. It takes an OCI container reference as argument\&. The second argument is a local name for the image (which will be generated as
299 \fBsystemd.mstack\fR(7)
300 directory referencing the OCI layers)\&. It should be suitable as a hostname, similarly to the matching argument of the
301 \fBPullTar()\fR/\fBPullTarEx()\fR
302 and
303 \fBPullRaw()\fR/\fBPullRawEx()\fR
304 methods above\&. The last argument is a 64bit flags parameter, where bit 0 controls the
305 "force"
306 flag, bit 1 is a
307 "read_only"
308 flag that controls whether the created image shall be marked read\-only\&. Like the pull calls above, this call return a pair of transfer identifier and object path for the ongoing download\&.
309 .PP
310 \fBImportFileSystem()\fR/\fBImportFileSystemEx()\fR
311 are similar to
312 \fBImportTar()\fR/\fBImportTarEx()\fR
313 but import a directory tree\&. The first argument must refer to a directory file descriptor for the source hierarchy to import\&.
314 .PP
315 \fBListTransfers()\fR/\fBListTransfersEx()\fR
316 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
317 "import\-tar",
318 "import\-raw",
319 "export\-tar",
320 "export\-raw",
321 "pull\-tar"
322 or
323 "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
324 \fBListTransfersEx()\fR; one of
325 "machine",
326 "portable",
327 "sysext",
328 "confext"), a progress value between 0\&.0 (for 0%) and 1\&.0 (for 100%), as well as the transfer object path\&.
329 .PP
330 \fBCancelTransfer()\fR
331 may be used to cancel an ongoing import, export or download operation\&. Simply specify the transfer identifier to cancel the ongoing operation\&.
332 .PP
333 \fBListImages()\fR
334 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)\&.
335 .SS "Signals"
336 .PP
337 The
338 \fBTransferNew()\fR
339 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\&.
340 .PP
341 The
342 \fBTransferRemoved()\fR
343 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
344 "done"
345 (on success),
346 "canceled"
347 or
348 "failed"\&.
349 .SH "THE TRANSFER OBJECT"
350 .sp
351 .if n \{\
352 .RS 4
353 .\}
354 .nf
355 node /org/freedesktop/import1/transfer/_1 {
356 interface org\&.freedesktop\&.import1\&.Transfer {
357 methods:
358 Cancel();
359 signals:
360 LogMessage(u priority,
361 s line);
362 ProgressUpdate(d progress);
363 properties:
364 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
365 readonly u Id = \&.\&.\&.;
366 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
367 readonly s Local = \*(Aq\&.\&.\&.\*(Aq;
368 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
369 readonly s Remote = \*(Aq\&.\&.\&.\*(Aq;
370 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
371 readonly s Type = \*(Aq\&.\&.\&.\*(Aq;
372 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("const")
373 readonly s Verify = \*(Aq\&.\&.\&.\*(Aq;
374 @org\&.freedesktop\&.DBus\&.Property\&.EmitsChangedSignal("false")
375 readonly d Progress = \&.\&.\&.;
376 };
377 interface org\&.freedesktop\&.DBus\&.Peer { \&.\&.\&. };
378 interface org\&.freedesktop\&.DBus\&.Introspectable { \&.\&.\&. };
379 interface org\&.freedesktop\&.DBus\&.Properties { \&.\&.\&. };
380 };
381 .fi
382 .if n \{\
383 .RE
384 .\}
385
386
387
388
389
390
391
392
393
394
395 .SS "Methods"
396 .PP
397 The
398 \fBCancel()\fR
399 method may be used to cancel the transfer\&. It takes no parameters\&. This method is pretty much equivalent to the
400 \fBCancelTransfer()\fR
401 method on the
402 Manager
403 interface (see above), but is exposed on the
404 Transfer
405 object itself instead of taking a transfer ID\&.
406 .SS "Properties"
407 .PP
408 The
409 \fIId\fR
410 property exposes the numeric transfer ID of the transfer object\&.
411 .PP
412 The
413 \fILocal\fR,
414 \fIRemote\fR
415 and
416 \fIType\fR
417 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
418 \fBListTransfer()\fR
419 method above for an explanation of the possible values)\&.
420 .PP
421 The
422 \fIVerify\fR
423 property exposes the selected verification setting and is only defined for download operations (see above)\&.
424 .PP
425 The
426 \fIProgress\fR
427 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\&.
428 .SS "Signals"
429 .PP
430 The
431 \fBLogMessage()\fR
432 signal is emitted for log messages generated by a transfer\&. It carries a pair of syslog log level integer and log string\&.
433 .PP
434 The
435 \fBProgressUpdate()\fR
436 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\&.
437 .SH "EXAMPLES"
438 .PP
439 \fBExample\ \&1.\ \&Introspect org\&.freedesktop\&.import1\&.Manager on the bus\fR
440 .sp
441 .if n \{\
442 .RS 4
443 .\}
444 .nf
445 $ gdbus introspect \-\-system \e
446 \-\-dest org\&.freedesktop\&.import1 \e
447 \-\-object\-path /org/freedesktop/import1
448 .fi
449 .if n \{\
450 .RE
451 .\}
452 .PP
453 \fBExample\ \&2.\ \&Introspect org\&.freedesktop\&.import1\&.Transfer on the bus\fR
454 .sp
455 .if n \{\
456 .RS 4
457 .\}
458 .nf
459 $ gdbus introspect \-\-system \e
460 \-\-dest org\&.freedesktop\&.import1 \e
461 \-\-object\-path /org/freedesktop/import1/transfer/_1
462 .fi
463 .if n \{\
464 .RE
465 .\}
466 .SH "VERSIONING"
467 .PP
468 These D\-Bus interfaces follow
469 \m[blue]\fBthe usual interface versioning guidelines\fR\m[]\&\s-2\u[1]\d\s+2\&.
470 .SH "HISTORY"
471 .SS "The Manager Object"
472 .PP
473 \fBImportTarEx()\fR,
474 \fBImportRawEx()\fR,
475 \fBImportFileSystemEx()\fR,
476 \fBExportTarEx()\fR,
477 \fBExportRawEx()\fR,
478 \fBPullTarEx()\fR,
479 \fBPullRawEx()\fR,
480 \fBListTransfersEx()\fR,
481 \fBListImages()\fR
482 were added in version 256\&.
483 .PP
484 \fBPullOci()\fR
485 was added in version 260\&.
486 .SS "Transfer Objects"
487 .PP
488 \fBProgressUpdate()\fR
489 was added in version 256\&.
490 .SH "SEE ALSO"
491 .PP
492 \fBsystemd\fR(1), \fBsystemd-importd.service\fR(8), \fBimportctl\fR(1)
493 .SH "NOTES"
494 .IP " 1." 4
495 the usual interface versioning guidelines
496 .RS 4
497 \%https://0pointer.de/blog/projects/versioning-dbus.html
498 .RE