iroh-ssh

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
# or with certificate
> iroh-ssh -i ~/.ssh/id_rsa_my_cert my-user@bb8e1a5661a6dfa9ae2dd978922f30f524f6fd8c99b3de021c53f292aae74330

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

---

Installation

git clone https://github.com/adapt-L/iroh-ssh.git
cargo install --path iroh-ssh

If you're on Windows, you can install from the binary on GitHub Releases, and move the executable to your PATH:

# Windows x86 64bit
curl -L -o iroh-ssh.exe https://github.com/adapt-L/iroh-ssh/releases/download/0.2.7/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

You'll still need to set up SSH on the server side. For Linux this will be straightforward, but for Windows you may want to read OpenSSH installation on windows and Passwordless OpenSSH configuration on windows

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

---

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

Connection information

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

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

    Your server iroh-ssh nodeid:
      iroh-ssh my-user@38b7dc10df96005255c3beaeaeef6cfebd88344aa8c85e1dbfc1ad5e50f372ac

    Your service iroh-ssh nodeid:
      iroh-ssh my-user@4fjeeiui4jdm96005255c3begj389xk3aeaeef6cfebd88344aa8c85e1dbfc1ad

---

How It Works

┌─[ Client Machine ]───────────────────────────────────────────────────┐  ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄
│┌────────────────────────────────────────────────────────────────────┐│ ┆ Iroh P2P Network ┆
││ user1> iroh-ssh connect user2@bb8e1...                             ││ ┆                  ┆
││┌────────────┐                      ┌──────────────┐                ││ ┆                  ┆
│││ Internal   │ ─[user1@localhost]─▶ │ Internal TCP │ ─[QUIC Tunnel]─────────────────────┐ ┆
│││ sh> ssh    │                      │   Listener   │                ││ ┆                │ ┆
││└────────────┘                      └──────────────┘                ││ ┆ Discovery and  │ ┆
│└────────────────────────────────────────────────────────────────────┘│ ┆ ┌──────────────┘ ┆
└──────────────────────────────────────────────────────────────────────┘ ┆ │NAT traversal   ┆
                                                                         ┆ └────────────┐   ┆
┌─[ Server Machine ]──────────────────────────────────────────────────┐  ┆  happens here│   ┆
│┌─────────────────┐                        ┌─────────────────────┐   │  ┆              │   ┆
││ Your SSH Daemon │ ◀─[user2@localhost:X]─ │ user3> iroh-ssh     │ ◀───────────────────┘   ┆
││ (Not iroh-ssh)  │                        │ server --ssh-port X │   │  ┆                  ┆
│└─────────────────┘                        └─────────────────────┘   │  ┆                  ┆
└─────────────────────────────────────────────────────────────────────┘   ┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄┄

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
> iroh-ssh service install --ssh-port 2222        # Background daemon with custom SSH port (default is --ssh-port 22)
> iroh-ssh service install --init-system openrc   # Background daemon for OpenRC (default is --init-sys systemd)
> iroh-ssh service uninstall                      # Uninstall service
> iroh-ssh service uninstall --init-system openrc # Uninstall service (OpenRC)

# Client connection
> iroh-ssh user@<NODE_ID>                           # Connect to remote server
> iroh-ssh connect user@<NODE_ID>                   # Explicit connect command
> iroh-ssh -i ~/.ssh/id_rsa_my_cert user@<NODE_ID>  # Connect with certificate
> iroh-ssh -L [bind_address:]port:host:hostport user@<NODE_ID>  # Forward connections made to client (bind_addr:port) to server (host:hostport)
> iroh-ssh -R [bind_address:]port:host:hostport user@<NODE_ID>  # Forward connections made to server (bind_addr:port) to client (host:hostport)
> iroh-ssh connect user@<NODE_ID> -- 'screen -d -R' # Arguments after -- get passed to ssh.

If the connection is unstable you may want to keep the session open with GNU Screen as shown above.

Security Model

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

Iroh-SSH is tested with Fedora Linux (SystemD) Gentoo Linux (OpenRC) and Windows 10 before release.

If installed as a service on Linux, the server is supposed to run as the same user that owns the iroh-ssh binary. This user can get the nodeid for the service by running iroh-ssh info.

If installed as a service on Windows, the server runs as the local system account. You can get the nodeid by checking the log at C:\ProgramData\iroh-ssh\iroh-ssh.log or running PowerShell as administrator and using iroh-ssh info.

The Windows executable is built on Windows 10 with the stable-x86_64-pc-windows-msvc toolchain until I can figure out cross-compilation.

Status

• Password authentication
• Persistent SSH keys
• Linux service mode
• Add howto gifs
• Add -p flag for persistence
• Windows service mode
• Certificate support (-i flag)
• OpenRC service script
• OpenDoas support for service installation
• More SSH features?
• Cross-compilation support to Windows from Linux

License

Code under this branch is distributed under GPLv3 (see LICENSE). Sublicensed from work originially distributed under MIT license (see LICENSE_OLD).