{"id":37228023,"url":"https://github.com/linakis/luci-app-mullvad","last_synced_at":"2026-01-15T03:25:33.103Z","repository":{"id":331830812,"uuid":"1119944634","full_name":"linakis/luci-app-mullvad","owner":"linakis","description":"A LuCI web application for OpenWrt that provides a user-friendly interface to manage Mullvad WireGuard VPN server selection and monitor connection status.","archived":false,"fork":false,"pushed_at":"2026-01-11T10:12:52.000Z","size":455,"stargazers_count":0,"open_issues_count":1,"forks_count":1,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-01-11T14:25:15.081Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/linakis.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2025-12-20T06:43:05.000Z","updated_at":"2026-01-11T10:12:55.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/linakis/luci-app-mullvad","commit_stats":null,"previous_names":["linakis/luci-app-mullvad"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/linakis/luci-app-mullvad","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linakis%2Fluci-app-mullvad","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linakis%2Fluci-app-mullvad/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linakis%2Fluci-app-mullvad/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linakis%2Fluci-app-mullvad/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/linakis","download_url":"https://codeload.github.com/linakis/luci-app-mullvad/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/linakis%2Fluci-app-mullvad/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28442270,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-15T00:55:22.719Z","status":"online","status_checked_at":"2026-01-15T02:00:08.019Z","response_time":62,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-15T03:25:32.515Z","updated_at":"2026-01-15T03:25:33.096Z","avatar_url":"https://github.com/linakis.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# LuCI Mullvad WireGuard Manager\n\nA LuCI web application for OpenWrt that provides a user-friendly interface to manage Mullvad WireGuard VPN server selection and monitor connection status.\n\n![Mullvad WireGuard Manager Interface](screenshots/mullvad-manager-ui.png)\n\n## 📦 Installation\n\n### Download Pre-built Package\n\n**[Download the latest release](https://github.com/linakis/luci-app-mullvad/releases/latest)** - Ready-to-install IPK package for all OpenWrt routers.\n\n### Quick Installation\n\nInstall dependencies and the package on your router:\n\n```bash\n# Install dependencies\nopkg update\nopkg install luci-base luci-proto-wireguard wireguard-tools curl jsonfilter\n\n# Download and install the package\ncd /tmp\nwget https://github.com/linakis/luci-app-mullvad/releases/latest/download/luci-app-mullvad_1.0.0_all.ipk\nopkg install luci-app-mullvad_1.0.0_all.ipk\n\n# Restart services\n/etc/init.d/rpcd restart \u0026\u0026 /etc/init.d/uhttpd restart\n```\n\nThen access the application at **Services → Mullvad WireGuard** in your router's LuCI interface.\n\n## Features\n\n- **Server Selection**: Browse and select from all available Mullvad WireGuard servers\n- **Connection Status**: Real-time display of connection status, handshake time, and transfer statistics\n- **Server List Caching**: Optional local caching with configurable TTL to reduce API calls\n- **Manual Refresh**: Update server list on-demand from Mullvad's API\n- **Safe Configuration**: Changes are staged and require explicit confirmation before applying\n- **Status Monitoring**: Shows current endpoint, last handshake, and data transfer metrics\n- **Auto-Detection**: Automatically detects your WireGuard interface name on first run\n\n## Prerequisites\n\n### Required Packages\n- `luci-base`\n- `luci-proto-wireguard`\n- `wireguard-tools`\n- `curl`\n- `jsonfilter`\n\n### Existing WireGuard Configuration\nThis app assumes you already have a working Mullvad WireGuard configuration in `/etc/config/network` with:\n- A WireGuard interface (the app will auto-detect it, or defaults to `MullvadWG`)\n- An associated peer section\n- Your Mullvad account's private key configured\n\nThe app will update the peer's public key and endpoint when switching servers.\n\n### Setting Up Mullvad WireGuard (If Not Already Configured)\n\nIf you haven't set up Mullvad WireGuard on OpenWrt yet, follow the official guides:\n\n**Official Mullvad Guides:**\n- [WireGuard on a Router](https://mullvad.net/en/help/running-wireguard-router/) - Complete WireGuard setup for routers including OpenWrt\n- [OpenWrt Routers and Mullvad VPN](https://mullvad.net/en/help/openwrt-routers-and-mullvad-vpn) - General OpenWrt guide (OpenVPN-focused but has useful background)\n\n**Quick Setup Summary:**\n1. Install packages: `luci-proto-wireguard`, `wireguard-tools`\n2. Generate WireGuard keys: `wg genkey | tee privatekey | wg pubkey \u003e publickey`\n3. Get your Mullvad IP address from the API with your account number and public key\n4. Configure the WireGuard interface in LuCI (Network → Interfaces)\n5. Install this app to easily manage server selection\n\n## Advanced Installation\n\n### Manual Installation (Development/Testing)\n\nThis method works without downloading packages. All files are scripts and configs that work as-is.\n\n1. **Copy files to your router**:\n```bash\nscp -r luci-app-mullvad root@\u003crouter-ip\u003e:/root/\n```\n\n2. **SSH into your router**:\n```bash\nssh root@\u003crouter-ip\u003e\n```\n\n3. **Install the application** (on the router):\n```bash\ncd /root/luci-app-mullvad\ncp -r root/* /\ncp -r htdocs/* /www/\n\n# Make scripts executable\nchmod +x /usr/bin/mullvad-fetch-servers.sh\nchmod +x /usr/bin/mullvad-apply-server.sh\nchmod +x /usr/bin/mullvad-get-status.sh\n\n# Fix file permissions\nchmod 644 /usr/share/rpcd/acl.d/luci-app-mullvad.json\nchmod 644 /usr/share/luci/menu.d/luci-app-mullvad.json\nchmod 644 /etc/config/mullvad\nchmod 644 /www/luci-static/resources/view/mullvad/manager.js\n\n# Fix directory permissions\nchmod 755 /www/luci-static/resources/view/mullvad\n```\n\n4. **Initialize configuration** (on the router):\n```bash\nuci commit mullvad\n```\n\n5. **Restart services** (on the router):\n```bash\n/etc/init.d/rpcd restart\n/etc/init.d/uhttpd restart\n```\n\n6. **Verify installation** (optional):\n```bash\n# Check that scripts are executable\nls -la /usr/bin/mullvad-*.sh\n\n# Check that all files have correct permissions\nls -la /usr/share/rpcd/acl.d/luci-app-mullvad.json\nls -la /usr/share/luci/menu.d/luci-app-mullvad.json\nls -la /etc/config/mullvad\nls -la /www/luci-static/resources/view/mullvad/manager.js\n\n# Test the fetch script\n/usr/bin/mullvad-fetch-servers.sh\n```\n\n7. **Access the application**:\n   - Navigate to your router's LuCI interface (e.g., http://10.0.0.1)\n   - Go to **Services → Mullvad WireGuard**\n\n## Usage\n\n### Accessing the Interface\n\n1. Open your router's LuCI web interface\n2. Navigate to **Services → Mullvad WireGuard**\n\n### Switching Servers\n\n1. **View Current Status**: The status section shows your current connection state\n2. **Refresh Server List** (optional): Click \"Refresh Server List\" to get the latest servers from Mullvad\n3. **Select Server**: Choose a server from the dropdown list\n   - Servers are displayed in the format: **Country - City - Hostname (Provider)**\n   - The list is sorted alphabetically by country, then city, then hostname\n   - Mullvad-owned servers are labeled as \"(Mullvad Owned)\"\n4. **Apply Server**: Click \"Apply Selected Server\" to switch to the new server\n5. **Confirm Change**: A confirmation dialog will show the server details before applying\n6. **Verify Connection**: Status will update within 30 seconds showing the new server\n\n### Configuration Options\n\n#### Cache Settings\n- **Enable Caching**: Store server list locally to reduce API calls\n- **Cache TTL**: Set how long cached data remains valid (default: 24 hours)\n- **WireGuard Interface**: Specify which interface to manage (auto-detected, or defaults to `MullvadWG`)\n\n## Configuration for Different Interface Names\n\nThe app automatically detects your WireGuard interface on first run. However, if you need to manually configure it:\n\n### Auto-Detection (Recommended)\n\nThe app will automatically detect your WireGuard interface by:\n1. Looking for interfaces with `proto=wireguard` in `/etc/config/network`\n2. Checking for an associated peer section following the pattern `wireguard_\u003cInterfaceName\u003e`\n3. Saving the detected interface name to `/etc/config/mullvad` for future use\n\nNo manual configuration needed in most cases!\n\n### Manual Configuration\n\nIf auto-detection doesn't work or you want to specify a different interface:\n\n1. **Check your current WireGuard interface name:**\n   ```bash\n   wg show  # Shows all WireGuard interfaces\n   uci show network | grep \"proto='wireguard'\"  # Shows UCI config\n   ```\n\n2. **Set the interface name manually:**\n   ```bash\n   uci set mullvad.config.wireguard_interface='YOUR_INTERFACE_NAME'\n   uci commit mullvad\n   ```\n\n3. **Restart LuCI:**\n   ```bash\n   /etc/init.d/uhttpd restart\n   ```\n\n### Examples\n\nFor an interface named `wg0`:\n```bash\nuci set mullvad.config.wireguard_interface='wg0'\nuci commit mullvad\n```\n\nFor the Mullvad guide's recommended name `WGINTERFACE`:\n```bash\nuci set mullvad.config.wireguard_interface='WGINTERFACE'\nuci commit mullvad\n```\n\n## Backend Scripts\n\n### mullvad-fetch-servers.sh\nFetches the server list from Mullvad's API (`https://api.mullvad.net/app/v1/relays`) and caches it locally.\n\n**Usage**:\n```bash\n/usr/bin/mullvad-fetch-servers.sh\n```\n\n**Output**: `/tmp/mullvad_servers.json`\n\n### mullvad-apply-server.sh\nUpdates the WireGuard peer configuration with a new server's details.\n\n**Usage**:\n```bash\n/usr/bin/mullvad-apply-server.sh \u003chostname\u003e \u003cpublic_key\u003e \u003cendpoint_ip\u003e \u003cendpoint_port\u003e\n```\n\n**Example**:\n```bash\n/usr/bin/mullvad-apply-server.sh gr-ath-wg-102 \"server_public_key\" \"185.213.154.68\" \"51820\"\n```\n\n### mullvad-get-status.sh\nRetrieves current WireGuard connection status and formats it as JSON.\n\n**Usage**:\n```bash\n/usr/bin/mullvad-get-status.sh\n```\n\n**Output**: JSON with connection status, endpoint, handshake time, and transfer statistics\n\n## Configuration\n\n### UCI Configuration File: `/etc/config/mullvad`\n\n```\nconfig settings 'config'\n    option cache_enabled '1'                   # Enable/disable caching\n    option cache_ttl '86400'                   # Cache TTL in seconds (24 hours)\n    option auto_refresh_enabled '0'            # Reserved for future use\n    option wireguard_interface 'MullvadWG'     # WireGuard interface name\n    option last_fetch '0'                      # Timestamp of last API fetch\n\nconfig cache 'servers'\n    option data ''                             # Cached server list (JSON)\n    option timestamp '0'                       # Cache timestamp\n```\n\n### Network Configuration Changes\n\nWhen you switch servers, the app updates `/etc/config/network`:\n\n**Before**:\n```\nconfig wireguard_MullvadWG\n    option description 'se-sto-wg-101'\n    option public_key 'old_server_public_key'\n    option endpoint_host '185.65.134.66'\n    option endpoint_port '51820'\n```\n\n**After**:\n```\nconfig wireguard_MullvadWG\n    option description 'gr-ath-wg-102'\n    option public_key 'new_server_public_key'\n    option endpoint_host '185.213.154.68'\n    option endpoint_port '51820'\n```\n\n## Troubleshooting\n\n### Server list won't load\n1. Check internet connectivity: `ping api.mullvad.net`\n2. Verify curl is installed: `opkg list-installed | grep curl`\n3. Manually test API: `/usr/bin/mullvad-fetch-servers.sh`\n4. Check logs: `logread | grep mullvad`\n\n### Changes don't apply\n1. Verify scripts are executable: `ls -l /usr/bin/mullvad-*.sh`\n2. Check UCI permissions: `uci show mullvad`\n3. Verify network configuration: `uci show network | grep -A5 MullvadWG`\n4. Check WireGuard status: `wg show MullvadWG`\n\n### Connection shows as disconnected\n1. Verify WireGuard interface is up: `ifstatus MullvadWG`\n2. Check recent handshake: `wg show MullvadWG latest-handshakes`\n3. Test network connectivity: `ping -I MullvadWG 1.1.1.1`\n4. Verify firewall rules allow WireGuard traffic\n\n### LuCI menu doesn't show the app\n1. Restart LuCI: `/etc/init.d/uhttpd restart`\n2. Clear browser cache\n3. Verify menu file exists: `ls /usr/share/luci/menu.d/luci-app-mullvad.json`\n4. Check ACL permissions: `cat /usr/share/rpcd/acl.d/luci-app-mullvad.json`\n\n### Permission denied errors\n1. Ensure scripts are executable: `chmod +x /usr/bin/mullvad-*.sh`\n2. Verify ACL file is present and valid\n3. Check rpcd is running: `/etc/init.d/rpcd status`\n4. Restart rpcd: `/etc/init.d/rpcd restart`\n\n## Security Considerations\n\n- **Private Key Protection**: Your Mullvad private key is never exposed or modified by this app\n- **ACL Restrictions**: The app uses minimal permissions (UCI access for network/mullvad configs only)\n- **Input Validation**: All scripts validate inputs to prevent command injection\n- **HTTPS Only**: Always access LuCI over HTTPS in production environments\n- **API Security**: Server list is fetched over HTTPS from Mullvad's official API\n\n## Technical Details\n\n### Interface Auto-Detection\n\nOn first run or when not configured, the app automatically detects your WireGuard interface:\n\n1. **Searches for WireGuard interfaces** with `proto=wireguard` in `/etc/config/network`\n2. **Validates the interface** by checking for an associated peer section (`wireguard_\u003cInterfaceName\u003e`)\n3. **Saves the detected name** to `/etc/config/mullvad` for future use\n4. **Falls back to `MullvadWG`** if auto-detection fails\n\nThis ensures compatibility with any WireGuard interface name, whether you followed Mullvad's official guide (using `WGINTERFACE`) or chose your own naming convention.\n\n### How Server Switching Works\n\n1. User selects a server in the UI\n2. JavaScript calls backend script with server details\n3. `mullvad-apply-server.sh` updates UCI network configuration\n4. Script commits changes but doesn't reload network immediately\n5. LuCI's save/apply mechanism triggers network reload\n6. WireGuard interface reconnects to the new server\n7. Status display updates with new endpoint information\n\n### Connection Status Detection\n\nConnection is considered active when:\n- WireGuard interface is up\n- Peer endpoint is configured\n- Last handshake occurred within 3 minutes\n\n### Data Flow\n\n```\nMullvad API → fetch script → /tmp/cache → UCI config → JavaScript UI\n                                                              ↓\nUser Selection → apply script → UCI network config → network reload\n                                      ↑\n                            Auto-detect interface (first run)\n```\n\n## API Reference\n\n### Mullvad API Endpoint\n```\nGET https://api.mullvad.net/app/v1/relays\n```\n\nReturns a list of all Mullvad relay servers including WireGuard configurations.\n\n## Contributing\n\nWhen modifying this application:\n1. Test all changes on a development router first\n2. Verify ACL permissions are minimal and appropriate\n3. Ensure backward compatibility with existing configurations\n4. Update this README with any new features or changes\n\n## License\n\nThis is a custom application for managing Mullvad WireGuard configurations on OpenWrt routers.\n\n## Version History\n\n- **1.0.0** - Initial release\n  - Server selection and switching\n  - Connection status monitoring\n  - Country/city filtering\n  - Server list caching\n  - Manual refresh capability\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinakis%2Fluci-app-mullvad","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Flinakis%2Fluci-app-mullvad","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Flinakis%2Fluci-app-mullvad/lists"}