AdGuard VPN CLI: установка, настройка и использование из терминала

Что такое AdGuard VPN CLI и кому он нужен

AdGuard VPN CLI — это официальный клиент VPN от компании AdGuard, у которого нет графического интерфейса. Всё управление происходит через терминал, что делает его естественным выбором для пользователей Linux, администраторов серверов и владельцев встраиваемых устройств. Это первый продукт AdGuard, получивший официальную поддержку Linux, хотя позже клиент также стал доступен для macOS и некоторых роутеров.

Основная целевая аудитория — те, кто привык работать с командной строкой и не хочет держать в системе лишние GUI-приложения. Благодаря небольшому размеру и отсутствию зависимостей от графической оболочки, утилита хорошо подходит для одноплатных компьютеров вроде Raspberry Pi и для использования в скриптах автоматизации.

CLI-версия поддерживает те же базовые функции, что и графические аналоги: подключение к серверам в разных странах, выбор протокола, Kill Switch и настройку DNS. Отличие в том, что здесь нет окон с переключателями — всё выполняется командами, а статус соединения отслеживается через вывод утилиты или системные логи.

Установка клиента на Linux и macOS

Процесс установки одинаков для большинства дистрибутивов Linux и для macOS. Разработчики распространяют установочный скрипт, который сам скачивает подходящий бинарный файл и размещает его в системе. Для запуска установки нужно открыть терминал и выполнить:

curl -fsSL https://raw.githubusercontent.com/AdguardTeam/AdGuardVPNCLI/master/scripts/release/install.sh | sh -s — -v

Обратите внимание, что установка производится в системную директорию /opt/adguardvpn_cli/, поэтому могут потребоваться права суперпользователя. В большинстве случаев скрипт сам запросит пароль через sudo, но если вы работаете в окружении без графического входа, убедитесь, что у вас есть права на запись в /opt.

После завершения установки проверьте версию клиента:

adguardvpn-cli --version

Если команда не найдена, возможно, потребуется перелогиниться или добавить путь к бинарнику в переменную окружения PATH. В некоторых дистрибутивах скрипт создаёт символьную ссылку в /usr/local/bin, что автоматически решает проблему.

Авторизация: переход на веб-подход

Ранние версии AdGuard VPN CLI использовали классическую авторизацию по имени пользователя и паролю. Начиная с версии 1.5.10 разработчики изменили механизм входа — теперь применяется веб-аутентификация через браузер. Это повышает безопасность, так как пароль не передаётся через консоль, но добавляет неудобство при первичной настройке, особенно на устройствах без браузера.

Чтобы авторизоваться, выполните команду:

adguardvpn-cli login

Утилита выведет ссылку вида https://auth.adguard.io/device_code?user_code=xxxx. Её нужно открыть в любом браузере на компьютере или смартфоне, подтвердить вход и при необходимости ввести код. После успешного подтверждения клиент автоматически завершит процесс.

Важный нюанс: если у вас включена двухфакторная аутентификация (2FA), в некоторых случаях веб-вход может работать некорректно. В документации проекта это отмечается как известная проблема. Если вы столкнулись с ней, попробуйте временно отключить 2FA на время входа или воспользоваться старой версией клиента.

Подключение и управление локациями

После входа в систему можно подключаться к VPN. Для быстрого старта используйте команду:

adguardvpn-cli connect

Она автоматически выберет либо самую быструю локацию, либо ту, к которой вы подключались в последний раз — это поведение зависит от настроек и версии клиента.

Чтобы увидеть полный список доступных серверов, выполните:

adguardvpn-cli list-locations

Вывод показывает страны и города в читаемом виде. Выбор конкретной точки осуществляется командой:

adguardvpn-cli connect -l HELSINKI

В качестве аргумента можно указывать город, страну или ISO-код. Например, connect -l FI, connect -l Finland и connect -l HELSINKI приведут к подключению к серверу в Хельсинки. Такой гибкий подход удобен для автоматизации, когда имя локации передаётся в скрипт.

Для отключения от VPN выполните:

adguardvpn-cli disconnect

Статус текущего соединения проверяется командой adguardvpn-cli status, которая показывает выбранную локацию, время работы туннеля и объём переданных данных.

