issue #303: add doas to the docs

docs/ansible.rst

@@ -127,8 +127,8 @@ Noteworthy Differences
   precluding its use for installing Python on a target. This will be addressed
   soon.
 
-* The ``su`` and ``sudo`` become methods are available. File bugs to register
+* The ``doas``, ``su`` and ``sudo`` become methods are available. File bugs to
-  interest in more.
+  register interest in more.
 
 * The `docker <https://docs.ansible.com/ansible/2.5/plugins/connection/docker.html>`_,
   `jail <https://docs.ansible.com/ansible/2.5/plugins/connection/jail.html>`_,
@@ -137,9 +137,9 @@ Noteworthy Differences
   `lxd <https://docs.ansible.com/ansible/2.5/plugins/connection/lxd.html>`_,
   and `ssh <https://docs.ansible.com/ansible/2.5/plugins/connection/ssh.html>`_
   built-in connection types are supported, along with Mitogen-specific
-  :ref:`machinectl <machinectl>`, :ref:`mitogen_su <su>`, :ref:`mitogen_sudo
+  :ref:`machinectl <machinectl>`, :ref:`mitogen_doas< mitogen_doas>`,
-  <sudo>`, and :ref:`setns <setns>` types. File bugs to register interest in
+  :ref:`mitogen_su <su>`, :ref:`mitogen_sudo <sudo>`, and :ref:`setns <setns>`
-  others.
+  types. File bugs to register interest in others.
 
 * Local commands execute in a reuseable interpreter created identically to
   interpreters on targets. Presently one interpreter per ``become_user``
@@ -477,6 +477,30 @@ establishment of additional reuseable interpreters as necessary to match the
 configuration of each task.
 
 
+.. _doas:
+
+Doas
+~~~~
+
+``doas`` can be used as a connection method that supports connection delegation, or
+as a become method.
+
+When used as a become method:
+
+* ``ansible_python_interpreter``
+* ``ansible_become_exe``: path to ``doas`` binary.
+* ``ansible_become_user`` (default: ``root``)
+* ``ansible_become_pass`` (default: assume passwordless)
+* ansible.cfg: ``timeout``
+
+When used as the ``mitogen_doas`` connection method:
+
+* The inventory hostname has no special meaning.
+* ``ansible_user``: username to use.
+* ``ansible_password``: password to use.
+* ``ansible_python_interpreter``
+
+
 .. _method-docker:
 
 Docker

docs/api.rst

@@ -523,6 +523,31 @@ Router Class
                 # Use the SSH connection to create a sudo connection.
                 remote_root = router.sudo(username='root', via=remote_machine)
 
+    .. method:: dos (username=None, password=None, su_path=None, password_prompt=None, incorrect_prompts=None, \**kwargs)
+
+        Construct a context on the local machine over a ``su`` invocation. The
+        ``su`` process is started in a newly allocated pseudo-terminal, and
+        supports typing interactive passwords.
+
+        Accepts all parameters accepted by :py:meth:`local`, in addition to:
+
+        :param str username:
+            Username to use, defaults to ``root``.
+        :param str password:
+            The account password to use if requested.
+        :param str su_path:
+            Filename or complete path to the ``su`` binary. ``PATH`` will be
+            searched if given as a filename. Defaults to ``su``.
+        :param bytes password_prompt:
+            A string that indicates ``doas`` is requesting a password. Defaults
+            to ``Password:``.
+        :param list incorrect_prompts:
+            List of bytestrings indicating the password is incorrect. Defaults
+            to `(b"doas: authentication failed")`.
+        :raises mitogen.su.PasswordError:
+            A password was requested but none was provided, the supplied
+            password was incorrect, or the target account did not exist.
+
     .. method:: docker (container=None, image=None, docker_path=None, \**kwargs)
 
         Construct a context on the local machine within an existing or
@@ -616,12 +641,9 @@ Router Class
         :param str su_path:
             Filename or complete path to the ``su`` binary. ``PATH`` will be
             searched if given as a filename. Defaults to ``su``.
-        :param str password_prompt:
+        :param bytes password_prompt:
-            The string to wait to that signals ``su`` is requesting a password.
+            The string that indicates ``su`` is requesting a password. Defaults
-            Defaults to ``Password:``.
+            to ``Password:``.
-        :param str password_prompt:
-            The string that signal a request for the password. Defaults to
-            ``Password:``.
         :param str incorrect_prompts:
             Strings that signal the password is incorrect. Defaults to `("su:
             sorry", "su: authentication failure")`.

docs/changelog.rst

@@ -15,6 +15,13 @@ Release Notes
     </style>
 
 
+v0.2.2 (2018-07-??)
+-------------------
+
+* `#303 <https://github.com/dw/mitogen/pull/303>`_: the ``doas`` become method
+  is now supported. Contributed by Mike Walker.
+
+
 v0.2.1 (2018-07-10)
 -------------------