From 985c5d0c811987a9d4d9fff712169e5125acc95a Mon Sep 17 00:00:00 2001 From: Jeff Forcier Date: Fri, 1 Oct 2021 15:12:46 -0400 Subject: README / www-index overhaul - Nuke old README in its entirety: - We don't want people using demos if possible, stop advertising them - Nix a bunch of bits that will now be replaced by standard PyPI sidebar links (docs, tests etc) - Ditto the 'headers', most of that stuff is either PyPI metadata or the about to be added shields.io badges - Some stuff deleted was also just old, eg IRC is no longer a support channel and I think librelist is dead too - Rip out www site index for use as README and inject back in via include - Rewrite a bunch of that too for clarity - Leverage it in long_description too --- README.rst | 174 +++++++++++-------------------------------------------------- 1 file changed, 29 insertions(+), 145 deletions(-) (limited to 'README.rst') diff --git a/README.rst b/README.rst index 5fb2f77f..804d8fdb 100644 --- a/README.rst +++ b/README.rst @@ -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 -:Copyright: Copyright (c) 2020 Jeff Forcier -:License: `LGPL `_ -: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 -`_). - -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 -`_ 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 `_ -:Mailing List: ``paramiko@librelist.com`` (see the `LibreList website - `_ 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 -`_ -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 `_, +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 `_; for API details, see `the +versioned docs `_. Additionally, the project +maintainer keeps a `roadmap `_ on his +personal site. + +.. [#] + Paramiko relies on `cryptography `_ for crypto + functionality, which makes use of C and Rust extensions but has many + precompiled options available. See `our installation page + `_ 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 + `_. Paramiko implements a large portion of the SSH + feature set, but there are occasional gaps. -- cgit v1.2.1