search

dlenski / vpn-slice

vpnc-script replacement for easy and secure split-tunnel VPN setup
GNU General Public License v3.0
743 stars 87 forks source link
iproute2 openconnect split-tunnel vpn-client vpn-slice vpnc

readme

vpn-slice

License: GPL v3 Build Status PyPI Homebrew

Table of Contents

Introduction

This is a replacement for the vpnc-script used by OpenConnect or VPNC.

Instead of trying to copy the behavior of standard corporate VPN clients, which normally reroute all your network traffic through the VPN, this one tries to minimize your contact with an intrusive VPN. This is also known as a split-tunnel VPN, since it splits your traffic between the VPN tunnel and your normal network interfaces.

vpn-slice makes it easy to set up a split-tunnel VPN:

Who this is for

If you are using a VPN to route all your traffic for privacy reasons (or to avoid censorship in repressive countries), then you do not want to use this.

The purpose of this tool is almost the opposite; it makes it easy to connect to a VPN while minimizing the traffic that passes over the VPN.

This is for people who have to connect to the high-security VPNs of corporations or other bureaucracies (which monitor and filter and otherwise impede network traffic), and thus wish to route as little traffic as possible through those VPNs.

Requirements

Installation

From PyPI

You can install the latest build from PyPI with pip (make sure you are using the Python 3.x version, usually invoked with pip3).

You should install as root (e.g. using sudo), because openconnect or vpnc will need to be able to invoke vpn-slice while running as root:

# latest release from PyPI
$ sudo pip3 install "vpn-slice[dnspython,setproctitle]"

# latest development version
$ sudo pip3 install "https://github.com/dlenski/vpn-slice/archive/master.zip#egg=vpn-slice[dnspython,setproctitle]"

(If your system doesn't support dnspython or setproctitle, for some reason, then omit those.)

As an RPM

You can use the bdist_rpm target to package vpn-slice as an RPM, and thereby install it with your distribution's packaging system, allowing it to keep track of installed files. See the documentation for important details about the portability and reusability of RPM packages built in this way:

$ python3 setup.py bdist_rpm --requires=python3-dns,python3-setproctitle
$ sudo dnf install dist/vpn-slice-*.noarch.rpm

On macOS

On macOS, you can also install from the Homebrew repository:

$ brew install vpn-slice

First steps

Before trying to use vpn-slice with openconnect or vpnc, check that it works properly on your platform, and can verify that it has all of the access and dependencies that it needs (to modify /etc/hosts, alter routing table, etc.):

$ sudo vpn-slice --self-test
***************************************************************************
*** Self-test passed. Try using vpn-slice with openconnect or vpnc now. ***
***************************************************************************

If you run the self-test as a non-root user, it will tell you what required access it is unable to obtain:

$ vpn-slice --self-test
WARNING: Couldn't configure hosts provider: Cannot read/write /etc/hosts
******************************************************************************************
*** Self-test did not pass. Double-check that you are running as root (e.g. with sudo) ***
******************************************************************************************
Aborting because providers for hosts are required; use --help for more information

When you start trying to use vpn-slice for real, you should use the diagnostic options (e.g openconnect -s 'vpn-slice --verbose --dump') to troubleshoot and understand its behavior.

Usage

You should specify vpn-slice as your connection script with openconnect or vpnc. It has been tested with vpnc v0.5.3, OpenConnect v7.06+ (Cisco AnyConnect and Juniper protocols) and v8.0+ (PAN GlobalProtect protocol).

For example:

$ sudo openconnect gateway.bigcorp.com -u user1234 \
    -s 'vpn-slice 192.168.1.0/24 hostname1 alias2=alias2.bigcorp.com=192.168.1.43'
$ cat /etc/hosts
...
192.168.1.1 dns0.tun0                   # vpn-slice-tun0 AUTOCREATED
192.168.1.2 dns1.tun0                   # vpn-slice-tun0 AUTOCREATED
192.168.1.57 hostname1 hostname1.bigcorp.com        # vpn-slice-tun0 AUTOCREATED
192.168.1.43 alias2 alias2.bigcorp.com      # vpn-slice-tun0 AUTOCREATED

or

# With most versions of vpnc, you *must* specify an absolute path
# for the disconnect hook to work correctly, due to a bug.
#
# I reported this bug, but the original maintainers no longer maintain vpnc.
#   https://lists.unix-ag.uni-kl.de/pipermail/vpnc-devel/2016-August/004199.html
#
# However, some Linux distro packagers have picked up my patch in recent
# releases, e.g. Ubuntu 17.04:
#   https://changelogs.ubuntu.com/changelogs/pool/universe/v/vpnc/vpnc_0.5.3r550-3/changelog
#
$ sudo vpnc config_file \
       --script '/path/to/vpn-slice 192.168.1.0/24 hostname1 alias2=alias2.bigcorp.com=192.168.1.43'

Notice that vpn-slice accepts several different kinds of routes and hostnames on the command line:

There are many command-line options to alter the behavior of vpn-slice; try vpn-slice --help to show them all.

Diagnostics

Running with --verbose makes it explain what it is doing, while running with --dump shows the environment variables passed in by the caller.

Inspiration and credits

License

GPLv3 or later.

TODO / Help Wanted