vpnns - Man Page

per-app VPN using namespaces


vpnns [--name=identifier] -- command

vpnns [--name=identifier] [--script=path] --attach


vpnns isolates VPN-related network traffic and applications inside a separate network namespace.  Applications intended to be used with the VPN cannot bypass the VPN to access the internet directly, and applications not intended to be used with the VPN cannot send traffic through the VPN tunnel.


This starts up an application in a fresh user/net/uts/mount namespace:

vpnns -- google-chrome --user-data-dir=/tmp/vpntest

vpnns -- firefox -no-remote -P vpn

vpnns -- transmission-gtk

Initially it will not have any network access as the only interface present in the netns is the loopback device.  The application should still be able to talk to Xorg through UNIX sockets in /tmp.

The next step is to connect to a VPN and invoke vpnns --attach to pass the VPN traffic back and forth:

openconnect --script "vpnns --attach" --script-tun vpn.example.com

openvpn --script-security 2 --config example.ovpn --dev "|HOME=$HOME vpnns --attach"

These commands connect to an ocserv or openvpn gateway, then tell vpnns to set up a tunnel device, default route, and resolv.conf inside the namespace created above.  On success, the web browser will have connectivity. When the VPN disconnects, the browser will lose all connectivity, preventing leaks.

vpnns can be rerun multiple times if the connection fails or if the VPN client crashes.  If run without arguments, it will open a shell inside the namespace.


-n,  --name identifier

vpnns is designed to allow multiple instances to coexist on the same system.  This feature could be useful for connecting to multiple VPNs at the same time.  identifier defaults to "default" but can be overridden through the --name option.

-s,  --script path

Invoke the program at path to set up and tear down the tunnel device's IP configuration, instead of letting vpnns handle it internally. $TUNDEV will be set to the device name (e.g. tun0). $reason will be set to either connect or disconnect. Any IP configuration variables such as $INTERNAL_IP4_ADDRESS set by the VPN client will be inherited, so it is possible for a modified vpnc-script to be used.  This option only has an effect if --attach is also specified.


vpnns is not a security tool.  It cannot prevent malicious applications from bypassing the namespace restrictions.

While OpenConnect works with vpnns out of the box, OpenVPN currently (as of 2017-01-08) requires out-of-tree patches to support non-root operation.

If /etc/resolv.conf is a symbolic link to a file that is regenerated on network connection changes, the bind mount used by vpnns to override the DNS configuration can be inadvertently deleted.  vpnns attempts to work around this by using overlayfs to override /etc/resolv.conf, but that does not work on all systems.

Some distributions patch their kernels to prevent unprivileged users from creating namespaces, resulting in a "can't unshare namespaces: Operation not permitted" error.  This security feature can be disabled using the following command:

sudo sysctl -w kernel.unprivileged_userns_clone=1

To make the change permanent, edit /etc/sysctl.conf.



State directory for a given vpnns instance.  By default, vpnns uses ~/.vpnns-default.

See Also

ocproxy(1), openconnect(8), openvpn(8)

Referenced By


January 8, 2017