Merge ~oddbloke/cloud-init/+git/cloud-init:doc into cloud-init:master

[Dan Watkins]

cc_set_passwords: rewrite documentation

What we had previously was inaccurate in a few respects.

LP: #1838794

[Server Team CI bot (server-team-bot)]

PASSED: Continuous integration, rev:abf57a42d03b52a6681756ab1b025351f7fd038b
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1025/
Executed test runs:
    SUCCESS: Checkout
    SUCCESS: Unit & Style Tests
    SUCCESS: Ubuntu LTS: Build
    SUCCESS: Ubuntu LTS: Integration
    IN_PROGRESS: Declarative: Post Actions

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1025/rebuild

review: Approve (continuous-integration)

[Ryan Harper (raharper)]

One question, otherwise happy to see the doc update.

[Ryan Harper (raharper)]

Thanks!

review: Approve

[Server Team CI bot (server-team-bot)]

FAILED: Continuous integration, rev:721585f34f15330b3a47a5d3e9723317ee76cd0b
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1029/
Executed test runs:
    SUCCESS: Checkout
    FAILED: Unit & Style Tests

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1029//rebuild

review: Needs Fixing (continuous-integration)

[Server Team CI bot (server-team-bot)]

PASSED: Continuous integration, rev:96fc01bc5a61c900671cb162028642039c27b82c
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1032/
Executed test runs:
    SUCCESS: Checkout
    SUCCESS: Unit & Style Tests
    SUCCESS: Ubuntu LTS: Build
    SUCCESS: Ubuntu LTS: Integration
    IN_PROGRESS: Declarative: Post Actions

Click here to trigger a rebuild:
https://jenkins.ubuntu.com/server/job/cloud-init-ci/1032//rebuild

review: Approve (continuous-integration)

diff --git a/cloudinit/config/cc_set_passwords.py b/cloudinit/config/cc_set_passwords.py
index 4585e4d..cf9b5ab 100755
--- a/cloudinit/config/cc_set_passwords.py
+++ b/cloudinit/config/cc_set_passwords.py
@@ -9,27 +9,40 @@
 """
 Set Passwords
 -------------
-**Summary:** Set user passwords
-
-Set system passwords and enable or disable ssh password authentication.
-The ``chpasswd`` config key accepts a dictionary containing a single one of two
-keys, either ``expire`` or ``list``. If ``expire`` is specified and is set to
-``false``, then the ``password`` global config key is used as the password for
-all user accounts. If the ``expire`` key is specified and is set to ``true``
-then user passwords will be expired, preventing the default system passwords
-from being used.
-
-If the ``list`` key is provided, a list of
-``username:password`` pairs can be specified. The usernames specified
-must already exist on the system, or have been created using the
-``cc_users_groups`` module. A password can be randomly generated using
-``username:RANDOM`` or ``username:R``. A hashed password can be specified
-using ``username:$6$salt$hash``. Password ssh authentication can be
-enabled, disabled, or left to system defaults using ``ssh_pwauth``.
+**Summary:** Set user passwords and enable/disable SSH password authentication
+
+This module consumes three top-level config keys: ``ssh_pwauth``, ``chpasswd``
+and ``password``.
+
+The ``ssh_pwauth`` config key determines whether or not sshd will be configured
+to accept password authentication.  True values will enable password auth,
+false values will disable password auth, and the literal string ``unchanged``
+will leave it unchanged.  Setting no value will also leave the current setting
+on-disk unchanged.
+
+The ``chpasswd`` config key accepts a dictionary containing either or both of
+``expire`` and ``list``.
+
+If the ``list`` key is provided, it should contain a list of
+``username:password`` pairs.  This can be either a YAML list (of strings), or a
+multi-line string with one pair per line.  Each user will have the
+corresponding password set.  A password can be randomly generated by specifying
+``RANDOM`` or ``R`` as a user's password.  A hashed password, created by a tool
+like ``mkpasswd``, can be specified; a regex
+(``r'\\$(1|2a|2y|5|6)(\\$.+){2}'``) is used to determine if a password value
+should be treated as a hash.
 
 .. note::
-    if using ``expire: true`` then a ssh authkey should be specified or it may
-    not be possible to login to the system
+    The users specified must already exist on the system.  Users will have been
+    created by the ``cc_users_groups`` module at this point.
+
+By default, all users on the system will have their passwords expired (meaning
+that they will have to be reset the next time the user logs in).  To disable
+this behaviour, set ``expire`` under ``chpasswd`` to a false value.
+
+If a ``list`` of user/password pairs is not specified under ``chpasswd``, then
+the value of the ``password`` config key will be used to set the default user's
+password.
 
 **Internal name:** ``cc_set_passwords``
 
@@ -160,6 +173,8 @@ def handle(_name, cfg, cloud, log, args):
         hashed_users = []
         randlist = []
         users = []
+        # N.B. This regex is included in the documentation (i.e. the module
+        # docstring), so any changes to it should be reflected there.
         prog = re.compile(r'\$(1|2a|2y|5|6)(\$.+){2}')
         for line in plist:
             u, p = line.split(':', 1)