Troubleshooting
===============

This document contains some useful debug information.

OSX
---
If you're having troubles with old versions of RiseupVPN that did not have an
uninstaller, and the new installer is not cleanly replacing the previous
install, you might need to manually clean things up. You will need root access to
stop the privileged helper.

First, see if the helper is running:

.. code:: bash

  pgrep bitmask-helper

To stop it:

.. code:: bash

  sudo launchctl unload /Library/LaunchDaemons/se.leap.bitmask-helper.plist

To start it:

.. code:: bash

  sudo launchctl load /Library/LaunchDaemons/se.leap.bitmask-helper.plist
  sudo launchctl start /Library/LaunchDaemons/se.leap.bitmask-helper.plist

Check that it's running:

.. code:: bash

  pgrep bitmask-helper

Manually check that the web api is running, and that it reports a version that matches what you currently have installed:

.. code:: bash

  curl http://localhost:7171/version

Also, you can check that the path near the end of the file /Library/LaunchDaemons/se.leap.bitmask-helper.plist
matches the current path where you installed RiseupVPN.app.

Cleaning up
~~~~~~~~~~~
If you have things messed up and you want to completely delete the bitmask-helper:

.. code:: bash

  sudo launchctl unload /Library/LaunchDaemons/se.leap.bitmask-helper.plist
  sudo rm -rf /Library/LaunchDaemons/se.leap.bitmask-helper.plist

Make sure that "pgrep bitmask-helper" does not return any pid.

Now you can move /Applications/RiseupVPN.app to the Trash, and launch a
recent installer to get a clean install.

Firewall
~~~~~~~~

In the unfortunate event that a crash lets you with a non-usable connection, you can restore the firewall by hand:

.. code:: bash

  # if you see drop ... <bitmask_gateways>, the fw is on
  sudo pfctl -a com.apple/250.BitmaskFirewall -sr
  # clean it up!
  sudo pfctl -a com.apple/250.BitmaskFirewall -F all

Windows
-------
In Windows you can use PowerShell to see if there's an old service Running (it
can be from RiseupVPN, CalyxVPN, LibraryVPN etc...).

.. code:: powershell

  PS C:\Users\admin> Get-Service bitmask-helper-v2

You can also stop it (needs admin)

.. code:: powershell

  PS C:\Users\admin> Stop-Service bitmask-helper-v2

To force logging:

.. code:: bash

  QT_FORCE_STDERR_LOGGING=1 ./riseup-vpn.exe

We should probably restrict this to non-release versions only.

Environment Variables
~~~~~~~~~~~~~~~~~~~~~

The envs are only used for debugging and developing. The envs affecting the logging behavior are documented in the logging section in the `README <https://0xacab.org/leap/bitmask-vpn/-/blob/main/README.md?ref_type=heads#logging>`_.

- ``SKIP_VERSION_CHECK``: Do not check if there is an update available
- ``LEAP_DRYRUN``: Don't route traffic over VPN (run openvpn with "--pull-filter ignore route" argument) and do not touch firewall rules
- ``MOTD_URL``: Overwrite the MOTD (message of the day) url
- ``SNAP``: If not empty, we expect to be in a Snap environment (client was installed by Snap)
- ``UDP``: If we use UDP, UDP is set to 1. If we use TCP, UDP is set to 0. The value is read by the bitmask-root helper which sets firewall rules on Linux
- ``LEAP_PROVIDER``: Select the provider to use. Must be one of the providers listed in ``gui/providers/providers.json``. File is generated by the Makefile which runs ``./branding/scripts/gen-providers-json``

obfs4
~~~~~

- ``LEAP_PRIVATE_BRIDGE_CERT``: Specify the cert string for the obfs4 bridge to be used
- ``LEAP_PRIVATE_BRIDGE``: Specify the host:port for the obfs4 bridge to be used

Only implemented in v3/vpnweb:
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- ``LEAP_GW``: Specify the gateway hostname to connect with. It needs to be one of the gateway returned by vpnweb
- ``LEAP_OPENVPN_EXTRA_CONFIG``: Specify a file with extra OpenVPN arguments to use. File should be in json format (in key value format like {"--dev": "tun"} or {"--persist-key": true})
- ``LEAP_KCP``: Enforce the use of KCP in obfsvpn
