ssh2-python
Super fast SSH2 protocol library. ssh2-python
provides Python bindings for libssh2.
Installation
Binary wheel packages are provided for Linux, OSX and Windows, all Python versions. Wheel packages have no dependencies.
pip
may need to be updated to be able to install binary wheel packages - pip install -U pip
.
pip install ssh2-python
Conda is another installation option - see documentation for more detailed instructions.
For from source installation instructions, including building against system provided libssh2, see documentation.
For creating native system packages for Centos/RedHat, Ubuntu, Debian and Fedora, see instructions in the documentation.
API Feature Set
At this time all of the libssh2 API has been implemented up to version 1.8.2
.
Complete example scripts for various operations can be found in the examples directory.
In addition, as ssh2-python
is a thin wrapper of libssh2
with Python semantics, its code examples can be ported straight over to Python with only minimal changes.
Library Features
The library uses Cython based native code extensions as wrappers to libssh2
.
Extension features:
- Thread safe - GIL is released as much as possible
- Very low overhead
- Super fast as a consequence of the excellent C library it uses and prodigious use of native code
- Object oriented - memory freed automatically and safely as objects are garbage collected by Python
- Use Python semantics where applicable, such as context manager and iterator support for opening and reading from SFTP file handles
- Raise errors as Python exceptions
- Provide access to
libssh2
error code definitions
Quick Start
Both byte and unicode strings are accepted as arguments and encoded appropriately. To change default encoding, utf-8
, change the value of ssh2.utils.ENCODING
. Output is always in byte strings.
See Complete Example for an example including socket connect.
Please use either the issue tracker for reporting issues with code or the mail group for discussion and questions.
Contributions are most welcome!
Authentication Methods
Connect and get available authentication methods.
from __future__ import print_function
from ssh2.session import Session
sock = <create and connect socket>
session = Session()
session.handshake(sock)
print(session.userauth_list())
Output will vary depending on SSH server configuration. For example:
['publickey', 'password', 'keyboard-interactive']
Agent Authentication
session.agent_auth(user)
Command Execution
channel = session.open_session()
channel.execute('echo Hello')
Reading Output
size, data = channel.read()
while(size > 0):
print(data)
size, data = channel.read()
Hello
Exit Code
print("Exit status: %s" % (channel.get_exit_status()))
Exit status: 0
Public Key Authentication
session.userauth_publickey_fromfile(
username, 'private_key_file')
Passphrase can be provided with the passphrase
keyword param - see API documentation.
Password Authentication
session.userauth_password(
username, '<my password>')
SFTP Read
from ssh2.sftp import LIBSSH2_FXF_READ, LIBSSH2_SFTP_S_IRUSR
sftp = session.sftp_init()
with sftp.open(<remote file to read>,
LIBSSH2_FXF_READ, LIBSSH2_SFTP_S_IRUSR) as remote_fh, \
open(<local file to write>, 'wb') as local_fh:
for size, data in remote_fh:
local_fh.write(data)
Complete Example
A simple usage example looks very similar to libssh2
usage examples.
See examples directory for more complete example scripts.
As mentioned, ssh2-python
is intentionally a thin wrapper over libssh2
and directly maps most of its API.
Clients using this library can be much simpler to use than interfacing with the libssh2
API directly.
from __future__ import print_function
import os
import socket
from ssh2.session import Session
host = 'localhost'
user = os.getlogin()
sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
sock.connect((host, 22))
session = Session()
session.handshake(sock)
session.agent_auth(user)
channel = session.open_session()
channel.execute('echo me; exit 2')
size, data = channel.read()
while size > 0:
print(data)
size, data = channel.read()
channel.close()
print("Exit status: %s" % channel.get_exit_status())
Output: | me Exit status: 2 |
---|
SSH Functionality currently implemented
- SSH channel operations (exec,shell,subsystem) and methods
- SSH agent functionality
- Public key authentication and management
- SFTP operations
- SFTP file handles and attributes
- SSH port forwarding and tunnelling
- Non-blocking mode
- SCP send and receive
- Listener for port forwarding
- Subsystem support
- Host key checking and manipulation
And more, as per libssh2 functionality.
Comparison with other Python SSH libraries
Performance of above example, compared with Paramiko.
time python examples/example_echo.py
time python examples/paramiko_comparison.py
Output: |
real 0m0.141s user 0m0.037s sys 0m0.008s
real 0m0.592s user 0m0.351s sys 0m0.021s |
---|