diff options
| -rw-r--r-- | README.rst | 156 | ||||
| -rw-r--r-- | paramiko/channel.py | 14 | ||||
| -rw-r--r-- | paramiko/packet.py | 7 | ||||
| -rw-r--r-- | paramiko/ssh_exception.py | 2 | ||||
| -rw-r--r-- | sites/www/changelog.rst | 2 |
5 files changed, 177 insertions, 4 deletions
diff --git a/README.rst b/README.rst new file mode 100644 index 00000000..df829f31 --- /dev/null +++ b/README.rst @@ -0,0 +1,156 @@ +======== +Paramiko +======== + +.. Continuous integration and code coverage badges + +.. image:: https://travis-ci.org/paramiko/paramiko.svg?branch=master + :target: https://travis-ci.org/paramiko/paramiko +.. image:: https://coveralls.io/repos/paramiko/paramiko/badge.svg?branch=master&service=github + :target: https://coveralls.io/github/paramiko/paramiko?branch=master + +:Paramiko: Python SSH module +:Copyright: Copyright (c) 2003-2009 Robey Pointer <robeypointer@gmail.com> +:Copyright: Copyright (c) 2013-2015 Jeff Forcier <jeff@bitprophet.org> +:License: `LGPL <https://www.gnu.org/copyleft/lesser.html>`_ +:Homepage: http://www.paramiko.org/ +:API docs: http://docs.paramiko.org +:Development: https://github.com/paramiko/paramiko + + +What +---- + +"Paramiko" is a combination of the esperanto words for "paranoid" and +"friend". It's a module for Python 2.6+ that implements the SSH2 protocol +for secure (encrypted and authenticated) connections to remote machines. +Unlike SSL (aka TLS), SSH2 protocol does not require hierarchical +certificates signed by a powerful central authority. You may know SSH2 as +the protocol that replaced Telnet and rsh for secure access to remote +shells, but the protocol also includes the ability to open arbitrary +channels to remote services across the encrypted tunnel (this is how SFTP +works, for example). + +It is written entirely in Python (no C or platform-dependent code) and is +released under the GNU Lesser General Public License (`LGPL +<https://www.gnu.org/copyleft/lesser.html>`_). + +The package and its API is fairly well documented in the "doc/" folder +that should have come with this archive. + + +Requirements +------------ + +- `Python <http://www.python.org/>`_ 2.6, 2.7, or 3.3+ +- Cryptography 0.8 or better <https://cryptography.io> +- pyasn1 0.1.7 or better <https://pypi.python.org/pypi/pyasn1> + + +Installation +------------ + +For most users, the recommended method to install is via pip:: + + pip install paramiko + +For more detailed instructions, see the `Installing +<http://www.paramiko.org/installing.html>`_ page on the main Paramiko website. + + +Portability Issues +------------------ + +Paramiko primarily supports POSIX platforms with standard OpenSSH +implementations, and is most frequently tested on Linux and OS X. Windows is +supported as well, though it may not be as straightforward. + +Some Python distributions don't include the UTF-8 string encodings, for +reasons of space (misguided as that is). If your distribution is +missing encodings, you'll see an error like this:: + + LookupError: no codec search functions registered: can't find encoding + +This means you need to copy string encodings over from a working system +(it probably only happens on embedded systems, not normal Python +installs). Valeriy Pogrebitskiy says the best place to look is +``.../lib/python*/encodings/__init__.py``. + + +Bugs & Support +-------------- + +:Bug Reports: `Github <https://github.com/paramiko/paramiko/issues/>`_ +:Mailing List: ``paramiko@librelist.com`` (see the `LibreList website + <http://librelist.com/>`_ for usage details). +:IRC: ``#paramiko`` on Freenode + + +Kerberos Support +---------------- + +Paramiko ships with optional Kerberos/GSSAPI support; for info on the extra +dependencies for this, see the `GSS-API section +<http://www.paramiko.org/installing.html#gssapi>`_ +on the main Paramiko website. + + +Demo +---- + +Several demo scripts come with Paramiko to demonstrate how to use it. +Probably the simplest demo of all is this:: + + import paramiko, base64 + key = paramiko.RSAKey(data=base64.decodestring('AAA...')) + client = paramiko.SSHClient() + client.get_host_keys().add('ssh.example.com', 'ssh-rsa', key) + client.connect('ssh.example.com', username='strongbad', password='thecheat') + stdin, stdout, stderr = client.exec_command('ls') + for line in stdout: + print '... ' + line.strip('\n') + client.close() + +This prints out the results of executing ``ls`` on a remote server. The host +key 'AAA...' should of course be replaced by the actual base64 encoding of the +host key. If you skip host key verification, the connection is not secure! + +The following example scripts (in demos/) get progressively more detailed: + +:demo_simple.py: + Calls invoke_shell() and emulates a terminal/TTY through which you can + execute commands interactively on a remote server. Think of it as a + poor man's SSH command-line client. + +:demo.py: + Same as demo_simple.py, but allows you to authenticate using a private + key, attempts to use an SSH agent if present, and uses the long form of + some of the API calls. + +:forward.py: + Command-line script to set up port-forwarding across an SSH transport. + +:demo_sftp.py: + Opens an SFTP session and does a few simple file operations. + +:demo_server.py: + An SSH server that listens on port 2200 and accepts a login for + 'robey' (password 'foo'), and pretends to be a BBS. Meant to be a + very simple demo of writing an SSH server. + +:demo_keygen.py: + A key generator similar to OpenSSH ``ssh-keygen(1)`` program with + Paramiko keys generation and progress functions. + +Use +--- + +The demo scripts are probably the best example of how to use this package. +There is also a lot of documentation, generated with Sphinx autodoc, in the +doc/ folder. + +There are also unit tests here:: + + $ python ./test.py + +Which will verify that most of the core components are working correctly. diff --git a/paramiko/channel.py b/paramiko/channel.py index 057b417b..4ce4f286 100644 --- a/paramiko/channel.py +++ b/paramiko/channel.py @@ -286,7 +286,8 @@ class Channel (ClosingContextManager): return an exit status in some cases (like bad servers). :return: - ``True`` if `recv_exit_status` will return immediately, else ``False``. + ``True`` if `recv_exit_status` will return immediately, else + ``False``. .. versionadded:: 1.7.3 """ @@ -300,6 +301,17 @@ class Channel (ClosingContextManager): it does, or until the channel is closed. If no exit status is provided by the server, -1 is returned. + .. warning:: + In some situations, receiving remote output larger than the current + `.Transport` or session's ``window_size`` (e.g. that set by the + ``default_window_size`` kwarg for `.Transport.__init__`) will cause + `.recv_exit_status` to hang indefinitely if it is called prior to a + sufficiently large `~Channel..read` (or if there are no threads + calling `~Channel.read` in the background). + + In these cases, ensuring that `.recv_exit_status` is called *after* + `~Channel.read` (or, again, using threads) can avoid the hang. + :return: the exit code (as an `int`) of the process on the server. .. versionadded:: 1.2 diff --git a/paramiko/packet.py b/paramiko/packet.py index bdd31efd..00cf5657 100644 --- a/paramiko/packet.py +++ b/paramiko/packet.py @@ -204,9 +204,10 @@ class Packetizer (object): def handshake_timed_out(self): """ Checks if the handshake has timed out. - If `start_handshake` wasn't called before the call to this function - the return value will always be `False`. - If the handshake completed before a time out was reached the return value will be `False` + + If `start_handshake` wasn't called before the call to this function, + the return value will always be `False`. If the handshake completed + before a timeout was reached, the return value will be `False` :return: handshake time out status, as a `bool` """ diff --git a/paramiko/ssh_exception.py b/paramiko/ssh_exception.py index 02f3e52e..016a411e 100644 --- a/paramiko/ssh_exception.py +++ b/paramiko/ssh_exception.py @@ -156,6 +156,8 @@ class NoValidConnectionsError(socket.error): It is implied/assumed that all the errors given to a single instance of this class are from connecting to the same hostname + port (and thus that the differences are in the resolution of the hostname - e.g. IPv4 vs v6). + + .. versionadded:: 1.16 """ def __init__(self, errors): """ diff --git a/sites/www/changelog.rst b/sites/www/changelog.rst index 084d13de..b66dd0db 100644 --- a/sites/www/changelog.rst +++ b/sites/www/changelog.rst @@ -2,6 +2,8 @@ Changelog ========= +* :support:`636` Clean up and enhance the README (and rename it to + ``README.rst`` from just ``README``). Thanks to ``@LucasRMehl``. * :release:`1.16.0 <2015-11-04>` * :bug:`194 major` (also :issue:`562`, :issue:`530`, :issue:`576`) Streamline use of ``stat`` when downloading SFTP files via `SFTPClient.get |