diff options
author | Daan De Meyer <daan.j.demeyer@gmail.com> | 2020-04-14 13:43:11 +0200 |
---|---|---|
committer | Zbigniew Jędrzejewski-Szmek <zbyszek@in.waw.pl> | 2020-04-16 20:12:56 +0200 |
commit | ca264f7d96df3c33ad808b5ca4c4fc8acadc0067 (patch) | |
tree | a062db3bd335d124b2fbd08a7e3e1c5122db4033 /man/org.freedesktop.machine1.xml | |
parent | ae53ea522600b1fc9a25347632299048f4f4c600 (diff) | |
download | systemd-ca264f7d96df3c33ad808b5ca4c4fc8acadc0067.tar.gz |
man: fixes from online review
Also includes the issues pointed out by @boucman.
Diffstat (limited to 'man/org.freedesktop.machine1.xml')
-rw-r--r-- | man/org.freedesktop.machine1.xml | 124 |
1 files changed, 62 insertions, 62 deletions
diff --git a/man/org.freedesktop.machine1.xml b/man/org.freedesktop.machine1.xml index 1c9c41f04c..0b35ab4313 100644 --- a/man/org.freedesktop.machine1.xml +++ b/man/org.freedesktop.machine1.xml @@ -177,27 +177,27 @@ node /org/freedesktop/machine1 { <title>Methods</title> <para><function>GetMachine()</function> may be used to get the machine object path for the machine with - the specified name. Similarly, <function>GetMachineByPID()</function> get the machine object the + the specified name. Similarly, <function>GetMachineByPID()</function> gets the machine object the specified PID belongs to if there is any.</para> - <para><function>GetImage()</function> may be used to the the image object path for the image with the + <para><function>GetImage()</function> may be used to get the image object path of the image with the specified name.</para> - <para><function>ListMachines()</function> returns an array with all currently registered machines. The + <para><function>ListMachines()</function> returns an array of all currently registered machines. The 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> - <para><function>ListImages()</function> returns an array with all currently known images. The + <para><function>ListImages()</function> returns an array of all currently known images. The structures in the array consist of the following fields: image name, type, read-only flag, creation - time, modification time, current disk space, image object path.</para> + time, modification time, current disk space, and image object path.</para> <para><function>CreateMachine()</function> may be used to register a new virtual machine or container - with <command>systemd-machined</command>, creating a scope unit for it. This takes as arguments: a - machine name chosen by the registrar, an optional UUID as 32 byte array, a string that identifies the + 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 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 - registration. The virtual machine name must be suitable as hostname, and hence should follow the usual - DNS hostname rules, as well as Linux hostname restrictions. Specifically: only 7 Bit ASCII is + 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 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 @@ -206,51 +206,51 @@ node /org/freedesktop/machine1 { <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 - to utilize Internet IDNA encoding. The UUID is passed as 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 one as + 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 <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 - 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 use the empty string. Finally, the + 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 scope properties are passed as array in the same way as to PID1's - <function>StartTransientUnit()</function>. This method call will internally register a transient scope - unit for the calling client (utilizing the passed scope_properties), and move the leader PID into - it. The call returns an object path for the registered machine object, implementing the + <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 + it. The call returns an object path for the registered machine object that implements the <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 - Interfaces</ulink> for details about scope units, and how to alter resource control settings on the + Interfaces</ulink> for details about scope units and how to alter resource control settings on the created machine at runtime.</para> - <para><function>RegisterMachine()</function> is similar to <function>CreateMachine()</function>, - however only registers a machine, but does not create a scope unit for it. The caller's unit will be - registered instead. This call is only recommended to be used for container or VM managers that are run + <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 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 - indexes that point towards the virtual machine or container. The interface indexes 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), or a - "tun"/"tap" link (in case of VMs) or the host side of a bridge interface that bridges access to the + 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 VM/container interfaces. Specifying this information is useful to enable support for link-local IPv6 - communication to the machines, since the scope field of sockaddr_in6 can be initialized by the + communication to the machines since the scope field of sockaddr_in6 can be initialized by the specified ifindex. <citerefentry><refentrytitle>nss-mymachines</refentrytitle><manvolnum>8</manvolnum></citerefentry> makes use of this information.</para> - <para><function>KillMachine()</function> sends a UNIX signal to the machine's processes. It takes a + <para><function>KillMachine()</function> sends a UNIX signal to the machine's processes. As its arguments, it takes a machine name (as originally passed to <function>CreateMachine()</function> or returned by - <function>ListMachines()</function>). An identifier what precisely to send the signal to being either - <literal>leader</literal> or <literal>all</literal>, plus a numeric UNIX signal integer.</para> + <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> <para><function>TerminateMachine()</function> terminates a virtual machine, killing its processes. It - takes a machine name as argument.</para> + takes a machine name as its only argument.</para> <para><function>GetMachineAddresses()</function> retrieves the IP addresses of a container. This call returns an array of pairs consisting of an address family specifier (<constant>AF_INET</constant> or @@ -258,41 +258,41 @@ node /org/freedesktop/machine1 { containers that make use of network namespacing.</para> <para><function>GetMachineOSRelease()</function> retrieves the OS release information of a - container. This call returns an array of key value pairs read from the + container. This method returns an array of key value pairs read from the <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file in - the container, and is useful to identify the operating system used in a container.</para> + the container and is useful to identify the operating system used in a container.</para> <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 <citerefentry><refentrytitle>posix_openpt</refentrytitle><manvolnum>3</manvolnum></citerefentry>.</para> <para><function>OpenMachineLogin()</function> allocates a pseudo TTY in the container and ensures that - a getty loging prompt of the container is running on the other end. It returns the file descriptor of - the PTY plus the PTY path. This is useful for acquiring a pty with a login prompt from the + 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 container.</para> <para><function>OpenMachineShell()</function> allocates a pseudo TTY in the container, as the specified - user, and invokes an executable of 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 plus the PTY + 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 path.</para> <para><function>BindMountMachine()</function> bind mounts a file or directory from the host into the - container. Takes a machine name, the source directory on the host, and the destination directory in the - container as argument. Also takes two booleans, one indicating whether the bind mount shall be + 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 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 - host. Takes a container name, a source directory in the container and a destination directory on the - host as argument. <function>CopyToMachine()</function> does the opposite and copies files from a source + 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 directory on the host into a destination directory in the container.</para> - <para><function>RemoveImage()</function> removes the image by the specified name.</para> + <para><function>RemoveImage()</function> removes the image with the specified name.</para> - <para><function>RenameImage()</function> renames the specified image to a new name.</para> + <para><function>RenameImage()</function> renames the specified image.</para> - <para><function>CloneImage()</function> clones the specified image under a new name. Also takes a - boolean argument indicating whether the resuling image shall be read-only or not.</para> + <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> <para><function>MarkImageReadOnly()</function> toggles the read-only flag of an image.</para> @@ -301,15 +301,15 @@ node /org/freedesktop/machine1 { <para><function>SetImageLimit()</function> sets a per-image quota limit.</para> <para><function>MapFromMachineUser()</function>, <function>MapToMachineUser()</function>, - <function>MapFromMachineGroup()</function>, <function>MapToMachineGroup()</function> may be used to map - UIDs/GIDs from the host user namespace to a container namespace or back.</para> + <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> </refsect2> <refsect2> <title>Signals</title> <para><function>MachineNew</function> and <function>MachineRemoved</function> are sent whenever a new - machine is registered or removed. These signals carry the machine name plus the object path to the + machine is registered or removed. These signals carry the machine name and the object path to the corresponding <interfacename>org.freedesktop.machine1.Machine</interfacename> interface (see below).</para> </refsect2> @@ -393,47 +393,47 @@ node /org/freedesktop/machine1/machine/rawhide { <refsect2> <title>Methods</title> - <para><function>Terminate()</function> and <function>Kill()</function> terminate/kill the machine, and + <para><function>Terminate()</function> and <function>Kill()</function> terminate/kill the machine. These methods take the same arguments as <function>TerminateMachine()</function> and - <function>KillMachine()</function> on the Manager interface.</para> + <function>KillMachine()</function> on the Manager interface, respectively.</para> - <para><function>GetAddresses()</function> and <function>GetOSRelease()</function> get IP address and OS - release information from the machine, and take the same arguments as + <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 <function>GetMachineAddresses()</function> and <function>GetMachineOSRelease()</function> of the - Manager interface, described above.</para> + Manager interface, respectively.</para> </refsect2> <refsect2> <title>Properties</title> - <para><varname>Name</varname> is the machine name, as it was passed in during registration with + <para><varname>Name</varname> is the machine name as it was passed in during registration with <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 - monotonic timestamps when the virtual machines where created.</para> + monotonic timestamps when the virtual machines where created in microseconds since the epoch.</para> - <para><varname>Service</varname> contains a short string identifying the registering service, as passed + <para><varname>Service</varname> contains a short string identifying the registering service as passed 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> - <para><varname>Class</varname> is the class of the machine and either the string "vm" (for real VMs + <para><varname>Class</varname> is the class of the machine and is either the string "vm" (for real VMs based on virtualized hardware) or "container" (for light-weight userspace virtualization sharing the same kernel as the host).</para> - <para><varname>RootDirectory</varname> is the root directory of the container if that is known and - applicable, or the empty string.</para> + <para><varname>RootDirectory</varname> is the root directory of the container if it is known and + applicable or the empty string.</para> - <para><varname>NetworkInterfaces</varname> contains an array of network interface indexes that point - towards the container or VM or the host. For details about this information see the description of + <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 <function>CreateMachineWithNetwork()</function> above.</para> - <para><varname>State</varname> is the state of the machine, and one of <literal>opening</literal>, - <literal>running</literal>, <literal>closing</literal>. Note that the state machine is not considered + <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 part of the API and states might be removed or added without this being considered API breakage. </para> </refsect2> |