Ipv6 (#322)

* Added IPV6 support to native client. Added IPV6 support to embedded server for tests, single client test connecting to IPV6 and IPV6 only test. Added flag for only connecting to IPV6 hosts and exception.
* Renamed exception. Added IPv6 flags to parallel client and ssh clients.
* Updated setup, changelog, documentation.
* Updated documentation.
* Updated requirements
Resolves #291

Author: pkittenis

Changelog.rst

@@ -1,6 +1,17 @@
 Change Log
 ============
 
+2.7.0
++++++
+
+Changes
+-------
+
+* All clients now support IPv6 addresses for both DNS and IP entries in host list.
+* Added ``ipv6_only`` flag to ``ParallelSSHClient`` and ``SSHClient`` for choosing only IPv6 addresses when both v4 and
+  v6 are available.
+* Removed Python 2 from binary wheel compatibility as it is no longer supported and not guaranteed to work.
+
 2.6.0
 +++++
 

doc/advanced.rst

@@ -882,3 +882,40 @@ Clients for hosts that would be removed by a reassignment can be calculated with
 
    set(enumerate(client.hosts)).difference(
        set(enumerate(new_hosts)))
+
+
+IPv6 Addresses
+***************
+
+All clients support IPv6 addresses in both host list, and via DNS. Typically IPv4 addresses are preferred as they are
+the first entries in DNS resolution depending on DNS server configuration and entries.
+
+The ``ipv6_only`` flag may be used to override this behaviour and force the client(s) to only choose IPv6 addresses, or
+raise an error if none are available.
+
+Connecting to localhost via an IPv6 address.
+
+.. code-block:: python
+
+   client = ParallelSSHClient(['::1'])
+   <..>
+
+Asking client to only use IPv6 for DNS resolution.
+:py:class:`NoIPv6AddressFoundError <pssh.exceptions.NoIPv6AddressFoundError>` is raised if no IPv6 address is available
+for hosts.
+
+.. code-block:: python
+
+   client = ParallelSSHClient(['myhost.com'], ipv6_only=True)
+   output = client.run_command('echo me')
+
+Similarly for single clients.
+
+.. code-block:: python
+
+   client = SSHClient(['myhost.com'], ipv6_only=True)
+
+For choosing a mix of IPv4/IPv6 depending on the host name, developers can use `socket.getaddrinfo` directly and pick
+from available addresses.
+
+*New in 2.7.0*

pssh/clients/base/parallel.py

@@ -41,7 +41,9 @@ def __init__(self, hosts, user=None, password=None, port=None, pkey=None,
                  num_retries=DEFAULT_RETRIES,
                  timeout=120, pool_size=10,
                  host_config=None, retry_delay=RETRY_DELAY,
-                 identity_auth=True):
+                 identity_auth=True,
+                 ipv6_only=False,
+                 ):
         self.allow_agent = allow_agent
         self.pool_size = pool_size
         self.pool = gevent.pool.Pool(size=self.pool_size)
@@ -57,6 +59,7 @@ def __init__(self, hosts, user=None, password=None, port=None, pkey=None,
         self.retry_delay = retry_delay
         self.cmds = None
         self.identity_auth = identity_auth
+        self.ipv6_only = ipv6_only
         self._check_host_config()
 
     def _validate_hosts(self, _hosts):

pssh/clients/base/single.py

@@ -32,7 +32,7 @@
 from ...constants import DEFAULT_RETRIES, RETRY_DELAY
 from ..reader import ConcurrentRWBuffer
 from ...exceptions import UnknownHostError, AuthenticationError, \
-    ConnectionError, Timeout
+    ConnectionError, Timeout, NoIPv6AddressFoundError
 from ...output import HostOutput, HostOutputBuffers, BufferData
 
 
@@ -166,7 +166,9 @@ def __init__(self, host,
                  proxy_host=None,
                  proxy_port=None,
                  _auth_thread_pool=True,
-                 identity_auth=True):
+                 identity_auth=True,
+                 ipv6_only=False,
+                 ):
         self._auth_thread_pool = _auth_thread_pool
         self.host = host
         self.user = user if user else getuser()
