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