Merge pull request #2036 from dbungert/doc-shutdown-ssh-source

reference: examples and clarifications for source, shutdown, ssh

doc/.custom_wordlist.txt

@@ -11,6 +11,7 @@ GPT
 GUID
 GiB
 GiB
+Kylin
 Libera
 LPAR
 LTS
@@ -36,6 +37,7 @@ Seagate
 Subiquity
 UEFI
 URI
+Xubuntu
 Zdev
 amd
 authorized
@@ -62,6 +64,7 @@ iSCSI
 init
 md
 oem
+openssh
 passwd
 ppc
 pre

doc/reference/autoinstall-reference.rst

@@ -218,9 +218,85 @@ id
 ^^
 
 * **type:** string
-* **default:** identifier of the first available source.
+* **default:** the default value as listed in install-sources
 
-Identifier of the source to install (e.g., ``ubuntu-server-minimal``).
+Identifier of the source to install (e.g., ``ubuntu-server-minimal``).  The
+correct ID to use is specific to a given install ISO.  As this ID may change
+over time, the canonical place to look for this information is the install ISO
+itself, in the file ``casper/install-sources.yaml``, where the value to use is
+the ``id``.
+
+Current values:
+
+* ubuntu-server:
+
+  * minimal: ``ubuntu-server-minimal``
+  * standard (default): ``ubuntu-server``
+
+* Ubuntu desktop:
+
+  * minimal (default): ``ubuntu-desktop-minimal``
+  * standard: ``ubuntu-desktop``
+
+* Ubuntu Budgie:
+
+  * minimal: ``ubuntu-budgie-desktop-minimal``
+  * standard (default): ``ubuntu-budgie-desktop``
+
+* Ubuntu Cinnamon:
+
+  * minimal: ``ubuntucinnamon-desktop-minimal``
+  * standard (default): ``ubuntucinnamon-desktop``
+
+* Edubuntu:
+
+  * minimal: ``edubuntu-desktop-minimal``
+  * standard (default): ``edubuntu-desktop``
+
+* Ubuntu Kylin:
+
+  * minimal: ``ubuntukylin-desktop-minimal``
+  * standard (default): ``ubuntukylin-desktop``
+
+* Ubuntu MATE:
+
+  * minimal: ``ubuntu-mate-desktop-minimal``
+  * standard (default): ``ubuntu-mate-desktop``
+
+* Ubuntu Studio:
+
+  * standard (default): ``ubuntustudio-desktop``
+
+* Xubuntu:
+
+  * full ISO:
+
+    * minimal: ``xubuntu-desktop-minimal``
+    * standard (default): ``xubuntu-desktop``
+
+  * minimal ISO:
+
+    * minimal (default): ``xubuntu-desktop-minimal``
+
+source examples:
+
+.. code-block:: yaml
+
+   autoinstall:
+     # default behavior
+     source:
+       search_drivers: true
+       id: <the install source marked as default in install-sources.yaml>
+
+   autoinstall:
+     # on the ubuntu-server ISO, install with the minimal source
+     source:
+       id: ubuntu-server-minimal
+
+   autoinstall:
+     # on the Ubuntu desktop ISO, install with the standard source
+     source:
+       id: ubuntu-desktop
 
 .. _ai-network:
 
@@ -718,7 +794,9 @@ install-server
 * **type:** boolean
 * **default:** ``false``
 
-Whether to install the OpenSSH server in the target system.
+Whether to install the OpenSSH server in the target system.  Note that Desktop
+install ISOs do not include openssh-server on the ISO, so installs of
+Desktop require Ubuntu archive access for install-server to be successful.
 
 authorized-keys
 ^^^^^^^^^^^^^^^
@@ -734,6 +812,33 @@ allow-pw
 * **type:** boolean
 * **default:** ``true`` if ``authorized_keys`` is empty, ``false`` otherwise
 
+ssh examples:
+
+.. code-block:: yaml
+
+   autoinstall:
+     # default behavior
+     ssh:
+       install-server: false
+       authorized-keys: []
+       allow-pw: true
+
+   autoinstall:
+     # recommended configuration when openssh-server is desired
+     ssh:
+       install-server: true
+       authorized-keys:
+         # replace with the contents of the public key(s) as generated by
+         # ssh-keygen or similar tools
+         - ssh-ed25519 AAAAC3NzaC..6O8tvZobj user@host
+       allow-pw: false
+
+   autoinstall:
+     # configuration for password access
+     ssh:
+       install-server: true
+       allow-pw: true
+
 .. _ai-codecs:
 
 codecs
@@ -892,6 +997,18 @@ Request the system to power off or reboot automatically after the installation h
 * ``reboot``
 * ``poweroff``
 
+shutdown examples:
+
+.. code-block:: yaml
+
+   autoinstall:
+     # default behavior
+     shutdown: reboot
+
+   autoinstall:
+     # shutdown instead of reboot
+     shutdown: poweroff
+
 .. _ai-late-commands:
 
 late-commands