diff options
| -rw-r--r-- | README | 154 | ||||
| -rw-r--r-- | README.md | 16 |
2 files changed, 154 insertions, 16 deletions
@@ -0,0 +1,154 @@ + +======== +paramiko +======== + +:Paramiko: Python SSH module +:Copyright: Copyright (c) 2003-2009 Robey Pointer <robeypointer@gmail.com> +:Copyright: Copyright (c) 2012 Jeff Forcier <jeff@bitprophet.org> +:License: LGPL +:Homepage: https://github.com/paramiko/paramiko/ + + +paramiko 1.8.0 +============== + +Release of MM.YY.DD + + +What +---- + +"paramiko" is a combination of the esperanto words for "paranoid" and +"friend". it's a module for python 2.2+ 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 LGPL (lesser GPL). + +the package and its API is fairly well documented in the "doc/" folder +that should have come with this archive. + + +Requirements +------------ + + - python 2.3 or better <http://www.python.org/> + (python 2.2 is also supported, but not recommended) + - pycrypto 2.1 or better <https://www.dlitz.net/software/pycrypto/> + +If you have setuptools, you can build and install paramiko and all its +dependencies with this command (as root):: + + easy_install ./ + + +Portability +----------- + +i code and test this library on Linux and MacOS X. for that reason, i'm +pretty sure that it works for all posix platforms, including MacOS. it +should also work on Windows, though i don't test it as frequently there. +if you run into Windows problems, send me a patch: portability is important +to me. + +python 2.2 may work, thanks to some patches from Roger Binns. things to +watch out for: + + * sockets in 2.2 don't support timeouts, so the 'select' module is + imported to do polling. + * logging is mostly stubbed out. it works just enough to let paramiko + create log files for debugging, if you want them. to get real logging, + you can backport python 2.3's logging package. Roger has done that + already: + http://sourceforge.net/project/showfiles.php?group_id=75211&package_id=113804 + +you really should upgrade to python 2.3. laziness is no excuse! :) + +some python distributions don't include the utf-8 string encodings, for +reasons of space (misdirected 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 +-------------- + +Please file bug reports at https://github.com/paramiko/paramiko/. There is currently no mailing list but we plan to create a new one ASAP. + + +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() + +...which 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 authenticiate 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. + (requires python 2.3.) + +: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: + an 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 epydoc, in the doc/ +folder. point your browser there. seriously, do it. mad props to +epydoc, which actually motivated me to write more documentation than i +ever would have before. + +there are also unit tests here:: + + $ python ./test.py + +which will verify that most of the core components are working correctly. diff --git a/README.md b/README.md deleted file mode 100644 index 4d3f9879..00000000 --- a/README.md +++ /dev/null @@ -1,16 +0,0 @@ -# ssh - -The `ssh` library is a fork of, and spiritual successor to, the -[Paramiko](http://www.lag.net/paramiko/) Python SSH library. It was created by -the developers of the [Fabric](http://fabfile.org) library as a way to ensure -timely updates and bugfixes for critical issues. - -`ssh` is currently in a transitional state and other than a rename and a -handful of small but crucial fixes/tweaks, the code and the documentation -remain unchanged from the original. - -We hope to clean up the presentation and documentation in the near future, as -more bugfixes and API additions are rolled out. We also plan to absorb some of -the higher profile bugs/issues from the Paramiko Github repository. - -Thank you for your patience! |