ansible-core 2.18.7rc1__py3-none-any.whl → 2.19.0__py3-none-any.whl

ansible/plugins/connection/local.py

@@ -4,30 +4,49 @@
 
 from __future__ import annotations
 
-DOCUMENTATION = '''
+DOCUMENTATION = """
     name: local
     short_description: execute on controller
     description:
         - This connection plugin allows ansible to execute tasks on the Ansible 'controller' instead of on a remote host.
     author: ansible (@core)
     version_added: historical
+    options:
+        become_success_timeout:
+            version_added: '2.19'
+            type: int
+            default: 10
+            description:
+                - Number of seconds to wait for become to succeed when enabled.
+                - The default will be used if the configured value is less than 1.
+            vars:
+                - name: ansible_local_become_success_timeout
+        become_strip_preamble:
+            version_added: '2.19'
+            type: bool
+            default: true
+            description:
+                - Strip internal become output preceding command execution. Disable for additional diagnostics.
+            vars:
+                - name: ansible_local_become_strip_preamble
     extends_documentation_fragment:
         - connection_pipelining
     notes:
         - The remote user is ignored, the user with which the ansible CLI was executed is used instead.
-'''
+"""
 
-import fcntl
+import functools
 import getpass
 import os
 import pty
 import selectors
 import shutil
 import subprocess
+import time
 import typing as t
 
 import ansible.constants as C
-from ansible.errors import AnsibleError, AnsibleFileNotFound
+from ansible.errors import AnsibleError, AnsibleFileNotFound, AnsibleConnectionFailure
 from ansible.module_utils.six import text_type, binary_type
 from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
 from ansible.plugins.connection import ConnectionBase
@@ -38,7 +57,7 @@ display = Display()
 
 
 class Connection(ConnectionBase):
-    ''' Local based connections '''
+    """ Local based connections """
 
     transport = 'local'
     has_pipelining = True
@@ -54,7 +73,7 @@ class Connection(ConnectionBase):
             self.default_user = ""
 
     def _connect(self) -> Connection:
-        ''' connect to the local host; nothing to do here '''
+        """ connect to the local host; nothing to do here """
 
         # Because we haven't made any remote connection we're running as
         # the local user, rather than as whatever is configured in remote_user.
@@ -66,7 +85,7 @@ class Connection(ConnectionBase):
         return self
 
     def exec_command(self, cmd: str, in_data: bytes | None = None, sudoable: bool = True) -> tuple[int, bytes, bytes]:
-        ''' run a command on the local host '''
+        """ run a command on the local host """
 
         super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
 
@@ -82,11 +101,11 @@ class Connection(ConnectionBase):
         display.debug("opening command with Popen()")
 
         if isinstance(cmd, (text_type, binary_type)):
-            cmd = to_bytes(cmd)
+            cmd = to_text(cmd)
         else:
-            cmd = map(to_bytes, cmd)
+            cmd = map(to_text, cmd)
 
-        master = None
+        pty_primary = None
         stdin = subprocess.PIPE
         if sudoable and self.become and self.become.expect_prompt() and not self.get_option('pipelining'):
             # Create a pty if sudoable for privilege escalation that needs it.
@@ -94,9 +113,9 @@ class Connection(ConnectionBase):
             # cause the command to fail in certain situations where we are escalating
             # privileges or the command otherwise needs a pty.
             try:
-                master, stdin = pty.openpty()
-            except (IOError, OSError) as e:
-                display.debug("Unable to open pty: %s" % to_native(e))
+                pty_primary, stdin = pty.openpty()
+            except OSError as ex:
+                display.debug(f"Unable to open pty: {ex}")
 
         p = subprocess.Popen(
             cmd,
@@ -108,63 +127,137 @@ class Connection(ConnectionBase):
             stderr=subprocess.PIPE,
         )
 
-        # if we created a master, we can close the other half of the pty now, otherwise master is stdin
-        if master is not None:
+        # if we created a pty, we can close the other half of the pty now, otherwise primary is stdin
+        if pty_primary is not None:
             os.close(stdin)
 
         display.debug("done running command with Popen()")
 
-        if self.become and self.become.expect_prompt() and sudoable:
-            fcntl.fcntl(p.stdout, fcntl.F_SETFL, fcntl.fcntl(p.stdout, fcntl.F_GETFL) | os.O_NONBLOCK)
-            fcntl.fcntl(p.stderr, fcntl.F_SETFL, fcntl.fcntl(p.stderr, fcntl.F_GETFL) | os.O_NONBLOCK)
-            selector = selectors.DefaultSelector()
-            selector.register(p.stdout, selectors.EVENT_READ)
-            selector.register(p.stderr, selectors.EVENT_READ)
-
-            become_output = b''
-            try:
-                while not self.become.check_success(become_output) and not self.become.check_password_prompt(become_output):
-                    events = selector.select(self._play_context.timeout)
-                    if not events:
-                        stdout, stderr = p.communicate()
-                        raise AnsibleError('timeout waiting for privilege escalation password prompt:\n' + to_native(become_output))
-
-                    for key, event in events:
-                        if key.fileobj == p.stdout:
-                            chunk = p.stdout.read()
-                        elif key.fileobj == p.stderr:
-                            chunk = p.stderr.read()
-
-                    if not chunk:
-                        stdout, stderr = p.communicate()
-                        raise AnsibleError('privilege output closed while waiting for password prompt:\n' + to_native(become_output))
-                    become_output += chunk
-            finally:
-                selector.close()
-
-            if not self.become.check_success(become_output):
-                become_pass = self.become.get_option('become_pass', playcontext=self._play_context)
-                if master is None:
-                    p.stdin.write(to_bytes(become_pass, errors='surrogate_or_strict') + b'\n')
-                else:
-                    os.write(master, to_bytes(become_pass, errors='surrogate_or_strict') + b'\n')
-
-            fcntl.fcntl(p.stdout, fcntl.F_SETFL, fcntl.fcntl(p.stdout, fcntl.F_GETFL) & ~os.O_NONBLOCK)
-            fcntl.fcntl(p.stderr, fcntl.F_SETFL, fcntl.fcntl(p.stderr, fcntl.F_GETFL) & ~os.O_NONBLOCK)
+        become_stdout_bytes, become_stderr_bytes = self._ensure_become_success(p, pty_primary, sudoable)
 
         display.debug("getting output with communicate()")
         stdout, stderr = p.communicate(in_data)
         display.debug("done communicating")
 
+        # preserve output from privilege escalation stage as `bytes`; it may contain actual output (eg `raw`) or error messages
+        stdout = become_stdout_bytes + stdout
+        stderr = become_stderr_bytes + stderr
+
         # finally, close the other half of the pty, if it was created
-        if master:
-            os.close(master)
+        if pty_primary:
+            os.close(pty_primary)
 
         display.debug("done with local.exec_command()")
-        return (p.returncode, stdout, stderr)
+        return p.returncode, stdout, stderr
+
+    def _ensure_become_success(self, p: subprocess.Popen, pty_primary: int, sudoable: bool) -> tuple[bytes, bytes]:
+        """
+        Ensure that become succeeds, returning a tuple containing stdout captured after success and all stderr.
+        Returns immediately if `self.become` or `sudoable` are False, or `build_become_command` was not called, without performing any additional checks.
+        """
+        if not self.become or not sudoable or not self.become._id:  # _id is set by build_become_command, if it was not called, assume no become
+            return b'', b''
+
+        start_seconds = time.monotonic()
+        become_stdout = bytearray()
+        become_stderr = bytearray()
+        last_stdout_prompt_offset = 0
+        last_stderr_prompt_offset = 0
+
+        # map the buffers to their associated stream for the selector reads
+        become_capture = {
+            p.stdout: become_stdout,
+            p.stderr: become_stderr,
+        }
+
+        expect_password_prompt = self.become.expect_prompt()
+        sent_password = False
+
+        def become_error_msg(reason: str) -> str:
+            error_message = f'{reason} waiting for become success'
+
+            if expect_password_prompt and not sent_password:
+                error_message += ' or become password prompt'
+
+            error_message += '.'
+
+            if become_stdout:
+                error_message += f'\n>>> Standard Output\n{to_text(bytes(become_stdout))}'
+
+            if become_stderr:
+                error_message += f'\n>>> Standard Error\n{to_text(bytes(become_stderr))}'
+
+            return error_message
+
+        os.set_blocking(p.stdout.fileno(), False)
+        os.set_blocking(p.stderr.fileno(), False)
+
+        with selectors.DefaultSelector() as selector:
+            selector.register(p.stdout, selectors.EVENT_READ, 'stdout')
+            selector.register(p.stderr, selectors.EVENT_READ, 'stderr')
+
+            while not self.become.check_success(become_stdout):
+                if not selector.get_map():  # we only reach end of stream after all descriptors are EOF
+                    raise AnsibleError(become_error_msg('Premature end of stream'))
+
+                if expect_password_prompt and (
+                    self.become.check_password_prompt(become_stdout[last_stdout_prompt_offset:]) or
+                    self.become.check_password_prompt(become_stderr[last_stderr_prompt_offset:])
+                ):
+                    if sent_password:
+                        raise AnsibleError(become_error_msg('Duplicate become password prompt encountered'))
+
+                    last_stdout_prompt_offset = len(become_stdout)
+                    last_stderr_prompt_offset = len(become_stderr)
+
+                    password_to_send = to_bytes(self.become.get_option('become_pass') or '') + b'\n'
+
+                    if pty_primary is None:
+                        p.stdin.write(password_to_send)
+                        p.stdin.flush()
+                    else:
+                        os.write(pty_primary, password_to_send)
+
+                    sent_password = True
+
+                remaining_timeout_seconds = self._become_success_timeout - (time.monotonic() - start_seconds)
+                events = selector.select(remaining_timeout_seconds) if remaining_timeout_seconds > 0 else []
+
+                if not events:
+                    # ignoring remaining output after timeout to prevent hanging
+                    raise AnsibleConnectionFailure(become_error_msg('Timed out'))
+
+                # read all content (non-blocking) from streams that signaled available input and append to the associated buffer
+                for key, event in events:
+                    obj = t.cast(t.BinaryIO, key.fileobj)
+
+                    if chunk := obj.read():
+                        become_capture[obj] += chunk
+                    else:
+                        selector.unregister(obj)  # EOF on this obj, stop polling it
+
+        os.set_blocking(p.stdout.fileno(), True)
+        os.set_blocking(p.stderr.fileno(), True)
+
+        become_stdout_bytes = bytes(become_stdout)
+        become_stderr_bytes = bytes(become_stderr)
+
+        if self.get_option('become_strip_preamble'):
+            become_stdout_bytes = self.become.strip_become_success(self.become.strip_become_prompt(become_stdout_bytes))
+            become_stderr_bytes = self.become.strip_become_prompt(become_stderr_bytes)
+
+        return become_stdout_bytes, become_stderr_bytes
+
+    @functools.cached_property
+    def _become_success_timeout(self) -> int:
+        """Timeout value for become success in seconds."""
+        if (timeout := self.get_option('become_success_timeout')) < 1:
+            timeout = C.config.get_config_default('become_success_timeout', plugin_type='connection', plugin_name='local')
+
+        return timeout
 
     def put_file(self, in_path: str, out_path: str) -> None:
-        ''' transfer a file from local to local '''
+        """ transfer a file from local to local """
 
         super(Connection, self).put_file(in_path, out_path)
 
@@ -178,17 +271,20 @@ class Connection(ConnectionBase):
             shutil.copyfile(to_bytes(in_path, errors='surrogate_or_strict'), to_bytes(out_path, errors='surrogate_or_strict'))
         except shutil.Error:
             raise AnsibleError("failed to copy: {0} and {1} are the same".format(to_native(in_path), to_native(out_path)))
-        except IOError as e:
-            raise AnsibleError("failed to transfer file to {0}: {1}".format(to_native(out_path), to_native(e)))
+        except OSError as ex:
+            raise AnsibleError(f"Failed to transfer file to {out_path!r}.") from ex
 
     def fetch_file(self, in_path: str, out_path: str) -> None:
-        ''' fetch a file from local to local -- for compatibility '''
+        """ fetch a file from local to local -- for compatibility """
 
         super(Connection, self).fetch_file(in_path, out_path)
 
         display.vvv(u"FETCH {0} TO {1}".format(in_path, out_path), host=self._play_context.remote_addr)
         self.put_file(in_path, out_path)
 
+    def reset(self) -> None:
+        pass
+
     def close(self) -> None:
-        ''' terminate the connection; nothing to do here '''
+        """ terminate the connection; nothing to do here """
         self._connected = False

ansible/plugins/connection/paramiko_ssh.py

@@ -248,11 +248,13 @@ from ansible.errors import (
     AnsibleError,
     AnsibleFileNotFound,
 )
-from ansible.module_utils.compat.paramiko import PARAMIKO_IMPORT_ERR, paramiko
+
+from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
+from ansible.module_utils.compat.paramiko import _PARAMIKO_IMPORT_ERR as PARAMIKO_IMPORT_ERR, _paramiko as paramiko
 from ansible.plugins.connection import ConnectionBase
 from ansible.utils.display import Display
 from ansible.utils.path import makedirs_safe
-from ansible.module_utils.common.text.converters import to_bytes, to_native, to_text
+from ansible.module_utils._internal import _deprecator
 
 display = Display()
 
@@ -321,11 +323,20 @@ SFTP_CONNECTION_CACHE: dict[str, paramiko.sftp_client.SFTPClient] = {}
 
 
 class Connection(ConnectionBase):
-    ''' SSH based connections with Paramiko '''
+    """ SSH based connections with Paramiko """
 
     transport = 'paramiko'
     _log_channel: str | None = None
 
+    def __init__(self, *args, **kwargs):
+        display.deprecated(  # pylint: disable=ansible-deprecated-unnecessary-collection-name
+            msg='The paramiko connection plugin is deprecated.',
+            version='2.21',
+            deprecator=_deprecator.ANSIBLE_CORE_DEPRECATOR,  # entire plugin being removed; this improves the messaging
+        )
+
+        super().__init__(*args, **kwargs)
+
     def _cache_key(self) -> str:
         return "%s__%s__" % (self.get_option('remote_addr'), self.get_option('remote_user'))
 
@@ -340,7 +351,7 @@ class Connection(ConnectionBase):
         return self
 
     def _set_log_channel(self, name: str) -> None:
-        '''Mimic paramiko.SSHClient.set_log_channel'''
+        """Mimic paramiko.SSHClient.set_log_channel"""
         self._log_channel = name
 
     def _parse_proxy_command(self, port: int = 22) -> dict[str, t.Any]:
@@ -366,7 +377,7 @@ class Connection(ConnectionBase):
         return sock_kwarg
 
     def _connect_uncached(self) -> paramiko.SSHClient:
-        ''' activates the connection object '''
+        """ activates the connection object """
 
         if paramiko is None:
             raise AnsibleError("paramiko is not installed: %s" % to_native(PARAMIKO_IMPORT_ERR))
@@ -402,7 +413,7 @@ class Connection(ConnectionBase):
                     # TODO: check if we need to look at several possible locations, possible for loop
                     ssh.load_system_host_keys(ssh_known_hosts)
                     break
-                except IOError:
+                except OSError:
                     pass  # file was not found, but not required to function
             ssh.load_system_host_keys()
 
@@ -444,24 +455,23 @@ class Connection(ConnectionBase):
             )
         except paramiko.ssh_exception.BadHostKeyException as e:
             raise AnsibleConnectionFailure('host key mismatch for %s' % e.hostname)
-        except paramiko.ssh_exception.AuthenticationException as e:
-            msg = 'Failed to authenticate: {0}'.format(to_text(e))
-            raise AnsibleAuthenticationFailure(msg)
-        except Exception as e:
-            msg = to_text(e)
+        except paramiko.ssh_exception.AuthenticationException as ex:
+            raise AnsibleAuthenticationFailure() from ex
+        except Exception as ex:
+            msg = str(ex)
             if u"PID check failed" in msg:
-                raise AnsibleError("paramiko version issue, please upgrade paramiko on the machine running ansible")
+                raise AnsibleError("paramiko version issue, please upgrade paramiko on the machine running ansible") from ex
             elif u"Private key file is encrypted" in msg:
                 msg = 'ssh %s@%s:%s : %s\nTo connect as a different user, use -u <username>.' % (
                     self.get_option('remote_user'), self.get_options('remote_addr'), port, msg)
-                raise AnsibleConnectionFailure(msg)
+                raise AnsibleConnectionFailure(msg) from ex
             else:
-                raise AnsibleConnectionFailure(msg)
+                raise AnsibleConnectionFailure(msg) from ex
 
         return ssh
 
     def exec_command(self, cmd: str, in_data: bytes | None = None, sudoable: bool = True) -> tuple[int, bytes, bytes]:
-        ''' run a command on the remote host '''
+        """ run a command on the remote host """
 
         super(Connection, self).exec_command(cmd, in_data=in_data, sudoable=sudoable)
 
@@ -541,7 +551,7 @@ class Connection(ConnectionBase):
         return (chan.recv_exit_status(), no_prompt_out + stdout, no_prompt_out + stderr)
 
     def put_file(self, in_path: str, out_path: str) -> None:
-        ''' transfer a file from local to remote '''
+        """ transfer a file from local to remote """
 
         super(Connection, self).put_file(in_path, out_path)
 
@@ -557,8 +567,8 @@ class Connection(ConnectionBase):
 
         try:
             self.sftp.put(to_bytes(in_path, errors='surrogate_or_strict'), to_bytes(out_path, errors='surrogate_or_strict'))
-        except IOError:
-            raise AnsibleError("failed to transfer file to %s" % out_path)
+        except OSError as ex:
+            raise AnsibleError(f"Failed to transfer file to {out_path!r}.") from ex
 
     def _connect_sftp(self) -> paramiko.sftp_client.SFTPClient:
 
@@ -570,7 +580,7 @@ class Connection(ConnectionBase):
             return result
 
     def fetch_file(self, in_path: str, out_path: str) -> None:
-        ''' save a remote file to the specified path '''
+        """ save a remote file to the specified path """
 
         super(Connection, self).fetch_file(in_path, out_path)
 
@@ -583,8 +593,8 @@ class Connection(ConnectionBase):
 
         try:
             self.sftp.get(to_bytes(in_path, errors='surrogate_or_strict'), to_bytes(out_path, errors='surrogate_or_strict'))
-        except IOError:
-            raise AnsibleError("failed to transfer file from %s" % in_path)
+        except OSError as ex:
+            raise AnsibleError(f"Failed to transfer file from {in_path!r}.") from ex
 
     def _any_keys_added(self) -> bool:
 
@@ -596,10 +606,10 @@ class Connection(ConnectionBase):
         return False
 
     def _save_ssh_host_keys(self, filename: str) -> None:
-        '''
+        """
         not using the paramiko save_ssh_host_keys function as we want to add new SSH keys at the bottom so folks
         don't complain about it :)
-        '''
+        """
 
         if not self._any_keys_added():
             return
@@ -632,7 +642,7 @@ class Connection(ConnectionBase):
         self._connect()
 
     def close(self) -> None:
-        ''' terminate the connection '''
+        """ terminate the connection """
 
         cache_key = self._cache_key()
         SSH_CONNECTION_CACHE.pop(cache_key, None)