@@ -183,6 +185,7 @@ def __init__(self, host,
         self.pkey = _validate_pkey_path(pkey, self.host)
         self.identity_auth = identity_auth
         self._keepalive_greenlet = None
+        self.ipv6_only = ipv6_only
         self._init()
 
     def _init(self):
@@ -254,25 +257,37 @@ def _connect_init_session_retry(self, retries):
         self._connect(self._host, self._port, retries=retries)
         return self._init_session(retries=retries)
 
+    def _get_addr_info(self, host, port):
+        addr_info = socket.getaddrinfo(host, port, proto=socket.IPPROTO_TCP)
+        if self.ipv6_only:
+            filtered = [addr for addr in addr_info if addr[0] is socket.AF_INET6]
+            if not filtered:
+                raise NoIPv6AddressFoundError(
+                    "Requested IPv6 only and no IPv6 addresses found for host %s from "
+                    "address list %s", host, [addr for _, _, _, _, addr in addr_info])
+            addr_info = filtered
+        return addr_info
+
     def _connect(self, host, port, retries=1):
-        self.sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
-        if self.timeout:
-            self.sock.settimeout(self.timeout)
-        logger.debug("Connecting to %s:%s", host, port)
         try:
-            self.sock.connect((host, port))
+            addr_info = self._get_addr_info(host, port)
         except sock_gaierror as ex:
             logger.error("Could not resolve host '%s' - retry %s/%s",
                          host, retries, self.num_retries)
             if retries < self.num_retries:
                 sleep(self.retry_delay)
                 return self._connect(host, port, retries=retries+1)
-            ex = UnknownHostError("Unknown host %s - %s - retry %s/%s",
-                                  host, str(ex.args[1]), retries,
-                                  self.num_retries)
-            ex.host = host
-            ex.port = port
-            raise ex
+            unknown_ex = UnknownHostError("Unknown host %s - %s - retry %s/%s",
+                                          host, str(ex.args[1]), retries,
+                                          self.num_retries)
+            raise unknown_ex from ex
+        family, _type, proto, _, sock_addr = addr_info[0]
+        self.sock = socket.socket(family, _type)
+        if self.timeout:
+            self.sock.settimeout(self.timeout)
+        logger.debug("Connecting to %s:%s", host, port)
+        try:
+            self.sock.connect(sock_addr)
         except sock_error as ex:
             logger.error("Error connecting to host '%s:%s' - retry %s/%s",
                          host, port, retries, self.num_retries)
@@ -387,8 +402,8 @@ def read_stderr(self, stderr_buffer, timeout=None):
         """Read standard error buffer.
         Returns a generator of line by line output.
 
-        :param stdout_buffer: Buffer to read from.
-        :type stdout_buffer: :py:class:`pssh.clients.reader.ConcurrentRWBuffer`
+        :param stderr_buffer: Buffer to read from.
+        :type stderr_buffer: :py:class:`pssh.clients.reader.ConcurrentRWBuffer`
         :rtype: generator
         """
         logger.debug("Reading from stderr buffer, timeout=%s", timeout)

pssh/clients/native/parallel.py

@@ -36,7 +36,9 @@ def __init__(self, hosts, user=None, password=None, port=22, pkey=None,
                  proxy_host=None, proxy_port=None,
                  proxy_user=None, proxy_password=None, proxy_pkey=None,
                  forward_ssh_agent=False,
-                 keepalive_seconds=60, identity_auth=True):
+                 keepalive_seconds=60, identity_auth=True,
+                 ipv6_only=False,
+                 ):
         """
         :param hosts: Hosts to connect to
         :type hosts: list(str)
@@ -109,6 +111,10 @@ def __init__(self, hosts, user=None, password=None, port=22, pkey=None,
           Defaults to False if not set.
           Requires agent forwarding implementation in libssh2 version used.
         :type forward_ssh_agent: bool
+        :param ipv6_only: Choose IPv6 addresses only if multiple are available
+          for the host(s) or raise NoIPv6AddressFoundError otherwise. Note this will
+          disable connecting to an IPv4 address if an IP address is provided instead.
+        :type ipv6_only: bool
 
         :raises: :py:class:`pssh.exceptions.PKeyFileError` on errors finding
           provided private key.
@@ -118,7 +124,9 @@ def __init__(self, hosts, user=None, password=None, port=22, pkey=None,
             allow_agent=allow_agent, num_retries=num_retries,
             timeout=timeout, pool_size=pool_size,
             host_config=host_config, retry_delay=retry_delay,
-            identity_auth=identity_auth)
+            identity_auth=identity_auth,
+            ipv6_only=ipv6_only,
+        )
         self.pkey = _validate_pkey_path(pkey)
         self.proxy_host = proxy_host
         self.proxy_port = proxy_port
@@ -241,6 +249,7 @@ def _make_ssh_client(self, host_i, host):
                 forward_ssh_agent=self.forward_ssh_agent,
                 keepalive_seconds=self.keepalive_seconds,
                 identity_auth=self.identity_auth,
+                ipv6_only=self.ipv6_only,
             )
             self._host_clients[(host_i, host)] = _client
             return _client

pssh/clients/native/single.py

@@ -58,7 +58,9 @@ def __init__(self, host,
                  proxy_user=None,
                  proxy_password=None,
                  _auth_thread_pool=True, keepalive_seconds=60,
-                 identity_auth=True,):
+                 identity_auth=True,
+                 ipv6_only=False,
+                 ):
         """:param host: Host name or IP to connect to.
         :type host: str
         :param user: User to connect as. Defaults to logged in user.
