Merging upstream version 256.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

1 files changed, 46 insertions, 11 deletions

diff --git a/man/org.freedesktop.machine1.xml b/man/org.freedesktop.machine1.xml
index 1af77e0..8abef00 100644
--- a/man/org.freedesktop.machine1.xml
+++ b/man/org.freedesktop.machine1.xml
@@ -1,6 +1,6 @@
 <?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" >
+  "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" >
 <!-- SPDX-License-Identifier: LGPL-2.1-or-later -->
 
 <refentry id="org.freedesktop.machine1" conditional='ENABLE_MACHINED'
@@ -89,6 +89,9 @@ node /org/freedesktop/machine1 {
                   in  i signal);
       GetMachineAddresses(in  s name,
                           out a(iay) addresses);
+      GetMachineSSHInfo(in  s name,
+                        out s ssh_address,
+                        out s ssh_private_key_path);
       GetMachineOSRelease(in  s name,
                           out a{ss} fields);
       @org.freedesktop.systemd1.Privileged("true")
@@ -184,8 +187,6 @@ node /org/freedesktop/machine1 {
 
     <!--method UnregisterMachine is not documented!-->
 
-    <!--method CopyToMachineWithFlags is not documented!-->
-
     <!--method OpenMachineRootDirectory is not documented!-->
 
     <!--method GetMachineUIDShift is not documented!-->
@@ -232,6 +233,8 @@ node /org/freedesktop/machine1 {
 
     <variablelist class="dbus-method" generated="True" extra-ref="GetMachineAddresses()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="GetMachineSSHInfo()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="GetMachineOSRelease()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="OpenMachinePTY()"/>
@@ -284,9 +287,9 @@ node /org/freedesktop/machine1 {
 
     <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="MachineNew()"/>
 
-    <variablelist class="dbus-signal" generated="True" extra-ref="MachineRemoved"/>
+    <variablelist class="dbus-signal" generated="True" extra-ref="MachineRemoved()"/>
 
     <variablelist class="dbus-property" generated="True" extra-ref="PoolPath"/>
 
@@ -344,7 +347,7 @@ node /org/freedesktop/machine1 {
       unit for the calling client (utilizing the passed scope_properties) and move the leader PID into
       it. The method 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
+      <ulink url="https://systemd.io/CONTROL_GROUP_INTERFACE">New Control Group
       Interfaces</ulink> for details about scope units and how to alter resource control settings on the
       created machine at runtime.</para>
 
@@ -380,6 +383,10 @@ node /org/freedesktop/machine1 {
       <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>GetMachineSSHInfo()</function> retrieves the SSH information of a machine. This method
+      returns two strings, the SSH address which can be used to tell SSH where to connect, and the path
+      to the SSH private key required for the connection to succeed.</para>
+
       <para><function>GetMachineOSRelease()</function> retrieves the OS release information of a
       container. This method returns an array of key value pairs read from the
       <citerefentry><refentrytitle>os-release</refentrytitle><manvolnum>5</manvolnum></citerefentry> file in
@@ -411,7 +418,7 @@ node /org/freedesktop/machine1 {
       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.
-      <function>CopyFromMachineWithFlags()</function> and <function>CopyToMachineWithFlags</function> do the same but take an additional flags argument.</para>
+      <function>CopyFromMachineWithFlags()</function> and <function>CopyToMachineWithFlags()</function> do the same but take an additional flags argument.</para>
 
       <para><function>RemoveImage()</function> removes the image with the specified name.</para>
 
@@ -434,7 +441,7 @@ node /org/freedesktop/machine1 {
     <refsect2>
       <title>Signals</title>
 
-      <para><function>MachineNew</function> and <function>MachineRemoved</function> are sent whenever a new
+      <para><function>MachineNew()</function> and <function>MachineRemoved()</function> are sent whenever a new
       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>
@@ -461,6 +468,8 @@ node /org/freedesktop/machine1/machine/rawhide {
       Kill(in  s who,
            in  i signal);
       GetAddresses(out a(iay) addresses);
+      GetSSHInfo(out s ssh_address,
+                 out s ssh_private_key_path);
       GetOSRelease(out a{ss} fields);
       GetUIDShift(out u shift);
       OpenPTY(out h pty,
@@ -509,6 +518,12 @@ node /org/freedesktop/machine1/machine/rawhide {
       readonly s RootDirectory = '...';
       @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
       readonly ai NetworkInterfaces = [...];
+      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
+      readonly u VSockCID = ...;
+      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
+      readonly s SSHAddress = '...';
+      @org.freedesktop.DBus.Property.EmitsChangedSignal("const")
+      readonly s SSHPrivateKeyPath = '...';
       @org.freedesktop.DBus.Property.EmitsChangedSignal("false")
       readonly s State = '...';
   };
@@ -550,6 +565,8 @@ node /org/freedesktop/machine1/machine/rawhide {
 
     <variablelist class="dbus-method" generated="True" extra-ref="GetAddresses()"/>
 
+    <variablelist class="dbus-method" generated="True" extra-ref="GetSSHInfo()"/>
+
     <variablelist class="dbus-method" generated="True" extra-ref="GetOSRelease()"/>
 
     <variablelist class="dbus-method" generated="True" extra-ref="GetUIDShift()"/>
@@ -592,6 +609,12 @@ node /org/freedesktop/machine1/machine/rawhide {
 
     <variablelist class="dbus-property" generated="True" extra-ref="NetworkInterfaces"/>
 
+    <variablelist class="dbus-property" generated="True" extra-ref="VSockCID"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="SSHAddress"/>
+
+    <variablelist class="dbus-property" generated="True" extra-ref="SSHPrivateKeyPath"/>
+
     <variablelist class="dbus-property" generated="True" extra-ref="State"/>
 
     <!--End of Autogenerated section-->
@@ -603,9 +626,9 @@ node /org/freedesktop/machine1/machine/rawhide {
       take the same arguments as <function>TerminateMachine()</function> and
       <function>KillMachine()</function> on the Manager interface, respectively.</para>
 
-      <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
+      <para><function>GetAddresses()</function>, <function>GetSSHInfo()</function> and <function>GetOSRelease()</function> get the IP address,
+      SSH connection and OS release information from the machine. These methods take the same arguments as
+      <function>GetMachineAddresses()</function>, <function>GetMachineSSHInfo()</function> and <function>GetMachineOSRelease()</function> of the
       Manager interface, respectively.</para>
     </refsect2>
 
@@ -638,6 +661,15 @@ node /org/freedesktop/machine1/machine/rawhide {
       towards the container, the VM or the host. For details about this information see the description of
       <function>CreateMachineWithNetwork()</function> above.</para>
 
+      <para><varname>VSockCID</varname> is the VSOCK CID of the VM if it is known, or
+      <constant>VMADDR_CID_ANY</constant> otherwise.</para>
+
+      <para><varname>SSHAddress</varname> is the address of the VM in a format <command>ssh</command> can understand
+      if it is known or the empty string.</para>
+
+      <para><varname>SSHPrivateKeyPath</varname> is the path to the SSH private key of the VM if it is known
+      or the empty string.</para>
+
       <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.
@@ -677,11 +709,14 @@ $ gdbus introspect --system \
       <title>The Manager Object</title>
       <para><function>CopyFromMachineWithFlags()</function> and
       <function>CopyToMachineWithFlags()</function> were added in version 252.</para>
+      <para><function>GetMachineSSHInfo()</function> was added in version 256.</para>
     </refsect2>
     <refsect2>
       <title>Machine Objects</title>
       <para><function>CopyFromWithFlags()</function> and
       <function>CopyToWithFlags()</function> were added in version 252.</para>
+      <para><function>GetSSHInfo()</function>, <varname>VSockCID</varname>, <varname>SSHAddress</varname>
+      and <varname>SSHPrivateKeyPath</varname> were added in version 256.</para>
     </refsect2>
   </refsect1>
 </refentry>