shaba/systemd
1
0
Fork 0
mirror of https://github.com/systemd/systemd.git synced 2024-11-01 00:51:24 +03:00
Code
8e5658010d
systemd/man/org.freedesktop.machine1.xml

644 lines
30 KiB
XML
Raw Normal View History

man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<?xml version='1.0'?>
<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" >
license: LGPL-2.1+ -> LGPL-2.1-or-later
2020-11-09 07:23:58 +03:00
<!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<refentry id="org.freedesktop.machine1" conditional='ENABLE_MACHINED'
xmlns:xi="http://www.w3.org/2001/XInclude">
<refentryinfo>
<title>org.freedesktop.machine1</title>
<productname>systemd</productname>
</refentryinfo>
<refmeta>
<refentrytitle>org.freedesktop.machine1</refentrytitle>
<manvolnum>5</manvolnum>
</refmeta>
<refnamediv>
<refname>org.freedesktop.machine1</refname>
<refpurpose>The D-Bus interface of systemd-machined</refpurpose>
</refnamediv>
<refsect1>
<title>Introduction</title>
<para>
<citerefentry><refentrytitle>systemd-machined.service</refentrytitle><manvolnum>8</manvolnum></citerefentry>
is a system service that keeps track of locally running virtual machines and containers.
This page describes the D-Bus interface.</para>
</refsect1>
<refsect1>
<title>The Manager Object</title>
<para>The service exposes the following interfaces on the Manager object on the bus:</para>
man: use --bus-introspect to autogenerate dbus api docs This has the advantage that the executables are always in place and we don't need any units to exist on the bus, so we can eventually hook this up into a normal build system. (Probably as a build time check.)
2020-04-24 13:08:10 +03:00
<programlisting executable="systemd-machined" node="/org/freedesktop/machine1" interface="org.freedesktop.machine1.Manager">
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
node /org/freedesktop/machine1 {
interface org.freedesktop.machine1.Manager {
methods:
GetMachine(in s name,
out o machine);
GetImage(in s name,
out o image);
GetMachineByPID(in u pid,
out o machine);
ListMachines(out a(ssso) machines);
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
ListImages(out a(ssbttto) images);
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
CreateMachine(in s name,
in ay id,
in s service,
in s class,
in u leader,
in s root_directory,
in a(sv) scope_properties,
out o path);
CreateMachineWithNetwork(in s name,
in ay id,
in s service,
in s class,
in u leader,
in s root_directory,
in ai ifindices,
in a(sv) scope_properties,
out o path);
RegisterMachine(in s name,
in ay id,
in s service,
in s class,
in u leader,
in s root_directory,
out o path);
RegisterMachineWithNetwork(in s name,
in ay id,
in s service,
in s class,
in u leader,
in s root_directory,
in ai ifindices,
out o path);
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
UnregisterMachine(in s name);
TerminateMachine(in s id);
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
KillMachine(in s name,
in s who,
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
in i signal);
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
GetMachineAddresses(in s name,
out a(iay) addresses);
GetMachineOSRelease(in s name,
out a{ss} fields);
OpenMachinePTY(in s name,
out h pty,
out s pty_path);
OpenMachineLogin(in s name,
out h pty,
out s pty_path);
OpenMachineShell(in s name,
in s user,
in s path,
in as args,
in as environment,
out h pty,
out s pty_path);
BindMountMachine(in s name,
in s source,
in s destination,
in b read_only,
in b mkdir);
CopyFromMachine(in s name,
in s source,
in s destination);
CopyToMachine(in s name,
in s source,
in s destination);
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
OpenMachineRootDirectory(in s name,
out h fd);
GetMachineUIDShift(in s name,
out u shift);
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
RemoveImage(in s name);
RenameImage(in s name,
in s new_name);
CloneImage(in s name,
in s new_name,
in b read_only);
MarkImageReadOnly(in s name,
in b read_only);
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
GetImageHostname(in s name,
out s hostname);
GetImageMachineID(in s name,
out ay id);
GetImageMachineInfo(in s name,
out a{ss} machine_info);
GetImageOSRelease(in s name,
out a{ss} os_release);
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
SetPoolLimit(in t size);
SetImageLimit(in s name,
in t size);
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
CleanPool(in s mode,
out a(st) images);
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
MapFromMachineUser(in s name,
in u uid_inner,
out u uid_outer);
MapToMachineUser(in u uid_outer,
out s machine_name,
out o machine_path,
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
out u uid_inner);
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
MapFromMachineGroup(in s name,
in u gid_inner,
out u gid_outer);
MapToMachineGroup(in u gid_outer,
out s machine_name,
out o machine_path,
out u gid_inner);
signals:
MachineNew(s machine,
o path);
MachineRemoved(s machine,
o path);
properties:
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s PoolPath = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly t PoolUsage = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly t PoolLimit = ...;
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
};
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
};
man: add markers to put all dbus entities in the directives index Follow-up for f92c8d1c67bcdeba097e3203d8aafe3a31230ada. directives.index: - This index contains 3398 entries in 19 sections, referring to 333 individual + This index contains 4316 entries in 19 sections, referring to 333 individual
2020-04-21 11:29:09 +03:00
</programlisting>
<!--method UnregisterMachine is not documented!-->
<!--method OpenMachineRootDirectory is not documented!-->
<!--method GetMachineUIDShift is not documented!-->
<!--method GetImageHostname is not documented!-->
<!--method GetImageMachineID is not documented!-->
<!--method GetImageMachineInfo is not documented!-->
<!--method GetImageOSRelease is not documented!-->
<!--method CleanPool is not documented!-->
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Manager"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Manager"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetImage()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetMachineByPID()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ListMachines()"/>
<variablelist class="dbus-method" generated="True" extra-ref="ListImages()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CreateMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CreateMachineWithNetwork()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RegisterMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RegisterMachineWithNetwork()"/>
<variablelist class="dbus-method" generated="True" extra-ref="UnregisterMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="TerminateMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="KillMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetMachineAddresses()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetMachineOSRelease()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenMachinePTY()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenMachineLogin()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenMachineShell()"/>
<variablelist class="dbus-method" generated="True" extra-ref="BindMountMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CopyFromMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CopyToMachine()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenMachineRootDirectory()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetMachineUIDShift()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RemoveImage()"/>
<variablelist class="dbus-method" generated="True" extra-ref="RenameImage()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CloneImage()"/>
<variablelist class="dbus-method" generated="True" extra-ref="MarkImageReadOnly()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetImageHostname()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetImageMachineID()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetImageMachineInfo()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetImageOSRelease()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetPoolLimit()"/>
<variablelist class="dbus-method" generated="True" extra-ref="SetImageLimit()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CleanPool()"/>
<variablelist class="dbus-method" generated="True" extra-ref="MapFromMachineUser()"/>
<variablelist class="dbus-method" generated="True" extra-ref="MapToMachineUser()"/>
<variablelist class="dbus-method" generated="True" extra-ref="MapFromMachineGroup()"/>
<variablelist class="dbus-method" generated="True" extra-ref="MapToMachineGroup()"/>
<variablelist class="dbus-signal" generated="True" extra-ref="MachineNew"/>
<variablelist class="dbus-signal" generated="True" extra-ref="MachineRemoved"/>
<variablelist class="dbus-property" generated="True" extra-ref="PoolPath"/>
<variablelist class="dbus-property" generated="True" extra-ref="PoolUsage"/>
<variablelist class="dbus-property" generated="True" extra-ref="PoolLimit"/>
<!--End of Autogenerated section-->
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<refsect2>
<title>Methods</title>
<para><function>GetMachine()</function> may be used to get the machine object path for the machine with
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
the specified name. Similarly, <function>GetMachineByPID()</function> gets the machine object the
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
specified PID belongs to if there is any.</para>
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><function>GetImage()</function> may be used to get the image object path of the image with the
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
specified name.</para>
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><function>ListMachines()</function> returns an array of all currently registered machines. The
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
structures in the array consist of the following fields: machine name, machine class, an identifier for
the service that registered the machine and the machine object path.</para>
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><function>ListImages()</function> returns an array of all currently known images. The
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
structures in the array consist of the following fields: image name, type, read-only flag, creation
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
time, modification time, current disk space, and image object path.</para>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<para><function>CreateMachine()</function> may be used to register a new virtual machine or container
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
with <command>systemd-machined</command>, creating a scope unit for it. It accepts the following arguments: a
machine name chosen by the registrar, an optional UUID as a 32 byte array, a string that identifies the
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
service that registers the machine, a class string, the PID of the leader process of the machine, an
optional root directory of the container, and an array of additional properties to use for the scope
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
registration. The virtual machine name must be suitable as a hostname, and hence should follow the usual
DNS hostname rules, as well as the Linux hostname restrictions. Specifically, only 7 bit ASCII is
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
permitted, a maximum length of 64 characters is enforced, only characters from the set
<literal>a-zA-Z0-9-_.</literal> are allowed, the name may not begin with a dot, and it may not contain
two dots immediately following each other. Container and VM managers should ideally use the hostname
used internally in the machine for this parameter. This recommendation is made in order to make the
machine name naturally resolvable using
<citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>. If
a container manager needs to embed characters outside of the indicated range, escaping is required,
possibly using <literal>_</literal> as the escape character. Another (somewhat natural) option would be
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
to utilize Internet IDNA encoding. The UUID is passed as a 32 byte array or, if no suitable UUID is
available, an empty array (zero length) or zeroed out array shall be passed. The UUID should identify
the virtual machine/container uniquely and should ideally be the same UUID that
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<filename>/etc/machine-id</filename> in the VM/container is initialized from. The service string can be
free-form, but it is recommended to pass a short lowercase identifier like
<literal>systemd-nspawn</literal>, <literal>libvirt-lxc</literal> or similar. The class string should
be either <literal>container</literal> or <literal>vm</literal> indicating whether the machine to
register is of the respective class. The leader PID should be the host PID of the init process of the
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
container or the encapsulating process of the VM. If the root directory of the container is known and
available in the host's hierarchy, it should be passed. Otherwise, pass the empty string instead. Finally, the
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
scope properties are passed as array in the same way as to PID1's
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<function>StartTransientUnit()</function> method. Calling this method will internally register a transient scope
unit for the calling client (utilizing the passed scope_properties) and move the leader PID into
D-Bus docs: Use method instead of call
2020-04-19 14:05:20 +03:00
it. The method returns an object path for the registered machine object that implements the
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below). Also see the
<ulink url="https://www.freedesktop.org/wiki/Software/systemd/ControlGroupInterface/">New Control Group
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
Interfaces</ulink> for details about scope units and how to alter resource control settings on the
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
created machine at runtime.</para>
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><function>RegisterMachine()</function> is similar to <function>CreateMachine()</function>.
However, it only registers a machine and does not create a scope unit for it. Instead, the caller's unit is
registered. We recommend to only use this method for container or VM managers that are run
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
multiple times, one instance for each container/VM they manage, and are invoked as system
services.</para>
<para><function>CreateMachineWithNetwork()</function> and
<function>RegisterMachineWithNetwork()</function> are similar to <function>CreateMachine()</function>
and <function>RegisterMachine()</function> but take an extra argument: an array of network interface
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
indices that point towards the virtual machine or container. The interface indices should reference one
or more network interfaces on the host that can be used to communicate with the guest. Commonly, the
passed interface index refers to the host side of a "veth" link (in case of containers), a
"tun"/"tap" link (in case of VMs), or the host side of a bridge interface that bridges access to the
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
VM/container interfaces. Specifying this information is useful to enable support for link-local IPv6
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
communication to the machines since the scope field of sockaddr_in6 can be initialized by the
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
specified ifindex.
<citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry>
makes use of this information.</para>
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><function>KillMachine()</function> sends a UNIX signal to the machine's processes. As its arguments, it takes a
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
machine name (as originally passed to <function>CreateMachine()</function> or returned by
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<function>ListMachines()</function>), an identifier that specifies what precisely to send the signal to (either
<literal>leader</literal> or <literal>all</literal>), and a numeric UNIX signal integer.</para>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<para><function>TerminateMachine()</function> terminates a virtual machine, killing its processes. It
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
takes a machine name as its only argument.</para>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
D-Bus docs: Use method instead of call
2020-04-19 14:05:20 +03:00
<para><function>GetMachineAddresses()</function> retrieves the IP addresses of a container. This method
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
returns an array of pairs consisting of an address family specifier (<constant>AF_INET</constant> or
<constant>AF_INET6</constant>) and a byte array containing the addresses. This is only supported for
containers that make use of network namespacing.</para>
<para><function>GetMachineOSRelease()</function> retrieves the OS release information of a
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
container. This method returns an array of key value pairs read from the
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file in
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
the container and is useful to identify the operating system used in a container.</para>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<para><function>OpenMachinePTY()</function> allocates a pseudo TTY in the container and returns a file
descriptor and its path. This is equivalent to transitioning into the container and invoking
man: import lxml formatting changes lxml insists on this, see 4fb222c4b29ec2a1a451a1e0e99c5d3c520395ab.
2020-08-22 13:24:32 +03:00
<citerefentry project="man-pages"><refentrytitle>posix_openpt</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
man: fix links to various external man pages In cases where we used both die-net and man-pages for the same reference, I switched to use man-pages everywhere.
2020-06-25 15:37:24 +03:00
</para>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<para><function>OpenMachineLogin()</function> allocates a pseudo TTY in the container and ensures that
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
a getty login prompt of the container is running on the other end. It returns the file descriptor of
the PTY and the PTY path. This is useful for acquiring a pty with a login prompt from the
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
container.</para>
<para><function>OpenMachineShell()</function> allocates a pseudo TTY in the container, as the specified
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
user, and invokes the executable at the specified path with a list of arguments (starting from
argv[0]) and an environment block. It then returns the file descriptor of the PTY and the PTY
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
path.</para>
<para><function>BindMountMachine()</function> bind mounts a file or directory from the host into the
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
container. Its arguments consist of a machine name, the source directory on the host, the destination directory in the
container, and two booleans, one indicating whether the bind mount shall be
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
read-only, the other indicating whether the destination mount point shall be created first, if it is
missing.</para>
<para><function>CopyFromMachine()</function> copies files or directories from a container into the
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
host. It takes a container name, a source directory in the container and a destination directory on the
host as arguments. <function>CopyToMachine()</function> does the opposite and copies files from a source
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
directory on the host into a destination directory in the container.</para>
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><function>RemoveImage()</function> removes the image with the specified name.</para>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><function>RenameImage()</function> renames the specified image.</para>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><function>CloneImage()</function> clones the specified image under a new name. It also takes a
boolean argument indicating whether the resulting image shall be read-only or not.</para>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<para><function>MarkImageReadOnly()</function> toggles the read-only flag of an image.</para>
<para><function>SetPoolLimit()</function> sets an overall quota limit on the pool of images.</para>
<para><function>SetImageLimit()</function> sets a per-image quota limit.</para>
<para><function>MapFromMachineUser()</function>, <function>MapToMachineUser()</function>,
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<function>MapFromMachineGroup()</function>, and <function>MapToMachineGroup()</function> may be used to map
UIDs/GIDs from the host user namespace to a container user namespace or vice versa.</para>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
</refsect2>
<refsect2>
<title>Signals</title>
<para><function>MachineNew</function> and <function>MachineRemoved</function> are sent whenever a new
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
machine is registered or removed. These signals carry the machine name and the object path to the corresponding
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below).</para>
</refsect2>
<refsect2>
<title>Properties</title>
<para><varname>PoolPath</varname> specifies the file system path where images are written to.</para>
<para><varname>PoolUsage</varname> specifies the current usage size of the image pool in bytes.</para>
<para><varname>PoolLimit</varname> specifies the size limit of the image pool in bytes.</para>
</refsect2>
</refsect1>
<refsect1>
<title>Machine Objects</title>
man: use --bus-introspect to autogenerate dbus api docs This has the advantage that the executables are always in place and we don't need any units to exist on the bus, so we can eventually hook this up into a normal build system. (Probably as a build time check.)
2020-04-24 13:08:10 +03:00
<programlisting executable="systemd-machined" node="/org/freedesktop/machine1/machine/rawhide" interface="org.freedesktop.machine1.Machine">
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
node /org/freedesktop/machine1/machine/rawhide {
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
interface org.freedesktop.machine1.Machine {
methods:
Terminate();
Kill(in s who,
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
in i signal);
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
GetAddresses(out a(iay) addresses);
GetOSRelease(out a{ss} fields);
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
GetUIDShift(out u shift);
OpenPTY(out h pty,
out s pty_path);
OpenLogin(out h pty,
out s pty_path);
OpenShell(in s user,
in s path,
in as args,
in as environment,
out h pty,
out s pty_path);
BindMount(in s source,
in s destination,
in b read_only,
in b mkdir);
CopyFrom(in s source,
in s destination);
CopyTo(in s source,
in s destination);
OpenRootDirectory(out h fd);
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
properties:
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Name = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly ay Id = [...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t Timestamp = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly t TimestampMonotonic = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Service = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Unit = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly u Leader = ...;
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s Class = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly s RootDirectory = '...';
@org.freedesktop.DBus.Property.EmitsChangedSignal("const")
readonly ai NetworkInterfaces = [...];
@org.freedesktop.DBus.Property.EmitsChangedSignal("false")
readonly s State = '...';
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
};
man: run dbus api docs through the updater This replaces the api export tables with updated versions, and inserts comments for all "undocumented" items. The slow work of documented them is left for later ;) lxml does some formatting changes that are not significant for lxml processing, but generate spurious difference in the diff (namely: ulinks become one-line, and double quotes are used instead of single quotes for element attribute values). This should be a one-time thing: subsequent renegeration should be idempotent with regards to this.
2020-04-10 16:07:03 +03:00
interface org.freedesktop.DBus.Peer { ... };
interface org.freedesktop.DBus.Introspectable { ... };
interface org.freedesktop.DBus.Properties { ... };
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
};
</programlisting>
man: add markers to put all dbus entities in the directives index Follow-up for f92c8d1c67bcdeba097e3203d8aafe3a31230ada. directives.index: - This index contains 3398 entries in 19 sections, referring to 333 individual + This index contains 4316 entries in 19 sections, referring to 333 individual
2020-04-21 11:29:09 +03:00
<!--method GetUIDShift is not documented!-->
<!--method OpenPTY is not documented!-->
<!--method OpenLogin is not documented!-->
<!--method OpenShell is not documented!-->
<!--method BindMount is not documented!-->
<!--method CopyFrom is not documented!-->
<!--method CopyTo is not documented!-->
<!--method OpenRootDirectory is not documented!-->
<!--Autogenerated cross-references for systemd.directives, do not edit-->
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Machine"/>
<variablelist class="dbus-interface" generated="True" extra-ref="org.freedesktop.machine1.Machine"/>
<variablelist class="dbus-method" generated="True" extra-ref="Terminate()"/>
<variablelist class="dbus-method" generated="True" extra-ref="Kill()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetAddresses()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetOSRelease()"/>
<variablelist class="dbus-method" generated="True" extra-ref="GetUIDShift()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenPTY()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenLogin()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenShell()"/>
<variablelist class="dbus-method" generated="True" extra-ref="BindMount()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CopyFrom()"/>
<variablelist class="dbus-method" generated="True" extra-ref="CopyTo()"/>
<variablelist class="dbus-method" generated="True" extra-ref="OpenRootDirectory()"/>
<variablelist class="dbus-property" generated="True" extra-ref="Name"/>
<variablelist class="dbus-property" generated="True" extra-ref="Id"/>
<variablelist class="dbus-property" generated="True" extra-ref="Timestamp"/>
<variablelist class="dbus-property" generated="True" extra-ref="TimestampMonotonic"/>
<variablelist class="dbus-property" generated="True" extra-ref="Service"/>
<variablelist class="dbus-property" generated="True" extra-ref="Unit"/>
<variablelist class="dbus-property" generated="True" extra-ref="Leader"/>
<variablelist class="dbus-property" generated="True" extra-ref="Class"/>
<variablelist class="dbus-property" generated="True" extra-ref="RootDirectory"/>
<variablelist class="dbus-property" generated="True" extra-ref="NetworkInterfaces"/>
<variablelist class="dbus-property" generated="True" extra-ref="State"/>
<!--End of Autogenerated section-->
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<refsect2>
<title>Methods</title>
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><function>Terminate()</function> and <function>Kill()</function> terminate/kill the machine. These methods
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
take the same arguments as <function>TerminateMachine()</function> and
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<function>KillMachine()</function> on the Manager interface, respectively.</para>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><function>GetAddresses()</function> and <function>GetOSRelease()</function> get the IP address and OS
release information from the machine. These methods take the same arguments as
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<function>GetMachineAddresses()</function> and <function>GetMachineOSRelease()</function> of the
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
Manager interface, respectively.</para>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
</refsect2>
<refsect2>
<title>Properties</title>
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><varname>Name</varname> is the machine name as it was passed in during registration with
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<function>CreateMachine()</function> on the manager object.</para>
<para><varname>Id</varname> is the machine UUID.</para>
<para><varname>Timestamp</varname> and <varname>TimestampMonotonic</varname> are the realtime and
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
monotonic timestamps when the virtual machines where created in microseconds since the epoch.</para>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><varname>Service</varname> contains a short string identifying the registering service as passed
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
in during registration of the machine.</para>
<para><varname>Unit</varname> is the systemd scope or service unit name for the machine.</para>
<para><varname>Leader</varname> is the PID of the leader process of the machine.</para>
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><varname>Class</varname> is the class of the machine and is either the string "vm" (for real VMs
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
based on virtualized hardware) or "container" (for light-weight userspace virtualization sharing the
same kernel as the host).</para>
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><varname>RootDirectory</varname> is the root directory of the container if it is known and
applicable or the empty string.</para>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><varname>NetworkInterfaces</varname> contains an array of network interface indices that point
towards the container, the VM or the host. For details about this information see the description of
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<function>CreateMachineWithNetwork()</function> above.</para>
man: fixes from online review Also includes the issues pointed out by @boucman.
2020-04-14 14:43:11 +03:00
<para><varname>State</varname> is the state of the machine and is one of <literal>opening</literal>,
<literal>running</literal>, or <literal>closing</literal>. Note that the state machine is not considered
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
part of the API and states might be removed or added without this being considered API breakage.
</para>
</refsect2>
</refsect1>
man: use --bus-introspect to autogenerate dbus api docs This has the advantage that the executables are always in place and we don't need any units to exist on the bus, so we can eventually hook this up into a normal build system. (Probably as a build time check.)
2020-04-24 13:08:10 +03:00
<refsect1>
<title>Examples</title>
<example>
<title>Introspect <interfacename>org.freedesktop.machine1.Manager</interfacename> on the bus</title>
<programlisting>
$ gdbus introspect --system \
--dest org.freedesktop.machine1 \
--object-path /org/freedesktop/machine1
</programlisting>
</example>
<example>
<title>Introspect <interfacename>org.freedesktop.machine1.Machine</interfacename> on the bus</title>
<programlisting>
$ gdbus introspect --system \
--dest org.freedesktop.machine1 \
--object-path /org/freedesktop/machine1/machine/rawhide
</programlisting>
</example>
</refsect1>
man: import org.freedesktop.machine1(3) from the wiki The wiki was primarily describing the D-Bus API, but it also had a large introduction to the daemon functionality. I moved that latter part into the page that describes the daemon, and the API description into the new page. This is mostly a straighforward import. Apart from some required formatting changes, I removed obvious repetitions, and made tiny grammar and typo fixes where I noticed them. The goal is not to have a perfect text immediately. <interfacename>org.foo.bar</interface> is used for interface names, <function>function()</function> for methods, and <function>signal</function> (no parentheses) for signal names. In D-Bus, signals are similar to methods, and docbook doesn't have a nice tag for them.
2020-04-07 22:22:13 +03:00
<refsect1>
<title>Versioning</title>
<para>These D-Bus interfaces follow <ulink url="http://0pointer.de/blog/projects/versioning-dbus.html">
the usual interface versioning guidelines</ulink>.</para>
</refsect1>
</refentry>
Copy Permalink