@@ -95,6 +97,11 @@ def __init__(self, host,
         :type proxy_port: int
         :param keepalive_seconds: Interval of keep alive messages being sent to
           server. Set to ``0`` or ``False`` to disable.
+        :type keepalive_seconds: int
+        :param ipv6_only: Choose IPv6 addresses only if multiple are available
+          for the host or raise NoIPv6AddressFoundError otherwise. Note this will
+          disable connecting to an IPv4 address if an IP address is provided instead.
+        :type ipv6_only: bool
 
         :raises: :py:class:`pssh.exceptions.PKeyFileError` on errors finding
           provided private key.
@@ -126,7 +133,9 @@ def __init__(self, host,
             allow_agent=allow_agent, _auth_thread_pool=_auth_thread_pool,
             timeout=timeout,
             proxy_host=proxy_host, proxy_port=proxy_port,
-            identity_auth=identity_auth)
+            identity_auth=identity_auth,
+            ipv6_only=ipv6_only,
+        )
 
     def _shell(self, channel):
         return self._eagain(channel.shell)

pssh/clients/ssh/parallel.py

@@ -38,7 +38,9 @@ def __init__(self, hosts, user=None, password=None, port=22, pkey=None,
                  gssapi_server_identity=None,
                  gssapi_client_identity=None,
                  gssapi_delegate_credentials=False,
-                 identity_auth=True):
+                 identity_auth=True,
+                 ipv6_only=False,
+                 ):
         """
         :param hosts: Hosts to connect to
         :type hosts: list(str)
@@ -123,6 +125,10 @@ def __init__(self, hosts, user=None, password=None, port=22, pkey=None,
         :param gssapi_delegate_credentials: Enable/disable server credentials
           delegation.
         :type gssapi_delegate_credentials: bool
+        :param ipv6_only: Choose IPv6 addresses only if multiple are available
+          for the host or raise NoIPv6AddressFoundError otherwise. Note this will
+          disable connecting to an IPv4 address if an IP address is provided instead.
+        :type ipv6_only: bool
 
         :raises: :py:class:`pssh.exceptions.PKeyFileError` on errors finding
           provided private key.
@@ -132,7 +138,9 @@ def __init__(self, hosts, user=None, password=None, port=22, pkey=None,
             allow_agent=allow_agent, num_retries=num_retries,
             timeout=timeout, pool_size=pool_size,
             host_config=host_config, retry_delay=retry_delay,
-            identity_auth=identity_auth)
+            identity_auth=identity_auth,
+            ipv6_only=ipv6_only,
+        )
         self.pkey = _validate_pkey_path(pkey)
         self.cert_file = _validate_pkey_path(cert_file)
         self.forward_ssh_agent = forward_ssh_agent
@@ -239,6 +247,7 @@ def _make_ssh_client(self, host_i, host):
                 gssapi_client_identity=self.gssapi_client_identity,
                 gssapi_delegate_credentials=self.gssapi_delegate_credentials,
                 identity_auth=self.identity_auth,
+                ipv6_only=self.ipv6_only,
             )
             self._host_clients[(host_i, host)] = _client
             # TODO - Add forward agent functionality

pssh/clients/ssh/single.py

@@ -49,6 +49,7 @@ def __init__(self, host,
                  gssapi_server_identity=None,
                  gssapi_client_identity=None,
                  gssapi_delegate_credentials=False,
+                 ipv6_only=False,
                  _auth_thread_pool=True):
         """:param host: Host name or IP to connect to.
         :type host: str