Запуск в Docker: изоляция и автоматизация

Для пользователей, предпочитающих контейнеризацию, существует сторонний Docker-образ supersunho/adguardvpn-cli. Он включает клиент AdGuard VPN CLI и позволяет запускать его в изолированном окружении. Это удобно для создания VPN-шлюза для других контейнеров, например, для торрент-клиента qBittorrent.

Базовый пример docker-compose.yml выглядит так:

version: "3"
services:
  adguard-vpn-cli:
    image: supersunho/adguardvpn-cli:latest
    restart: unless-stopped
    container_name: adguard-vpn-cli
    env_file: .env
    volumes:
      - ./data:/root/.local/share/adguardvpn-cli
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun

При первом запуске необходимо проверить логи контейнера, чтобы найти ссылку для веб-авторизации:

docker logs adguard-vpn-cli

После перехода по ссылке и подтверждения входа учётные данные сохраняются в смонтированном томе ./data. При последующих перезапусках авторизация не потребуется, что делает такой подход пригодным для долгоживущих сервисов.

Стоит отметить, что автоматический вход через браузер в контейнере работает с перебоями. Иногда процесс выглядит зависшим, но на самом деле нужно просто подождать несколько секунд после открытия ссылки — клиент сам завершит авторизацию.

Переменные окружения и расширенная конфигурация

Docker-образ поддерживает тонкую настройку через переменные окружения. Многие из них соответствуют параметрам, доступным в конфигурационном файле оригинального CLI, поэтому понимание этих опций пригодится и тем, кто запускает клиент напрямую.

Ключевые переменные:

• ADGUARD_CONNECTION_LOCATION — локация для подключения по умолчанию (например, JP для Токио или HELSINKI для Хельсинки).
• ADGUARD_CONNECTION_TYPE — режим работы: TUN (создаёт виртуальный сетевой интерфейс) или SOCKS (локальный SOCKS5-прокси).
• ADGUARD_SOCKS5_PORT — порт для SOCKS5-режима, по умолчанию 1080.
• ADGUARD_USE_KILL_SWITCH — включает или отключает Kill Switch.
• ADGUARD_CUSTOM_DNS — адрес вышестоящего DNS-сервера.
• ADGUARD_PROTOCOL — выбор протокола: auto, http2 или quic.
• ADGUARD_POST_QUANTUM — включает постквантовую криптографию для защиты от будущих атак.
• ADGUARD_SET_SYSTEM_DNS — разрешает клиенту изменять системные DNS-настройки.

Старые переменные ADGUARD_USERNAME и ADGUARD_PASSWORD больше не используются для аутентификации, но оставлены для обратной совместимости. Если вы видите их в примерах конфигурации, помните: они не выполняют функцию входа в аккаунт.

Безопасность: Kill Switch, утечки и выбор интерфейса

Kill Switch — это механизм, который блокирует сетевой трафик, если VPN-соединение внезапно прерывается. Без него пакеты могут уходить напрямую через обычное интернет-соединение, раскрывая ваш реальный IP-адрес. В AdGuard VPN CLI эта функция включена по умолчанию и управляется параметром ADGUARD_USE_KILL_SWITCH.

В Docker-образе предусмотрены дополнительные опции для контроля утечек:

• ADGUARD_MAX_LEAK_TOLERANCE — количество допустимых утечек до полной остановки (0 означает немедленное завершение при первой же утечке).
• ADGUARD_LEAK_WARNING_ONLY — при значении true система не останавливает VPN, а только выводит предупреждение.
• ADGUARD_MAX_IP_DETECTION_RETRIES — количество попыток определения внешнего IP-адреса для проверки.

Параметр ADGUARD_BOUND_IF_OVERRIDE позволяет указать конкретный сетевой интерфейс для исходящего VPN-трафика. Это бывает полезно на серверах с несколькими сетевыми картами, когда нужно гарантировать, что VPN использует только определённый физический канал.

Практический сценарий: VPN для qBittorrent в Docker

