1ORG.FREEDESKTOP.IMPORT1(5)  org.freedesktop.import1 ORG.FREEDESKTOP.IMPORT1(5)
2
3
4

NAME

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

INTRODUCTION

9       systemd-importd.service(8) is a system service which may be used to
10       import, export and download additional system images. These images can
11       be used by tools such as systemd-nspawn(1) to run local containers. The
12       service is used as the backend for machinectl pull-raw, machinectl
13       pull-tar and related commands. This page describes the D-Bus interface.
14
15       Note that systemd-importd.service(8) is mostly a small companion
16       service for systemd-machined.service(8). Many operations to manipulate
17       local container and VM images are hence available via the
18       systemd-machined D-Bus API, c.f.  org.freedesktop.machine1(5).
19

THE MANAGER OBJECT

21       The service exposes the following interfaces on the Manager object on
22       the bus:
23
24           node /org/freedesktop/import1 {
25             interface org.freedesktop.import1.Manager {
26               methods:
27                 ImportTar(in  h fd,
28                           in  s local_name,
29                           in  b force,
30                           in  b read_only,
31                           out u transfer_id,
32                           out o transfer_path);
33                 ImportRaw(in  h fd,
34                           in  s local_name,
35                           in  b force,
36                           in  b read_only,
37                           out u transfer_id,
38                           out o transfer_path);
39                 ImportFileSystem(in  h fd,
40                                  in  s local_name,
41                                  in  b force,
42                                  in  b read_only,
43                                  out u transfer_id,
44                                  out o transfer_path);
45                 ExportTar(in  s local_name,
46                           in  h fd,
47                           in  s format,
48                           out u transfer_id,
49                           out o transfer_path);
50                 ExportRaw(in  s local_name,
51                           in  h fd,
52                           in  s format,
53                           out u transfer_id,
54                           out o transfer_path);
55                 PullTar(in  s url,
56                         in  s local_name,
57                         in  s verify_mode,
58                         in  b force,
59                         out u transfer_id,
60                         out o transfer_path);
61                 PullRaw(in  s url,
62                         in  s local_name,
63                         in  s verify_mode,
64                         in  b force,
65                         out u transfer_id,
66                         out o transfer_path);
67                 ListTransfers(out a(usssdo) transfers);
68                 CancelTransfer(in  u transfer_id);
69               signals:
70                 TransferNew(u transfer_id,
71                             o transfer_path);
72                 TransferRemoved(u transfer_id,
73                                 o transfer_path,
74                                 s result);
75             };
76             interface org.freedesktop.DBus.Peer { ... };
77             interface org.freedesktop.DBus.Introspectable { ... };
78             interface org.freedesktop.DBus.Properties { ... };
79           };
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94   Methods
95       ImportTar() and ImportRaw() import a system image and place it into
96       /var/lib/machines/. The first argument should be a file descriptor
97       (opened for reading) referring to the tar or raw file to import. It
98       should reference a file on disk, a pipe or a socket. When ImportTar()
99       is used the file descriptor should refer to a tar file, optionally
100       compressed with gzip(1), bzip2(1), or xz(1).  systemd-importd will
101       detect the used compression scheme (if any) automatically. When
102       ImportRaw() is used the file descriptor should refer to a raw or qcow2
103       disk image containing an MBR or GPT disk label, also optionally
104       compressed with gzip, bzip2 or xz. In either case, if the file is
105       specified as a file descriptor on disk, progress information is
106       generated for the import operation (as in that case we know the total
107       size on disk). If a socket or pipe is specified, progress information
108       is not available. The file descriptor argument is followed by a local
109       name for the image. This should be a name suitable as a hostname and
110       will be used to name the imported image below /var/lib/machines/. A tar
111       import is placed as a directory tree or a btrfs(8) subvolume below
112       /var/lib/machines/ under the specified name with no suffix appended. A
113       raw import is placed as a file in /var/lib/machines/ with the .raw
114       suffix appended. If the force argument is true, any pre-existing image
115       with the same name is removed before starting the operation. Otherwise,
116       the operation fails if an image with the same name already exists.
117       Finally, the read_only argument controls whether to create a writable
118       or read-only image. Both methods return immediately after starting the
119       import, with the import transfer ongoing. They return a pair of
120       transfer identifier and object path, which may be used to retrieve
121       progress information about the transfer or to cancel it. The transfer
122       identifier is a simple numeric identifier, the object path references
123       an org.freedesktop.import1.Transfer object, see below. Listen for a
124       TransferRemoved signal for the transfer ID in order to detect when a
125       transfer is complete. The returned transfer object is useful to
126       determine the current progress or log output of the ongoing import
127       operation.
128
129       ExportTar() and ExportRaw() implement the reverse operation, and may be
130       used to export a system image in order to place it in a tar or raw
131       image. They take the machine name to export as their first parameter,
132       followed by a file descriptor (opened for writing) where the tar or raw
133       file will be written. It may either reference a file on disk or a
134       pipe/socket. The third argument specifies in which compression format
135       to write the image. It takes one of "uncompressed", "xz", "bzip2" or
136       "gzip", depending on which compression scheme is required. The image
137       written to the specified file descriptor will be a tar file in case of
138       ExportTar() or a raw disk image in case of ExportRaw(). Note that
139       currently raw disk images may not be exported as tar files, and vice
140       versa. This restriction might be lifted eventually. The method returns
141       a transfer identifier and object path for cancelling or tracking the
142       export operation, similarly to ImportTar() or ImportRaw() as described
143       above.
144
145       PullTar() and PullRaw() may be used to download, verify and import a
146       system image from a URL. They take an URL argument which should point
147       to a tar or raw file on the "http://" or "https://" protocols, possibly
148       compressed with xz, bzip2 or gzip. The second argument is a local name
149       for the image. It should be suitable as a hostname, similarly to the
150       matching argument of the ImportTar() and ImportRaw() methods above. The
151       third argument indicates the verification mode for the image. It may be
152       one of "no", "checksum", "signature".  "no" turns off any kind of
153       verification of the image; "checksum" looks for a SHA256SUM file next
154       to the downloaded image and verifies any SHA256 hash value in that file
155       against the image; "signature" does the same but also tries to
156       authenticate the SHA256SUM file via gpg(8) first. The last argument
157       indicates whether to replace a possibly pre-existing image with the
158       same local name (if "true"), or whether to fail (if "false"). Like the
159       import and export calls above, these calls return a pair of transfer
160       identifier and object path for the ongoing download.
161
162       ListTransfers() returns a list of ongoing import, export or download
163       operations as created with the six calls described above. It returns an
164       array of structures which consist of the numeric transfer identifier, a
165       string indicating the operation (one of "import-tar", "import-raw",
166       "export-tar", "export-raw", "pull-tar" or "pull-raw"), a string
167       describing the remote file (in case of download operations this is the
168       source URL, in case of import/export operations this is a short string
169       describing the file descriptor passed in), a string with the local
170       machine image name, a progress value between 0.0 (for 0%) and 1.0 (for
171       100%), as well as the transfer object path.
172
173       CancelTransfer() may be used to cancel an ongoing import, export or
174       download operation. Simply specify the transfer identifier to cancel
175       the ongoing operation.
176
177   Signals
178       The TransferNew signal is generated each time a new transfer is started
179       with the import, export or download calls described above. It carries
180       the transfer ID and object path that have just been created.
181
182       The TransferRemoved signal is sent each time a transfer finishes, is
183       canceled or fails. It also carries the transfer ID and object path,
184       followed by a string indicating the result of the operation, which is
185       one of "done" (on success), "canceled" or "failed".
186

