Overview

Date: 2026-05-11

Time: 15:43

Overview

This is a comprehensive example/demo script showing how to perform remote execution over SSH using FTL2's SSH transport layer. It covers the full range of SSH operations a user would need: running commands, file transfers via SFTP, connection pooling, concurrent multi-host execution, convenience one-liner functions, and error handling. It requires a Docker container as the SSH target.

Usage Patterns

Run with Docker providing the SSH target:

docker-compose up -d
uv run python example_remote.py
docker-compose down

Basic SSH command execution:

host = SSHHost(hostname="localhost", port=2222, username="testuser", password="testpass", disable_host_key_checking=True)
async with host:
    stdout, stderr, rc = await host.run("uptime")

SFTP file operations:

async with host:
    await host.write_file("/tmp/file.txt", b"content")
    exists = await host.has_file("/tmp/file.txt")
    content = await host.read_file("/tmp/file.txt")

Connection pooling (reuse connections across calls):

async with SSHConnectionPool() as pool:
    host = await pool.get(**SSH_CONFIG)
    await host.connect()
    stdout, _, _ = await host.run("echo hello")

One-off convenience functions (no context manager needed):

stdout, stderr, rc = await ssh_run(hostname="host", command="date", port=22, username="user", password="pass")

results = await ssh_run_on_hosts(hostnames=["h1", "h2"], command="whoami", port=22, username="user", password="pass")

Concurrent execution across hosts:

tasks = [run_on_host(h, i) for i, h in enumerate(hosts)]
results = await asyncio.gather(*tasks)

API and Configuration

SSHHost constructor parameters: hostname, port, username, password, disablehostkey_checking (bool, for test environments only).

SSHHost methods:

• run(command, stdin=None, timeout=None) → (stdout, stderr, rc)
• writefile(path, contentbytes) — SFTP write
• read_file(path) → bytes — SFTP read
• has_file(path) → bool — SFTP existence check
• connect() / disconnect() — manual lifecycle (or use async with)
• config.connect_timeout — settable timeout for connection attempts

SSHConnectionPool: context-managed pool; pool.get(**config) returns/reuses an SSHHost.

Convenience functions:

• ssh_run(hostname, command, port, username, password) → (stdout, stderr, rc)
• sshrunon_hosts(hostnames, command, port, username, password) → list of (hostname, stdout, stderr, rc)

Key Behaviors

• SSHHost is used as an async context manager (async with host:), which handles connect/disconnect automatically.
• host.run() returns a 3-tuple (stdout, stderr, rc) — non-zero rc does not raise an exception; the caller must check it.
• stdin can be passed as a string to host.run() for piping input.
• SSHConnectionPool.get() reuses connections to the same host — calling get() with identical config returns the same object.
• sshrunon_hosts runs commands on multiple hosts in parallel and returns all results.
• disablehostkey_checking=True is explicitly flagged as only for test containers — production usage should verify host keys.
• The script checks Docker availability before running examples, with a 2-second connect timeout for the preflight check.

Relationships

Imports from FTL2: ftl2.ssh — specifically SSHHost, SSHConnectionPool, sshrun, sshrunonhosts.

Infrastructure dependency: Requires a Docker container with SSH server (port 2222, user testuser/testpass), configured via a docker-compose.yml in the same directory.

Project location: Lives under examples/ in the FTL2 target repo, used for demonstration and testing of the SSH transport subsystem. Represents the user-facing API for remote execution that modules and automation scripts build upon.