redlibssh2

Super fast SSH library - bindings for libssh2

These details have not been verified by PyPI

Project links

Homepage

Project description

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

https://travis-ci.org/Red-M/redlibssh2.svg?branch=master

https://img.shields.io/pypi/wheel/redlibssh2.svg

https://coveralls.io/repos/github/Red-M/Redlibssh2/badge.svg?branch=master

https://img.shields.io/pypi/pyversions/redlibssh2.svg

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 redlibssh2

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.

Who Should Use This

Developers of bespoke SSH clients.

Who Should Not Use This

Developers looking for ready made SSH clients.

This library is not an SSH client.

Developers looking for high level easy to use clients based on this library should use RedSSH.

This library provides bindings to libssh2 and its API closely matches libssh2.

If the examples seem long, this is not the right library. Use RedSSH.

API Feature Set

At this time all of the libssh2 API has been implemented up to the libssh2 version in the repository. Please report any missing implementation.

Complete example scripts for various operations can be found in the examples directory.

In addition, as redlibssh2 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. Note that libssh2 does not support sharing sessions across threads
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.

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, redlibssh2 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:

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:

redlibssh2:

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

paramiko:

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

Why did you drop manylinux1 wheels?

Because frankly the manylinux1 docker containers won’t run on my build hosts because I run up to date software and kernels. The manylinux1 docker images are also full of extremely old package versions that will not receive updates or security fixes. The way that ParallelSSH handled this was to bundle their own versions of libssh2, OpenSSL and zlib in the repository.

Project details

These details have not been verified by PyPI

Project links

Homepage

Release history Release notifications | RSS feed

2.1.5.post1

Jan 30, 2023

2.1.4.post2

May 9, 2022

2.1.4

May 2, 2022

2.1.3

Jan 31, 2022

2.1.2.post2

Jan 29, 2022

2.1.1.post1

Jan 17, 2022

2.1.1

Jan 8, 2022

2.1.0

Dec 28, 2021

This version

2.0.3.post2

Oct 10, 2021

2.0.3.post1

Oct 5, 2021

2.0.3

Sep 2, 2021

2.0.2.post1

Aug 14, 2021

2.0.2

Jan 5, 2021

2.0.1.post3

Jan 5, 2021

2.0.1.post2

Dec 22, 2020

2.0.1.post1 yanked

Dec 22, 2020

2.0.1 yanked

Dec 22, 2020

2.0.0

Dec 20, 2020

0.19.0 yanked

Jun 6, 2020

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

redlibssh2-2.0.3.post2.tar.gz (1.1 MB view details)

Uploaded Oct 10, 2021 Source

Built Distributions

redlibssh2-2.0.3.post2-pp37-pypy37_pp73-manylinux_2_24_x86_64.whl (2.5 MB view details)

Uploaded Oct 10, 2021 PyPy manylinux: glibc 2.24+ x86-64

redlibssh2-2.0.3.post2-pp37-pypy37_pp73-manylinux_2_24_i686.whl (2.5 MB view details)

Uploaded Oct 10, 2021 PyPy manylinux: glibc 2.24+ i686

redlibssh2-2.0.3.post2-pp37-pypy37_pp73-manylinux_2_24_aarch64.whl (2.2 MB view details)

Uploaded Oct 10, 2021 PyPy manylinux: glibc 2.24+ ARM64

redlibssh2-2.0.3.post2-pp37-pypy37_pp73-manylinux_2_17_x86_64.manylinux2014_x86_64.whl (3.3 MB view details)

Uploaded Oct 10, 2021 PyPy manylinux: glibc 2.17+ x86-64

redlibssh2-2.0.3.post2-pp37-pypy37_pp73-manylinux_2_17_i686.manylinux2014_i686.whl (3.1 MB view details)

Uploaded Oct 10, 2021 PyPy manylinux: glibc 2.17+ i686

redlibssh2-2.0.3.post2-pp37-pypy37_pp73-manylinux_2_17_aarch64.manylinux2014_aarch64.whl (3.0 MB view details)

Uploaded Oct 10, 2021 PyPy manylinux: glibc 2.17+ ARM64

redlibssh2-2.0.3.post2-pp37-pypy37_pp73-manylinux_2_12_x86_64.manylinux2010_x86_64.whl (2.8 MB view details)