Один из самых популярных сценариев использования AdGuard VPN CLI в Docker — это организация безопасного торрент-скачивания. Весь трафик клиента заворачивается в VPN-туннель, а если соединение падает, Kill Switch не даёт данным уходить напрямую.

Пример конфигурации из официального репозитория Docker-образа:

version: "3"
services:
  adguard-vpn-cli:
    image: supersunho/adguardvpn-cli:latest
    restart: unless-stopped
    container_name: adguard-vpn-cli
    env_file: .env
    volumes:
      - ./data:/root/.local/share/adguardvpn-cli
    healthcheck:
      test: ping -c 1 www.google.com || exit 1
      interval: 1m
      timeout: 10s
      retries: 1
    cap_add:
      - NET_ADMIN
    devices:
      - /dev/net/tun
    ports:
      - 6089:6089
      - 6881:6881
      - 6881:6881/udp

  qbittorrent:
    image: linuxserver/qbittorrent:latest
    container_name: qbittorrent
    environment:
      - PUID=0
      - PGID=0
      - TZ=Asia/Seoul
    volumes:
      - ./config:/config
      - ./downloads:/downloads
    devices:
      - /dev/fuse:/dev/fuse:rwm
    cap_add:
      - SYS_ADMIN
    depends_on:
      - adguard-vpn-cli
    network_mode: service:adguard-vpn-cli

Ключевая особенность схемы — использование network_mode: service:adguard-vpn-cli. Это заставляет qBittorrent разделять сетевой стек с контейнером VPN. В результате весь трафик торрент-клиента проходит через туннель, и никакой другой трафик наружу не уходит. Порт 6881 открыт для входящих торрент-соединений.

Ограничения, бета-статус и ожидания

Важно понимать, что AdGuard VPN CLI — относительно молодой продукт. Долгое время он распространялся в статусе открытой беты, и пользователи отмечали, что некоторые функции работают с недочётами. Например, в ранних версиях нельзя было посмотреть оставшийся трафик по подписке — эта информация просто не выводилась.

Версия 1.0 стала важной вехой, после которой продукт был признан стабильным. Однако пользователи сообщают о следующих ограничениях:

• Интерфейс полностью текстовый, поэтому новичкам нужно привыкать к командам.
• Нет встроенного механизма автоматического запуска при старте системы — это придётся настраивать через systemd или cron.
• Веб-авторизация неудобна на устройствах без браузера (хотя решается через перенос ссылки на другое устройство).
• При использовании 2FA возможны сбои входа.
• Для работы в Docker требуются привилегии NET_ADMIN и устройство /dev/net/tun, что может быть проблемой в некоторых облачных окружениях.

Несмотря на эти шероховатости, утилита работает стабильно на популярных дистрибутивах, включая Steam Deck, и получает регулярные обновления от разработчиков.

Сравнение с графическими версиями и альтернативами

Если у вас уже есть подписка AdGuard VPN для Windows или мобильных устройств, она действует и для CLI-версии — дополнительно платить не нужно. Это удобно для тех, кто хочет использовать один аккаунт на разных платформах.

Ключевые различия между графической и консольной версиями:

• Управление: в GUI всё делается кликами, в CLI — командами и флагами.
• Ресурсы: CLI потребляет значительно меньше памяти и не требует графической подсистемы.
• Автоматизация: CLI легко встраивается в скрипты, GUI — нет.
• Поддержка платформ: CLI работает на Linux, macOS и роутерах; GUI-версии есть для Windows, Android, iOS и macOS.

Из альтернатив для командной строки можно рассматривать WireGuard, OpenVPN и Tailscale. Но у них другой подход к управлению: часто требуется вручную настраивать конфигурационные файлы и маршрутизацию. AdGuard VPN CLI предлагает готовую инфраструктуру с автоматическим выбором сервера и встроенной защитой от утечек, что упрощает жизнь пользователям, которые не хотят вникать в детали сетевого стека.

Вопросы и ответы

curl -fsSL https://raw.githubusercontent.com/AdguardTeam/AdGuardVPNCLI/master/scripts/release/install.sh | sh -s — -v

adguardvpn-cli list-locations

adguardvpn-cli connect -l HELSINKI

docker logs adguard-vpn-cli