Skip to content

Latest commit

 

History

History
156 lines (112 loc) · 3.53 KB

README.md

File metadata and controls

156 lines (112 loc) · 3.53 KB

SSH2.nim

A high-level async SSH library for Nim, providing SSH, SCP, and SFTP functionality. Built on top of libssh2.

Features

  • ✨ Asynchronous API using async/await
  • 🔒 Secure SSH connections with password and key authentication
  • 📂 SCP file transfers (upload/download)
  • 📁 SFTP operations (file transfer, directory management)
  • 🛠️ Command execution on remote servers
  • 🔐 Support for various authentication methods
  • 📝 Comprehensive error handling

Installation

  1. First, ensure you have libssh2 installed on your system:
# Ubuntu/Debian
apt-get install libssh2-1-dev

# macOS
brew install libssh2

# Windows (using vcpkg)
vcpkg install libssh2:x64-windows
  1. Install using Nimble:
nimble install ssh2

Quick Start

import asyncdispatch
import ssh2

proc main() {.async.} =
  let ssh = newSSHClient()
  try:
    # Connect to remote server
    await ssh.connect("example.com", "username", password = "password")

    # Execute a command
    let (output, exitCode) = await ssh.execute("ls -la")
    echo "Command output: ", output

    # Upload a file using SCP
    let scp = initSCPClient(ssh)
    await scp.uploadFile("local.txt", "/remote/path/file.txt")

    # SFTP operations
    var sftp = initSFTPClient(ssh)
    defer: sftp.close()

    # Create directory
    sftp.mkdir("/remote/new_dir")

    # List directory contents
    let files = await sftp.dir("/remote/new_dir")
    for file in files:
    echo "File: ", file.name`
  finally:
    ssh.disconnect()

waitFor main()

API Documentation

The library provides three main components:

SSH Client

  • Connect to remote servers
  • Execute commands
  • Handle authentication

SCP Client

  • Upload files
  • Download files
  • Preserve file permissions

SFTP Client

  • File transfers (upload/download)
  • Directory operations (create, remove, list)
  • File management (rename, delete)

For detailed API documentation, see the documentation.

Authentication Methods

The library supports multiple authentication methods:

# Password authentication
await ssh.connect("host", "user", password = "pass")

# Private key authentication
await ssh.connect("host", "user",
privateKeyPath = "~/.ssh/id_rsa",
passphrase = "optional-passphrase"
)

# Agent authentication
await ssh.connect("host", "user", useAgent = true)

Error Handling

The library uses Nim's exception system for error handling:

try:
await ssh.connect("host", "user", password = "pass")
let (output, code) = await ssh.execute("command")
except SSHException as e:
echo "SSH error: ", e.msg
except IOError as e:
echo "IO error: ", e.msg

Development

To run tests, you can use a Docker instance with sshd installed:

# Host: 127.0.0.1
# Port: 2222
# Username: root
# Password: root

docker run -d --name test_sshd -p 2222:22 rastasheep/ubuntu-sshd:16.04

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

  1. Fork the repository
  2. Create your feature branch (git checkout -b feature/amazing-feature)
  3. Commit your changes (git commit -m 'Add some amazing feature')
  4. Push to the branch (git push origin feature/amazing-feature)
  5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

  • libssh2 - The underlying SSH library
  • Nim - The programming language