Riseup OpenVPN

Overview

riseup-openvpn.sh is a POSIX-compatible shell script that generates and manages OpenVPN profiles for Riseup’s LEAP VPN service using Riseup’s official JSON endpoints.

The script automates:

• Retrieval and validation of the Riseup CA certificate
• Retrieval and reuse of client certificates
• Gateway discovery and selection
• OpenVPN profile generation
• Foreground and background VPN connections

It is designed to be safe, predictable, and transparent, following traditional Unix CLI conventions.

Features

• Generate OpenVPN profiles from Riseup LEAP JSON endpoints
• Random or constrained gateway selection
• Reuse valid client certificates automatically
• Verify CA certificate validity and expiration
• Foreground (Ctrl+C to disconnect) and background VPN connections
• Safe background disconnect using PID tracking
• Fully POSIX sh compatible (no Bash-specific features)

Usage

./riseup-openvpn.sh [OPTIONS]

Options

General

• --help, -h
  Show the help message and exit

• --status, -s
  Show CA certificate, client certificate, and profile status

• --check-deps
  Check required external dependencies and exit

Profile generation

• --force, -f
  Force regeneration of the OpenVPN profile

• --port=PORT
  Require a specific OpenVPN port (e.g. 1194)

• --protocol=PROTO
  Require a specific OpenVPN protocol (tcp or udp)

• --gateway=GW
  Require a specific gateway (hostname or IP)

Certificate management

• --refresh-ca
  Force re-download of the CA certificate

• --refresh-client-cert
  Force refresh of the client certificate
  Warning: Repeated requests to Riseup’s certificate endpoint may result in rate limiting or bans. Use sparingly.

Connection management

• --connect
  Launch OpenVPN in the foreground (Ctrl+C disconnects)

• --connect-bg
  Launch OpenVPN in the background
  Creates a PID file for safe disconnection

• --disconnect
  Disconnect background OpenVPN started with --connect-bg

Discovery helpers

• --list-gateways
  List available OpenVPN gateways with ports and protocols

• --list-ports
  List all OpenVPN ports used by any gateway
  (Note: not all gateways support all ports)

• --list-protocols
  List all OpenVPN protocols used by any gateway
  (Note: not all gateways support all protocols)

• --list-profiles
  List generated OpenVPN profile files

Behavior

• If a valid client certificate already exists, it is reused
• OpenVPN profiles are regenerated only when necessary
• Constraint flags (--port, --protocol, --gateway) are combined using AND logic
• If no gateways match the constraints, an error is printed
• Only OpenVPN transports are supported (obfs4 is ignored)

Requirements

To use riseup-openvpn.sh, the following software and system requirements must be met.

Operating system

• A Unix-like operating system (Linux, BSD, macOS, or similar)
• A POSIX-compliant /bin/sh (bash ≥ 3.2, zsh ≥ 5.0, dash ≥ 0.5.8)

The script avoids Bash-specific features and should work with common POSIX shells such as dash, ash, or ksh.

Required tools (must be installed and available in PATH)

• OpenVPN 2.4+ - Required to establish VPN connections using the generated profiles.
• curl 7.29+ - Used to retrieve configuration data, certificates, and metadata from Riseup’s official endpoints over HTTPS.
• jq 1.5+, 1.6 recommended - A command-line JSON processor used to parse and filter Riseup’s configuration and metadata responses. On PowerPC it does not work with Macports’ provided jq 1.8+, only 1.6.
• openssl 1.0.2+, LibreSSL supported - Used to inspect certificate validity and verify certificate fingerprints.

Permissions

• Root privileges are required only when launching OpenVPN (--connect or --connect-bg).
• All other operations (profile generation, listing, status checks) can be performed as an unprivileged user.

Network requirements

• HTTPS access to the following Riseup endpoints must be available:
  • https://api.black.riseup.net
  • https://riseup.net
• Firewalls or captive portals must allow outbound HTTPS traffic for initial configuration and certificate retrieval.

Optional but recommended

• A modern terminal emulator with UTF-8 support (for clean status output)
• A fixed-width font for best readability

Examples

Generate a profile using a random OpenVPN gateway:

./riseup-openvpn.sh

Force regeneration of the OpenVPN profile:

./riseup-openvpn.sh --force

Use a specific OpenVPN port:

./riseup-openvpn.sh --port=1194

Use UDP over port 1194:

./riseup-openvpn.sh --protocol=udp --port=1194

Use a specific gateway:

./riseup-openvpn.sh --gateway=vpn01-sea.riseup.net

Check certificate and profile status:

./riseup-openvpn.sh --status

Launch OpenVPN in the foreground:

sudo ./riseup-openvpn.sh --connect

Launch OpenVPN in the background and disconnect later:

sudo ./riseup-openvpn.sh --connect-bg
sudo ./riseup-openvpn.sh --disconnect

Notes

• Only OpenVPN gateways are supported
• Obfs4 transports are ignored
• Root privileges are required only when launching OpenVPN
• The script does not interfere with system-managed OpenVPN instances

License

This project was written by främling <http://framling.org> and is licensed under the GNU General Public License version 3 (or any later version).

See the LICENSE file for details.

Downloads

• Latest release:
  • riseup-openvpn-1.0.0.tar.gz
  • riseup-openvpn-1.0.0.zip

FAQ — Frequently Asked Questions

--refresh-client-cert

./riseup-openvpn.sh --refresh-client-cert

--port=443 --protocol=tcp

--list-gateways

Useful links

• Riseup — Official site - https://riseup.net

The home of the Riseup Collective, a volunteer-run organization providing secure, privacy-focused online services including email, mailing lists, collaborative tools, and VPN access. Their philosophy centers on supporting digital security for people and projects involved in social change.

