diff options
Diffstat (limited to 'sites')
| -rw-r--r-- | sites/docs/api/config.rst | 125 | ||||
| -rw-r--r-- | sites/docs/conf.py | 12 | ||||
| -rw-r--r-- | sites/www/changelog.rst | 79 | ||||
| -rw-r--r-- | sites/www/installing.rst | 27 |
4 files changed, 237 insertions, 6 deletions
diff --git a/sites/docs/api/config.rst b/sites/docs/api/config.rst index afb004c9..ea4939b2 100644 --- a/sites/docs/api/config.rst +++ b/sites/docs/api/config.rst @@ -1,5 +1,130 @@ +============= Configuration ============= +Paramiko **does not itself** leverage `OpenSSH-style config file directives +<ssh_config>`_, but it **does** implement a parser for the format, which users +can honor themselves (and is used by higher-level libraries, such as +`Fabric`_). + +The API for this is `.SSHConfig`, which loads SSH config files from disk, +file-like object, or string and exposes a "look up a hostname, get a dict of +applicable keywords/values back" functionality. + +As with OpenSSH's own support, this dict will contain values from across the +parsed file, depending on the order in which keywords were encountered and how +specific or generic the ``Host`` or ``Match`` directives were. + +.. note:; + Result keys are lowercased for consistency and ease of deduping, as the + overall parsing/matching is itself case-insensitive. Thus, a source file + containing e.g. ``ProxyCommand`` will result in lookup results like + ``{"proxycommand": "shell command here"}``. + + +.. _ssh-config-support: + +Keywords currently supported +============================ + +The following is an alphabetical list of which `ssh_config`_ directives +Paramiko interprets during the parse/lookup process (as above, actual SSH +connections **do not** reference parsed configs). Departures from `OpenSSH's +implementation <ssh_config>`_ (e.g. to support backwards compat with older +Paramiko releases) are included. A keyword by itself means no known departures. + +- ``AddressFamily``: used when looking up the local hostname for purposes of + expanding the ``%l``/``%L`` :ref:`tokens <TOKENS>` (this is actually a minor + value-add on top of OpenSSH, which doesn't actually honor this setting when + expanding ``%l``). +- ``CanonicalDomains`` + + .. versionadded:: 2.7 + +- ``CanonicalizeFallbackLocal``: when ``no``, triggers raising of + `.CouldNotCanonicalize` for target hostnames which do not successfully + canonicalize. + + .. versionadded:: 2.7 + +- ``CanonicalizeHostname``: along with the other ``Canonicaliz*`` settings + (sans ``CanonicalizePermittedCNAMEs``, which is not yet implemented), enables + hostname canonicalization, insofar as calling `.SSHConfig.lookup` with a + given hostname will return a canonicalized copy of the config data, including + an updated ``HostName`` value. + + .. versionadded:: 2.7 + +- ``CanonicalizeMaxDots`` + + .. versionadded:: 2.7 + +- ``Host`` +- ``HostName``: used in ``%h`` :ref:`token expansion <TOKENS>` +- ``Match``: fully supported, with the following caveats: + + - You must have the optional dependency Invoke installed; see :ref:`the + installation docs <paramiko-itself>` (in brief: install + ``paramiko[invoke]`` or ``paramiko[all]``). + - As usual, connection-time information is not present during config + lookup, and thus cannot be used to determine matching. This primarily + impacts ``Match user``, which can match against loaded ``User`` values + but has no knowledge about connection-time usernames. + + .. versionadded:: 2.7 + +- ``Port``: supplies potential values for ``%p`` :ref:`token expansion + <TOKENS>`. +- ``ProxyCommand``: see our `.ProxyCommand` class for an easy + way to honor this keyword from a config you've parsed. + + - Honors :ref:`token expansion <TOKENS>`. + - When a lookup would result in an effective ``ProxyCommand none``, + Paramiko (as of 1.x-2.x) strips it from the resulting dict entirely. A + later major version may retain the ``"none"`` marker for clarity's sake. + +- ``User``: supplies potential values for ``%u`` :ref:`token expansion + <TOKENS>`. + +.. _TOKENS: + +Expansion tokens +---------------- + +We support most SSH config expansion tokens where possible, so when they are +present in a config file source, the result of a `.SSHConfig.lookup` will +contain the expansions/substitutions (based on the rest of the config or +properties of the local system). + +Specifically, we are known to support the below, where applicable (e.g. as in +OpenSSH, ``%L`` works in ``ControlPath`` but not elsewhere): + +- ``%d`` +- ``%h`` +- ``%l`` +- ``%L`` +- ``%n`` +- ``%p`` +- ``%r`` +- ``%u``: substitutes the configured ``User`` value, or the local user (as seen + by ``getpass.getuser``) if not specified. + +In addition, we extend OpenSSH's tokens as follows: + +- ``~`` is treated like ``%d`` (expands to the local user's home directory + path) when expanding ``ProxyCommand`` values, since ``ProxyCommand`` does not + natively support ``%d`` for some reason. + + +.. _ssh_config: https://man.openbsd.org/ssh_config +.. _Fabric: http://fabfile.org + + +``config`` module API documentation +=================================== + +Mostly of interest to contributors; see previous section for behavioral +details. + .. automodule:: paramiko.config :member-order: bysource diff --git a/sites/docs/conf.py b/sites/docs/conf.py index eb895804..4805a03c 100644 --- a/sites/docs/conf.py +++ b/sites/docs/conf.py @@ -1,8 +1,9 @@ # Obtain shared config values import os, sys +from os.path import abspath, join, dirname -sys.path.append(os.path.abspath("..")) -sys.path.append(os.path.abspath("../..")) +sys.path.append(abspath("..")) +sys.path.append(abspath("../..")) from shared_conf import * # Enable autodoc, intersphinx @@ -11,6 +12,13 @@ extensions.extend(["sphinx.ext.autodoc"]) # Autodoc settings autodoc_default_flags = ["members", "special-members"] +# Default is 'local' building, but reference the public www site when building +# under RTD. +target = join(dirname(__file__), "..", "www", "_build") +if os.environ.get("READTHEDOCS") == "True": + target = "http://paramiko.org" +intersphinx_mapping["www"] = (target, None) + # Sister-site links to WWW html_theme_options["extra_nav_links"] = { "Main website": "http://www.paramiko.org" diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 02e48e92..7c20e434 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -8,6 +8,85 @@ Changelog to a bug causing them to ignore the ``hash_algo`` class attribute. This has been corrected. Big thanks to ``@miverson`` for the report and to Benno Rice for the patch. +- :release:`2.7.2 <2020-08-30>` +- :support:`- backported` Update our CI to catch issues with sdist generation, + installation and testing. +- :support:`1727 backported` Add missing test suite fixtures directory to + MANIFEST.in, reinstating the ability to run Paramiko's tests from an sdist + tarball. Thanks to Sandro Tosi for reporting the issue and to Blazej Michalik + for the PR. +- :support:`1722 backported` Remove leading whitespace from OpenSSH RSA test + suite static key fixture, to conform better to spec. Credit: Alex Gaynor. +- :bug:`-` Fix incorrect string formatting causing unhelpful error message + annotation when using Kerberos/GSSAPI. (Thanks, newer version of flake8!) +- :bug:`1723` Fix incorrectly swapped order of ``p`` and ``q`` numbers when + loading OpenSSH-format RSA private keys. At minimum this should address a + slowdown when using such keys, and it also means Paramiko works with + Cryptography 3.1 and above (which complains strenuously when this problem + appears). Thanks to Alex Gaynor for the patch. +- :release:`2.7.1 <2019-12-09>` +- :bug:`1567` The new-style private key format (added in 2.7) suffered from an + unpadding bug which had been fixed earlier for Ed25519 (as that key type has + always used the newer format). That fix has been refactored and applied to + the base key class, courtesy of Pierce Lopez. +- :bug:`1565` (via :issue:`1566`) Fix a bug in support for ECDSA keys under the + newly supported OpenSSH key format. Thanks to Pierce Lopez for the patch. +- :release:`2.7.0 <2019-12-03>` +- :feature:`602` (via :issue:`1343`, :issue:`1313`, :issue:`618`) Implement + support for OpenSSH 6.5-style private key files (typically denoted as having + ``BEGIN OPENSSH PRIVATE KEY`` headers instead of PEM format's ``BEGIN RSA + PRIVATE KEY`` or similar). If you were getting any sort of weird auth error + from "modern" keys generated on newer operating system releases (such as + macOS Mojave), this is the first update to try. + + Major thanks to everyone who contributed or tested versions of the patch, + including but not limited to: Kevin Abel, Michiel Tiller, Pierce Lopez, and + Jared Hobbs. +- :bug:`- major` ``ssh_config`` :ref:`token expansion <TOKENS>` used a + different method of determining the local username (``$USER`` env var), + compared to what the (much older) client connection code does + (``getpass.getuser``, which includes ``$USER`` but may check other variables + first, and is generally much more comprehensive). Both modules now use + ``getpass.getuser``. +- :feature:`-` A couple of outright `~paramiko.config.SSHConfig` parse errors + were previously represented as vanilla ``Exception`` instances; as part of + recent feature work a more specific exception class, + `~paramiko.ssh_exception.ConfigParseError`, has been created. It is now also + used in those older spots, which is naturally backwards compatible. +- :feature:`717` Implement support for the ``Match`` keyword in ``ssh_config`` + files. Previously, this keyword was simply ignored & keywords inside such + blocks were treated as if they were part of the previous block. Thanks to + Michael Leinartas for the initial patchset. + + .. note:: + This feature adds a new :doc:`optional install dependency </installing>`, + `Invoke <https://www.pyinvoke.org>`_, for managing ``Match exec`` + subprocesses. + +- :support:`-` Additional :doc:`installation </installing>` ``extras_require`` + "flavors" (``ed25519``, ``invoke``, and ``all``) have been added to + our packaging metadata; see the install docs for details. +- :bug:`- major` Paramiko's use of ``subprocess`` for ``ProxyCommand`` support + is conditionally imported to prevent issues on limited interpreter platforms + like Google Compute Engine. However, any resulting ``ImportError`` was lost + instead of preserved for raising (in the rare cases where a user tried + leveraging ``ProxyCommand`` in such an environment). This has been fixed. +- :bug:`- major` Perform deduplication of ``IdentityFile`` contents during + ``ssh_config`` parsing; previously, if your config would result in the same + value being encountered more than once, ``IdentityFile`` would contain that + many copies of the same string. +- :feature:`897` Implement most 'canonical hostname' ``ssh_config`` + functionality (``CanonicalizeHostname``, ``CanonicalDomains``, + ``CanonicalizeFallbackLocal``, and ``CanonicalizeMaxDots``; + ``CanonicalizePermittedCNAMEs`` has **not** yet been implemented). All were + previously silently ignored. Reported by Michael Leinartas. +- :support:`-` Explicitly document :ref:`which ssh_config features we + currently support <ssh-config-support>`. Previously users just had to guess, + which is simply no good. +- :feature:`-` Add new convenience classmethod constructors to + `~paramiko.config.SSHConfig`: `~paramiko.config.SSHConfig.from_text`, + `~paramiko.config.SSHConfig.from_file`, and + `~paramiko.config.SSHConfig.from_path`. No more annoying two-step process! - :release:`2.6.0 <2019-06-23>` - :feature:`1463` Add a new keyword argument to `SSHClient.connect <paramiko.client.SSHClient.connect>` and `~paramiko.transport.Transport`, diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 2e2f639c..b50efc4b 100644 --- a/sites/www/installing.rst +++ b/sites/www/installing.rst @@ -22,15 +22,31 @@ via `pip <http://pip-installer.org>`_:: We currently support **Python 2.7, 3.4+, and PyPy**. Users on Python 2.6 or older (or 3.3 or older) are urged to upgrade. -Paramiko has only a few direct dependencies: +Paramiko has only a few **direct dependencies**: - The big one, with its own sub-dependencies, is Cryptography; see :ref:`its - specific note below <cryptography>` for more details. + specific note below <cryptography>` for more details; - `bcrypt <https://pypi.org/project/bcrypt/>`_, for Ed25519 key support; - `pynacl <https://pypi.org/project/PyNaCl/>`_, also for Ed25519 key support. -If you need GSS-API / SSPI support, see :ref:`the below subsection on it -<gssapi>` for details on its optional dependencies. +There are also a number of **optional dependencies** you may install using +`setuptools 'extras' +<https://packaging.python.org/tutorials/installing-packages/#installing-setuptools-extras>`_: + +.. TODO 3.0: tweak the invoke line to mention proxycommand too +.. TODO 3.0: tweak the ed25519 line to remove the caveat + +- If you want all optional dependencies at once, use ``paramiko[all]``. +- For ``Match exec`` config support, use ``paramiko[invoke]`` (which installs + `Invoke <https://www.pyinvoke.org>`_). +- For GSS-API / SSPI support, use ``paramiko[gssapi]``, though also see + :ref:`the below subsection on it <gssapi>` for details. +- ``paramiko[ed25519]`` references the dependencies for Ed25519 key support. + + - As of Paramiko 2.x this doesn't technically do anything, as those + dependencies are core installation requirements. + - However, you should use this for forwards compatibility; 3.0 will drop + those dependencies from core, leaving them purely optional. .. _release-lines: @@ -122,6 +138,9 @@ optional Python package requirements by changing your installation to refer to (Or update your ``requirements.txt``, or etc.) + +.. TODO: just axe this once legacy gssapi support is gone, no point reiterating + Manual dependency installation ------------------------------ |