🛡️ AdGuard VPN — DankMaterialShell Plugin

Control, monitor, and configure AdGuard VPN directly from your DankBar — no terminal needed. Language / Idioma: English is the primary documentation language. A Portuguese (Brazil) version is provided below for the same user-facing guidance.

✨ Features

📋 Requirements

🚀 Installation

Optional systemd-managed tunnel

By default the plugin invokes adguardvpn-cli directly, so it works without extra system services. Advanced setups can set useSystemdService: true in the plugin settings and provide /usr/local/sbin/adguardvpn-dms-control; in that mode connect and disconnect actions delegate the persistent tunnel to a root systemd service rather than leaving it in the DMS cgroup. Keep this opt-in unless the matching service and control wrapper have been installed.

A reference implementation ships in scripts/adguardvpn-dms-control:

sudo install -m 755 -o root -g root \
  scripts/adguardvpn-dms-control /usr/local/sbin/adguardvpn-dms-control

Then grant the desktop user a NOPASSWD sudoers rule for that exact path — the plugin always calls it through sudo -n, so an interactive prompt makes the action fail silently.

Write your own helper? Make connect-fastest and connect-location idempotent. systemctl restart tears the tunnel down for a few seconds: NetworkManager flags the interface as unmanaged, systemd-resolved swaps DNS servers, and every in-flight connection dies with it — downloads, SSH, long HTTP sessions. A helper that restarts unconditionally turns a no-op click ("connect to the location I'm already on") into a real network outage. The reference implementation exits 0 without restarting when the unit is already active and /var/lib/adguardvpn-dms/location already matches the requested target; --force restores the unconditional behaviour for deliberately re-picking a server.

1. Clone into DMS plugins directory

git clone https://github.com/bernardopg/dms-adguard-vpn-plugin.git \
  ~/.config/DankMaterialShell/plugins/adguardVPplugin

2. Reload & enable

dms ipc plugins reload adguardVPplugin
dms ipc plugins enable adguardVPplugin

3. Add to DankBar

Open DMS Settings → Widgets and add AdGuard VPN to your bar.

⚙️ Settings

All settings are configurable through the DMS plugin settings screen.

🏗️ Project Structure

adguardVPplugin/
├── plugin.json                 # Manifest & permissions
├── qmldir                      # QML singleton registration
├── AdGuardVpnWidget.qml        # Bar pill + popout UI
├── AdGuardVpnSettings.qml      # DMS settings screen
├── AdGuardVpnService.qml       # Singleton: polling, actions, state
├── AdGuardVpnParsers.js        # CLI output parsers (status, config, license, locations)
├── AdGuardVpnI18n.qml          # Localization singleton
├── i18n/
│   ├── en.js                   # English (fallback)
│   ├── pt_BR.js                # Português (Brasil)
│   ├── es_ES.js                # Espanol
│   ├── zh_CN.js                # Chinese (Simplified)
│   ├── hi_IN.js                # Hindi
│   ├── ar.js                   # Arabic
│   ├── bn_BD.js                # Bengali
│   ├── fr_FR.js                # French
│   ├── de_DE.js                # German
│   ├── ja_JP.js                # Japanese
│   ├── ru_RU.js                # Russian
│   ├── ko_KR.js                # Korean
│   ├── id_ID.js                # Indonesian
│   ├── tr_TR.js                # Turkish
│   ├── vi_VN.js                # Vietnamese
│   ├── it_IT.js                # Italian
│   ├── pl_PL.js                # Polish
│   ├── nl_NL.js                # Dutch
│   ├── fa_IR.js                # Persian
│   ├── th_TH.js                # Thai
│   ├── ur_PK.js                # Urdu
│   ├── ms_MY.js                # Malay
│   └── README.md               # Translation guide
├── scripts/
│   ├── check-i18n-keys.mjs     # i18n key parity checker
│   ├── test-parsers.mjs        # Parser unit tests (status/license/config/locations)
│   ├── lint-markdown.sh        # Markdown linter
│   └── validate-qml.sh         # QML syntax validator
├── docs/
│   ├── ARCHITECTURE.md         # Component design & data flow
│   ├── COMMANDS.md             # CLI command mapping
│   ├── RELEASE_CHECKLIST.md    # Release process
│   └── releases/               # Per-version release notes
├── CHANGELOG.md
├── CONTRIBUTING.md
└── LICENSE                     # MIT

For detailed architecture and data flow, see docs/ARCHITECTURE.md. For the CLI command map, see docs/COMMANDS.md.

🔒 Security & Permissions

