diff options
Diffstat (limited to 'README.rst')
| -rw-r--r-- | README.rst | 174 |
1 files changed, 29 insertions, 145 deletions
@@ -1,145 +1,29 @@ -======== -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://codecov.io/gh/paramiko/paramiko/branch/master/graph/badge.svg - :target: https://codecov.io/gh/paramiko/paramiko - -:Paramiko: Python SSH module -:Copyright: Copyright (c) 2009 Robey Pointer <robeypointer@gmail.com> -:Copyright: Copyright (c) 2020 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.7/3.4+ 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 (though it depends on third-party C wrappers -for low level crypto; these are often available precompiled) 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 ``docs`` folder that -should have come with this repository. - - -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. - -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 is this:: - - import base64 - import paramiko - key = paramiko.RSAKey(data=base64.b64decode(b'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 ``b'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. -Also a lot of documentation is generated by Sphinx autodoc, in the -doc/ folder. - -There are also unit tests here:: - - $ pip install -r dev-requirements.txt - $ pytest - -Which will verify that most of the core components are working correctly. - -To test Kerberos/GSSAPI, you need a Kerberos environment. On UNIX you can -use the package k5test to setup a Kerberos environment on the fly:: - - $ pip install -r dev-requirements.txt - $ pip install k5test gssapi pyasn1 - $ pytest +Welcome to Paramiko! +==================== + +Paramiko is a pure-Python [#]_ (2.7, 3.4+) implementation of the SSHv2 protocol +[#]_, providing both client and server functionality. It provides the +foundation for the high-level SSH library `Fabric <https://fabfile.org>`_, +which is what we recommend you use for common client use-cases such as running +remote shell commands or transferring files. + +Direct use of Paramiko itself is only intended for users who need +advanced/low-level primitives or want to run an in-Python sshd. + +For installation information, changelogs, FAQs and similar, please visit `our +main project website <https://paramiko.org>`_; for API details, see `the +versioned docs <https://docs.paramiko.org>`_. Additionally, the project +maintainer keeps a `roadmap <http://bitprophet.org/projects#roadmap>`_ on his +personal site. + +.. [#] + Paramiko relies on `cryptography <https://cryptography.io>`_ for crypto + functionality, which makes use of C and Rust extensions but has many + precompiled options available. See `our installation page + <https://www.paramiko.org/installing.html>`_ for details. + +.. [#] + SSH is defined in :rfc:`4251`, :rfc:`4252`, :rfc:`4253` and :rfc:`4254`. The + primary working implementation of the protocol is the `OpenSSH project + <http://openssh.org>`_. Paramiko implements a large portion of the SSH + feature set, but there are occasional gaps. |