Super fast Python SSH library. Based on libssh2 C library.
pkittenis Handle EAGAIN for channel and sftp writes correctly and return rc, by…
…tes_written tuple so clients can resume from last written byte on next call to write.

Updated docstrings for channel write functions, tests, travis cfg, flake8 configuration for sftp.
Latest commit 5ebdd89 Nov 1, 2018
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.github Updated documentation, readme, contribution guide Oct 18, 2017
ci Added static bundled libssh2 source code. Oct 20, 2018
conda-recipe Appveyor wheel (#4) Aug 21, 2017
doc Updated readme, installation instructions in documentation. Oct 20, 2018
examples Fix for AttributeError in non-blocking example (#31) Jul 18, 2018
libssh2 Added static bundled libssh2 source code. Oct 20, 2018
ssh2 Handle EAGAIN for channel and sftp writes correctly and return rc, by… Nov 3, 2018
tests Handle EAGAIN for channel and sftp writes correctly and return rc, by… Nov 3, 2018
.appveyor.yml Added static bundled libssh2 source code. Oct 20, 2018
.environment.yml Updated setup.py for readthedocs integration. May 31, 2018
.gitattributes Added versioneer based versions - added setup.cfg and updated setup.py. Aug 1, 2017
.gitignore wait for entire buffer to be written before returning when calling sf… Jun 5, 2018
.readthedocs.yml Rtd (#11) Oct 8, 2017
.travis.yml Handle EAGAIN for channel and sftp writes correctly and return rc, by… Nov 3, 2018
COPYING Added version and agent auth helper functions. Added Agent and Public… Jul 27, 2017
Changelog.rst Handle EAGAIN for channel and sftp writes correctly and return rc, by… Nov 3, 2018
LICENSE Updated license file to long version Jul 31, 2017
MANIFEST.in Added static bundled libssh2 source code. Oct 20, 2018
README.rst Updated readme, installation instructions in documentation. Oct 20, 2018
_setup_libssh2.py Added static bundled libssh2 source code. Oct 20, 2018
requirements_dev.txt Enable delocated OSX binary wheel builds and tag upload to PyPi. Aug 17, 2017
setup.cfg Updated sources for error code refactoring. Aug 11, 2017
setup.py Updated readme, installation instructions in documentation. Oct 20, 2018
versioneer.py Add bdist_ext functionality to versioneer. Resolves #17 Jan 31, 2018

README.rst

ssh2-python

Super fast SSH2 protocol library. ssh2-python provides Python bindings for libssh2.

License Latest Version https://travis-ci.org/ParallelSSH/ssh2-python.svg?branch=master https://ci.appveyor.com/api/projects/status/github/parallelssh/ssh2-python?svg=true&branch=master Latest documentation

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:

ssh2-python:

real       0m0.141s
user       0m0.037s
sys        0m0.008s

paramiko:

real       0m0.592s
user       0m0.351s
sys        0m0.021s