Poor mans VPN over SSH
Shell JavaScript
Switch branches/tags
Nothing to show
Clone or download

README.asciidoc

README

pvpn is a tool to set up layer 3 VPNs over SSH. It is mostly a wrapper around OpenSSH and pppd(8), but provides a helpful interface. Given that you fulfil the requirements (root access to local machine and SSH server, IP forwarding enabled; see REQUIREMENTS for details), you can, for example, reroute all your IP traffic through myserver with

$ pvpn root@myserver default

pvpn can use several different ways of tunneling, using the -t option: ppp over ssh (-t ppp) or the OpenSSH built-in Layer 3 tunnel (-t ssh-3). The different ways have slightly different requirements. See below for details.

pvpn is useful to protect your network communication when on a public, unencrypted network, or when you need access to a private network without any regular VPN infrastructure available.

See pvpn(8) for a complete reference.

SYNOPSIS

pvpn [OPTION] …​ SSH-HOST [ROUTE] …​

GENERAL OPTIONS

-h, --help

Show help and exit.

-v, --version

Show version and exit.

-d, --debug

Trace code execution.

CONNECT OPTIONS

-t TYPE, --type TYPE

Type of tunnel. Valid options are:

  • ppp (ppp over ssh)

  • ssh-3 (OpenSSH Layer 3)

-i IP1:IP2, --ip IP1:IP2

Use IP1 for local and IP2 for remote tunnel device IPs. Default any:any, which becomes 10.b.c.1:10.b.c.2 where b and c are random.

-s SSH-IP, --first-ssh-hop SSH-IP

Tell IP address or hostname of first SSH server. Needed when you connect through reverse tunnels or intermediate servers with ProxyCommand.

-D, --inherit-dns

Inherit DNS settings from SSH-HOST. When disconnecting, the current DNS settings will be restored.

DISCONNECT OPTIONS

-S [DEVICE], --stop [DEVICE]

Stop tunnel with client device DEVICE, or all if no DEVICE is given, then exit.

EXAMPLES

Gain access to the 192.168.xxx.yyy network at work

$ pvpn -i 10.10.0.1:10.10.0.2 root@work 192.168.0.0/16

Encrypt all IP traffic, e.g. when on a public wifi using OpenSSH Layer 3

$ pvpn -t ssh-3 root@secureproxy default

Disconnect tunnel with device ppp0

$ pvpn -S ppp0

Adding additional arguments to SSH:

$ SSH_ARGS="-i ~/.ssh/id_rsa" 10.10.0.1:10.10.0.2 root@work 192.168.0.0/16

Test that traffic is routed through your tunnel with e.g. traceroute(8).

DEPENDENCIES

  • GNU/Linux

  • OpenSSH

  • pppd

  • bash

  • iproute2

  • dnsutils (dig(1))

  • asciidoc

INSTALLATION

Configure

Edit config.mk if you need to customize your installation.

PREFIX

Directory under which pvpn will be installed as bin/pvpn

MANPREFIX

Directory under which the manpage will be installed

Install

$ make install

Uninstall

$ make uninstall

REQUIREMENTS

To establish a VPN connection through an SSH server, the following is required:

  • root access on both client and server. To enable root SSH access on the server via authentication keys, set below in /etc/ssh/sshd_config.

PermitRootLogin without-password
  • Authentication through SSH authentication keys. On the client, as root, run

$ ssh-keygen

$ ssh-copy-id root@<server>
  • IP forwarding enabled on server. It can be enabled by something like below, depending on your software stack.

$ sysctl net.ipv4.ip_forward = 1

$ iptables -P FORWARD ACCEPT

$ iptables -t nat -A POSTROUTING -o eth0 -j MASQUERADE
  • iproute2 installed on client and server (ip(8)).

  • dnsutils installed on client (dig(1)).

Table 1. Tunnel type specific requirements
ppp ssh-3

sshd_config PermitTunnel

point-to-point or yes

Software

pppd(8) on both sides

OpenSSH 4.3+

PORTABILITY

Works-for-me™. Developed and tested on Arch Linux. I have not tested this on other systems but would like to hear from you if you have, successfully or not. Let me know at henrik@k2h.se.

LICENSE

Released under the New BSD License; see LICENSE.