vpnc-script replacement for easy and secure split-tunnel VPN setup

dlenski, updated πŸ•₯ 2022-12-20 15:06:56


License: GPL v3 Build Status PyPI Homebrew

Table of Contents


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:

  • By default, it only routes traffic for specific hosts or subnets through the VPN.
  • It automatically looks up named hosts, using the VPN's DNS servers, and adds entries for them to your /etc/hosts (which it cleans up after VPN disconnection), however it does not otherwise alter your /etc/resolv.conf at all.
  • It has many additional options to customize routing and lookup (for example, --route-splits to additionally route traffic for specific subnets requested by the server). Run vpn-slice --help to see them all.

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.


  • Python 3.3+
  • Either of the following:
  • dnspython module (preferred, tested with v1.16.0)
  • dig command-line DNS lookup tool (tested with v9.9.5 and v9.10.3)
  • Supported OSes:
  • Linux kernel 3.x+ with iproute2 and iptables utilities (used for all routing setup) Furthermore, resolveconf or systemd-resolved is needed for split DNS. SystemD's resolvconf is preferred over resolvconf, if both are present on a system.
  • macOS 10.x with BSD route
  • FreeBSD with BSD route if procfs is mounted

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.)

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 documention for important details about the portability and reusability of RPM packages built in this way:

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

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

sh $ 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.):

```sh $ 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:

```sh $ 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.


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:

sh $ sudo openconnect gateway.bigcorp.com -u user1234 \ -s 'vpn-slice hostname1 alias2=alias2.bigcorp.com=' $ cat /etc/hosts ... dns0.tun0 # vpn-slice-tun0 AUTOCREATED dns1.tun0 # vpn-slice-tun0 AUTOCREATED hostname1 hostname1.bigcorp.com # vpn-slice-tun0 AUTOCREATED alias2 alias2.bigcorp.com # vpn-slice-tun0 AUTOCREATED



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.


However, some Linux distro packagers have picked up my patch in recent

releases, e.g. Ubuntu 17.04:


$ sudo vpnc config_file \ --script '/path/to/vpn-slice hostname1 alias2=alias2.bigcorp.com=' ```

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

  • Hostnames alone (hostname1) as well as host-to-IP aliases (alias2=alias2.bigcorp.com= The former are first looked up using the VPN's DNS servers. Both are also added to the routing table, as well as to /etc/hosts (unless --no-host-names is specified). As in this example, multiple aliases can be specified for a single IP address.
  • Subnets to include ( in the VPN routes as well as subnets to explicitly exclude (%

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


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

  • @jagtesh's split-tunnelling tutorial gist taught me the basics of how to set up a split-tunnel VPN by wrapping the standard vpnc-script.
  • @apenwarr's sshuttle has the excellent --auto-hosts and --seed-hosts options. These inspired the automatic host lookup feature.
  • @gmacon's PR #11 substantially refactored the code to separate the OS-dependent parts more cleanly, and added macOS support.
  • @joelbu's PR #30 added support for IPv6 DNS lookups using dig.


GPLv3 or later.

TODO / Help Wanted

  • Better error-explaining
  • Fix timing issues
  • Improve IPv6 support
  • Support OSes other than Linux and macOS
    • Other Unix-like operating systems should be pretty easy


Cannot read/write /etc/hosts with no-ns-hosts option

opened on 2023-01-22 09:39:30 by GRomR1

I want prevent any writes into /etc/hosts and I use --no-host-names --no-short-names --no-ns-hosts options. But I always get a message WARNING: Couldn't configure hosts provider: Cannot read/write /etc/hosts. I think when this options was added this configuration doesn't need.

What I want? I want to use vpn-slice without any hidden sudo privileges on my MacOS. Only add %admin ALL=(ALL) NOPASSWD: /opt/homebrew/bin/vpn-slice to sudoers file.

resolve to absolute path

opened on 2022-12-20 15:06:55 by rogeliodh

In ubuntu 22.10 /etc/resolv.conf resolves to ../run/systemd/resolve/stub-resolv.conf so it does not match the regex.

So, it is better to use the absolute path.

vpn-slice fails to install on Fedora 37

opened on 2022-12-07 18:40:03 by thrykol

Using the repository name=Copr repo for vpn-slice owned by janbaudisch baseurl=https://download.copr.fedorainfracloud.org/results/janbaudisch/vpn-slice/fedora-$releasever-$basearch/ type=rpm-md skip_if_unavailable=True gpgcheck=1 gpgkey=https://download.copr.fedorainfracloud.org/results/janbaudisch/vpn-slice/pubkey.gpg repo_gpgcheck=0 enabled=1 enabled_metadata=1

the package fails to install due to missing dependencies which no longer exist. On Fedora 37, it looks like the dependency package names have changed to a prefixed format (python-setproctitle, python-dns, etc).

Sample error:

[[email protected] ~]# dnf install vpn-slice Repository copr:copr.fedorainfracloud.org:janbaudisch:vpn-slice is listed more than once in the configuration Last metadata expiration check: 0:15:52 ago on Wed 07 Dec 2022 11:17:28 AM MST. Error: Problem: conflicting requests - nothing provides python3.9dist(dnspython) needed by vpn-slice-0.15-1.fc35.x86_64 - nothing provides python3.9dist(setproctitle) needed by vpn-slice-0.15-1.fc35.x86_64 - nothing provides python3.9dist(setuptools) needed by vpn-slice-0.15-1.fc35.x86_64 - nothing provides python(abi) = 3.9 needed by vpn-slice-0.15-1.fc35.x86_64 (try to add '--skip-broken' to skip uninstallable packages)

current `vpn-slice` fails with `(22, 'Invalid argument')`

opened on 2022-11-21 11:18:07 by cresh

Using vpn-slice from current master in a Docker container on macOS fails with "Invalid argument":


vpn-slice example.com

(22, 'Invalid argument') ```

It even fails in the same way without any arguments:



(22, 'Invalid argument') ```

Using revision fde18b767df20bcea842084f2e03eb0723f9b4ea still works as expected.

You can find a complete strace here: strace-vpn-slice.log

fix crash if /etc/resolv.conf is not a symlink

opened on 2022-10-22 19:58:42 by ottojo

add check if /etc/resolv.conf is symlink to ResolvedSplitDNSProvider.inuse() before resolving the link, this prevents EINVAL from os.readlink()

self test would fail with "invalid argument" error since os.readlink would fail with EINVAL if the argument is not a link

Do not run code to test the Python version

opened on 2022-10-07 09:24:26 by DimitriPapadopoulos
  • Use python_requires instead.
  • Python < 3.3 reached end-of-life status long ago (2016-02-20).


Dan Lenski

Physics PhD, marathoner, former Intel semiconductor engineer. I'm a long-time FLOSS user, like to code in Python and C, and enjoy ЯƎƎИIβ…Π˜ΖŽing.

GitHub Repository

vpnc openconnect vpn-client iproute2 split-tunnel vpn-slice