]>
Commit | Line | Data |
---|---|---|
de2efb75 ZJS |
1 | <?xml version='1.0'?> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
eea10b26 | 3 | "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" > |
db9ecf05 | 4 | <!-- SPDX-License-Identifier: LGPL-2.1-or-later --> |
de2efb75 ZJS |
5 | |
6 | <refentry id="org.freedesktop.machine1" conditional='ENABLE_MACHINED' | |
7 | xmlns:xi="http://www.w3.org/2001/XInclude"> | |
8 | <refentryinfo> | |
9 | <title>org.freedesktop.machine1</title> | |
10 | <productname>systemd</productname> | |
11 | </refentryinfo> | |
12 | ||
13 | <refmeta> | |
14 | <refentrytitle>org.freedesktop.machine1</refentrytitle> | |
15 | <manvolnum>5</manvolnum> | |
16 | </refmeta> | |
17 | ||
18 | <refnamediv> | |
19 | <refname>org.freedesktop.machine1</refname> | |
20 | <refpurpose>The D-Bus interface of systemd-machined</refpurpose> | |
21 | </refnamediv> | |
22 | ||
23 | <refsect1> | |
24 | <title>Introduction</title> | |
25 | ||
26 | <para> | |
27 | <citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
28 | is a system service that keeps track of locally running virtual machines and containers. | |
29 | This page describes the D-Bus interface.</para> | |
30 | </refsect1> | |
31 | ||
32 | <refsect1> | |
33 | <title>The Manager Object</title> | |
34 | ||
35 | <para>The service exposes the following interfaces on the Manager object on the bus:</para> | |
36 | ||
48f99d7c | 37 | <programlisting executable="systemd-machined" node="/org/freedesktop/machine1" interface="org.freedesktop.machine1.Manager"> |
de2efb75 ZJS |
38 | node /org/freedesktop/machine1 { |
39 | interface org.freedesktop.machine1.Manager { | |
40 | methods: | |
41 | GetMachine(in s name, | |
42 | out o machine); | |
43 | GetImage(in s name, | |
44 | out o image); | |
45 | GetMachineByPID(in u pid, | |
46 | out o machine); | |
47 | ListMachines(out a(ssso) machines); | |
4fb222c4 | 48 | ListImages(out a(ssbttto) images); |
34b56848 | 49 | @org.freedesktop.systemd1.Privileged("true") |
de2efb75 ZJS |
50 | CreateMachine(in s name, |
51 | in ay id, | |
52 | in s service, | |
53 | in s class, | |
54 | in u leader, | |
55 | in s root_directory, | |
56 | in a(sv) scope_properties, | |
57 | out o path); | |
34b56848 | 58 | @org.freedesktop.systemd1.Privileged("true") |
de2efb75 ZJS |
59 | CreateMachineWithNetwork(in s name, |
60 | in ay id, | |
61 | in s service, | |
62 | in s class, | |
63 | in u leader, | |
64 | in s root_directory, | |
65 | in ai ifindices, | |
66 | in a(sv) scope_properties, | |
67 | out o path); | |
34b56848 | 68 | @org.freedesktop.systemd1.Privileged("true") |
de2efb75 ZJS |
69 | RegisterMachine(in s name, |
70 | in ay id, | |
71 | in s service, | |
72 | in s class, | |
73 | in u leader, | |
74 | in s root_directory, | |
75 | out o path); | |
34b56848 | 76 | @org.freedesktop.systemd1.Privileged("true") |
de2efb75 ZJS |
77 | RegisterMachineWithNetwork(in s name, |
78 | in ay id, | |
79 | in s service, | |
80 | in s class, | |
81 | in u leader, | |
82 | in s root_directory, | |
83 | in ai ifindices, | |
84 | out o path); | |
4fb222c4 ZJS |
85 | UnregisterMachine(in s name); |
86 | TerminateMachine(in s id); | |
de2efb75 ZJS |
87 | KillMachine(in s name, |
88 | in s who, | |
4fb222c4 | 89 | in i signal); |
de2efb75 ZJS |
90 | GetMachineAddresses(in s name, |
91 | out a(iay) addresses); | |
1f815bf1 SL |
92 | GetMachineSSHInfo(in s name, |
93 | out s ssh_address, | |
94 | out s ssh_private_key_path); | |
de2efb75 ZJS |
95 | GetMachineOSRelease(in s name, |
96 | out a{ss} fields); | |
34b56848 | 97 | @org.freedesktop.systemd1.Privileged("true") |
de2efb75 ZJS |
98 | OpenMachinePTY(in s name, |
99 | out h pty, | |
100 | out s pty_path); | |
101 | OpenMachineLogin(in s name, | |
102 | out h pty, | |
103 | out s pty_path); | |
104 | OpenMachineShell(in s name, | |
105 | in s user, | |
106 | in s path, | |
107 | in as args, | |
108 | in as environment, | |
109 | out h pty, | |
110 | out s pty_path); | |
111 | BindMountMachine(in s name, | |
112 | in s source, | |
113 | in s destination, | |
114 | in b read_only, | |
115 | in b mkdir); | |
116 | CopyFromMachine(in s name, | |
117 | in s source, | |
118 | in s destination); | |
119 | CopyToMachine(in s name, | |
120 | in s source, | |
121 | in s destination); | |
ae03e1a9 AW |
122 | CopyFromMachineWithFlags(in s name, |
123 | in s source, | |
124 | in s destination, | |
125 | in t flags); | |
126 | CopyToMachineWithFlags(in s name, | |
127 | in s source, | |
128 | in s destination, | |
129 | in t flags); | |
4fb222c4 ZJS |
130 | OpenMachineRootDirectory(in s name, |
131 | out h fd); | |
132 | GetMachineUIDShift(in s name, | |
133 | out u shift); | |
de2efb75 ZJS |
134 | RemoveImage(in s name); |
135 | RenameImage(in s name, | |
136 | in s new_name); | |
137 | CloneImage(in s name, | |
138 | in s new_name, | |
139 | in b read_only); | |
140 | MarkImageReadOnly(in s name, | |
141 | in b read_only); | |
4fb222c4 ZJS |
142 | GetImageHostname(in s name, |
143 | out s hostname); | |
144 | GetImageMachineID(in s name, | |
145 | out ay id); | |
146 | GetImageMachineInfo(in s name, | |
147 | out a{ss} machine_info); | |
148 | GetImageOSRelease(in s name, | |
149 | out a{ss} os_release); | |
de2efb75 ZJS |
150 | SetPoolLimit(in t size); |
151 | SetImageLimit(in s name, | |
152 | in t size); | |
4fb222c4 ZJS |
153 | CleanPool(in s mode, |
154 | out a(st) images); | |
de2efb75 ZJS |
155 | MapFromMachineUser(in s name, |
156 | in u uid_inner, | |
157 | out u uid_outer); | |
158 | MapToMachineUser(in u uid_outer, | |
159 | out s machine_name, | |
160 | out o machine_path, | |
4fb222c4 | 161 | out u uid_inner); |
de2efb75 ZJS |
162 | MapFromMachineGroup(in s name, |
163 | in u gid_inner, | |
164 | out u gid_outer); | |
165 | MapToMachineGroup(in u gid_outer, | |
166 | out s machine_name, | |
167 | out o machine_path, | |
168 | out u gid_inner); | |
169 | signals: | |
170 | MachineNew(s machine, | |
171 | o path); | |
172 | MachineRemoved(s machine, | |
173 | o path); | |
174 | properties: | |
4fb222c4 ZJS |
175 | @org.freedesktop.DBus.Property.EmitsChangedSignal("false") |
176 | readonly s PoolPath = '...'; | |
177 | @org.freedesktop.DBus.Property.EmitsChangedSignal("false") | |
178 | readonly t PoolUsage = ...; | |
179 | @org.freedesktop.DBus.Property.EmitsChangedSignal("false") | |
180 | readonly t PoolLimit = ...; | |
de2efb75 | 181 | }; |
4fb222c4 ZJS |
182 | interface org.freedesktop.DBus.Peer { ... }; |
183 | interface org.freedesktop.DBus.Introspectable { ... }; | |
184 | interface org.freedesktop.DBus.Properties { ... }; | |
de2efb75 | 185 | }; |
00bb75d7 ZJS |
186 | </programlisting> |
187 | ||
188 | <!--method UnregisterMachine is not documented!--> | |
189 | ||
190 | <!--method OpenMachineRootDirectory is not documented!--> | |
191 | ||
192 | <!--method GetMachineUIDShift is not documented!--> | |
193 | ||
194 | <!--method GetImageHostname is not documented!--> | |
195 | ||
196 | <!--method GetImageMachineID is not documented!--> | |
197 | ||
198 | <!--method GetImageMachineInfo is not documented!--> | |
199 | ||
200 | <!--method GetImageOSRelease is not documented!--> | |
201 | ||
202 | <!--method CleanPool is not documented!--> | |
203 | ||
204 | <!--Autogenerated cross-references for systemd.directives, do not edit--> | |
205 | ||
206 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Manager"/> | |
207 | ||
208 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Manager"/> | |
209 | ||
210 | <variablelist class="dbus-method" generated="True" extra-ref="GetMachine()"/> | |
211 | ||
212 | <variablelist class="dbus-method" generated="True" extra-ref="GetImage()"/> | |
213 | ||
214 | <variablelist class="dbus-method" generated="True" extra-ref="GetMachineByPID()"/> | |
215 | ||
216 | <variablelist class="dbus-method" generated="True" extra-ref="ListMachines()"/> | |
217 | ||
218 | <variablelist class="dbus-method" generated="True" extra-ref="ListImages()"/> | |
219 | ||
220 | <variablelist class="dbus-method" generated="True" extra-ref="CreateMachine()"/> | |
221 | ||
222 | <variablelist class="dbus-method" generated="True" extra-ref="CreateMachineWithNetwork()"/> | |
223 | ||
224 | <variablelist class="dbus-method" generated="True" extra-ref="RegisterMachine()"/> | |
225 | ||
226 | <variablelist class="dbus-method" generated="True" extra-ref="RegisterMachineWithNetwork()"/> | |
227 | ||
228 | <variablelist class="dbus-method" generated="True" extra-ref="UnregisterMachine()"/> | |
229 | ||
230 | <variablelist class="dbus-method" generated="True" extra-ref="TerminateMachine()"/> | |
231 | ||
232 | <variablelist class="dbus-method" generated="True" extra-ref="KillMachine()"/> | |
233 | ||
234 | <variablelist class="dbus-method" generated="True" extra-ref="GetMachineAddresses()"/> | |
235 | ||
1f815bf1 SL |
236 | <variablelist class="dbus-method" generated="True" extra-ref="GetMachineSSHInfo()"/> |
237 | ||
00bb75d7 ZJS |
238 | <variablelist class="dbus-method" generated="True" extra-ref="GetMachineOSRelease()"/> |
239 | ||
240 | <variablelist class="dbus-method" generated="True" extra-ref="OpenMachinePTY()"/> | |
241 | ||
242 | <variablelist class="dbus-method" generated="True" extra-ref="OpenMachineLogin()"/> | |
243 | ||
244 | <variablelist class="dbus-method" generated="True" extra-ref="OpenMachineShell()"/> | |
245 | ||
246 | <variablelist class="dbus-method" generated="True" extra-ref="BindMountMachine()"/> | |
247 | ||
248 | <variablelist class="dbus-method" generated="True" extra-ref="CopyFromMachine()"/> | |
249 | ||
250 | <variablelist class="dbus-method" generated="True" extra-ref="CopyToMachine()"/> | |
251 | ||
ae03e1a9 AW |
252 | <variablelist class="dbus-method" generated="True" extra-ref="CopyFromMachineWithFlags()"/> |
253 | ||
254 | <variablelist class="dbus-method" generated="True" extra-ref="CopyToMachineWithFlags()"/> | |
255 | ||
00bb75d7 ZJS |
256 | <variablelist class="dbus-method" generated="True" extra-ref="OpenMachineRootDirectory()"/> |
257 | ||
258 | <variablelist class="dbus-method" generated="True" extra-ref="GetMachineUIDShift()"/> | |
259 | ||
260 | <variablelist class="dbus-method" generated="True" extra-ref="RemoveImage()"/> | |
261 | ||
262 | <variablelist class="dbus-method" generated="True" extra-ref="RenameImage()"/> | |
263 | ||
264 | <variablelist class="dbus-method" generated="True" extra-ref="CloneImage()"/> | |
265 | ||
266 | <variablelist class="dbus-method" generated="True" extra-ref="MarkImageReadOnly()"/> | |
267 | ||
268 | <variablelist class="dbus-method" generated="True" extra-ref="GetImageHostname()"/> | |
269 | ||
270 | <variablelist class="dbus-method" generated="True" extra-ref="GetImageMachineID()"/> | |
271 | ||
272 | <variablelist class="dbus-method" generated="True" extra-ref="GetImageMachineInfo()"/> | |
273 | ||
274 | <variablelist class="dbus-method" generated="True" extra-ref="GetImageOSRelease()"/> | |
275 | ||
276 | <variablelist class="dbus-method" generated="True" extra-ref="SetPoolLimit()"/> | |
277 | ||
278 | <variablelist class="dbus-method" generated="True" extra-ref="SetImageLimit()"/> | |
279 | ||
280 | <variablelist class="dbus-method" generated="True" extra-ref="CleanPool()"/> | |
281 | ||
282 | <variablelist class="dbus-method" generated="True" extra-ref="MapFromMachineUser()"/> | |
283 | ||
284 | <variablelist class="dbus-method" generated="True" extra-ref="MapToMachineUser()"/> | |
285 | ||
286 | <variablelist class="dbus-method" generated="True" extra-ref="MapFromMachineGroup()"/> | |
287 | ||
288 | <variablelist class="dbus-method" generated="True" extra-ref="MapToMachineGroup()"/> | |
289 | ||
43b238f1 | 290 | <variablelist class="dbus-signal" generated="True" extra-ref="MachineNew()"/> |
00bb75d7 | 291 | |
43b238f1 | 292 | <variablelist class="dbus-signal" generated="True" extra-ref="MachineRemoved()"/> |
00bb75d7 ZJS |
293 | |
294 | <variablelist class="dbus-property" generated="True" extra-ref="PoolPath"/> | |
295 | ||
296 | <variablelist class="dbus-property" generated="True" extra-ref="PoolUsage"/> | |
297 | ||
298 | <variablelist class="dbus-property" generated="True" extra-ref="PoolLimit"/> | |
299 | ||
300 | <!--End of Autogenerated section--> | |
de2efb75 ZJS |
301 | |
302 | <refsect2> | |
303 | <title>Methods</title> | |
304 | ||
305 | <para><function>GetMachine()</function> may be used to get the machine object path for the machine with | |
ca264f7d | 306 | the specified name. Similarly, <function>GetMachineByPID()</function> gets the machine object the |
de2efb75 ZJS |
307 | specified PID belongs to if there is any.</para> |
308 | ||
ca264f7d | 309 | <para><function>GetImage()</function> may be used to get the image object path of the image with the |
de2efb75 ZJS |
310 | specified name.</para> |
311 | ||
ca264f7d | 312 | <para><function>ListMachines()</function> returns an array of all currently registered machines. The |
de2efb75 ZJS |
313 | structures in the array consist of the following fields: machine name, machine class, an identifier for |
314 | the service that registered the machine and the machine object path.</para> | |
315 | ||
ca264f7d | 316 | <para><function>ListImages()</function> returns an array of all currently known images. The |
de2efb75 | 317 | structures in the array consist of the following fields: image name, type, read-only flag, creation |
ca264f7d | 318 | time, modification time, current disk space, and image object path.</para> |
de2efb75 ZJS |
319 | |
320 | <para><function>CreateMachine()</function> may be used to register a new virtual machine or container | |
ca264f7d DDM |
321 | with <command>systemd-machined</command>, creating a scope unit for it. It accepts the following arguments: a |
322 | machine name chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies the | |
de2efb75 ZJS |
323 | service that registers the machine, a class string, the PID of the leader process of the machine, an |
324 | optional root directory of the container, and an array of additional properties to use for the scope | |
ca264f7d DDM |
325 | registration. The virtual machine name must be suitable as a hostname, and hence should follow the usual |
326 | DNS hostname rules, as well as the Linux hostname restrictions. Specifically, only 7 bit ASCII is | |
de2efb75 ZJS |
327 | permitted, a maximum length of 64 characters is enforced, only characters from the set |
328 | <literal>a-zA-Z0-9-_.</literal> are allowed, the name may not begin with a dot, and it may not contain | |
329 | two dots immediately following each other. Container and VM managers should ideally use the hostname | |
330 | used internally in the machine for this parameter. This recommendation is made in order to make the | |
331 | machine name naturally resolvable using | |
332 | <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>. If | |
333 | a container manager needs to embed characters outside of the indicated range, escaping is required, | |
334 | possibly using <literal>_</literal> as the escape character. Another (somewhat natural) option would be | |
ca264f7d DDM |
335 | to utilize Internet IDNA encoding. The UUID is passed as a 32 byte array or, if no suitable UUID is |
336 | available, an empty array (zero length) or zeroed out array shall be passed. The UUID should identify | |
337 | the virtual machine/container uniquely and should ideally be the same UUID that | |
de2efb75 ZJS |
338 | <filename>/etc/machine-id</filename> in the VM/container is initialized from. The service string can be |
339 | free-form, but it is recommended to pass a short lowercase identifier like | |
340 | <literal>systemd-nspawn</literal>, <literal>libvirt-lxc</literal> or similar. The class string should | |
341 | be either <literal>container</literal> or <literal>vm</literal> indicating whether the machine to | |
342 | register is of the respective class. The leader PID should be the host PID of the init process of the | |
ca264f7d DDM |
343 | container or the encapsulating process of the VM. If the root directory of the container is known and |
344 | available in the host's hierarchy, it should be passed. Otherwise, pass the empty string instead. Finally, the | |
de2efb75 | 345 | scope properties are passed as array in the same way as to PID1's |
ca264f7d DDM |
346 | <function>StartTransientUnit()</function> method. Calling this method will internally register a transient scope |
347 | unit for the calling client (utilizing the passed scope_properties) and move the leader PID into | |
89fc6fd3 | 348 | it. The method returns an object path for the registered machine object that implements the |
de2efb75 | 349 | <interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below). Also see the |
a25d9395 | 350 | <ulink url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface">New Control Group |
ca264f7d | 351 | Interfaces</ulink> for details about scope units and how to alter resource control settings on the |
de2efb75 ZJS |
352 | created machine at runtime.</para> |
353 | ||
ca264f7d DDM |
354 | <para><function>RegisterMachine()</function> is similar to <function>CreateMachine()</function>. |
355 | However, it only registers a machine and does not create a scope unit for it. Instead, the caller's unit is | |
356 | registered. We recommend to only use this method for container or VM managers that are run | |
de2efb75 ZJS |
357 | multiple times, one instance for each container/VM they manage, and are invoked as system |
358 | services.</para> | |
359 | ||
360 | <para><function>CreateMachineWithNetwork()</function> and | |
361 | <function>RegisterMachineWithNetwork()</function> are similar to <function>CreateMachine()</function> | |
362 | and <function>RegisterMachine()</function> but take an extra argument: an array of network interface | |
ca264f7d DDM |
363 | indices that point towards the virtual machine or container. The interface indices should reference one |
364 | or more network interfaces on the host that can be used to communicate with the guest. Commonly, the | |
365 | passed interface index refers to the host side of a "veth" link (in case of containers), a | |
366 | "tun"/"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the | |
de2efb75 | 367 | VM/container interfaces. Specifying this information is useful to enable support for link-local IPv6 |
ca264f7d | 368 | communication to the machines since the scope field of sockaddr_in6 can be initialized by the |
de2efb75 ZJS |
369 | specified ifindex. |
370 | <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
371 | makes use of this information.</para> | |
372 | ||
ca264f7d | 373 | <para><function>KillMachine()</function> sends a UNIX signal to the machine's processes. As its arguments, it takes a |
de2efb75 | 374 | machine name (as originally passed to <function>CreateMachine()</function> or returned by |
ca264f7d DDM |
375 | <function>ListMachines()</function>), an identifier that specifies what precisely to send the signal to (either |
376 | <literal>leader</literal> or <literal>all</literal>), and a numeric UNIX signal integer.</para> | |
de2efb75 ZJS |
377 | |
378 | <para><function>TerminateMachine()</function> terminates a virtual machine, killing its processes. It | |
ca264f7d | 379 | takes a machine name as its only argument.</para> |
de2efb75 | 380 | |
89fc6fd3 | 381 | <para><function>GetMachineAddresses()</function> retrieves the IP addresses of a container. This method |
de2efb75 ZJS |
382 | returns an array of pairs consisting of an address family specifier (<constant>AF_INET</constant> or |
383 | <constant>AF_INET6</constant>) and a byte array containing the addresses. This is only supported for | |
384 | containers that make use of network namespacing.</para> | |
385 | ||
1f815bf1 SL |
386 | <para><function>GetMachineSSHInfo()</function> retrieves the SSH information of a machine. This method |
387 | returns two strings, the SSH address which can be used to tell SSH where to connect, and the path | |
388 | to the SSH private key required for the connection to succeed.</para> | |
389 | ||
de2efb75 | 390 | <para><function>GetMachineOSRelease()</function> retrieves the OS release information of a |
ca264f7d | 391 | container. This method returns an array of key value pairs read from the |
de2efb75 | 392 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file in |
ca264f7d | 393 | the container and is useful to identify the operating system used in a container.</para> |
de2efb75 ZJS |
394 | |
395 | <para><function>OpenMachinePTY()</function> allocates a pseudo TTY in the container and returns a file | |
396 | descriptor and its path. This is equivalent to transitioning into the container and invoking | |
d3fcecf3 | 397 | <citerefentry project="man-pages"><refentrytitle>posix_openpt</refentrytitle><manvolnum>3</manvolnum></citerefentry>. |
b7a47345 | 398 | </para> |
de2efb75 ZJS |
399 | |
400 | <para><function>OpenMachineLogin()</function> allocates a pseudo TTY in the container and ensures that | |
ca264f7d DDM |
401 | a getty login prompt of the container is running on the other end. It returns the file descriptor of |
402 | the PTY and the PTY path. This is useful for acquiring a pty with a login prompt from the | |
de2efb75 ZJS |
403 | container.</para> |
404 | ||
405 | <para><function>OpenMachineShell()</function> allocates a pseudo TTY in the container, as the specified | |
ca264f7d DDM |
406 | user, and invokes the executable at the specified path with a list of arguments (starting from |
407 | argv[0]) and an environment block. It then returns the file descriptor of the PTY and the PTY | |
de2efb75 ZJS |
408 | path.</para> |
409 | ||
410 | <para><function>BindMountMachine()</function> bind mounts a file or directory from the host into the | |
ca264f7d DDM |
411 | container. Its arguments consist of a machine name, the source directory on the host, the destination directory in the |
412 | container, and two booleans, one indicating whether the bind mount shall be | |
de2efb75 ZJS |
413 | read-only, the other indicating whether the destination mount point shall be created first, if it is |
414 | missing.</para> | |
415 | ||
416 | <para><function>CopyFromMachine()</function> copies files or directories from a container into the | |
ca264f7d | 417 | host. It takes a container name, a source directory in the container and a destination directory on the |
ae03e1a9 AW |
418 | host as arguments. |
419 | <function>CopyToMachine()</function> does the opposite and copies files from a source | |
420 | directory on the host into a destination directory in the container. | |
43b238f1 | 421 | <function>CopyFromMachineWithFlags()</function> and <function>CopyToMachineWithFlags()</function> do the same but take an additional flags argument.</para> |
de2efb75 | 422 | |
ca264f7d | 423 | <para><function>RemoveImage()</function> removes the image with the specified name.</para> |
de2efb75 | 424 | |
ca264f7d | 425 | <para><function>RenameImage()</function> renames the specified image.</para> |
de2efb75 | 426 | |
ca264f7d DDM |
427 | <para><function>CloneImage()</function> clones the specified image under a new name. It also takes a |
428 | boolean argument indicating whether the resulting image shall be read-only or not.</para> | |
de2efb75 ZJS |
429 | |
430 | <para><function>MarkImageReadOnly()</function> toggles the read-only flag of an image.</para> | |
431 | ||
432 | <para><function>SetPoolLimit()</function> sets an overall quota limit on the pool of images.</para> | |
433 | ||
434 | <para><function>SetImageLimit()</function> sets a per-image quota limit.</para> | |
435 | ||
436 | <para><function>MapFromMachineUser()</function>, <function>MapToMachineUser()</function>, | |
ca264f7d DDM |
437 | <function>MapFromMachineGroup()</function>, and <function>MapToMachineGroup()</function> may be used to map |
438 | UIDs/GIDs from the host user namespace to a container user namespace or vice versa.</para> | |
de2efb75 ZJS |
439 | </refsect2> |
440 | ||
441 | <refsect2> | |
442 | <title>Signals</title> | |
443 | ||
43b238f1 | 444 | <para><function>MachineNew()</function> and <function>MachineRemoved()</function> are sent whenever a new |
ca264f7d | 445 | machine is registered or removed. These signals carry the machine name and the object path to the corresponding |
de2efb75 ZJS |
446 | <interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below).</para> |
447 | </refsect2> | |
448 | ||
449 | <refsect2> | |
450 | <title>Properties</title> | |
451 | ||
452 | <para><varname>PoolPath</varname> specifies the file system path where images are written to.</para> | |
453 | ||
454 | <para><varname>PoolUsage</varname> specifies the current usage size of the image pool in bytes.</para> | |
455 | ||
456 | <para><varname>PoolLimit</varname> specifies the size limit of the image pool in bytes.</para> | |
457 | </refsect2> | |
458 | </refsect1> | |
459 | ||
460 | <refsect1> | |
461 | <title>Machine Objects</title> | |
462 | ||
48f99d7c | 463 | <programlisting executable="systemd-machined" node="/org/freedesktop/machine1/machine/rawhide" interface="org.freedesktop.machine1.Machine"> |
4fb222c4 | 464 | node /org/freedesktop/machine1/machine/rawhide { |
de2efb75 ZJS |
465 | interface org.freedesktop.machine1.Machine { |
466 | methods: | |
467 | Terminate(); | |
468 | Kill(in s who, | |
4fb222c4 | 469 | in i signal); |
de2efb75 | 470 | GetAddresses(out a(iay) addresses); |
1f815bf1 SL |
471 | GetSSHInfo(out s ssh_address, |
472 | out s ssh_private_key_path); | |
de2efb75 | 473 | GetOSRelease(out a{ss} fields); |
4fb222c4 ZJS |
474 | GetUIDShift(out u shift); |
475 | OpenPTY(out h pty, | |
476 | out s pty_path); | |
477 | OpenLogin(out h pty, | |
478 | out s pty_path); | |
479 | OpenShell(in s user, | |
480 | in s path, | |
481 | in as args, | |
482 | in as environment, | |
483 | out h pty, | |
484 | out s pty_path); | |
485 | BindMount(in s source, | |
486 | in s destination, | |
487 | in b read_only, | |
488 | in b mkdir); | |
489 | CopyFrom(in s source, | |
490 | in s destination); | |
491 | CopyTo(in s source, | |
492 | in s destination); | |
ae03e1a9 AW |
493 | CopyFromWithFlags(in s source, |
494 | in s destination, | |
495 | in t flags); | |
496 | CopyToWithFlags(in s source, | |
497 | in s destination, | |
498 | in t flags); | |
4fb222c4 | 499 | OpenRootDirectory(out h fd); |
de2efb75 | 500 | properties: |
4fb222c4 ZJS |
501 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
502 | readonly s Name = '...'; | |
503 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
504 | readonly ay Id = [...]; | |
505 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
506 | readonly t Timestamp = ...; | |
507 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
508 | readonly t TimestampMonotonic = ...; | |
509 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
510 | readonly s Service = '...'; | |
511 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
512 | readonly s Unit = '...'; | |
513 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
514 | readonly u Leader = ...; | |
515 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
516 | readonly s Class = '...'; | |
517 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
518 | readonly s RootDirectory = '...'; | |
519 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
520 | readonly ai NetworkInterfaces = [...]; | |
1f815bf1 SL |
521 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") |
522 | readonly u VSockCID = ...; | |
523 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
524 | readonly s SSHAddress = '...'; | |
525 | @org.freedesktop.DBus.Property.EmitsChangedSignal("const") | |
526 | readonly s SSHPrivateKeyPath = '...'; | |
4fb222c4 ZJS |
527 | @org.freedesktop.DBus.Property.EmitsChangedSignal("false") |
528 | readonly s State = '...'; | |
de2efb75 | 529 | }; |
4fb222c4 ZJS |
530 | interface org.freedesktop.DBus.Peer { ... }; |
531 | interface org.freedesktop.DBus.Introspectable { ... }; | |
532 | interface org.freedesktop.DBus.Properties { ... }; | |
de2efb75 ZJS |
533 | }; |
534 | </programlisting> | |
535 | ||
00bb75d7 ZJS |
536 | <!--method GetUIDShift is not documented!--> |
537 | ||
538 | <!--method OpenPTY is not documented!--> | |
539 | ||
540 | <!--method OpenLogin is not documented!--> | |
541 | ||
542 | <!--method OpenShell is not documented!--> | |
543 | ||
544 | <!--method BindMount is not documented!--> | |
545 | ||
546 | <!--method CopyFrom is not documented!--> | |
547 | ||
548 | <!--method CopyTo is not documented!--> | |
549 | ||
ae03e1a9 AW |
550 | <!--method CopyFromWithFlags is not documented!--> |
551 | ||
552 | <!--method CopyToWithFlags is not documented!--> | |
553 | ||
00bb75d7 ZJS |
554 | <!--method OpenRootDirectory is not documented!--> |
555 | ||
556 | <!--Autogenerated cross-references for systemd.directives, do not edit--> | |
557 | ||
558 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Machine"/> | |
559 | ||
560 | <variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Machine"/> | |
561 | ||
562 | <variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/> | |
563 | ||
564 | <variablelist class="dbus-method" generated="True" extra-ref="Kill()"/> | |
565 | ||
566 | <variablelist class="dbus-method" generated="True" extra-ref="GetAddresses()"/> | |
567 | ||
1f815bf1 SL |
568 | <variablelist class="dbus-method" generated="True" extra-ref="GetSSHInfo()"/> |
569 | ||
00bb75d7 ZJS |
570 | <variablelist class="dbus-method" generated="True" extra-ref="GetOSRelease()"/> |
571 | ||
572 | <variablelist class="dbus-method" generated="True" extra-ref="GetUIDShift()"/> | |
573 | ||
574 | <variablelist class="dbus-method" generated="True" extra-ref="OpenPTY()"/> | |
575 | ||
576 | <variablelist class="dbus-method" generated="True" extra-ref="OpenLogin()"/> | |
577 | ||
578 | <variablelist class="dbus-method" generated="True" extra-ref="OpenShell()"/> | |
579 | ||
580 | <variablelist class="dbus-method" generated="True" extra-ref="BindMount()"/> | |
581 | ||
582 | <variablelist class="dbus-method" generated="True" extra-ref="CopyFrom()"/> | |
583 | ||
584 | <variablelist class="dbus-method" generated="True" extra-ref="CopyTo()"/> | |
585 | ||
ae03e1a9 AW |
586 | <variablelist class="dbus-method" generated="True" extra-ref="CopyFromWithFlags()"/> |
587 | ||
588 | <variablelist class="dbus-method" generated="True" extra-ref="CopyToWithFlags()"/> | |
589 | ||
00bb75d7 ZJS |
590 | <variablelist class="dbus-method" generated="True" extra-ref="OpenRootDirectory()"/> |
591 | ||
592 | <variablelist class="dbus-property" generated="True" extra-ref="Name"/> | |
593 | ||
594 | <variablelist class="dbus-property" generated="True" extra-ref="Id"/> | |
595 | ||
596 | <variablelist class="dbus-property" generated="True" extra-ref="Timestamp"/> | |
597 | ||
598 | <variablelist class="dbus-property" generated="True" extra-ref="TimestampMonotonic"/> | |
599 | ||
600 | <variablelist class="dbus-property" generated="True" extra-ref="Service"/> | |
601 | ||
602 | <variablelist class="dbus-property" generated="True" extra-ref="Unit"/> | |
603 | ||
604 | <variablelist class="dbus-property" generated="True" extra-ref="Leader"/> | |
605 | ||
606 | <variablelist class="dbus-property" generated="True" extra-ref="Class"/> | |
607 | ||
608 | <variablelist class="dbus-property" generated="True" extra-ref="RootDirectory"/> | |
609 | ||
610 | <variablelist class="dbus-property" generated="True" extra-ref="NetworkInterfaces"/> | |
611 | ||
1f815bf1 SL |
612 | <variablelist class="dbus-property" generated="True" extra-ref="VSockCID"/> |
613 | ||
614 | <variablelist class="dbus-property" generated="True" extra-ref="SSHAddress"/> | |
615 | ||
616 | <variablelist class="dbus-property" generated="True" extra-ref="SSHPrivateKeyPath"/> | |
617 | ||
00bb75d7 ZJS |
618 | <variablelist class="dbus-property" generated="True" extra-ref="State"/> |
619 | ||
620 | <!--End of Autogenerated section--> | |
621 | ||
de2efb75 ZJS |
622 | <refsect2> |
623 | <title>Methods</title> | |
624 | ||
ca264f7d | 625 | <para><function>Terminate()</function> and <function>Kill()</function> terminate/kill the machine. These methods |
de2efb75 | 626 | take the same arguments as <function>TerminateMachine()</function> and |
ca264f7d | 627 | <function>KillMachine()</function> on the Manager interface, respectively.</para> |
de2efb75 | 628 | |
1f815bf1 SL |
629 | <para><function>GetAddresses()</function>, <function>GetSSHInfo()</function> and <function>GetOSRelease()</function> get the IP address, |
630 | SSH connection and OS release information from the machine. These methods take the same arguments as | |
631 | <function>GetMachineAddresses()</function>, <function>GetMachineSSHInfo()</function> and <function>GetMachineOSRelease()</function> of the | |
ca264f7d | 632 | Manager interface, respectively.</para> |
de2efb75 ZJS |
633 | </refsect2> |
634 | ||
635 | <refsect2> | |
636 | <title>Properties</title> | |
637 | ||
ca264f7d | 638 | <para><varname>Name</varname> is the machine name as it was passed in during registration with |
de2efb75 ZJS |
639 | <function>CreateMachine()</function> on the manager object.</para> |
640 | ||
641 | <para><varname>Id</varname> is the machine UUID.</para> | |
642 | ||
643 | <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> are the realtime and | |
ca264f7d | 644 | monotonic timestamps when the virtual machines where created in microseconds since the epoch.</para> |
de2efb75 | 645 | |
ca264f7d | 646 | <para><varname>Service</varname> contains a short string identifying the registering service as passed |
de2efb75 ZJS |
647 | in during registration of the machine.</para> |
648 | ||
649 | <para><varname>Unit</varname> is the systemd scope or service unit name for the machine.</para> | |
650 | ||
651 | <para><varname>Leader</varname> is the PID of the leader process of the machine.</para> | |
652 | ||
ca264f7d | 653 | <para><varname>Class</varname> is the class of the machine and is either the string "vm" (for real VMs |
de2efb75 ZJS |
654 | based on virtualized hardware) or "container" (for light-weight userspace virtualization sharing the |
655 | same kernel as the host).</para> | |
656 | ||
ca264f7d DDM |
657 | <para><varname>RootDirectory</varname> is the root directory of the container if it is known and |
658 | applicable or the empty string.</para> | |
de2efb75 | 659 | |
ca264f7d DDM |
660 | <para><varname>NetworkInterfaces</varname> contains an array of network interface indices that point |
661 | towards the container, the VM or the host. For details about this information see the description of | |
de2efb75 ZJS |
662 | <function>CreateMachineWithNetwork()</function> above.</para> |
663 | ||
1f815bf1 SL |
664 | <para><varname>VSockCID</varname> is the VSOCK CID of the VM if it is known, or |
665 | <constant>VMADDR_CID_ANY</constant> otherwise.</para> | |
666 | ||
667 | <para><varname>SSHAddress</varname> is the address of the VM in a format <command>ssh</command> can understand | |
668 | if it is known or the empty string.</para> | |
669 | ||
670 | <para><varname>SSHPrivateKeyPath</varname> is the path to the SSH private key of the VM if it is known | |
671 | or the empty string.</para> | |
672 | ||
ca264f7d DDM |
673 | <para><varname>State</varname> is the state of the machine and is one of <literal>opening</literal>, |
674 | <literal>running</literal>, or <literal>closing</literal>. Note that the state machine is not considered | |
de2efb75 ZJS |
675 | part of the API and states might be removed or added without this being considered API breakage. |
676 | </para> | |
677 | </refsect2> | |
678 | </refsect1> | |
679 | ||
48f99d7c ZJS |
680 | <refsect1> |
681 | <title>Examples</title> | |
682 | ||
683 | <example> | |
684 | <title>Introspect <interfacename>org.freedesktop.machine1.Manager</interfacename> on the bus</title> | |
685 | ||
686 | <programlisting> | |
687 | $ gdbus introspect --system \ | |
688 | --dest org.freedesktop.machine1 \ | |
689 | --object-path /org/freedesktop/machine1 | |
690 | </programlisting> | |
691 | </example> | |
692 | ||
693 | <example> | |
694 | <title>Introspect <interfacename>org.freedesktop.machine1.Machine</interfacename> on the bus</title> | |
695 | ||
696 | <programlisting> | |
697 | $ gdbus introspect --system \ | |
698 | --dest org.freedesktop.machine1 \ | |
699 | --object-path /org/freedesktop/machine1/machine/rawhide | |
700 | </programlisting> | |
701 | </example> | |
702 | </refsect1> | |
703 | ||
e4239a34 | 704 | <xi:include href="org.freedesktop.locale1.xml" xpointer="versioning"/> |
d9d2d16a AK |
705 | |
706 | <refsect1> | |
707 | <title>History</title> | |
708 | <refsect2> | |
709 | <title>The Manager Object</title> | |
710 | <para><function>CopyFromMachineWithFlags()</function> and | |
711 | <function>CopyToMachineWithFlags()</function> were added in version 252.</para> | |
1f815bf1 | 712 | <para><function>GetMachineSSHInfo()</function> was added in version 256.</para> |
d9d2d16a AK |
713 | </refsect2> |
714 | <refsect2> | |
715 | <title>Machine Objects</title> | |
716 | <para><function>CopyFromWithFlags()</function> and | |
717 | <function>CopyToWithFlags()</function> were added in version 252.</para> | |
1f815bf1 SL |
718 | <para><function>GetSSHInfo()</function>, <varname>VSockCID</varname>, <varname>SSHAddress</varname> |
719 | and <varname>SSHPrivateKeyPath</varname> were added in version 256.</para> | |
d9d2d16a AK |
720 | </refsect2> |
721 | </refsect1> | |
de2efb75 | 722 | </refentry> |