259 lines
10 KiB
Plaintext
259 lines
10 KiB
Plaintext
paramiko 1.6.3
|
|
"xatu" release, 14 oct 2006
|
|
|
|
Copyright (c) 2003-2006 Robey Pointer <robey@lag.net>
|
|
|
|
http://www.lag.net/paramiko/
|
|
|
|
|
|
*** 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 heirarchical
|
|
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 <http://www.python.org/>
|
|
(python 2.2 is also supported, but not recommended)
|
|
pycrypto 1.9+ <http://www.amk.ca/python/code/crypto.html>
|
|
(2.0 works too)
|
|
|
|
pycrypto compiled for Win32 can be downloaded from the HashTar homepage:
|
|
http://nitace.bsd.uchicago.edu:8080/hashtar
|
|
you can also build it yourself using the free MinGW tools and this command
|
|
line (thanks to Roger Binns for the info):
|
|
python setup.py build --compiler=mingw32 bdist_wininst
|
|
|
|
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. i
|
|
also think it will work on Windows, though i've never tested it 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
|
|
installls.)
|
|
Valeriy Pogrebitskiy says the best place to look is
|
|
'.../lib/python*/encodings/__init__.py'.
|
|
|
|
|
|
*** BUGS & SUPPORT
|
|
|
|
there's a launchpage page for paramiko, with a bug tracker:
|
|
|
|
http://www.launchpad.net/products/paramiko/
|
|
|
|
this is the primary place to file and browse bug reports.
|
|
|
|
there's also a low-traffic mailing list for support and discussions:
|
|
|
|
http://www.lag.net/mailman/listinfo/paramiko
|
|
|
|
|
|
*** 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.
|
|
|
|
|
|
*** 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.
|
|
|
|
|
|
*** WHAT'S NEW
|
|
|
|
highlights of what's new in each release:
|
|
|
|
v1.6.3 XATU
|
|
* fixed bug where HostKeys.__setitem__ wouldn't always do the right thing
|
|
* fixed bug in SFTPClient.chdir and SFTPAttributes.__str__ [patch from
|
|
mike barber]
|
|
* try harder not to raise EOFError from within SFTPClient
|
|
* fixed bug where a thread waiting in accept() could block forever if the
|
|
transport dies [patch from mike looijmans]
|
|
|
|
v1.6.2 WEEDLE
|
|
* added support for "old" group-exchange server mode, for compatibility
|
|
with the windows putty client
|
|
* fixed some more interactions with SFTP file readv() and prefetch()
|
|
* when saving the known_hosts file, preserve the original order [patch from
|
|
warren young]
|
|
* fix a couple of broken lines when exporting classes (bug 55946)
|
|
|
|
v1.6.1 VULPIX
|
|
* more unit tests fixed for windows/cygwin (thanks to alexander belchenko)
|
|
* a couple of fixes related to exceptions leaking out of SFTPClient
|
|
* added ability to set items in HostKeys via __setitem__
|
|
* HostKeys now retains order and has a save() method
|
|
* added PKey.write_private_key and PKey.from_private_key
|
|
|
|
v1.6 UMBREON
|
|
* pageant support on Windows thanks to john arbash meinel and todd whiteman
|
|
* fixed unit tests to work under windows and cygwin (thanks to alexander
|
|
belchenko for debugging)
|
|
* various bugfixes/tweaks to SFTP file prefetch
|
|
* added SSHClient for a higher-level API
|
|
* SFTP readv() now yields results as it gets them
|
|
* several APIs changed to throw an exception instead of "False" on failure
|
|
|
|
v1.5.4 TENTACOOL
|
|
* fixed HostKeys to more correctly emulate a python dict
|
|
* fixed a bug where file read buffering was too aggressive
|
|
* improved prefetching so that out-of-order reads still use the prefetch
|
|
buffer
|
|
* added experimental SFTPFile.readv() call
|
|
* more unit tests
|
|
|
|
v1.5.3 SQUIRTLE
|
|
* a few performance enhancements
|
|
* added HostKeys, for dealing with openssh style "known_hosts" files, and
|
|
added support for hashed hostnames
|
|
* added Transport.atfork() for dealing with forked children
|
|
* added SFTPClient.truncate, SFTPFile.chmod, SFTPFile.chown, SFTPFile.utime,
|
|
and SFTPFile.truncate
|
|
* improved windows demos [patch from mike looijmans], added an sftp demo, and
|
|
moved demos to the demos/ folder
|
|
* fixed a few interoperability bugs
|
|
* cleaned up logging a bit
|
|
* fixed a bug where EOF on a Channel might not be detected by select [found
|
|
by thomas steinacher]
|
|
* fixed python 2.4-ism that crept in [patch by jan hudec]
|
|
* fixed a few reference loops that could have interacted badly with the python
|
|
garbage collector
|
|
* fixed a bunch of pychecker warnings, some of which were bugs
|
|
|
|
v1.5.2 RHYDON
|
|
* compression support (opt-in via Transport.use_compression)
|
|
* sftp files may be opened with mode flag 'x' for O_EXCL (exclusive-open)
|
|
behavior, which has no direct python equivalent
|
|
* added experimental util functions for parsing openssh config files
|
|
* fixed a few bugs (and potential deadlocks) with key renegotiation
|
|
* fixed a bug that caused SFTPFile.prefetch to occasionally lock up
|
|
* fixed an sftp bug which affected van dyke sftp servers
|
|
* fixed the behavior of select()ing on a closed channel, such that it will
|
|
always trigger as readable
|
|
|
|
v1.5.1 QUILAVA
|
|
* SFTPFile.prefetch() added to dramatically speed up downloads (automatically
|
|
turned on in SFTPClient.get())
|
|
* fixed bug where garbage-collected Channels could trigger the Transport to
|
|
close the session (reported by gordon good)
|
|
* fixed a deadlock in rekeying (reported by wendell wood)
|
|
* fixed some windows bugs and SFTPAttributes.__str__() (reported by grzegorz
|
|
makarewicz)
|
|
* better sftp error reporting by adding fake "errno" info to IOErrors
|
|
|
|
v1.5 PARAS
|
|
* added support for "keyboard-interactive" authentication
|
|
* added mode (on by default) where password authentication will try to
|
|
fallback to "keyboard-interactive" if it's supported
|
|
* added pipelining to SFTPFile.write and SFTPClient.put
|
|
* fixed bug with SFTPFile.close() not guarding against being called more
|
|
than once (thanks to Nathaniel Smith)
|
|
* fixed broken 'a' flag in SFTPClient.file() (thanks to Nathaniel Smith)
|
|
* fixed up epydocs to look nicer
|
|
* reorganized auth_transport into auth_handler, which seems to be a cleaner
|
|
separation
|
|
* demo scripts fixed to have a better chance of loading the host keys
|
|
correctly on windows/cygwin
|
|
|
|
|
|
*** MISSING LINKS
|
|
|
|
* allow setting chmod bits on SFTPClient.open() for create
|
|
* host-based auth (yuck!)
|
|
* ctr forms of ciphers are missing (blowfish-ctr, aes128-ctr, aes256-ctr)
|
|
* sftp protocol 6 support (ugh....) -- once it settles down more
|
|
* make a simple example demonstrating use of SocketServer (besides forward.py?)
|
|
* should SSHClient try to use openssh config files?
|
|
* figure out how to parse ssh.com encrypted key files?
|
|
* is it possible to poll on a set of events at once?
|
|
* potentially create only one thread shared by all Transports
|