sshtunnel SSH tunnelling SystemD daemon.

Configure SSH tunnels and port forwardings.

Tip

On a desktop linux you better to try NetworkManager SSH plugin It allows to configure an SSH VPN with GUI.

If your computer is behind a NAT you can expose your website with a tunnel. There are a few of services that provides free or cheap tunnels e.g. https://localhost.run, https://srv.us etc.

Installation

Debian/Ubuntu

For Ubuntu use PPA repository:

sudo add-apt-repository ppa:stokito/utils
sudo apt update
sudo apt install sshtunnel

Or install by downloading the package:

wget -O /tmp/sshtunnel https://github.com/yurt-page/sshtunnel/releases/download/v1.2.0/sshtunnel_1.2.0_all.deb
sudo dpkg -i /tmp/sshtunnel
rm -f /tmp/sshtunnel

From sources for development

git clone git@github.com:yurt-page/sshtunnel.git
cd sshtunnel
# install files, service and reload systemd services    
sudo make install_all
# reload to test after changes
sudo make restart
sudo make stop

Usage

Set keys

To configure server and a tunnel you need to set up the SSH key for the server. The sshtunnel is runed under your user. So you need to configure keys in home directory ~/.ssh/. You can generate a new key with a command ssh-keygen.

Also add an SSH server's host key to ~/.ssh/known_hosts or use StrictHostKeyChecking accept-new bellow. But it would be simpler to just ssh manually into the server and it will be remembered. The step is not needed for known SSH tunnel providers.

Configure ~/.ssh/config

When the sshtunnel starts it reads ~/.ssh/config finds all hosts that ends with _tun e.g. Host router_tun and starts an ssh connection to the host. So edit the ~/.ssh/config by this example:

Host router_tun
    HostName 192.168.1.1
    Port 2222
    User root
    ServerAliveInterval 30
    ConnectionAttempts 10
    StrictHostKeyChecking accept-new
    # When someone connect to the router's public IP on 80 port forward it to the local 8080 port
    RemoteForward 80 127.0.0.1:8080
    # When sendmail connecting to the local 25 port then connect to the router and forward to its 25 port  
    LocalForward 25 127.0.0.1:25
    # Start a SOCKS proxy on local 1080 port. Configure a browser to use it.
    DynamicForward 1080

The sshtunnel will also add -N -o ExitOnForwardFailure=yes -o BatchMode=yes options when starting the ssh connection.

Then restart with systemctl --user restart sshtunnel and check status with systemctl --user status sshtunnel.

If no any tunnel specified the sshtunnel stops and a service won't be running unless you restart it.

Important

Your host must be exactly like Host router_tun e.g. with a space after Host and nothing after _tun. I.e. Host router_tun # tunnel won't work. If you want to disable it then change suffix e.g. Host router_tun_disabled

Configure ~/.ssh/sshtunnel.config.sh

Another configuration file is ~/.ssh/sshtunnel.config.sh. The file is a DSL over a plain shell script. It may be more expressive but has fewer options.

Edit the config file ~/.ssh/sshtunnel.config.sh e.g.:

server "srv_us"
  HostName="srv.us"
  User="root"

tunnelR "srv_us_http"
  servername="srv_us"
  remoteaddress="1"
  remoteport=80
  localaddress="127.0.0.1"
  localport=8080

See sshtunnel.config.sh for more samples.

Supported options by sshtunnel.config.sh

• server specify SSH server options. One server may have multiple tunnels.
  • enabled set to 0 to disable.
  • HostName IP, domain or Host configured in ~/.ssh/config. Required.
  • User default is a user that started the sshtunnel service i.e. root. You better to create a separate limited user on the server.
  • Port default 22.
  • IdentityFile an absolute path to a private key. If empty then the ssh will try ~/.ssh/id_rsa, then ~/.ssh/id_ed25519 etc. Set it only if name is non-standard.
  • StrictHostKeyChecking default accept-new. If you are afraid that server can change it in future then set to no to your own risk.
  • ServerAliveInterval default 30.
  • ServerAliveCountMax default 2.
  • ConnectionAttempts default 10.
• tunnelR remote to local tunnel
  • remoteaddress, remoteport, localaddress, localport
• tunnelL local to remote tunnel
  • remoteaddress, remoteport, localaddress, localport
• tunnelD dynamic tunnel e.g. SOCKS proxy
  • localaddress, localport
• tunnelW VPN
  • Tunnel point-to-point (default) or ethernet. See Tunnel in man ssh_config
  • localdev, remotedev tun devices. See TunnelDevice in man ssh_config

Options from SSH config file are starting from Upper case but the sshtunnel specific options starts with lowercase. So use man ssh_config to see the meaning of options. If you need more options e.g. ProxyJump then specify them in ~/.ssh/config.

Troubleshooting

Check that ssh has been started with ps ax | grep ssh e.g.:

ssh root@srv.us -R 1:80:127.0.0.1:8080 -N -o ExitOnForwardFailure=yes -o BatchMode=yes

To read logs use:

journalctl --user-unit sshtunnel -f -n 50

See also

• SystemD SSH client unit based on SystemD templates. Configure port forwardings in the SSH config
• OpenWrt sshtunnel for a router with OpenWrt firmware. You can setup it as a SOCKS for simplicity.
• NetworkManager SSH plugin
• srv.us SystemdD runner
• localhost.run SystemdD runner
• python3-sshtunnel - a Python tool to start an SSH tunnel
• jfifield/sshtunnel - a GUI SSH tunnel manager in Java
• shyim/tunnelmanager - a Qt GUI SSH tunnel manager in CPP
• mjun/gnome-connection-manager - a rich GUI in Python.
• Gnome SSH Tunnel Manager (gSTM) - a GUI in Python.
• sshuttle - a popular transparent proxy server that works as a poor man's VPN over SSH. Doesn't require admin. Supports DNS tunneling.