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