paramiko 0.9 "horsea" release, 27 jun 2004 Copyright (c) 2003-2004 Robey Pointer http://www.lag.net/~robey/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 (python 2.2 is also supported, but not recommended) pycrypto 1.9+ (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 *** 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. the Channel object supports a "fileno()" call so that it can be passed into select or poll, for polling on posix. once you call "fileno()" on a Channel, it changes behavior in some fundamental ways, and these ways require posix. so don't call "fileno()" on a Channel on Windows. this is detailed in the documentation for the "fileno" method. 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. this may not work on windows. (works fine on osx.) * 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'. *** DEMO the demo client (demo.py) is a raw implementation of the normal 'ssh' CLI tool. while the paramiko library should work on all platforms, the demo app will only run on posix, because it uses select. you can run demo.py with no arguments, or you can give a hostname (or username@hostname) on the command line. if you don't, it'll prompt you for a hostname and username. if you have an ".ssh/" folder, it will try to read the host keys from there, though it's easily confused. you can choose to authenticate with a password, or with an RSA or DSS key. the demo app leaves a logfile called "demo.log" so you can see what paramiko logs as it works. but the most interesting part is probably the code itself, which hopefully demonstrates how you can use the paramiko library. a simpler example is in demo_simple.py, which is a copy of the demo client that uses the simpler "connect" method call (new with 0.9-doduo). there's also now a demo server (demo_server.py) which listens on port 2200 and accepts a login (robey/foo) and pretends to be a BBS, just to demonstrate how to perform the server side of things. *** USE the demo clients (demo.py & demo_simple.py) and the demo server (demo_server.py) 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 some of the core components are working correctly. not much is tested yet, but it's a start. the tests for SFTP are probably the best and easiest examples of how to use the SFTP class. *** WHAT'S NEW highlights of what's new in each release: v0.9 HORSEA * fixed a lockup that could happen if the channel was closed while the send window was full * better checking of maximum packet sizes * better line buffering for file objects * now chops sftp requests into smaller packets for some older servers * more sftp unit tests v0.9 GYARADOS * Transport.open_channel() -- supports local & remote port forwarding now * now imports UTF-8 encodings explicitly as a hint to "freeze" utilities * no longer rejects older SFTP servers * default packet size bumped to 8kB * fixed deadlock in closing a channel * Transport.connect() -- fixed bug where it would always fail when given a host key to verify v0.9 FEAROW * Transport.send_ignore() -- send random ignored bytes * RSAKey/DSSKey added from_private_key_file() as a factory constructor; write_private_key_file() & generate() to create and save ssh2 keys; get_base64() to retrieve the exported public key * Transport added global_request() [client] and check_global_request() [server] * Transport.get_remove_server_key() now returns a PKey object instead of a tuple of strings * Transport.get_username() -- return the username you auth'd as [client] * Transport.set_keepalive() -- makes paramiko send periodic junk packets to the remote host, to keep the session active * python 2.2 support (thanks to Roger Binns) * misc. bug fixes *** MISSING LINKS * ctr forms of ciphers are missing (blowfish-ctr, aes128-ctr, aes256-ctr) * multi-part auth not supported (ie, need username AND pk) * server mode needs better documentation * sftp server mode ivysaur?