search

yurt-page / sshtunnel

SSH tunneling daemon
BSD Zero Clause License
14 stars 3 forks source link
socks-proxy ssh-client ssh-tunnel systemd-unit

readme

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

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