tunn: Simplify SSH Tunnel Management with YAML Configuration

Introduction

tunn is an open-source tool written in Go, designed to simplify the creation and management of SSH tunnels. It acts as a developer-friendly wrapper around OpenSSH, enabling users to define and control multiple tunnels through a single, intuitive YAML configuration file. This utility is ideal for developers and system administrators who frequently need to establish secure connections to remote services, such as databases or APIs, without complex manual commands.

Installation

tunn offers several straightforward installation methods to get you up and running quickly.

Quick Install

curl -sSL https://raw.githubusercontent.com/strandnerd/tunn/main/scripts/install.sh | sh

From Go Install

Ensure you have Go 1.21 or higher installed.

go install github.com/strandnerd/tunn@latest

Build Locally

git clone https://github.com/strandnerd/tunn.git
cd tunn
go build -o tunn
sudo mv tunn /usr/local/bin/

Examples

tunn makes managing SSH tunnels intuitive with its YAML configuration and simple command-line interface.

Configuration

Create a ~/.tunnrc file in your home directory to define your tunnels:

tunnels:
  api:
    host: myserver          # SSH host from ~/.ssh/config
    ports:
      - 3000:3000           # local:remote port mapping
      - 4000:4001
    user: apiuser           # optional: SSH user
    identity_file: ~/.ssh/id_rsa  # optional: SSH key

  db:
    host: database
    ports:
      - 3306:3306           # MySQL
      - 5432:5432           # PostgreSQL
    user: dbadmin           # optional: overrides SSH config

  cache:
    host: cacheserver
    ports:
      - 6379:6379           # Redis

Ensure your SSH hosts are defined in ~/.ssh/config, for example:

Host myserver
    HostName 192.168.1.100
    User myuser
    Port 22

Usage

Run All Tunnels:

tunn

Run Specific Tunnels:

# Single tunnel
tunn api

# Multiple tunnels
tunn api db

Run Tunnels in the Background (Daemon Mode):

tunn --detach

This command detaches tunn to run as a background service.

Check Daemon Status:

tunn status

This reports the PID, mode, and port states for managed tunnels.

Stop the Daemon:

tunn stop

This command cleanly shuts down the tunn daemon.

Why Use tunn?

tunn stands out for its simplicity and powerful features, making it an excellent choice for managing SSH tunnels:

• Simple Configuration: Define all your tunnels in a single, easy-to-read YAML file.
• Leverages Existing SSH Setup: Integrates seamlessly with your ~/.ssh/config and existing SSH keys.
• Parallel Execution: All defined tunnels run concurrently, improving efficiency.
• Daemon Mode: Run tunnels as a background service, freeing up your terminal.
• Fine-Grained Control: Run all tunnels or selectively launch specific ones by name.
• Go Module: A lean Go module with minimal dependencies, ensuring clean and portable builds.

Links

For more detailed information, contributions, or to report issues, visit the official GitHub repository:

• GitHub Repository