1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
|
========
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.2 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.
Kerberos Support
----------------
If you want paramiko to do kerberos authentication or key exchange using GSS-API or SSPI, you
need the following python packages:
- pyasn1 0.1.7 or better
- python-gssapi 0.4.0 or better (Unix)
- pywin32 2.1.8 or better (Windows)
So you have to install pyasn1 and python-gssapi on Unix or pywin32 on Windows.
To enable GSS-API / SSPI authentication or key exchange see the demos or paramiko docs.
Note: If you use Microsoft SSPI for kerberos authentication and credential
delegation in paramiko, make sure that the target host is trusted for
delegation in the active directory configuration. For details see:
http://technet.microsoft.com/en-us/library/cc738491%28v=ws.10%29.aspx
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.
|
