ssh2.cr - GitLite

KO | EN

gitlite — search

#anthropic #c #awesome #web #agents #video #rust #kotlin #ios #macos

ssh2.cr

(★ 51)

libssh2 binding for Crystal language

File Explorer

ZIP Download

- - ci.yml
- exec.cr
- scp.cr
- sftp.cr
- shell.cr
- - fixed_methods_spec.cr
  - integration_helper.cr
  - known_host_helper_spec.cr
  - known_hosts_spec.cr
  - sftp_spec.cr
  - ssh_spec.cr
  - transfer_spec.cr
- - id_rsa
  - id_rsa.pub
- agent_spec.cr
- attributes_spec.cr
- enum_spec.cr
- error_spec.cr
- spec_helper.cr
- version_spec.cr
- - attributes.cr
  - base.cr
  - dir.cr
  - file.cr
  - node.cr
  - session.cr
- agent.cr
- channel.cr
- known_hosts.cr
- lib_ssh2.cr
- listener.cr
- session.cr
- ssh2.cr
.ameba.yml
.gitignore
CLAUDE.md
docker-compose.yml
LICENSE
mise.toml
README.md
shard.yml

# Use via CDN

jsDelivr

jsDelivr serves any public GitHub repository as a CDN with zero setup. Pick a version and a file to get a ready-to-paste link and snippet.

Version

File

Link

Example

Command Glossary

Commands referenced in this DOCs, explained below.

🔍

`brew install`

View Details ▼

Install a Homebrew formula or cask.

brew install {{formula|cask}}

Install a formula/cask:

brew install {{[-s|--build-from-source]}} {{formula}}

Build and install a formula from source (dependencies will still be installed from bottles):

brew install {{[-n|--dry-run]}} {{formula|cask}}

Download the manifest, print what would be installed but don't actually install anything:

🔍

`mise`

View Details ▼

Manage language runtimes like Node.js, Python, Ruby, Go, Java, etc and various tools.

mise plugins list-all

List all available plugins:

mise plugins add {{name}}

Install a plugin:

mise ls-remote {{name}}

List runtime versions available for install:

🔍

`shards`

View Details ▼

Dependency management tool for the Crystal language.

shards init

Create a skeleton `shard.yml` file:

shards install

Install dependencies from a `shard.yml` file:

shards update

Update all dependencies:

# Project Badges

CI Visit
Release Visit
License Visit

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

This library provides binding for libssh2 library.

# Requirements

- libssh2 version 1.11.0 or higher

You can use `homebrew` to install the latest libssh2:

```
$ brew install libssh2
```

# Installation

Add the shard to your `shard.yml`:

```yaml
dependencies:
  ssh2:
    github: spider-gazelle/ssh2.cr
```

Then run:

```
shards install
```

# Goal

The goal is to utilize libssh2 API by providing services like ability to run
shell commands via ssh as well as scp and sftp services.

# Usage

An example of running a shell command via SSH on the remote server:

```crystal
require "ssh2"

SSH2::Session.open("my_server") do |session|
  session.login("username", "password")
  session.open_session do |channel|
    channel.command("uptime")
    IO.copy(channel, STDOUT)
  end
end
```

An example of running shell:

```crystal
require "ssh2"

session = SSH2::Session.connect("localhost", 2222)
session.login("root", "somepassword")
channel = session.open_session

# request the terminal has echo mode off
channel.request_pty("vt100", [{SSH2::TerminalMode::ECHO, 0u32}])
channel.shell

# Send commands
spawn {
  list = ["ls\n", "ps aux\n", "uptime\n"]
  loop do
    channel.write(list.sample(1)[0].to_slice)
    sleep 3
  end
}

# Receive responses
raw_data = Bytes.new(2048)
loop do
  bytes_read = channel.read(raw_data)
  puts String.new(raw_data[0, bytes_read])
end
```

An example of transferring files over SCP:

```crystal
require "ssh2"

SSH2::Session.open("localhost", 2222) do |session|
  session.login("root", "somepassword")
  # upload a local file, then download it back
  session.scp_send_file("./hello.txt", "/tmp/hello.txt")
  session.scp_recv_file("/tmp/hello.txt", "./hello-copy.txt")
end
```

An example of using SFTP API:

```crystal
require "ssh2"

SSH2::Session.open("localhost", 2222) do |session|
  # NOTE:: ED25519 based keys only work on latest versions of libssh2
  session.login_with_pubkey("root", "./spec/keys/id_rsa", "./spec/keys/id_rsa.pub")
  session.sftp_session do |sftp|
    sftp.open_dir(".").ll do |fn|
      puts fn
    end
    file = sftp.open(".bashrc")
    puts file.gets_to_end
  end
end
```

# Development

This project uses [mise](https://mise.jdx.dev) to manage the Crystal toolchain and
the developer tasks (`mise tasks` lists them all). Install the dependencies with:

```
mise dev:deps
```

# Testing

The suite is split in two tiers:

- **Unit specs** are serverless and run everywhere:

```
  mise dev:spec       # single-threaded
  mise dev:spec-mt    # multi-threaded (fiber-safety gate)
  ```

- **Integration specs** drive a real SSH server (a `testcontainers/sshd` container
  defined in `docker-compose.yml`) and are gated behind `-Dintegration`:

```
  mise dev:ssh-up             # start the container
  mise dev:spec-integration   # run the e2e suite
  mise dev:ssh-down           # stop it
  ```

Connection settings default to the container (`localhost:10022`, `root` /
`somepassword`) and can be overridden via the `SPEC_SSH_HOST`, `SPEC_SSH_PORT`,
`SPEC_SSH_USER` and `SPEC_SSH_PASS` environment variables.

# License

MIT clause - see LICENSE for more details.
Many thanks to the original author [Kent Sibilev](https://github.com/datanoise/ssh2.cr)