Skip to content

rustonbsd/iroh-ssh

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

55 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

iroh-ssh

Crates.io Documentation License

SSH to any machine without ip, behind a NAT/firewall without port forwarding or VPN setup.

# on server
> iroh-ssh server --persist

    Connect to this this machine:

    iroh-ssh my-user@bb8e1a5661a6dfa9ae2dd978922f30f524f6fd8c99b3de021c53f292aae74330


# on client
> iroh-ssh user@bb8e1a5661a6dfa9ae2dd978922f30f524f6fd8c99b3de021c53f292aae74330

That's all it takes. (requires ssh/(an ssh server) to be installed)


Installation

cargo install iroh-ssh

Download and setup the binary automatically for your operating system from GitHub Releases:

Linux

# Linux
wget https://github.com/rustonbsd/iroh-ssh/releases/download/0.2.2/iroh-ssh.linux
chmod +x iroh-ssh.linux
sudo mv iroh-ssh.linux /usr/local/bin/iroh-ssh

macOS

# macOS arm
curl -LJO https://github.com/rustonbsd/iroh-ssh/releases/download/0.2.2/iroh-ssh.macos
chmod +x iroh-ssh.macos
sudo mv iroh-ssh.macos /usr/local/bin/iroh-ssh

Windows

# Windows x86 64bit
curl -L -o iroh-ssh.exe https://github.com/rustonbsd/iroh-ssh/releases/download/0.2.2/iroh-ssh.exe
mkdir %LOCALAPPDATA%\iroh-ssh
move iroh-ssh.exe %LOCALAPPDATA%\iroh-ssh\
setx PATH "%PATH%;%LOCALAPPDATA%\iroh-ssh"

Verify that the installation was successful

# restart your terminal first
> iroh-ssh --help

Client Connection

# Install for your distro (see above)
# Connect from anywhere
> iroh-ssh my-user@38b7dc10df96005255c3beaeaeef6cfebd88344aa8c85e1dbfc1ad5e50f372ac

Works through any firewall, NAT, or private network. No configuration needed.

Connecting to remote server
(video slightly out of date)


Server Setup

# Install for your distro (see above)
# (use with tmux or install as service on linux)

> iroh-ssh server --persist

    Connect to this this machine:

    iroh-ssh my-user@bb8e1a5661a6dfa9ae2dd978922f30f524f6fd8c99b3de021c53f292aae74330

    (using persistent keys in /home/my-user/.ssh/irohssh_ed25519)

    Server listening for iroh connections...
    client -> iroh-ssh -> direct connect -> iroh-ssh -> local ssh :22
    Waiting for incoming connections...
    Press Ctrl+C to exit

or use ephemeral keys

# Install for your distro (see above)
# (use with tmux or install as service on linux)

> iroh-ssh server

    Connect to this this machine:

    iroh-ssh my-user@bb8e1a5661a6dfa9ae2dd978922f30f524f6fd8c99b3de021c53f292aae74330

    warning: (using ephemeral keys, run 'iroh-ssh server --persist' to create persistent keys)

    client -> iroh-ssh -> direct connect -> iroh-ssh -> local ssh :22
    Waiting for incoming connections...
    Press Ctrl+C to exit
    Server listening for iroh connections...

Display its Node ID and share it to allow connection

Starting server/Installing as service
(video slightly out of date)

Connection information

// note: works only with persistent keys 
> iroh-ssh info

    Your iroh-ssh nodeid: 38b7dc10df96005255c3beaeaeef6cfebd88344aa8c85e1dbfc1ad5e50f372ac
    iroh-ssh version 0.2.2
    https://github.com/rustonbsd/iroh-ssh

    run 'iroh-ssh server --persist' to start the server with persistent keys
    run 'iroh-ssh server' to start the server with ephemeral keys
    run 'iroh-ssh service install' to start the server as a service (always uses persistent keys)

    Your iroh-ssh nodeid:
      iroh-ssh root@38b7dc10df96005255c3beaeaeef6cfebd88344aa8c85e1dbfc1ad5e50f372ac

How It Works

┌─────────────┐    ┌──────────────┐    ┌─────────────────┐    ┌─────────────┐
│ iroh-ssh    │───▶│ internal TCP │───▶│ QUIC Tunnel     │───▶│ iroh-ssh    │
│ (your machine)   │    Listener  │    │ (P2P Network)   │    │ server      │
└─────────────┘    | (your machine)    └─────────────────┘    └─────────────┘
                   └──────────────┘
        │                  ▲                                           │
        ▼                  │                                           ▼
                   ┌──────────────┐                            ┌─────────────┐
        ⦜   -- ▶   │ run:     ssh │                            │ SSH Server  │
                   │ user@localhost                            │ (port 22)   │
                   └──────────────┘                            └─────────────┘
  1. Client: Creates local TCP listener, connects system SSH client to it
  2. Tunnel: QUIC connection through Iroh's P2P network (automatic NAT traversal)
  3. Server: Proxies connections to local SSH daemon running on (e.g. port localhost:22) (requires ssh server)
  4. Authentication: Standard SSH security applies end-to-end. The tunnel is ontop of that an encrypted QUIC connection.

Use Cases

  • Remote servers: Access cloud instances without exposing SSH ports
  • Home networks: Connect to devices behind router/firewall
  • Corporate networks: Bypass restrictive network policies
  • IoT devices: SSH to embedded systems on private networks
  • Development: Access staging servers and build machines

Commands

# Get your Node ID and info
> iroh-ssh info

# Server modes
> iroh-ssh server --persist          # Interactive mode, e.g. use tmux (default SSH port 22)
> iroh-ssh server --ssh-port 2222    # Custom SSH port (using ephemeral keys)

# Service mode
> iroh-ssh service install                   # Background daemon (linux and windows only, default port 22)
> iroh-ssh service install --ssh-port 2222   # Background daemon with custom SSH port
> iroh-ssh service uninstall                 # Uninstall service

# Client connection
> iroh-ssh user@<NODE_ID>            # Connect to remote server
> iroh-ssh connect user@<NODE_ID>    # Explicit connect command

Security Model

  • Node ID access: Anyone with the Node ID can reach your SSH port
  • SSH authentication: ATM only password auth is supported
  • Persistent keys: Uses dedicated .ssh/iroh_ssh_ed25519 keypair
  • QUIC encryption: Transport layer encryption between endpoints

Status

  • Password authentication
  • Persistent SSH keys
  • Linux service mode
  • Add howto gifs
  • Add -p flag for persistence
  • Windows service mode
  • Certificate support (-i flag)
  • MacOS service mode
  • Additional SSH features

License

Licensed under either of Apache License 2.0 or MIT license at your option.