Knuckles-Team/tunnel-manager

Tunnel Class

The Tunnel class can be used standalone for SSH operations. Examples:

Using RSA Keys

from tunnel_manager.tunnel_manager import Tunnel

# Initialize with a remote host (assumes ~/.ssh/config or explicit params)
tunnel = Tunnel(
    remote_host="192.168.1.10",
    username="admin",
    password="mypassword",
    identity_file="/path/to/id_rsa",
    certificate_file="/path/to/cert",  # Optional for Teleport
    proxy_command="tsh proxy ssh %h",  # Optional for Teleport
    ssh_config_file="~/.ssh/config",
)

# Connect and run a command
tunnel.connect()
out, err = tunnel.run_command("ls -la /tmp")
print(f"Output: {out}\nError: {err}")

# Upload a file
tunnel.send_file("/local/file.txt", "/remote/file.txt")

# Download a file
tunnel.receive_file("/remote/file.txt", "/local/downloaded.txt")

# Setup passwordless SSH with RSA
tunnel.setup_passwordless_ssh(local_key_path="~/.ssh/id_rsa", key_type="rsa")

# Copy SSH config
tunnel.copy_ssh_config("/local/ssh_config", "~/.ssh/config")

# Rotate SSH key with RSA
tunnel.rotate_ssh_key("/path/to/new_rsa_key", key_type="rsa")

# Close the connection
tunnel.close()

Using Ed25519 Keys

from tunnel_manager.tunnel_manager import Tunnel

# Initialize with a remote host (assumes ~/.ssh/config or explicit params)
tunnel = Tunnel(
    remote_host="192.168.1.10",
    username="admin",
    password="mypassword",
    identity_file="/path/to/id_ed25519",
    certificate_file="/path/to/cert",  # Optional for Teleport
    proxy_command="tsh proxy ssh %h",  # Optional for Teleport
    ssh_config_file="~/.ssh/config",
)

# Connect and run a command
tunnel.connect()
out, err = tunnel.run_command("ls -la /tmp")
print(f"Output: {out}\nError: {err}")

# Upload a file
tunnel.send_file("/local/file.txt", "/remote/file.txt")

# Download a file
tunnel.receive_file("/remote/file.txt", "/local/downloaded.txt")

# Setup passwordless SSH with Ed25519
tunnel.setup_passwordless_ssh(local_key_path="~/.ssh/id_ed25519", key_type="ed25519")

# Copy SSH config
tunnel.copy_ssh_config("/local/ssh_config", "~/.ssh/config")

# Rotate SSH key with Ed25519
tunnel.rotate_ssh_key("/path/to/new_ed25519_key", key_type="ed25519")

# Close the connection
tunnel.close()

Tunnel Manager CLI Usage

The tunnel_manager.py script provides a CLI for managing SSH operations across hosts defined in an Ansible-style YAML inventory file. Below are examples for each command, targeting different inventory groups (all, homelab, poweredge). The CLI now supports both RSA and Ed25519 keys via the --key-type flag for relevant commands (default: ed25519).

Inventory File Example (inventory.yml):

all:
  hosts:
    r510:
      ansible_host: 192.168.1.10
      ansible_user: admin
      ansible_ssh_private_key_file: "~/.ssh/id_ed25519"
    r710:
      ansible_host: 192.168.1.11
      ansible_user: admin
      ansible_ssh_pass: mypassword
    gr1080:
      ansible_host: 192.168.1.14
      ansible_user: admin
      ansible_ssh_private_key_file: "~/.ssh/id_rsa"
homelab:
  hosts:
    r510:
      ansible_host: 192.168.1.10
      ansible_user: admin
      ansible_ssh_private_key_file: "~/.ssh/id_ed25519"
    r710:
      ansible_host: 192.168.1.11
      ansible_user: admin
      ansible_ssh_pass: mypassword
    gr1080:
      ansible_host: 192.168.1.14
      ansible_user: admin
      ansible_ssh_private_key_file: "~/.ssh/id_rsa"
poweredge:
  hosts:
    r510:
      ansible_host: 192.168.1.10
      ansible_user: admin
      ansible_ssh_private_key_file: "~/.ssh/id_ed25519"
    r710:
      ansible_host: 192.168.1.11
      ansible_user: admin
      ansible_ssh_pass: mypassword

Replace IPs, usernames, and passwords with your actual values.

CLI Commands

1. Setup Passwordless SSH

Set up passwordless SSH for hosts in the inventory, distributing a shared key. Use --key-type to specify RSA or Ed25519 (default: ed25519).

• Target all group (sequential, Ed25519):

  tunnel-manager setup-all --inventory inventory.yml --shared-key-path ~/.ssh/id_shared --key-type ed25519
  

• Target homelab group (parallel, 3 threads, RSA):

  tunnel-manager setup-all --inventory inventory.yml --shared-key-path ~/.ssh/id_shared_rsa --key-type rsa --group homelab --parallel --max-threads 3
  

• Target poweredge group (sequential, Ed25519):

  tunnel-manager --log-file setup_poweredge.log setup-all --inventory inventory.yml --shared-key-path ~/.ssh/id_shared --key-type ed25519 --group poweredge
  

2. Run a Command

Execute a shell command on all hosts in the specified group.

• Run uptime on all group (sequential):

  tunnel-manager run-command --inventory inventory.yml --remote-command "uptime"
  

• Run df -h on homelab group (parallel, 5 threads):

  tunnel-manager run-command --inventory inventory.yml --remote-command "df -h" --group homelab --parallel --max-threads 5
  

• Run whoami on poweredge group (sequential):

  tunnel-manager run-command --inventory inventory.yml --remote-command "whoami" --group poweredge
  

3. Copy SSH Config

Copy a local SSH config file to the remote hosts’ ~/.ssh/config.

