-
Notifications
You must be signed in to change notification settings - Fork 80
10. Updating VPNs
The files used by each of the VPN providers can be overridden by files that exist in the userdata path in order to update them with the new connection information, or to change the behaviour in some way.
These file overrides will persist across updates and may prevent you from automatically picking up any updates that are made within the add-on.
User versions of the files must be in the userdata path, in the right directory, with the same name as the provider directory, and they must have an identical name.
You must reset the VPN provider for any changes in the userdata path to be recognised.
If you change any of these files and deviate from the supplied files, then you're on your own regarding debugging any issues that arise.
No .ovpn files will be overridden. For most providers these are generated using a combination of the TEMPLATE.txt and LOCATIONS.txt files, but also any .ovpn files that are static will also not be overridden.
Files that are managed by the add-on will not be overridden. The are the files related to user authentication, i.e. pass.txt, user.key, user.crt, user,txt.
The authentication requirements of a provider can also not be changed. If a provider is asking for user name/password or one or more key/certs, then you cannot change this by overriding any files.
The LOCATIONS.txt file is the file that has details on each of the different VPN connections that are available to the user. Changing this file allows you to alter the set of connections that you have available, and the domain name or IP address being used.
Unlike other userdata path files, if an alternative LOCATIONS.txt file is found then rather than just overridding the default connections profile, an additional connections profile will be offered up during the connection sequence. The userdata version must still be called 'LOCATIONS.txt', but it will appear in the connections profile list as 'User' rather than 'Default' (or any other options that may exist).
This file has a strict format (it's machine generated) and the parsing has minimal error checking. If you do change it, you need to stick to the format rigidly and be careful that you don't introduce errors.
Each line in the file represents a connection via comma separated tuple in the following format:
Display Name, DNS or IP, Protocol (UDP or TCP), Port[, 0 to n tags]
There can be multiple DNS or IP values separated by a space, but there must be an identical number of Port values, also separated by a space.
Tags can be used to alter the generation of an .ovpn file from the TEMPLATE.txt file. These aren't really designed to be human consumable so if you want to mess with these you can view the code in the add-on libs/vpnproviders.py file and compare the different TEMPLATE.txt and LOCATIONS.txt files across the different providers to get a feel for how these are used and what's supported. I don't anticipate there being a need to great change these so I'm not going to document them here.
If the LOCATIONS.txt file fails to parse then you'll see an error during the generation of the .ovpn files on the first connection attempt and you'll have to turn on debug and go and look at the log for clues.
The TEMPLATE.txt file is the file that's used in conjunction with LOCATIONS.txt to generate all of the .ovpn files that are needed. It's basically an .ovpn file that goes through some post processing to remove tags. You can add or remove openvpn parameters to this file but you should pay attention to the tags within it and how it relates to the LOCATIONS.txt file contents.
During the processing of this file some additional tags may also be added as driven by the openvpn options. These include the parameters related to the up and down scripts, block-outside-dns on Windows and ping connection parameters. If you want to avoid the this, then disable the behaviour within the GUI and update your TEMPLATE.txt file as needed.
In some cases you might just want to add some specific openvpn options to either a downloaded TEMPLATE.txt or .ovpn file. This approach can be better than creating an alternative TEMPLATE.txt because it will still allow updates to be applied when they're made available. This can be done by creating an APPEND.txt with the openvpn parameters you want to add. When TEMPLATE.txt or .ovpn files are downloaded or created, the APPEND.txt file will be added to the end of those files.
As with the alternative TEMPLATE.txt just above, you should be aware of the additional tags that can be added, and disable any undesirable behaviour within the GUI.
The ca, tls-auth, crl-verify and da parameters found in the TEMPLATE.txt files are updated to use the files supplied by the add-on. These files can all be overridden using a file with the same name in the userdata path. A typical use for this function would be if a provider changes a certificate or key that's supplied by default with the add-on. The user can put the new certificate or key in the userdata path and the add-on will use it without needing an update.