From 3c7813683b1845959aca706eaa23f062a006356b Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Wed, 12 Jun 2024 19:47:36 +0200 Subject: Adding upstream version 3.4.0. Signed-off-by: Daniel Baumann --- sites/docs/.readthedocs.yaml | 13 ++++ sites/docs/api/agent.rst | 6 ++ sites/docs/api/auth.rst | 8 +++ sites/docs/api/buffered_pipe.rst | 4 ++ sites/docs/api/channel.rst | 4 ++ sites/docs/api/client.rst | 5 ++ sites/docs/api/config.rst | 135 +++++++++++++++++++++++++++++++++++++++ sites/docs/api/file.rst | 4 ++ sites/docs/api/hostkeys.rst | 5 ++ sites/docs/api/kex_gss.rst | 5 ++ sites/docs/api/keys.rst | 28 ++++++++ sites/docs/api/message.rst | 4 ++ sites/docs/api/packet.rst | 4 ++ sites/docs/api/pipe.rst | 4 ++ sites/docs/api/proxy.rst | 4 ++ sites/docs/api/server.rst | 5 ++ sites/docs/api/sftp.rst | 13 ++++ sites/docs/api/ssh_exception.rst | 4 ++ sites/docs/api/ssh_gss.rst | 17 +++++ sites/docs/api/transport.rst | 5 ++ sites/docs/conf.py | 28 ++++++++ sites/docs/index.rst | 75 ++++++++++++++++++++++ 22 files changed, 380 insertions(+) create mode 100644 sites/docs/.readthedocs.yaml create mode 100644 sites/docs/api/agent.rst create mode 100644 sites/docs/api/auth.rst create mode 100644 sites/docs/api/buffered_pipe.rst create mode 100644 sites/docs/api/channel.rst create mode 100644 sites/docs/api/client.rst create mode 100644 sites/docs/api/config.rst create mode 100644 sites/docs/api/file.rst create mode 100644 sites/docs/api/hostkeys.rst create mode 100644 sites/docs/api/kex_gss.rst create mode 100644 sites/docs/api/keys.rst create mode 100644 sites/docs/api/message.rst create mode 100644 sites/docs/api/packet.rst create mode 100644 sites/docs/api/pipe.rst create mode 100644 sites/docs/api/proxy.rst create mode 100644 sites/docs/api/server.rst create mode 100644 sites/docs/api/sftp.rst create mode 100644 sites/docs/api/ssh_exception.rst create mode 100644 sites/docs/api/ssh_gss.rst create mode 100644 sites/docs/api/transport.rst create mode 100644 sites/docs/conf.py create mode 100644 sites/docs/index.rst (limited to 'sites/docs') diff --git a/sites/docs/.readthedocs.yaml b/sites/docs/.readthedocs.yaml new file mode 100644 index 0000000..3212c93 --- /dev/null +++ b/sites/docs/.readthedocs.yaml @@ -0,0 +1,13 @@ +version: 2 + +build: + os: "ubuntu-22.04" + tools: + python: "3.7" + +python: + install: + - requirements: dev-requirements.txt + +sphinx: + configuration: sites/docs/conf.py diff --git a/sites/docs/api/agent.rst b/sites/docs/api/agent.rst new file mode 100644 index 0000000..f01ad97 --- /dev/null +++ b/sites/docs/api/agent.rst @@ -0,0 +1,6 @@ +SSH agents +========== + +.. automodule:: paramiko.agent + :inherited-members: + :no-special-members: diff --git a/sites/docs/api/auth.rst b/sites/docs/api/auth.rst new file mode 100644 index 0000000..b6bce36 --- /dev/null +++ b/sites/docs/api/auth.rst @@ -0,0 +1,8 @@ +Authentication modules +====================== + +.. automodule:: paramiko.auth_strategy + :member-order: bysource + +.. automodule:: paramiko.auth_handler + :member-order: bysource diff --git a/sites/docs/api/buffered_pipe.rst b/sites/docs/api/buffered_pipe.rst new file mode 100644 index 0000000..54d87c5 --- /dev/null +++ b/sites/docs/api/buffered_pipe.rst @@ -0,0 +1,4 @@ +Buffered pipes +============== + +.. automodule:: paramiko.buffered_pipe diff --git a/sites/docs/api/channel.rst b/sites/docs/api/channel.rst new file mode 100644 index 0000000..e71526f --- /dev/null +++ b/sites/docs/api/channel.rst @@ -0,0 +1,4 @@ +Channel +======= + +.. automodule:: paramiko.channel diff --git a/sites/docs/api/client.rst b/sites/docs/api/client.rst new file mode 100644 index 0000000..b201812 --- /dev/null +++ b/sites/docs/api/client.rst @@ -0,0 +1,5 @@ +Client +====== + +.. automodule:: paramiko.client + :member-order: bysource diff --git a/sites/docs/api/config.rst b/sites/docs/api/config.rst new file mode 100644 index 0000000..9015a77 --- /dev/null +++ b/sites/docs/api/config.rst @@ -0,0 +1,135 @@ +============= +Configuration +============= + +Paramiko **does not itself** leverage `OpenSSH-style config file directives +`_, 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 `_ (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 ` (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 ` +- ``Match``: supports the keywords ``all``, ``canonical``, ``exec``, ``final``, + ``host``, ``localuser``, ``originalhost``, and ``user``, with the following + caveats: + + - You must have the optional dependency Invoke installed; see :ref:`the + installation docs ` (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 + .. versionchanged:: 3.3 + Added support for the ``final`` keyword. + +- ``Port``: supplies potential values for ``%p`` :ref:`token expansion + `. +- ``ProxyCommand``: see our `.ProxyCommand` class for an easy + way to honor this keyword from a config you've parsed. + + - Honors :ref:`token expansion `. + - 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: + +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): + +- ``%C`` +- ``%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/file.rst b/sites/docs/api/file.rst new file mode 100644 index 0000000..199f3ec --- /dev/null +++ b/sites/docs/api/file.rst @@ -0,0 +1,4 @@ +Buffered files +============== + +.. automodule:: paramiko.file diff --git a/sites/docs/api/hostkeys.rst b/sites/docs/api/hostkeys.rst new file mode 100644 index 0000000..770652f --- /dev/null +++ b/sites/docs/api/hostkeys.rst @@ -0,0 +1,5 @@ +Host keys / ``known_hosts`` files +================================= + +.. automodule:: paramiko.hostkeys + :member-order: bysource diff --git a/sites/docs/api/kex_gss.rst b/sites/docs/api/kex_gss.rst new file mode 100644 index 0000000..9fd0922 --- /dev/null +++ b/sites/docs/api/kex_gss.rst @@ -0,0 +1,5 @@ +GSS-API key exchange +==================== + +.. automodule:: paramiko.kex_gss + :member-order: bysource diff --git a/sites/docs/api/keys.rst b/sites/docs/api/keys.rst new file mode 100644 index 0000000..a456f50 --- /dev/null +++ b/sites/docs/api/keys.rst @@ -0,0 +1,28 @@ +============ +Key handling +============ + +Parent key class +================ + +.. automodule:: paramiko.pkey + +DSA (DSS) +========= + +.. automodule:: paramiko.dsskey + +RSA +=== + +.. automodule:: paramiko.rsakey + +ECDSA +===== + +.. automodule:: paramiko.ecdsakey + +Ed25519 +======= + +.. automodule:: paramiko.ed25519key diff --git a/sites/docs/api/message.rst b/sites/docs/api/message.rst new file mode 100644 index 0000000..8d531e0 --- /dev/null +++ b/sites/docs/api/message.rst @@ -0,0 +1,4 @@ +Message +======= + +.. automodule:: paramiko.message diff --git a/sites/docs/api/packet.rst b/sites/docs/api/packet.rst new file mode 100644 index 0000000..4089203 --- /dev/null +++ b/sites/docs/api/packet.rst @@ -0,0 +1,4 @@ +Packetizer +========== + +.. automodule:: paramiko.packet diff --git a/sites/docs/api/pipe.rst b/sites/docs/api/pipe.rst new file mode 100644 index 0000000..e480446 --- /dev/null +++ b/sites/docs/api/pipe.rst @@ -0,0 +1,4 @@ +Cross-platform pipe implementations +=================================== + +.. automodule:: paramiko.pipe diff --git a/sites/docs/api/proxy.rst b/sites/docs/api/proxy.rst new file mode 100644 index 0000000..489b14e --- /dev/null +++ b/sites/docs/api/proxy.rst @@ -0,0 +1,4 @@ +``ProxyCommand`` support +======================== + +.. automodule:: paramiko.proxy diff --git a/sites/docs/api/server.rst b/sites/docs/api/server.rst new file mode 100644 index 0000000..ea85454 --- /dev/null +++ b/sites/docs/api/server.rst @@ -0,0 +1,5 @@ +Server implementation +===================== + +.. automodule:: paramiko.server + :member-order: bysource diff --git a/sites/docs/api/sftp.rst b/sites/docs/api/sftp.rst new file mode 100644 index 0000000..956eada --- /dev/null +++ b/sites/docs/api/sftp.rst @@ -0,0 +1,13 @@ +SFTP +==== + +.. automodule:: paramiko.sftp +.. automodule:: paramiko.sftp_client +.. automodule:: paramiko.sftp_server +.. automodule:: paramiko.sftp_attr +.. automodule:: paramiko.sftp_file + :inherited-members: + :no-special-members: + :show-inheritance: +.. automodule:: paramiko.sftp_handle +.. automodule:: paramiko.sftp_si diff --git a/sites/docs/api/ssh_exception.rst b/sites/docs/api/ssh_exception.rst new file mode 100644 index 0000000..64872dc --- /dev/null +++ b/sites/docs/api/ssh_exception.rst @@ -0,0 +1,4 @@ +Exceptions +========== + +.. automodule:: paramiko.ssh_exception diff --git a/sites/docs/api/ssh_gss.rst b/sites/docs/api/ssh_gss.rst new file mode 100644 index 0000000..155fcff --- /dev/null +++ b/sites/docs/api/ssh_gss.rst @@ -0,0 +1,17 @@ +GSS-API authentication +====================== + +.. automodule:: paramiko.ssh_gss + :member-order: bysource + +.. autoclass:: _SSH_GSSAuth + :member-order: bysource + +.. autoclass:: _SSH_GSSAPI_OLD + :member-order: bysource + +.. autoclass:: _SSH_GSSAPI_NEW + :member-order: bysource + +.. autoclass:: _SSH_SSPI + :member-order: bysource diff --git a/sites/docs/api/transport.rst b/sites/docs/api/transport.rst new file mode 100644 index 0000000..7c9d9fd --- /dev/null +++ b/sites/docs/api/transport.rst @@ -0,0 +1,5 @@ +Transport +========= + +.. automodule:: paramiko.transport + :member-order: bysource diff --git a/sites/docs/conf.py b/sites/docs/conf.py new file mode 100644 index 0000000..79958e6 --- /dev/null +++ b/sites/docs/conf.py @@ -0,0 +1,28 @@ +# Obtain shared config values +import os, sys +from os.path import abspath, join, dirname + +sys.path.append(abspath("..")) +sys.path.append(abspath("../..")) +from shared_conf import * + +# Enable autodoc, intersphinx +extensions.extend(["sphinx.ext.autodoc"]) + +# Autodoc settings +autodoc_default_options = { + "members": True, + "special-members": True, +} + +# 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/docs/index.rst b/sites/docs/index.rst new file mode 100644 index 0000000..675fe59 --- /dev/null +++ b/sites/docs/index.rst @@ -0,0 +1,75 @@ +==================================== +Welcome to Paramiko's documentation! +==================================== + +This site covers Paramiko's usage & API documentation. For basic info on what +Paramiko is, including its public changelog & how the project is maintained, +please see `the main project website `_. + + +API documentation +================= + +The high-level client API starts with creation of an `.SSHClient` object. For +more direct control, pass a socket (or socket-like object) to a `.Transport`, +and use `start_server <.Transport.start_server>` or `start_client +<.Transport.start_client>` to negotiate with the remote host as either a server +or client. + +As a client, you are responsible for authenticating using a password or private +key, and checking the server's host key. (Key signature and verification is +done by paramiko, but you will need to provide private keys and check that the +content of a public key matches what you expected to see.) + +As a server, you are responsible for deciding which users, passwords, and keys +to allow, and what kind of channels to allow. + +Once you have finished, either side may request flow-controlled `channels +<.Channel>` to the other side, which are Python objects that act like sockets, +but send and receive data over the encrypted session. + +For details, please see the following tables of contents (which are organized +by area of interest.) + + +Core SSH protocol classes +------------------------- + +.. toctree:: + api/channel + api/client + api/message + api/packet + api/transport + + +Authentication & keys +--------------------- + +.. toctree:: + api/auth + api/agent + api/hostkeys + api/keys + api/ssh_gss + api/kex_gss + + +Other primary functions +----------------------- + +.. toctree:: + api/config + api/proxy + api/server + api/sftp + + +Miscellany +---------- + +.. toctree:: + api/buffered_pipe + api/file + api/pipe + api/ssh_exception -- cgit v1.2.3