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)