NAME

       vpnns - per-app VPN using namespaces

SYNOPSIS

       vpnns [--name=identifier] -- command

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

DESCRIPTION

       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.

USAGE

       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.

OPTIONS

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

CAVEATS

       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.

FILES

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

SEE ALSO

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

                                                 January 8, 2017                                        VPNNS(1)