paramiko/README

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