{"id":13596700,"url":"https://github.com/dlenski/vpn-slice","last_synced_at":"2025-05-15T16:04:31.467Z","repository":{"id":38816516,"uuid":"59932020","full_name":"dlenski/vpn-slice","owner":"dlenski","description":"vpnc-script replacement for easy and secure split-tunnel VPN setup","archived":false,"fork":false,"pushed_at":"2024-09-05T19:10:11.000Z","size":239,"stargazers_count":783,"open_issues_count":29,"forks_count":91,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-05-12T00:36:51.594Z","etag":null,"topics":["iproute2","openconnect","split-tunnel","vpn-client","vpn-slice","vpnc"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dlenski.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-05-29T07:41:01.000Z","updated_at":"2025-05-09T07:07:53.000Z","dependencies_parsed_at":"2024-04-12T18:26:38.995Z","dependency_job_id":"d9aa7ff6-57a3-4bb8-9694-3b5d5bf5d117","html_url":"https://github.com/dlenski/vpn-slice","commit_stats":{"total_commits":206,"total_committers":17,"mean_commits":"12.117647058823529","dds":"0.20873786407766992","last_synced_commit":"9ecb50db80fe912f99bc0996b4465aeb97f65ac2"},"previous_names":[],"tags_count":27,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlenski%2Fvpn-slice","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlenski%2Fvpn-slice/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlenski%2Fvpn-slice/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dlenski%2Fvpn-slice/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dlenski","download_url":"https://codeload.github.com/dlenski/vpn-slice/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254374408,"owners_count":22060610,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["iproute2","openconnect","split-tunnel","vpn-client","vpn-slice","vpnc"],"created_at":"2024-08-01T16:02:41.093Z","updated_at":"2025-05-15T16:04:31.424Z","avatar_url":"https://github.com/dlenski.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"vpn-slice\n=========\n\n[![License: GPL v3](https://img.shields.io/badge/License-GPL%20v3-blue.svg)](https://www.gnu.org/licenses/gpl-3.0)\n[![Build Status](https://github.com/dlenski/vpn-slice/workflows/test_and_release/badge.svg)](https://github.com/dlenski/vpn-slice/actions?query=workflow%3Atest_and_release)\n[![PyPI](https://img.shields.io/pypi/v/vpn-slice.svg)](https://pypi.python.org/pypi/vpn-slice)\n[![Homebrew](https://img.shields.io/homebrew/v/vpn-slice.svg)](https://formulae.brew.sh/formula/vpn-slice)\n\nTable of Contents\n=================\n\n  * [Introduction](#introduction)\n    * [Who this is for](#who-this-is-for)\n    * [Requirements](#requirements)\n    * [Installation](#installation)\n      * [From PyPI](#from-pypi)\n      * [As an RPM](#as-an-rpm)\n      * [On MacOS](#on-macos)\n    * [First steps](#first-steps)\n    * [Usage](#usage)\n    * [Diagnostics](#diagnostics)\n  * [Inspiration and credits](#inspiration-and-credits)\n  * [License](#license)\n    * [TODO](#todo--help-wanted)\n\n## Introduction\n\nThis is a replacement for the\n[`vpnc-script`](https://www.infradead.org/openconnect/vpnc-script.html)\nused by [OpenConnect](https://www.infradead.org/openconnect) or\n[VPNC](https://www.unix-ag.uni-kl.de/~massar/vpnc).\n\nInstead of trying to copy the behavior of standard corporate VPN clients,\nwhich normally reroute **all** your network traffic through the VPN,\nthis one tries to _minimize your contact_ with an intrusive VPN.\nThis is also known as a\n[split-tunnel](https://en.wikipedia.org/wiki/Split_tunneling) VPN, since\nit splits your traffic between the VPN tunnel and your normal network\ninterfaces.\n\n`vpn-slice` makes it easy to set up a split-tunnel VPN:\n\n* By default, it only routes traffic for **specific hosts or subnets**\n  through the VPN.\n* It automatically looks up named hosts, using the VPN's DNS servers,\n  and adds entries for them to your `/etc/hosts` (which it cleans up\n  after VPN disconnection), however it **does not otherwise alter your\n  `/etc/resolv.conf` at all**.\n* It has many additional options to customize routing and lookup (for\n  example, `--route-splits` to additionally route traffic for specific\n  subnets requested *by the server*). Run `vpn-slice --help` to see\n  them all.\n\n## Who this is for\n\nIf you are using a VPN to route *all* your traffic for privacy reasons\n(or to avoid censorship in repressive countries), then you **do not want\nto use this**.\n\nThe purpose of this tool is almost the opposite; it makes it easy to\nconnect to a VPN while **minimizing** the traffic that passes over the\nVPN.\n\nThis is for people who have to connect to the high-security VPNs of\ncorporations or other bureaucracies (which monitor and filter and\notherwise impede network traffic), and thus wish to route as little\ntraffic as possible through those VPNs.\n\n## Requirements\n\n* Python 3.5+\n* Either of the following:\n  * [`dnspython`](https://pypi.org/project/dnspython) module (**preferred**, tested with v1.16.0)\n  * [`dig`](https://en.wikipedia.org/wiki/Dig_(command)) command-line DNS lookup tool (tested with v9.9.5 and v9.10.3)\n* Supported OSes:\n  * Linux kernel 3.x+ with\n    [`iproute2`](https://en.wikipedia.org/wiki/iproute2) and\n    [`iptables`](https://en.wikipedia.org/wiki/iptables) utilities\n    (used for all routing setup)\n  * macOS 10.x with BSD\n    [`route`](https://en.wikipedia.org/wiki/Route_(command))\n  * FreeBSD with BSD\n    [`route`](https://en.wikipedia.org/wiki/Route_(command))\n    if [`procfs`](https://www.freebsd.org/cgi/man.cgi?query=procfs\u0026sektion=5) is mounted\n\n## Installation\n\n### From PyPI\n\nYou can install the latest build [from PyPI](https://pypi.org/project/vpn-slice)\nwith `pip` (make sure you are using the Python 3.x version, usually invoked\nwith `pip3`).\n\nYou should install as `root` (e.g. using `sudo`), because\n`openconnect` or `vpnc` will need to be able to invoke `vpn-slice`\nwhile running as root:\n\n```sh\n# latest release from PyPI\n$ sudo pip3 install \"vpn-slice[dnspython,setproctitle]\"\n\n# latest development version\n$ sudo pip3 install \"https://github.com/dlenski/vpn-slice/archive/master.zip#egg=vpn-slice[dnspython,setproctitle]\"\n```\n\n(If your system doesn't support `dnspython` or `setproctitle`, for some reason, then omit those.)\n\n### As an RPM\n\nYou can use the `bdist_rpm` target to package vpn-slice as an RPM, and thereby install it with your distribution's\npackaging system, allowing it to keep track of installed files.\nSee [the documentation](https://docs.python.org/3/distutils/builtdist.html#creating-rpm-packages) for important\ndetails about the portability and reusability of RPM packages built in this way:\n\n```sh\n$ python3 setup.py bdist_rpm --requires=python3-dns,python3-setproctitle\n$ sudo dnf install dist/vpn-slice-*.noarch.rpm\n```\n\n### On macOS\n\nOn macOS, you can also install from the [Homebrew](https://brew.sh) repository:\n\n```sh\n$ brew install vpn-slice\n```\n\n## First steps\n\nBefore trying to use `vpn-slice` with `openconnect` or `vpnc`,\ncheck that it works properly on your platform, and can verify that it has all of\nthe access and dependencies that it needs (to modify `/etc/hosts`, alter\nrouting table, etc.):\n\n```sh\n$ sudo vpn-slice --self-test\n***************************************************************************\n*** Self-test passed. Try using vpn-slice with openconnect or vpnc now. ***\n***************************************************************************\n```\n\nIf you run the self-test as a non-`root` user, it will tell you what required\naccess it is unable to obtain:\n\n```sh\n$ vpn-slice --self-test\nWARNING: Couldn't configure hosts provider: Cannot read/write /etc/hosts\n******************************************************************************************\n*** Self-test did not pass. Double-check that you are running as root (e.g. with sudo) ***\n******************************************************************************************\nAborting because providers for hosts are required; use --help for more information\n```\n\nWhen you start trying to use `vpn-slice` for real, you should use the\n[diagnostic options](#diagnostics) (e.g `openconnect -s 'vpn-slice\n--verbose --dump'`) to troubleshoot and understand its behavior.\n\n## Usage\n\nYou should specify `vpn-slice` as your connection script with\n`openconnect` or `vpnc`. It has been tested with vpnc v0.5.3, OpenConnect\nv7.06+ (Cisco AnyConnect and Juniper protocols) and v8.0+ (PAN GlobalProtect\nprotocol).\n\nFor example:\n\n```sh\n$ sudo openconnect gateway.bigcorp.com -u user1234 \\\n    -s 'vpn-slice 192.168.1.0/24 hostname1 alias2=alias2.bigcorp.com=192.168.1.43'\n$ cat /etc/hosts\n...\n192.168.1.1 dns0.tun0\t\t\t\t\t# vpn-slice-tun0 AUTOCREATED\n192.168.1.2 dns1.tun0\t\t\t\t\t# vpn-slice-tun0 AUTOCREATED\n192.168.1.57 hostname1 hostname1.bigcorp.com\t\t# vpn-slice-tun0 AUTOCREATED\n192.168.1.43 alias2 alias2.bigcorp.com\t\t# vpn-slice-tun0 AUTOCREATED\n```\n\nor\n\n```sh\n# With most versions of vpnc, you *must* specify an absolute path\n# for the disconnect hook to work correctly, due to a bug.\n#\n# I reported this bug, but the original maintainers no longer maintain vpnc.\n#   https://lists.unix-ag.uni-kl.de/pipermail/vpnc-devel/2016-August/004199.html\n#\n# However, some Linux distro packagers have picked up my patch in recent\n# releases, e.g. Ubuntu 17.04:\n#   https://changelogs.ubuntu.com/changelogs/pool/universe/v/vpnc/vpnc_0.5.3r550-3/changelog\n#\n$ sudo vpnc config_file \\\n       --script '/path/to/vpn-slice 192.168.1.0/24 hostname1 alias2=alias2.bigcorp.com=192.168.1.43'\n```\n\nNotice that `vpn-slice` accepts several different kinds of routes and hostnames on the command line:\n\n- Hostnames *alone* (`hostname1`) as well as *host-to-IP* aliases (`alias2=alias2.bigcorp.com=192.168.1.43`).\n  The former are first looked up using the VPN's DNS servers. Both are also added to the routing table, as\n  well as to `/etc/hosts` (unless `--no-host-names` is specified). As in this example, multiple aliases can\n  be specified for a single IP address.\n- Subnets to *include* (`10.0.0.0/8`) in the VPN routes as well as subnets to explicitly *exclude* (`%10.123.0.0/24`).\n\nThere are many command-line options to alter the behavior of\n`vpn-slice`; try `vpn-slice --help` to show them all.\n\n# Diagnostics\n\nRunning with `--verbose` makes it explain what it is doing, while running with\n`--dump` shows the environment variables passed in by the caller.\n\n# Inspiration and credits\n\n* [**@jagtesh**](https://github.com/jagtesh)'s\n  [split-tunnelling tutorial gist](https://gist.github.com/jagtesh/5531300) taught me the\n  basics of how to set up a split-tunnel VPN by wrapping the standard `vpnc-script`.\n* [**@apenwarr**](https://github.com/apenwarr)'s\n  [sshuttle](https://github.com/apenwarr/sshuttle) has the excellent\n  `--auto-hosts` and `--seed-hosts` options. These inspired the\n  automatic host lookup feature.\n* [**@gmacon**](https://github.com/gmacon)'s\n  [PR #11](https://github.com/dlenski/vpn-slice/pull/11) substantially\n  refactored the code to separate the OS-dependent parts more\n  cleanly, and added macOS support.\n* [**@joelbu**](https://github.com/joelbu)'s\n  [PR #30](https://github.com/dlenski/vpn-slice/pull/30) added support for IPv6 DNS\n  lookups using `dig`.\n\n# License\n\nGPLv3 or later.\n\n## TODO / Help Wanted\n\n* Better error-explaining\n* Fix timing issues\n* Improve IPv6 support\n* Support OSes other than Linux and macOS\n    * Other Unix-like operating systems should be pretty easy\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdlenski%2Fvpn-slice","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdlenski%2Fvpn-slice","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdlenski%2Fvpn-slice/lists"}