diff options
Diffstat (limited to 'sites')
| -rw-r--r-- | sites/docs/api/config.rst | 125 | ||||
| -rw-r--r-- | sites/docs/api/ssh_gss.rst | 5 | ||||
| -rw-r--r-- | sites/docs/conf.py | 12 | ||||
| -rw-r--r-- | sites/www/changelog.rst | 146 | ||||
| -rw-r--r-- | sites/www/installing.rst | 72 |
5 files changed, 334 insertions, 26 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/api/ssh_gss.rst b/sites/docs/api/ssh_gss.rst index 7a687e11..155fcfff 100644 --- a/sites/docs/api/ssh_gss.rst +++ b/sites/docs/api/ssh_gss.rst @@ -7,7 +7,10 @@ GSS-API authentication .. autoclass:: _SSH_GSSAuth :member-order: bysource -.. autoclass:: _SSH_GSSAPI +.. autoclass:: _SSH_GSSAPI_OLD + :member-order: bysource + +.. autoclass:: _SSH_GSSAPI_NEW :member-order: bysource .. autoclass:: _SSH_SSPI 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 ff87bfbb..67ba6554 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,139 @@ Changelog ========= +- :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 ``everything``) 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`, + ``disabled_algorithms``, which allows selectively disabling one or more + kex/key/cipher/etc algorithms. This can be useful when disabling algorithms + your target server (or client) does not support cleanly, or to work around + unpatched bugs in Paramiko's own implementation thereof. +- :release:`2.5.1 <2019-06-23>` +- :release:`2.4.3 <2019-06-23>` +- :bug:`1306` (via :issue:`1400`) Fix Ed25519 key handling so certain key + comment lengths don't cause ``SSHException("Invalid key")`` (this was + technically a bug in how padding, or lack thereof, is + calculated/interpreted). Thanks to ``@parke`` for the bug report & Pierce + Lopez for the patch. +- :support:`1440` (with initial fixes via :issue:`1460`) Tweak many exception + classes so their string representations are more human-friendly; this also + includes incidental changes to some ``super()`` calls. + + The definitions of exceptions' ``__init__`` methods have *not* changed, nor + have any log messages been altered, so this should be backwards compatible + for everything except the actual exceptions' ``__str__()`` outputs. + + Thanks to Fabian Büchler for original report & Pierce Lopez for the + foundational patch. +- :support:`1311` (for :issue:`584`, replacing :issue:`1166`) Add + backwards-compatible support for the ``gssapi`` GSSAPI library, as the + previous backend (``python-gssapi``) has since become defunct. This change + also includes tests for the GSSAPI functionality. + + Big thanks to Anselm Kruis for the patch and to Sebastian Deiß (author of our + initial GSSAPI functionality) for review. + + .. note:: + This feature also adds ``setup.py`` 'extras' support for installing + Paramiko as ``paramiko[gssapi]``, which pulls in the optional + dependencies you had to get by hand previously. + + .. note:: + To be very clear, this patch **does not** remove support for the older + ``python-gssapi`` library. We *may* remove that support in a later release, + but for now, either library will work. Please upgrade to ``gssapi`` when + you can, however, as ``python-gssapi`` is no longer maintained upstream. + +- :bug:`322 major` `SSHClient.exec_command + <paramiko.client.SSHClient.exec_command>` previously returned a naive + `~paramiko.channel.ChannelFile` object for its ``stdin`` value; such objects + don't know to properly shut down the remote end's stdin when they + ``.close()``. This lead to issues (such as hangs) when running remote + commands that read from stdin. + + A new subclass, `~paramiko.channel.ChannelStdinFile`, has been created which + closes remote stdin when it itself is closed. + `~paramiko.client.SSHClient.exec_command` has been updated to use that class + for its ``stdin`` return value. + + Thanks to Brandon Rhodes for the report & steps to reproduce. +- :release:`2.5.0 <2019-06-09>` +- :feature:`1233` (also :issue:`1229`, :issue:`1332`) Add support for + encrypt-then-MAC (ETM) schemes (``hmac-sha2-256-etm@openssh.com``, + ``hmac-sha2-512-etm@openssh.com``) and two newer Diffie-Hellman group key + exchange algorithms (``group14``, using SHA256; and ``group16``, using + SHA512). Patch courtesy of Edgar Sousa. +- :feature:`532` (via :issue:`1384` and :issue:`1258`) Add support for + Curve25519 key exchange (aka ``curve25519-sha256@libssh.org``). Thanks to + Alex Gaynor and Dan Fuhry for supplying patches. +- :support:`1379` (also :issue:`1369`) Raise Cryptography dependency + requirement to version 2.5 (from 1.5) and update some deprecated uses of its + API. + + This removes a bunch of warnings of the style + ``CryptographyDeprecationWarning: encode_point has been deprecated on + EllipticCurvePublicNumbers and will be removed in a future version. Please + use EllipticCurvePublicKey.public_bytes to obtain both compressed and + uncompressed point encoding`` and similar, which users who had eventually + upgraded to Cryptography 2.x would encounter. + + .. warning:: + This change is backwards incompatible **if** you are unable to upgrade your + version of Cryptography. Please see `Cryptography's own changelog + <https://cryptography.io/en/latest/changelog/>`_ for details on what may + change when you upgrade; for the most part the only changes involved + dropping older Python versions (such as 2.6, 3.3, or some PyPy editions) + which Paramiko itself has already dropped. + +- :support:`1378 backported` Add support for the modern (as of Python 3.3) + import location of ``MutableMapping`` (used in host key management) to avoid + the old location becoming deprecated in Python 3.8. Thanks to Josh Karpel for + catch & patch. - :release:`2.4.2 <2018-09-18>` - :release:`2.3.3 <2018-09-18>` - :release:`2.2.4 <2018-09-18>` @@ -23,8 +156,9 @@ Changelog for this particular channel). Thanks to Daniel Hoffman for the detailed report. -- :support:`1292 backported` Backport changes from :issue:`979` (added in - Paramiko 2.3) to Paramiko 2.0-2.2, using duck-typing to preserve backwards +- :support:`1292 backported (<2.4)` Backport changes from :issue:`979` (added + in Paramiko + 2.3) to Paramiko 2.0-2.2, using duck-typing to preserve backwards compatibility. This allows these older versions to use newer Cryptography sign/verify APIs when available, without requiring them (as is the case with Paramiko 2.3+). @@ -37,9 +171,9 @@ Changelog This is a no-op for Paramiko 2.3+, which have required newer Cryptography releases since they were released. -- :support:`1291 backported` Backport pytest support and application of the - ``black`` code formatter (both of which previously only existed in the 2.4 - branch and above) to everything 2.0 and newer. This makes back/forward +- :support:`1291 backported (<2.4)` Backport pytest support and application of + the ``black`` code formatter (both of which previously only existed in the + 2.4 branch and above) to everything 2.0 and newer. This makes back/forward porting bugfixes significantly easier. - :support:`1262 backported` Add ``*.pub`` files to the MANIFEST so distributed source packages contain some necessary test assets. Credit: Alexander @@ -95,7 +229,7 @@ Changelog - :support:`1100` Updated the test suite & related docs/metadata/config to be compatible with pytest instead of using the old, custom, crufty unittest-based ``test.py``. - + This includes marking known-slow tests (mostly the SFTP ones) so they can be filtered out by ``inv test``'s default behavior; as well as other minor tweaks to test collection and/or display (for example, GSSAPI tests are diff --git a/sites/www/installing.rst b/sites/www/installing.rst index 3631eb0d..f2d9a341 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: @@ -95,22 +111,44 @@ In general, you'll need one of the following setups: Optional dependencies for GSS-API / SSPI / Kerberos =================================================== -In order to use GSS-API/Kerberos & related functionality, a couple of -additional dependencies are required (these are not listed in our ``setup.py`` -due to their infrequent utility & non-platform-agnostic requirements): - -* It hopefully goes without saying but **all platforms** need **a working - installation of GSS-API itself**, e.g. Heimdal. -* **Unix** needs `python-gssapi <https://pypi.org/project/python-gssapi/>`_ - ``0.6.1`` or better. - - .. note:: This library appears to only function on Python 2.7 and up. - -* **Windows** needs `pywin32 <https://pypi.python.org/pypi/pywin32>`_ ``2.1.8`` - or better. +In order to use GSS-API/Kerberos & related functionality, additional +dependencies are required. It hopefully goes without saying but **all +platforms** need **a working installation of GSS-API itself**, e.g. Heimdal. .. note:: If you use Microsoft SSPI for kerberos authentication and credential delegation, make sure that the target host is trusted for delegation in the active directory configuration. For details see: http://technet.microsoft.com/en-us/library/cc738491%28v=ws.10%29.aspx + +The ``gssapi`` "extra" install flavor +------------------------------------- + +If you're installing via ``pip`` (recommended), you should be able to get the +optional Python package requirements by changing your installation to refer to +``paramiko[gssapi]`` (from simply ``paramiko``), e.g.:: + + pip install "paramiko[gssapi]" + +(Or update your ``requirements.txt``, or etc.) + + +.. TODO: just axe this once legacy gssapi support is gone, no point reiterating + +Manual dependency installation +------------------------------ + +If you're not using ``pip`` or your ``pip`` is too old to support the "extras" +functionality, the optional dependencies are as follows: + +* All platforms need `pyasn1 <https://pypi.org/project/pyasn1/>`_ ``0.1.7`` or + later. +* **Unix** needs: `gssapi <https://pypi.org/project/gssapi/>`__ ``1.4.1`` or better. + + * An alternative is the `python-gssapi + <https://pypi.org/project/python-gssapi/>`_ library (``0.6.1`` or above), + though it is no longer maintained upstream, and Paramiko's support for + its API may eventually become deprecated. + +* **Windows** needs `pywin32 <https://pypi.python.org/pypi/pywin32>`_ ``2.1.8`` + or better. |