• Copy to all group (sequential):

  tunnel-manager copy-config --inventory inventory.yml --local-config-path ~/.ssh/config
  

• Copy to homelab group (parallel, 4 threads):

  tunnel-manager copy-config --inventory inventory.yml --local-config-path ~/.ssh/config --group homelab --parallel --max-threads 4
  

• Copy to poweredge group with custom remote path:

  tunnel-manager --log-file copy_config.log copy-config --inventory inventory.yml --local-config-path ~/.ssh/config --remote-config-path ~/.ssh/custom_config --group poweredge
  

4. Rotate SSH Keys

Rotate SSH keys for hosts, generating new keys with a prefix. Use --key-type to specify RSA or Ed25519 (default: ed25519).

• Rotate keys for all group (sequential, Ed25519):

  tunnel-manager rotate-key --inventory inventory.yml --key-prefix ~/.ssh/id_ --key-type ed25519
  

• Rotate keys for homelab group (parallel, 3 threads, RSA):

  tunnel-manager rotate-key --inventory inventory.yml --key-prefix ~/.ssh/id_rsa_ --key-type rsa --group homelab --parallel --max-threads 3
  

• Rotate keys for poweredge group (sequential, Ed25519):

  tunnel-manager --log-file rotate.log rotate-key --inventory inventory.yml --key-prefix ~/.ssh/id_ --key-type ed25519 --group poweredge
  

5. Upload a File

Upload a local file to all hosts in the specified group.

• Upload to all group (sequential):

  tunnel-manager send-file --inventory inventory.yml --local-path ./myfile.txt --remote-path /home/user/myfile.txt
  

• Upload to homelab group (parallel, 3 threads):

  tunnel-manager send-file --inventory inventory.yml --local-path ./myfile.txt --remote-path /home/user/myfile.txt --group homelab --parallel --max-threads 3
  

• Upload to poweredge group (sequential):

  tunnel-manager --log-file upload_poweredge.log send-file --inventory inventory.yml --local-path ./myfile.txt --remote-path /home/user/myfile.txt --group poweredge
  

6. Download a File

Download a file from all hosts in the specified group, saving to host-specific subdirectories (e.g., downloads/R510/myfile.txt).

• Download from all group (sequential):

  tunnel-manager receive-file --inventory inventory.yml --remote-path /home/user/myfile.txt --local-path-prefix ./downloads
  

• Download from homelab group (parallel, 3 threads):

  tunnel-manager receive-file --inventory inventory.yml --remote-path /home/user/myfile.txt --local-path-prefix ./downloads --group homelab --parallel --max-threads 3
  

• Download from poweredge group (sequential):

  tunnel-manager --log-file download_poweredge.log receive-file --inventory inventory.yml --remote-path /home/user/myfile.txt --local-path-prefix ./downloads --group poweredge
  

CLI Command Table

Notes

One of the commands (setup-all, run-command, copy-config, rotate-key, send-file, receive-file) must be specified as the first argument to tunnel_manager.py. Each command has required arguments that must be specified with flags:

• setup-all: Requires --inventory.
• run-command: Requires --inventory and --remote-command.
• copy-config: Requires --inventory and --local-config-path.
• rotate-key: Requires --inventory.
• send-file: Requires --inventory, --local-path, and --remote-path.
• receive-file: Requires --inventory, --remote-path, and --local-path-prefix.

Additional Notes

• Ensure ansible_host values in inventory.yml are resolvable IPs or hostnames.
• Update ansible_ssh_private_key_file in the inventory after running rotate-key.
• Use --log-file for file-based logging or omit for console output.
• The --parallel option speeds up operations but may overload resources; adjust --max-threads as needed.
• The receive-file command saves files to local_path_prefix/<hostname>/<filename> to preserve original filenames and avoid conflicts.
• Ed25519 keys are recommended for better security and performance over RSA, but RSA is supported for compatibility with older systems.

FastMCP Server

The FastMCP server exposes the Tunnel functionality as AI-accessible tools. Start the server with:

python tunnel_manager_mcp.py --transport stdio

Or for HTTP transport:

python tunnel_manager_mcp.py --transport http --host 127.0.0.1 --port 8080

Use with AI

Configure mcp.json

{
  "mcpServers": {
    "tunnel_manager": {
      "command": "uv",
      "args": [
        "run",
        "--with",
        "tunnel-manager",
        "tunnel_manager_mcp"
      ],
      "env": {
        "TUNNEL_REMOTE_HOST": "192.168.1.12",      // Optional
        "TUNNEL_USERNAME": "admin",                // Optional
        "TUNNEL_PASSWORD": "",                     // Optional
        "TUNNEL_REMOTE_PORT": "22",                // Optional
        "TUNNEL_IDENTITY_FILE": "",                // Optional
        "TUNNEL_INVENTORY": "~/inventory.yaml",    // Optional
        "TUNNEL_INVENTORY_GROUP": "all",           // Optional
        "TUNNEL_PARALLEL": "true",                 // Optional
        "TUNNEL_CERTIFICATE": "",                  // Optional
        "TUNNEL_PROXY_COMMAND": "",                // Optional
        "TUNNEL_LOG_FILE": "~/tunnel_log.txt",     // Optional
        "TUNNEL_MAX_THREADS": "6"                  // Optional
      },
      "timeout": 200000
    }
  }
}

Deploy MCP Server as a Container

docker pull knucklessg1/tunnel-manager:latest

Modify the compose.yml

services:
  tunnel-manager:
    image: knucklessg1/tunnel-manager:latest
    environment:
      - HOST=0.0.0.0
      - PORT=8021
    ports:
      - 8021:8021

Install Python Package

python -m pip install tunnel-manager

or

uv pip install --upgrade tunnel-manager