diff --git a/docs/ansible.rst b/docs/ansible.rst index 3dd17c3a..a8f5df02 100644 --- a/docs/ansible.rst +++ b/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 - interest in more. +* The ``doas``, ``su`` and ``sudo`` become methods are available. File bugs to + register interest in more. * The `docker `_, `jail `_, @@ -137,9 +137,9 @@ Noteworthy Differences `lxd `_, and `ssh `_ built-in connection types are supported, along with Mitogen-specific - :ref:`machinectl `, :ref:`mitogen_su `, :ref:`mitogen_sudo - `, and :ref:`setns ` types. File bugs to register interest in - others. + :ref:`machinectl `, :ref:`mitogen_doas< mitogen_doas>`, + :ref:`mitogen_su `, :ref:`mitogen_sudo `, and :ref:`setns ` + 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 diff --git a/docs/api.rst b/docs/api.rst index 0bb42ec2..bc88a622 100644 --- a/docs/api.rst +++ b/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: - The string to wait to that signals ``su`` is requesting a password. - Defaults to ``Password:``. - :param str password_prompt: - The string that signal a request for the password. Defaults to - ``Password:``. + :param bytes password_prompt: + The string that indicates ``su`` is requesting a password. Defaults + to ``Password:``. :param str incorrect_prompts: Strings that signal the password is incorrect. Defaults to `("su: sorry", "su: authentication failure")`. diff --git a/docs/changelog.rst b/docs/changelog.rst index 9e85446e..b999ba4d 100644 --- a/docs/changelog.rst +++ b/docs/changelog.rst @@ -15,6 +15,13 @@ Release Notes +v0.2.2 (2018-07-??) +------------------- + +* `#303 `_: the ``doas`` become method + is now supported. Contributed by Mike Walker. + + v0.2.1 (2018-07-10) -------------------