Skip to content
This repository

Native Python SSHv2 protocol library

Merge pull request #307 from offbyone/tox-py25

Remove python 2.5 from tox
latest commit 417102dbea
Jeff Forcier bitprophet authored
Octocat-spinner-32 demos Remove byte conversions and unhexlify calls that we only needed for P… November 19, 2013
Octocat-spinner-32 images [project @ Arch-1:robey@lag.net--2005-master-shake%paramiko--dev--1--… April 18, 2005
Octocat-spinner-32 paramiko Merge branch '1.13' April 16, 2014
Octocat-spinner-32 sites Merge branch '1.13' April 16, 2014
Octocat-spinner-32 tests Merge branch '1.13' April 16, 2014
Octocat-spinner-32 .bzrignore [project @ robey@lag.net-20080706223938-fn82xx2k0zvklazm] July 06, 2008
Octocat-spinner-32 .gitignore Add coverage command as Invoke task February 11, 2014
Octocat-spinner-32 .travis.yml Merge remote-tracking branch 'scottkmaxwell/py3-support-without-py25'… March 05, 2014
Octocat-spinner-32 ChangeLog.0 [project @ Arch-1:robey@lag.net--2005-master-shake%paramiko--dev--1--… May 21, 2005
Octocat-spinner-32 ChangeLog.1 [project @ Arch-1:robey@lag.net--2005-master-shake%paramiko--dev--1--… May 21, 2005
Octocat-spinner-32 LICENSE Fix FSF address September 23, 2012
Octocat-spinner-32 MANIFEST.in [project @ robey@lag.net-20061031185035-b57ad8184c39063a] October 31, 2006
Octocat-spinner-32 NEWS Nuke sphinx-changelogg'd material January 30, 2014
Octocat-spinner-32 NOTES [project @ Arch-1:robey@lag.net--2003-public%secsh--dev--1.0--patch-33] March 09, 2004
Octocat-spinner-32 README README py3 update March 13, 2014
Octocat-spinner-32 TODO Take ownership of TODO file September 23, 2012
Octocat-spinner-32 dev-requirements.txt Use newer alabaster w/ showhidden in sidebar TOC April 06, 2014
Octocat-spinner-32 setup.cfg Revert "Revert "Add a setup.cfg identifying this package as universal"" March 22, 2014
Octocat-spinner-32 setup.py Formatting April 06, 2014
Octocat-spinner-32 setup_helper.py Fixed a typo in the license header of most files September 27, 2013
Octocat-spinner-32 tasks.py Fixes #275 -- upload wheels as a part of the release process March 22, 2014
Octocat-spinner-32 test.py Switch from using PyCrypto's Random to using os.urandom. March 29, 2014
Octocat-spinner-32 tox-requirements.txt Meta prep work (reqs.txt, tasks.py) January 21, 2014
Octocat-spinner-32 tox.ini Remove python 2.5 from tox April 14, 2014
README
========
paramiko
========

:Paramiko: Python SSH module
:Copyright: Copyright (c) 2003-2009  Robey Pointer <robeypointer@gmail.com>
:Copyright: Copyright (c) 2013-2014  Jeff Forcier <jeff@bitprophet.org>
:License: LGPL
:Homepage: https://github.com/paramiko/paramiko/
:API docs: http://docs.paramiko.org


What
----

"paramiko" is a combination of the esperanto words for "paranoid" and
"friend".  it's a module for python 2.6+ 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.6 or better <http://www.python.org/> - this includes Python
    3.3 and higher as well.
  - pycrypto 2.1 or better <https://www.dlitz.net/software/pycrypto/>
  - ecdsa 0.9 or better <https://pypi.python.org/pypi/ecdsa>

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.

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 Sphinx autodoc, in the doc/ folder.

there are also unit tests here::

    $ python ./test.py

which will verify that most of the core components are working correctly.
Something went wrong with that request. Please try again.