Transition back to Paramiko's readme; update to be currently accurate
This commit is contained in:
Jeff Forcier
parent
217512430d
commit
3cba95f112
|
|
@ -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.
|
||||||
16
README.md
16
README.md
|
|
@ -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!
|
|
||||||
Loading…
Reference in New Issue