Probe

This repo contains the application source for https://probe.sh, a web service for testing WireGuard® connectivity built by the team behind Firezone.

How it works

1. When the Probe application boots, it starts an Elixir gen_udp server for each WireGuard listen port defined in config.exs to listen for incoming UDP payloads on that port.
2. When a user visits the app, Probe starts a Phoenix LiveView process and generates a unique cryptographic token to use for the test.
3. When the user runs the script shown, it first sends a request to start the test, followed by a series of UDP payloads, and finally either a complete or cancel request to end the test.
4. The gen_udp receives these payloads, and if they match one of the four WireGuard message types, it broadcasts test updates to the LiveView process for that test.
5. The user is immediately shown the results of the test.

Contents of this repository

• apps/probe: Phoenix application for the Probe service
• priv/static/scripts: OS-specific scripts for running the Probe tests, designed to be launched from the web app UI.
• config: Configuration settings for various environments. You can add and remove more ports for testing in the config.exs file.
• docker-compose.yml: Docker Compose file to start required services for local development.
• fly.toml: Fly.io configuration file for deploying the Probe app.
• Dockerfile: Dockerfile for building the Probe app image to run on Fly.io.

Contributing to Probe

We welcome any and all contributions to Probe. Before you invest a lot of time into a pull request, however, we recommend opening an issue to discuss the proposed changes. For small fixes, feel free to open a pull request directly.

Local development

You'll need the following pre-requisites to run Probe locally:

1. Docker + Docker Compose for your platform. Docker Desktop should work just fine.
2. We use asdf to manage runtime versions for this repository. You can install asdf with brew install asdf on macOS.
3. Install required asdf plugins with asdf plugin add erlang elixir nodejs.
4. Install the required versions of Erlang, Elixir, and Node.js with asdf install in the root of this repository.
5. Install frontend dependencies with pnpm i --prefix assets.
6. Setup remaining dependencies with mix setup.

You're now ready to start a local development environment:

1. docker compose up -d to start the required services (PostgreSQL)
2. Start Phoenix endpoint with mix phx.server or inside IEx with iex -S mix phx.server

Now you can visit localhost:4000 from your browser to see the Probe service running locally.

To add or remove ports to use for testing, see config/config.exs. Note that you'll need to start the probe service with a privileged user (or with CAP_NET_BIND_SERVICE capabilities on Linux) to bind to ports below 1024.

Deployment

The Firezone team deploys Probe to Fly.io using the Fly.io CLI.

You're welcome to deploy Probe to your own infrastructure for non-commercial purposes.

Security policy

See SECURITY.md

FAQ

See https://probe.sh/faq

License

See LICENSE

Attribution

WireGuard is a registered trademark of Jason A. Donenfeld.