• Riseup VPN (LEAP) - https://riseup.net/en/vpn

The official documentation and overview page for Riseup’s VPN service (also known as LEAP). This resource explains the purpose of the VPN, which is protecting network traffic from surveillance and censorship, and provides general information about its capabilities and limitations.

• EIP service configuration (JSON) - https://api.black.riseup.net/3/config/eip-service.json

A machine-readable endpoint used by this script to retrieve up-to-date VPN configuration information, such as available gateways, supported ports, and protocols. Using this JSON avoids hard coding server details and enables automatic profile generation.

• Provider metadata (JSON) - https://riseup.net/provider.json

Riseup’s provider metadata endpoint, which includes the URI for the CA certificate and its expected fingerprint. This data enables secure CA retrieval and verification within the script without embedding fixed URLs or fingerprints.

• Client certificate endpoint - https://api.black.riseup.net/3/cert

The API endpoint used to obtain a new client certificate and private key for LEAP authentication. This script fetches credentials from this endpoint when none exist locally or when a refresh is forced.

• Riseup Canary Statement (Transparency) - https://riseup.net/en/canary

Riseup’s warrant canary statement, a transparency mechanism meant to indicate whether the organization has received secret government orders (e.g., National Security Letters) requiring silence. The presence and regular update of the canary help users gauge whether Riseup’s infrastructure has been compelled to disclose information.

• Riseup Privacy Policy - https://riseup.net/en/privacy-policy

The official privacy policy detailing what data Riseup collects, retains, and avoids retaining. It outlines their approach to handling user information, emphasizing minimal data retention and strong privacy guarantees.

• OpenVPN: Official protocol and software - https://openvpn.net

The project site for OpenVPN, the underlying VPN protocol and client used by profiles generated with this script. Provides documentation on OpenVPN configuration options, security considerations, and client software downloads.

Security considerations

Riseup’s VPN aims to minimize logging and protect user traffic, but like any VPN provider, the service operator can potentially see some metadata. A VPN primarily protects traffic between the client and the VPN gateway, but it does not provide anonymity beyond that gateway, destinations on the internet can still see traffic unless encrypted end-to-end.

While Riseup publishes warrant canary statements and a privacy policy, transparency practices can vary. Users concerned about legal compliance and surveillance should review these resources directly and consider how they align with their threat model.

Read the OpenVPN documentation for protocol security and configuration best practices.

If you are operating in a high-risk or adversarial environment, you should:

• manually verify CA certificates out-of-band
• review the script before execution
• avoid automatic certificate refreshes without understanding their implications

Security-sensitive users should always apply defense-in-depth.

Disclaimer

This project is not affiliated with, endorsed by, or maintained by Riseup.

The script interacts exclusively with publicly documented Riseup endpoints to retrieve configuration data and certificates for the LEAP VPN service. All information is fetched directly from Riseup’s infrastructure without modification.

While care is taken to verify certificates and metadata where possible, the correctness, availability, and consistency of the data returned by Riseup’s services are outside the control of this project.

Use of this script is entirely at your own discretion.

Warning: CA certificate fingerprint mismatch

./riseup-openvpn.sh
[ ] Downloading CA certificate
[✗] CA certificate fingerprint mismatch!
		Expected:  A5244308A1374709A9AFCE95E3AE47C1B44BC2398C0A70CCBF8B3A8A97F29494
		Actual:   DD919B7513B4A1368FAA20E38CD3314156805677F48B787CDD9B4A92DEC64EB0
[✗] WARNING: CA fingerprint does not match provider.json
		Continuing anyway because Riseup metadata is inconsistent
		This may be fixed upstream in the future
[✓] CA certificate downloaded

In some cases, users may observe a SHA-256 fingerprint mismatch between:

• the CA certificate retrieved from Riseup’s VPN endpoint, and
• the fingerprint advertised in Riseup’s provider metadata (provider.json).

This situation is not caused by this script.

What this means:

• The script verifies the CA certificate fingerprint using Riseup’s own published metadata.
• If the fingerprint differs, it indicates that Riseup is serving a CA certificate that does not match the fingerprint currently published in their metadata.

This can happen during:

• certificate rotation
• transitional deployments
• delayed metadata updates

What this script does:

• The script detects and reports the mismatch clearly.
• No fingerprint values are hardcoded or overridden.
• The script does not attempt to guess which certificate is “correct”.

What users should do:

• Do not ignore fingerprint mismatches blindly.
• Verify the situation independently using Riseup’s official communication channels if concerned.
• Monitor Riseup’s documentation or announcements for certificate updates.

You can manually compare the fingerprints by downloading Riseup’s CA certificate and using OpenSSL on it. This will output the SHA 256 fingerprint of the certificate.

openssl x509 -noout -fingerprint -sha256 -in ca.crt
sha256 Fingerprint=DD:91:9B:75:13:B4:A1:36:8F:AA:20:E3:8C:D3:31:41:56:80:56:77:F4:8B:78:7C:DD:9B:4A:92:DE:C6:4E:B0

The published Riseup CA certificate fingerprint value can be found in the official provider.json file, and it currently resides in the ca_cert_fingerprint key with the value SHA256: a5244308a1374709a9afce95e3ae47c1b44bc2398c0a70ccbf8b3a8a97f29494.

Therefore, it’s a mismatch.

This script cannot resolve or correct inconsistencies in Riseup’s infrastructure or published metadata. Fingerprint mismatches are a service-side issue and must be addressed by Riseup.

Riseup VPN gateways

Gateway data shown below reflects the state of Riseup’s VPN infrastructure as of February 2026, and is generated directly from the official EIP service JSON endpoint.