The plugin only executes local CLI commands through the DMS process API. No credentials are stored — secrets live in adguardvpn-cli's own config. Network traffic is entirely managed by the CLI itself.

🔍 Troubleshooting

adguardvpn-cli --version

adguardvpn-cli login

dms ipc plugins status  adguardVPplugin
dms ipc plugins reload  adguardVPplugin

💻 Development

Follow the DMS plugin development guide.

Recommended loop:

# edit code…
dms ipc plugins reload adguardVPplugin

Quality checks before committing:

node scripts/check-i18n-keys.mjs   # i18n key parity
node scripts/test-parsers.mjs      # parser unit tests
bash scripts/lint-markdown.sh       # markdown lint
bash scripts/validate-qml.sh       # QML syntax

🌐 Localization

This plugin is now officially multilang and ships with:

• Full locales: English, Português (Brasil)
• Full locales (previously extended with English fallback): Español, 中文 (简体), हिन्दी, العربية, বাংলা, Français, Deutsch, 日本語, Русский, 한국어, Indonesia, Türkçe, Tiếng Việt, Italiano, Polski, Nederlands, فارسی, ไทย, اردو, Bahasa Melayu

Every shipped locale is now fully translated (all 179 message keys). Untranslated strings, if any are added later, fall back to English.

Adding or extending locales is straightforward — see i18n/README.md.

🤝 Contributing

See CONTRIBUTING.md for workflow, quality checks, and release process.

📦 Publishing

Follow the Release Checklist, then:

git tag vX.Y.Z
git push origin main --tags

Submit to the DMS Plugin Registry.

📄 License

MIT — Bernardo Gomes

Português (Brasil)

Controle, monitore e configure o AdGuard VPN diretamente pela DankBar — sem precisar abrir o terminal.

Recursos

Requisitos

Instalação

git clone https://github.com/bernardopg/dms-adguard-vpn-plugin.git \
  ~/.config/DankMaterialShell/plugins/adguardVPplugin

dms ipc plugins reload adguardVPplugin
dms ipc plugins enable adguardVPplugin

Depois, abra DMS Settings → Widgets e adicione AdGuard VPN à barra.

Túnel gerenciado por systemd (opcional)

Por padrão o plugin chama o adguardvpn-cli direto e funciona sem nenhum serviço extra. Configurações avançadas podem ativar useSystemdService: true e fornecer /usr/local/sbin/adguardvpn-dms-control; nesse modo, conectar e desconectar delegam o túnel persistente a um serviço systemd de root em vez de deixá-lo no cgroup do DMS. Há uma implementação de referência em scripts/adguardvpn-dms-control:

sudo install -m 755 -o root -g root \
  scripts/adguardvpn-dms-control /usr/local/sbin/adguardvpn-dms-control

Depois conceda ao usuário do desktop uma regra NOPASSWD no sudoers para esse caminho exato — o plugin sempre chama por sudo -n, então um prompt interativo faz a ação falhar em silêncio.

Vai escrever seu próprio helper? Faça connect-fastest e connect-location serem idempotentes. O systemctl restart derruba o túnel por alguns segundos: o NetworkManager marca a interface como unmanaged, o systemd-resolved troca de servidor DNS e toda conexão em curso morre junto — downloads, SSH, sessões HTTP longas. Um helper que reinicia incondicionalmente transforma um clique que não muda nada ("conectar na localização em que já estou") numa queda de rede real. A implementação de referência sai com 0 sem reiniciar quando a unit já está ativa e /var/lib/adguardvpn-dms/location já corresponde ao destino pedido; --force restaura o comportamento incondicional para reescolher servidor de propósito.

Configurações

Todas as configurações ficam na tela de settings do plugin no DMS.

Segurança e permissões

O plugin executa apenas comandos locais pelo processo do DMS. Credenciais não são armazenadas pelo plugin; elas ficam no próprio adguardvpn-cli.

Solução de problemas

Se o CLI aparecer como indisponível, verifique:

adguardvpn-cli --version

Se usa caminho customizado, atualize adguardBinary nas configurações. Para problemas de sessão, rode adguardvpn-cli login. Para erros de localização, atualize a lista no widget e prefira o rótulo visível cidade, país; use ISO quando quiser deixar o CLI escolher dentro do país.

Desenvolvimento

Loop recomendado:

dms ipc plugins reload adguardVPplugin

Checks antes de commitar:

node scripts/check-i18n-keys.mjs
node scripts/test-parsers.mjs
bash scripts/lint-markdown.sh
bash scripts/validate-qml.sh

Licença

MIT — Bernardo Gomes