]>
Commit | Line | Data |
---|---|---|
de2efb75 ZJS |
1 | <?xml version='1.0'?> |
2 | <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" | |
3 | "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" > | |
4 | <!-- SPDX-License-Identifier: LGPL-2.1+ --> | |
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 | ||
37 | <programlisting> | |
38 | $ gdbus introspect --system \ | |
39 | --dest org.freedesktop.machine1 \ | |
40 | --object-path /org/freedesktop/machine1 | |
41 | ||
42 | node /org/freedesktop/machine1 { | |
43 | interface org.freedesktop.machine1.Manager { | |
44 | methods: | |
45 | GetMachine(in s name, | |
46 | out o machine); | |
47 | GetImage(in s name, | |
48 | out o image); | |
49 | GetMachineByPID(in u pid, | |
50 | out o machine); | |
51 | ListMachines(out a(ssso) machines); | |
52 | ListImages(out a(ssbttto) machines); | |
53 | CreateMachine(in s name, | |
54 | in ay id, | |
55 | in s service, | |
56 | in s class, | |
57 | in u leader, | |
58 | in s root_directory, | |
59 | in a(sv) scope_properties, | |
60 | out o path); | |
61 | CreateMachineWithNetwork(in s name, | |
62 | in ay id, | |
63 | in s service, | |
64 | in s class, | |
65 | in u leader, | |
66 | in s root_directory, | |
67 | in ai ifindices, | |
68 | in a(sv) scope_properties, | |
69 | out o path); | |
70 | RegisterMachine(in s name, | |
71 | in ay id, | |
72 | in s service, | |
73 | in s class, | |
74 | in u leader, | |
75 | in s root_directory, | |
76 | out o path); | |
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); | |
85 | KillMachine(in s name, | |
86 | in s who, | |
87 | in s signal); | |
88 | TerminateMachine(in s id); | |
89 | GetMachineAddresses(in s name, | |
90 | out a(iay) addresses); | |
91 | GetMachineOSRelease(in s name, | |
92 | out a{ss} fields); | |
93 | OpenMachinePTY(in s name, | |
94 | out h pty, | |
95 | out s pty_path); | |
96 | OpenMachineLogin(in s name, | |
97 | out h pty, | |
98 | out s pty_path); | |
99 | OpenMachineShell(in s name, | |
100 | in s user, | |
101 | in s path, | |
102 | in as args, | |
103 | in as environment, | |
104 | out h pty, | |
105 | out s pty_path); | |
106 | BindMountMachine(in s name, | |
107 | in s source, | |
108 | in s destination, | |
109 | in b read_only, | |
110 | in b mkdir); | |
111 | CopyFromMachine(in s name, | |
112 | in s source, | |
113 | in s destination); | |
114 | CopyToMachine(in s name, | |
115 | in s source, | |
116 | in s destination); | |
117 | RemoveImage(in s name); | |
118 | RenameImage(in s name, | |
119 | in s new_name); | |
120 | CloneImage(in s name, | |
121 | in s new_name, | |
122 | in b read_only); | |
123 | MarkImageReadOnly(in s name, | |
124 | in b read_only); | |
125 | SetPoolLimit(in t size); | |
126 | SetImageLimit(in s name, | |
127 | in t size); | |
128 | MapFromMachineUser(in s name, | |
129 | in u uid_inner, | |
130 | out u uid_outer); | |
131 | MapToMachineUser(in u uid_outer, | |
132 | out s machine_name, | |
133 | out o machine_path, | |
134 | out u uid_inner; | |
135 | MapFromMachineGroup(in s name, | |
136 | in u gid_inner, | |
137 | out u gid_outer); | |
138 | MapToMachineGroup(in u gid_outer, | |
139 | out s machine_name, | |
140 | out o machine_path, | |
141 | out u gid_inner); | |
142 | signals: | |
143 | MachineNew(s machine, | |
144 | o path); | |
145 | MachineRemoved(s machine, | |
146 | o path); | |
147 | properties: | |
148 | readonly s PoolPath = '/var/lib/machines'; | |
149 | readonly t PoolUsage = 18446744070652059648; | |
150 | readonly t PoolLimit = 2160721920; | |
151 | }; | |
152 | interface org.freedesktop.DBus.Properties { | |
153 | }; | |
154 | interface org.freedesktop.DBus.Peer { | |
155 | }; | |
156 | interface org.freedesktop.DBus.Introspectable { | |
157 | }; | |
158 | }; | |
2fe60ff1 | 159 | </programlisting> |
de2efb75 ZJS |
160 | |
161 | <refsect2> | |
162 | <title>Methods</title> | |
163 | ||
164 | <para><function>GetMachine()</function> may be used to get the machine object path for the machine with | |
165 | the specified name. Similarly, <function>GetMachineByPID()</function> get the machine object the | |
166 | specified PID belongs to if there is any.</para> | |
167 | ||
168 | <para><function>GetImage()</function> may be used to the the image object path for the image with the | |
169 | specified name.</para> | |
170 | ||
171 | <para><function>ListMachines()</function> returns an array with all currently registered machines. The | |
172 | structures in the array consist of the following fields: machine name, machine class, an identifier for | |
173 | the service that registered the machine and the machine object path.</para> | |
174 | ||
175 | <para><function>ListImages()</function> returns an array with all currently known images. The | |
176 | structures in the array consist of the following fields: image name, type, read-only flag, creation | |
177 | time, modification time, current disk space, image object path.</para> | |
178 | ||
179 | <para><function>CreateMachine()</function> may be used to register a new virtual machine or container | |
180 | with <command>systemd-machined</command>, creating a scope unit for it. This takes as arguments: a | |
181 | machine name chosen by the registrar, an optional UUID as 32 byte array, a string that identifies the | |
182 | service that registers the machine, a class string, the PID of the leader process of the machine, an | |
183 | optional root directory of the container, and an array of additional properties to use for the scope | |
184 | registration. The virtual machine name must be suitable as hostname, and hence should follow the usual | |
185 | DNS hostname rules, as well as Linux hostname restrictions. Specifically: only 7 Bit ASCII is | |
186 | permitted, a maximum length of 64 characters is enforced, only characters from the set | |
187 | <literal>a-zA-Z0-9-_.</literal> are allowed, the name may not begin with a dot, and it may not contain | |
188 | two dots immediately following each other. Container and VM managers should ideally use the hostname | |
189 | used internally in the machine for this parameter. This recommendation is made in order to make the | |
190 | machine name naturally resolvable using | |
191 | <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>. If | |
192 | a container manager needs to embed characters outside of the indicated range, escaping is required, | |
193 | possibly using <literal>_</literal> as the escape character. Another (somewhat natural) option would be | |
194 | to utilize Internet IDNA encoding. The UUID is passed as 32 byte array, or if no suitable UUID is | |
195 | available an empty array (zero length) or zeroed out array shall be passed. The UUID should identify | |
196 | the virtual machine/container uniquely, and should ideally be the same one as | |
197 | <filename>/etc/machine-id</filename> in the VM/container is initialized from. The service string can be | |
198 | free-form, but it is recommended to pass a short lowercase identifier like | |
199 | <literal>systemd-nspawn</literal>, <literal>libvirt-lxc</literal> or similar. The class string should | |
200 | be either <literal>container</literal> or <literal>vm</literal> indicating whether the machine to | |
201 | register is of the respective class. The leader PID should be the host PID of the init process of the | |
202 | container, or the encapsulating process of the VM. If the root directory of the container is known and | |
203 | available in the host's hierarchy, it should be passed, otherwise use the empty string. Finally, the | |
204 | scope properties are passed as array in the same way as to PID1's | |
205 | <function>StartTransientUnit()</function>. This method call will internally register a transient scope | |
206 | unit for the calling client (utilizing the passed scope_properties), and move the leader PID into | |
207 | it. The call returns an object path for the registered machine object, implementing the | |
208 | <interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below). Also see the | |
209 | <ulink url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New Control Group | |
210 | Interfaces</ulink> for details about scope units, and how to alter resource control settings on the | |
211 | created machine at runtime.</para> | |
212 | ||
213 | <para><function>RegisterMachine()</function> is similar to <function>CreateMachine()</function>, | |
214 | however only registers a machine, but does not create a scope unit for it. The caller's unit will be | |
215 | registered instead. This call is only recommended to be used for container or VM managers that are run | |
216 | multiple times, one instance for each container/VM they manage, and are invoked as system | |
217 | services.</para> | |
218 | ||
219 | <para><function>CreateMachineWithNetwork()</function> and | |
220 | <function>RegisterMachineWithNetwork()</function> are similar to <function>CreateMachine()</function> | |
221 | and <function>RegisterMachine()</function> but take an extra argument: an array of network interface | |
222 | indexes that point towards the virtual machine or container. The interface indexes should reference one | |
223 | or more network interfaces on the host that can be used to communicate with the guest. Commonly the | |
224 | passed interface index refers to the host side of a "veth" link (in case of containers), or a | |
225 | "tun"/"tap" link (in case of VMs) or the host side of a bridge interface that bridges access to the | |
226 | VM/container interfaces. Specifying this information is useful to enable support for link-local IPv6 | |
227 | communication to the machines, since the scope field of sockaddr_in6 can be initialized by the | |
228 | specified ifindex. | |
229 | <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry> | |
230 | makes use of this information.</para> | |
231 | ||
232 | <para><function>KillMachine()</function> sends a UNIX signal to the machine's processes. It takes a | |
233 | machine name (as originally passed to <function>CreateMachine()</function> or returned by | |
234 | <function>ListMachines()</function>). An identifier what precisely to send the signal to being either | |
235 | <literal>leader</literal> or <literal>all</literal>, plus a numeric UNIX signal integer.</para> | |
236 | ||
237 | <para><function>TerminateMachine()</function> terminates a virtual machine, killing its processes. It | |
238 | takes a machine name as argument.</para> | |
239 | ||
240 | <para><function>GetMachineAddresses()</function> retrieves the IP addresses of a container. This call | |
241 | returns an array of pairs consisting of an address family specifier (<constant>AF_INET</constant> or | |
242 | <constant>AF_INET6</constant>) and a byte array containing the addresses. This is only supported for | |
243 | containers that make use of network namespacing.</para> | |
244 | ||
245 | <para><function>GetMachineOSRelease()</function> retrieves the OS release information of a | |
246 | container. This call returns an array of key value pairs read from the | |
247 | <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file in | |
248 | the container, and is useful to identify the operating system used in a container.</para> | |
249 | ||
250 | <para><function>OpenMachinePTY()</function> allocates a pseudo TTY in the container and returns a file | |
251 | descriptor and its path. This is equivalent to transitioning into the container and invoking | |
252 | <citerefentry><refentrytitle>posix_openpt</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> | |
253 | ||
254 | <para><function>OpenMachineLogin()</function> allocates a pseudo TTY in the container and ensures that | |
255 | a getty loging prompt of the container is running on the other end. It returns the file descriptor of | |
256 | the PTY plus the PTY path. This is useful for acquiring a pty with a login prompt from the | |
257 | container.</para> | |
258 | ||
259 | <para><function>OpenMachineShell()</function> allocates a pseudo TTY in the container, as the specified | |
260 | user, and invokes an executable of the specified path, with a list of arguments (starting from | |
261 | argv[0]), and an environment block. It then returns the file descriptor of the PTY plus the PTY | |
262 | path.</para> | |
263 | ||
264 | <para><function>BindMountMachine()</function> bind mounts a file or directory from the host into the | |
265 | container. Takes a machine name, the source directory on the host, and the destination directory in the | |
266 | container as argument. Also takes two booleans, one indicating whether the bind mount shall be | |
267 | read-only, the other indicating whether the destination mount point shall be created first, if it is | |
268 | missing.</para> | |
269 | ||
270 | <para><function>CopyFromMachine()</function> copies files or directories from a container into the | |
271 | host. Takes a container name, a source directory in the container and a destination directory on the | |
272 | host as argument. <function>CopyToMachine()</function> does the opposite and copies files from a source | |
273 | directory on the host into a destination directory in the container.</para> | |
274 | ||
275 | <para><function>RemoveImage()</function> removes the image by the specified name.</para> | |
276 | ||
277 | <para><function>RenameImage()</function> renames the specified image to a new name.</para> | |
278 | ||
279 | <para><function>CloneImage()</function> clones the specified image under a new name. Also takes a | |
280 | boolean argument indicating whether the resuling image shall be read-only or not.</para> | |
281 | ||
282 | <para><function>MarkImageReadOnly()</function> toggles the read-only flag of an image.</para> | |
283 | ||
284 | <para><function>SetPoolLimit()</function> sets an overall quota limit on the pool of images.</para> | |
285 | ||
286 | <para><function>SetImageLimit()</function> sets a per-image quota limit.</para> | |
287 | ||
288 | <para><function>MapFromMachineUser()</function>, <function>MapToMachineUser()</function>, | |
289 | <function>MapFromMachineGroup()</function>, <function>MapToMachineGroup()</function> may be used to map | |
290 | UIDs/GIDs from the host user namespace to a container namespace or back.</para> | |
291 | </refsect2> | |
292 | ||
293 | <refsect2> | |
294 | <title>Signals</title> | |
295 | ||
296 | <para><function>MachineNew</function> and <function>MachineRemoved</function> are sent whenever a new | |
297 | machine is registered or removed. These signals carry the machine name plus the object path to the | |
298 | <interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below).</para> | |
299 | </refsect2> | |
300 | ||
301 | <refsect2> | |
302 | <title>Properties</title> | |
303 | ||
304 | <para><varname>PoolPath</varname> specifies the file system path where images are written to.</para> | |
305 | ||
306 | <para><varname>PoolUsage</varname> specifies the current usage size of the image pool in bytes.</para> | |
307 | ||
308 | <para><varname>PoolLimit</varname> specifies the size limit of the image pool in bytes.</para> | |
309 | </refsect2> | |
310 | </refsect1> | |
311 | ||
312 | <refsect1> | |
313 | <title>Machine Objects</title> | |
314 | ||
315 | <programlisting> | |
316 | $ gdbus introspect --system \ | |
317 | --dest org.freedesktop.machine1 \ | |
318 | --object-path /org/freedesktop/machine1/machine/rawhide | |
319 | ||
320 | node /org/freedesktop/machine1/machine/fedora_2dtree { | |
321 | interface org.freedesktop.machine1.Machine { | |
322 | methods: | |
323 | Terminate(); | |
324 | Kill(in s who, | |
325 | in s signal); | |
326 | GetAddresses(out a(iay) addresses); | |
327 | GetOSRelease(out a{ss} fields); | |
328 | signals: | |
329 | properties: | |
330 | readonly s Name = 'fedora-tree'; | |
331 | readonly ay Id = [0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]; | |
332 | readonly t Timestamp = 1374193370484284; | |
333 | readonly t TimestampMonotonic = 128247251308; | |
334 | readonly s Service = 'nspawn'; | |
335 | readonly s Unit = 'machine-fedora\\x2dtree.scope'; | |
336 | readonly u Leader = 30046; | |
337 | readonly s Class = 'container'; | |
338 | readonly s RootDirectory = '/home/lennart/fedora-tree'; | |
339 | readonly ai NetworkInterfaces = [7]; | |
340 | readonly s State = 'running'; | |
341 | }; | |
342 | interface org.freedesktop.DBus.Properties { | |
343 | }; | |
344 | interface org.freedesktop.DBus.Peer { | |
345 | }; | |
346 | interface org.freedesktop.DBus.Introspectable { | |
347 | }; | |
348 | }; | |
349 | </programlisting> | |
350 | ||
351 | <refsect2> | |
352 | <title>Methods</title> | |
353 | ||
354 | <para><function>Terminate()</function> and <function>Kill()</function> terminate/kill the machine, and | |
355 | take the same arguments as <function>TerminateMachine()</function> and | |
356 | <function>KillMachine()</function> on the Manager interface.</para> | |
357 | ||
358 | <para><function>GetAddresses()</function> and <function>GetOSRelease()</function> get IP address and OS | |
359 | release information from the machine, and take the same arguments as | |
360 | <function>GetMachineAddresses()</function> and <function>GetMachineOSRelease()</function> of the | |
361 | Manager interface, described above.</para> | |
362 | </refsect2> | |
363 | ||
364 | <refsect2> | |
365 | <title>Properties</title> | |
366 | ||
367 | <para><varname>Name</varname> is the machine name, as it was passed in during registration with | |
368 | <function>CreateMachine()</function> on the manager object.</para> | |
369 | ||
370 | <para><varname>Id</varname> is the machine UUID.</para> | |
371 | ||
372 | <para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> are the realtime and | |
373 | monotonic timestamps when the virtual machines where created.</para> | |
374 | ||
375 | <para><varname>Service</varname> contains a short string identifying the registering service, as passed | |
376 | in during registration of the machine.</para> | |
377 | ||
378 | <para><varname>Unit</varname> is the systemd scope or service unit name for the machine.</para> | |
379 | ||
380 | <para><varname>Leader</varname> is the PID of the leader process of the machine.</para> | |
381 | ||
382 | <para><varname>Class</varname> is the class of the machine and either the string "vm" (for real VMs | |
383 | based on virtualized hardware) or "container" (for light-weight userspace virtualization sharing the | |
384 | same kernel as the host).</para> | |
385 | ||
386 | <para><varname>RootDirectory</varname> is the root directory of the container if that is known and | |
387 | applicable, or the empty string.</para> | |
388 | ||
389 | <para><varname>NetworkInterfaces</varname> contains an array of network interface indexes that point | |
390 | towards the container or VM or the host. For details about this information see the description of | |
391 | <function>CreateMachineWithNetwork()</function> above.</para> | |
392 | ||
393 | <para><varname>State</varname> is the state of the machine, and one of <literal>opening</literal>, | |
394 | <literal>running</literal>, <literal>closing</literal>. Note that the state machine is not considered | |
395 | part of the API and states might be removed or added without this being considered API breakage. | |
396 | </para> | |
397 | </refsect2> | |
398 | </refsect1> | |
399 | ||
400 | <refsect1> | |
401 | <title>Versioning</title> | |
402 | ||
403 | <para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html"> | |
404 | the usual interface versioning guidelines</ulink>.</para> | |
405 | </refsect1> | |
406 | </refentry> |