Package: vpn-slice
vpn-sliceTable of ContentsIntroductionWho this is forRequirementsFirst stepsUsageDiagnosticsInspiration and creditsLicenseTODOIntroductionThis is a replacement for thevpnc-scriptused byOpenConnectorVPNC.Instead of trying to copy the behavior of standard corporate VPN clients,
which normally rerouteallyour network traffic through the VPN,
this one tries tominimize your contactwith an intrusive VPN.
This is also known as asplit-tunnelVPN, since
it splits your traffic between the VPN tunnel and your normal network
interfaces.vpn-slicemakes it easy to set up a split-tunnel VPN:By default, it only routes traffic forspecific hosts or subnetsthrough 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 itdoes not otherwise alter your/etc/resolv.confat all.It has many additional options to customize routing and lookup (for
example,--route-splitsto additionally route traffic for specific
subnets requestedby the server). Runvpn-slice --helpto see
them all.Who this is forIf you are using a VPN to routeallyour traffic for privacy reasons
(or to avoid censorship in repressive countries), then youdo not want
to use this.The purpose of this tool is almost the opposite; it makes it easy to
connect to a VPN whileminimizingthe 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.RequirementsPython 3.3+Either of the following:dnspythonmodule (preferred, tested with v1.16.0)digcommand-line DNS lookup tool (tested with v9.9.5 and v9.10.3)Supported OSes:Linux kernel 3.x+ withiproute2andiptablesutilities
(used for all routing setup)macOS 10.x with BSDrouteFreeBSD with BSDrouteifprocfsis mountedYou can install the latest buildfrom PyPIwithpip(make sure you are using the Python 3.x version, usually invoked
withpip3).You should install asroot(e.g. usingsudo), becauseopenconnectorvpncwill need to be able to invokevpn-slicewhile running as root:# latest release from PyPI$sudopip3installvpn-slice# latest development version$sudopip3installhttps://github.com/dlenski/vpn-slice/archive/master.zipOn macOS, you can also install from theHomebrewrepository:$brewinstallvpn-sliceFirst stepsBefore trying to usevpn-slicewithopenconnectorvpnc,
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.):$sudovpn-slice--self-test
***************************************************************************
***Self-testpassed.Tryusingvpn-slicewithopenconnectorvpncnow.***
***************************************************************************If you run the self-test as a non-rootuser, it will tell you what required
access it is unable to obtain:$vpn-slice--self-test
WARNING:Couldn'tconfigurehostsprovider:Cannotread/write/etc/hosts
******************************************************************************************
***Self-testdidnotpass.Double-checkthatyouarerunningasroot(e.g.withsudo)***
******************************************************************************************
Abortingbecauseprovidersforhostsarerequired;use--helpformoreinformationWhen you start trying to usevpn-slicefor real, you should use thediagnostic options(e.gopenconnect -s 'vpn-slice --verbose --dump') to troubleshoot and understand its behavior.UsageYou should specifyvpn-sliceas your connection script withopenconnectorvpnc. 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:$sudoopenconnectgateway.bigcorp.com-uuser1234\-s'vpn-slice 192.168.1.0/24 hostname1 alias2=alias2.bigcorp.com=192.168.1.43'$cat/etc/hosts
...192.168.1.1dns0.tun0# vpn-slice-tun0 AUTOCREATED192.168.1.2dns1.tun0# vpn-slice-tun0 AUTOCREATED192.168.1.57hostname1hostname1.bigcorp.com# vpn-slice-tun0 AUTOCREATED192.168.1.43alias2alias2.bigcorp.com# vpn-slice-tun0 AUTOCREATEDor# 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#$sudovpncconfig_file\--script'/path/to/vpn-slice 192.168.1.0/24 hostname1 alias2=alias2.bigcorp.com=192.168.1.43'Notice thatvpn-sliceaccepts several different kinds of routes and hostnames on the command line:Hostnamesalone(hostname1) as well ashost-to-IPaliases (alias2=alias2.bigcorp.com=192.168.1.43).
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-namesis specified). As in this example, multiple aliases can
be specified for a single IP address.Subnets toinclude(10.0.0.0/8) in the VPN routes as well as subnets to explicitlyexclude(%10.123.0.0/24).There are many command-line options to alter the behavior ofvpn-slice; tryvpn-slice --helpto show them all.DiagnosticsRunning with--verbosemakes it explain what it is doing, while running with--dumpshows the environment variables passed in by the caller.Inspiration and credits@jagtesh'ssplit-tunnelling tutorial gisttaught me the
basics of how to set up a split-tunnel VPN by wrapping the standardvpnc-script.@apenwarr'ssshuttlehas the excellent--auto-hostsand--seed-hostsoptions. These inspired the
automatic host lookup feature.@gmacon'sPR #11substantially
refactored the code to separate the OS-dependent parts more
cleanly, and added macOS support.@joelbu'sPR #30added support for IPv6 DNS
lookups usingdig.LicenseGPLv3 or later.TODO / Help WantedBetter error-explainingFix timing issuesImprove IPv6 supportSupport OSes other than Linux and macOSOther Unix-like operating systems should be pretty easy