1ORG.FREEDESKTOP.IMPORT1(5) org.freedesktop.import1 ORG.FREEDESKTOP.IMPORT1(5)
2
6 org.freedesktop.import1 - The D-Bus interface of systemd-importd
7
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 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
21 The service exposes the following interfaces on the Manager object on
22 the bus:
23 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 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 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 PullTar() and PullRaw() may be used to download, verify and import a
146 system image from a URL. They take a URL argument which should point to
147 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 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 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 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 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
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 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 Properties
231 The Id property exposes the numeric transfer ID of the transfer object.
232 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 The Verify property exposes the selected verification setting and is
240 only defined for download operations (see above).
241 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
248 Example 1. Introspect org.freedesktop.import1.Manager on the bus
249 $ gdbus introspect --system \
251 --dest org.freedesktop.import1 \
252 --object-path /org/freedesktop/import1
253 Example 2. Introspect org.freedesktop.import1.Transfer on the bus
256 $ gdbus introspect --system \
258 --dest org.freedesktop.import1 \
259 --object-path /org/freedesktop/import1/transfer/_1
260
263 These D-Bus interfaces follow the usual interface versioning
264 guidelines[1].
265
267 1. the usual interface versioning guidelines
268 https://0pointer.de/blog/projects/versioning-dbus.html
269systemd 254 ORG.FREEDESKTOP.IMPORT1(5)