THE TRANSFER OBJECT

188           node /org/freedesktop/import1/transfer/_1 {
189             interface org.freedesktop.import1.Transfer {
190               methods:
191                 Cancel();
192               signals:
193                 LogMessage(u priority,
194                            s line);
195               properties:
196                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
197                 readonly u Id = ...;
198                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
199                 readonly s Local = '...';
200                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
201                 readonly s Remote = '...';
202                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
203                 readonly s Type = '...';
204                 @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
205                 readonly s Verify = '...';
206                 @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
207                 readonly d Progress = ...;
208             };
209             interface org.freedesktop.DBus.Peer { ... };
210             interface org.freedesktop.DBus.Introspectable { ... };
211             interface org.freedesktop.DBus.Properties { ... };
212           };
213
214
215
216
217
218
219
220
221
222
223
224   Methods
225       The Cancel() method may be used to cancel the transfer. It takes no
226       parameters. This method is pretty much equivalent to the
227       CancelTransfer() method on the Manager interface (see above), but is
228       exposed on the Transfer object itself instead of taking a transfer ID.
229
230   Properties
231       The Id property exposes the numeric transfer ID of the transfer object.
232
233       The Local, Remote and Type properties expose the local container name
234       of this transfer, the remote source (in case of download: the URL, in
235       case of import/export: a string describing the file descriptor passed
236       in), and the type of operation (see the Manager's ListTransfer() method
237       above for an explanation of the possible values).
238
239       The Verify property exposes the selected verification setting and is
240       only defined for download operations (see above).
241
242       The Progress property exposes the current progress of the transfer as a
243       value between 0.0 and 1.0. To show a progress bar on screen we
244       recommend to query this value in regular intervals, for example every
245       500 ms or so.
246

EXAMPLES

248       Example 1. Introspect org.freedesktop.import1.Manager on the bus
249
250           $ gdbus introspect --system \
251             --dest org.freedesktop.import1 \
252             --object-path /org/freedesktop/import1
253
254
255       Example 2. Introspect org.freedesktop.import1.Transfer on the bus
256
257           $ gdbus introspect --system \
258             --dest org.freedesktop.import1 \
259             --object-path /org/freedesktop/import1/transfer/_1
260
261

VERSIONING

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

NOTES

267        1. the usual interface versioning guidelines
268           https://0pointer.de/blog/projects/versioning-dbus.html
269
270
271
272systemd 253                                         ORG.FREEDESKTOP.IMPORT1(5)
Impressum