@@ -97,6 +98,10 @@ def __init__(self, host,
         :param gssapi_delegate_credentials: Enable/disable server credentials
           delegation.
         :type gssapi_delegate_credentials: bool
+        :param ipv6_only: Choose IPv6 addresses only if multiple are available
+          for the host or raise NoIPv6AddressFoundError otherwise. Note this will
+          disable connecting to an IPv4 address if an IP address is provided instead.
+        :type ipv6_only: bool
 
         :raises: :py:class:`pssh.exceptions.PKeyFileError` on errors finding
           provided private key.
@@ -112,7 +117,9 @@ def __init__(self, host,
             allow_agent=allow_agent,
             _auth_thread_pool=_auth_thread_pool,
             timeout=timeout,
-            identity_auth=identity_auth)
+            identity_auth=identity_auth,
+            ipv6_only=ipv6_only,
+        )
 
     def disconnect(self):
         """Close socket if needed."""
@@ -141,9 +148,9 @@ def _init_session(self, retries=1):
         if self.gssapi_client_identity or self.gssapi_server_identity:
             self.session.options_set_gssapi_delegate_credentials(
                 self.gssapi_delegate_credentials)
-        self.session.set_socket(self.sock)
         logger.debug("Session started, connecting with existing socket")
         try:
+            self.session.set_socket(self.sock)
             self._session_connect()
         except Exception as ex:
             if retries < self.num_retries:

pssh/config.py

@@ -27,7 +27,7 @@ class HostConfig(object):
     __slots__ = ('user', 'port', 'password', 'private_key', 'allow_agent',
                  'num_retries', 'retry_delay', 'timeout', 'identity_auth',
                  'proxy_host', 'proxy_port', 'proxy_user', 'proxy_password', 'proxy_pkey',
-                 'keepalive_seconds',
+                 'keepalive_seconds', 'ipv6_only',
                  )
 
     def __init__(self, user=None, port=None, password=None, private_key=None,
@@ -36,6 +36,7 @@ def __init__(self, user=None, port=None, password=None, private_key=None,
                  proxy_host=None, proxy_port=None, proxy_user=None, proxy_password=None,
                  proxy_pkey=None,
                  keepalive_seconds=None,
+                 ipv6_only=None,
                  ):
         """
         :param user: Username to login as.
@@ -72,6 +73,8 @@ def __init__(self, user=None, port=None, password=None, private_key=None,
         :param keepalive_seconds: Seconds between keepalive packets being sent.
           0 to disable.
         :type keepalive_seconds: int
+        :param ipv6_only: Use IPv6 addresses only. Currently unused.
+        :type ipv6_only: bool
         """
         self.user = user
         self.port = port
@@ -88,6 +91,7 @@ def __init__(self, user=None, port=None, password=None, private_key=None,
         self.proxy_password = proxy_password
         self.proxy_pkey = proxy_pkey
         self.keepalive_seconds = keepalive_seconds
+        self.ipv6_only = ipv6_only
         self._sanity_checks()
 
     def _sanity_checks(self):
@@ -121,3 +125,5 @@ def _sanity_checks(self):
             raise ValueError("Proxy pkey %s is not a string" % (self.proxy_pkey,))
         if self.keepalive_seconds is not None and not isinstance(self.keepalive_seconds, int):
             raise ValueError("Keepalive seconds %s is not an integer" % (self.keepalive_seconds,))
+        if self.ipv6_only is not None and not isinstance(self.ipv6_only, bool):
+            raise ValueError("IPv6 only %s is not a boolean value" % (self.ipv6_only,))

pssh/exceptions.py

@@ -19,6 +19,16 @@
 """Exceptions raised by parallel-ssh classes."""
 
 
+class NoIPv6AddressFoundError(Exception):
+    """Raised when an IPV6 only address was requested but none are
+     available for a host.
+
+     This exception is raised instead of UnknownHostError
+     in the case where only IPV4 addresses are available via DNS for a host,
+     or an IPV4 address was provided but IPV6 only was requested.
+     """
+
+
 class UnknownHostError(Exception):
     """Raised when a host is unknown (dns failure)"""
     pass