[feature] allow manual gateway selection for vpn

For now, the way to select a gateway is to add a section in
bitmaskd.cfg:

  [vpn_prefs]
  locations = ["frankfurt", "seattle__wa"]
  countries = ["DE", "US"]

Note that the location indication has priority over country code.

This will be exposed by the UI in release 0.11

- Resolves: #8855

3 files changed, 42 insertions, 1 deletions

diff --git a/docs/changelog.rst b/docs/changelog.rst
index c89f51ed..6f94d873 100644
--- a/docs/changelog.rst
+++ b/docs/changelog.rst
@@ -5,6 +5,7 @@ Changelog
 
 Features
 ~~~~~~~~
+- Initial cli port of the legacy vpn code
 - `#8112 <https://0xacab.org/leap/bitmask-dev/issues/8112>`_: Check validity of key signature
 - `#8755 <https://0xacab.org/leap/bitmask-dev/issues/8755>`_: Add account based keymanagement API
 - `#8770 <https://0xacab.org/leap/bitmask-dev/issues/8770>`_: Simplify mail status in the cli
@@ -16,7 +17,7 @@ Features
 - `#8049 <https://0xacab.org/leap/bitmask-dev/issues/8049>`_: Restart the VPN automatically
 - `#8852 <https://0xacab.org/leap/bitmask-dev/issues/8852>`_: Stop the vpn (and all services) when application is shut down
 - `#8804 <https://0xacab.org/leap/bitmask-dev/issues/8804>`_: Automatic selection of gateways, based on user timezone
-- Initial cli port of the legacy vpn code
+- `#8855 <https://0xacab.org/leap/bitmask-dev/issues/8855>`_: Manual override for the vpn gateway selection
 - Add VPN API to bitmask.js
 - Add vpn get_cert command
 - Indicate a successful/failure OpenPGP header import
diff --git a/docs/index.rst b/docs/index.rst
index ecd9d603..bc509ca2 100644
--- a/docs/index.rst
+++ b/docs/index.rst
@@ -66,6 +66,7 @@ Contents
    hacking/index
    bundles/index
    cli/index
+   vpn/index
    core/index
    bonafide/index
    keymanager/index
diff --git a/docs/vpn/index.rst b/docs/vpn/index.rst
new file mode 100644
index 00000000..7bb4799a
--- /dev/null
+++ b/docs/vpn/index.rst
@@ -0,0 +1,39 @@
+:LastChangedDate: $LastChangedDate$
+:LastChangedRevision: $LastChangedRevision$
+:LastChangedBy: $LastChangedBy$
+
+.. _vpn:
+
+
+Bitmask VPN
+================================
+
+The Bitmask VPN Module
+
+Gateway Selection
+-----------------------------------
+
+By default, the Gateway Selector will apply a heuristic based on the configured
+timezone of the system.  This will choose the closest gateway based on the
+timezones that the provider states in the ``eip-config.json`` file.
+
+If the locations section is not properly set by the provider, or if the user
+wants to manually override the selection, the only way to do this for the
+``0.10`` version of Bitmask is to add a section to the ``bitmaskd.cfg``
+configuration file::
+
+  [vpn_prefs]
+  locations = ["rio__br"]
+  countries = ["BR", "AR", "UY"]
+
+Take into account that the locations entry has precedence over the country codes enumeration.
+
+Also, the normalization is done so that any non-alphabetic character is substituted by an underscore ('``_``).
+
+You can list all the configured locations using the CLI::
+
+  % bitmaskctl vpn list
+  demo.bitmask.net      [DE] Frankfurt (UTC+1)
+  demo.bitmask.net      [US] Seattle, WA (UTC-7)
+
+This manual override functionality will be exposed through the UI and the CLI in release ``0.11``.