README

pvpn is a tool to set up layer 3 VPNs over SSH. It is mostly a wrapper around http://www.openssh.org/[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 <<XREQUIREMENTS, 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

[[XREQUIREMENTS]] 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)).

.Tunnel type specific requirements [width="50%",options="header"] |=================================================================================== | | ppp | ssh-3 | sshd_config +PermitTunnel+ | | +point-to-point+ or +yes+ | Software | pppd(8) on both sides | OpenSSH 4.3+ |===================================================================================

PORTABILITY

Works-for-me(TM). Developed and tested on http://www.archlinux.org[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.

FURTHER READING

• http://tldp.org/HOWTO/ppp-ssh/[VPN PPP-SSH Mini HOWTO]
• https://wiki.archlinux.org/index.php/SSH_Keys[SSH Keys]
• http://backdrift.org/transparent-proxy-with-ssh[SSH tunnel through bastion host]
• http://sites.inka.de/bigred/devel/tcp-tcp.html[Why TCP over TCP is a bad idea]