インストール - AdGuard

概要

AdGuard for Linux (AdGuard CLI) は、Linux向けの広告ブロックおよびトラフィックフィルタリング用CLIアプリケーションである。
AdGuard CLIは、安定版、Beta版、Nightly版の3系統で配布されている。

対応ディストリビューションとして、公式情報では Debian 10以降、Ubuntu 22.04 / 24.04以降、RHEL 8.0以降、Fedora 35以降が案内されている。
非Debian系または非Red Hat系の環境では、証明書インストールが失敗する場合がある。

インストールは、公式の install.sh ファイルを用いたコマンドで実行する。

既定では、実体ファイルは /opt/adguard-cli に配置される。
インストール時には、必要に応じて /usr/local/bin への実行ファイルリンクを作成する。

AdGuard CLIの利用には、AdGuardライセンスが必要である。
ライセンスがない場合でも、公式案内に従って14日間の試用を開始できる。

初期導入後は、adguard-cli activate と adguard-cli configure を順に実行する。
<bt> 保護を開始するコマンドは adguard-cli start である。
保護状態の確認は adguard-cli status、停止は adguard-cli stop で行う。

現在の設定内容と設定ファイルの場所は adguard-cli config show で確認できる。

作業ディレクトリは ~/.local/share/adguard-cli/ であり、主要ファイルとして proxy.yaml、browsers.yaml、user.txt がある。

DNSフィルタリングは v1.3 以降で利用できるが、既定では無効である。

自動モードを使う場合は、iptables、nat テーブル、REDIRECT と QUEUE チェーン、sudo が必要である。
また、VPNや自動モードの併用では、環境によって通信経路の競合が起こる場合がある。

IPv6関連の問題は、調査資料ではv1.3.41以降または v1.4系で修正済みとされている。

前提条件

インストール前に、以下に示す条件を確認する。

対応ディストリビューションを使用していること
Debian 10以降

Ubuntu 22.04 / 24.04以降

RHEL 8.0以降

Fedora 35以降
インターネットへ接続できること
curl コマンドを利用できること。
管理者権限を利用できること。
ライセンス認証または試用開始のためにAdGuardアカウントへアクセスできること。
自動モードを使う場合は、iptables、sudo、nat テーブル、REDIRECT と QUEUE チェーンを利用できること。

証明書インストールは、非Debian系または非Red Hat系で失敗する場合がある。
その場合は、公式トラブルシューティングも併せて確認する。

インストール手順

AdGuard CLIは、配布チャネルごとにインストールコマンドが異なる。
以下に示すコマンドは、公式インストールスクリプトをそのまま使用する。

安定版

安定版をインストールする。

curl -fsSL https://raw.githubusercontent.com/AdguardTeam/AdGuardCLI/release/install.sh | sh -s -- -v

必要に応じて管理者パスワードを入力する。
インストール途中で確認が表示された場合は、/usr/local/bin へのリンク作成を許可する。

Beta版

Beta版をインストールする。

curl -fsSL https://raw.githubusercontent.com/AdguardTeam/AdGuardCLI/beta/install.sh | sh -s -- -v

Beta版は安定版より新しい変更を含む可能性がある。
本番環境では、必要に応じて安定版との使い分けを行う。

Nightly版

Nightly版をインストールする。

curl -fsSL https://raw.githubusercontent.com/AdguardTeam/AdGuardCLI/nightly/install.sh | sh -s -- -v

Nightly版は最新の修正を含む一方で、運用前の検証が必要である。

アンインストール

インストールしたチャネルに対応するスクリプトへ -u オプションを付加して削除する。

安定版
curl -fsSL https://raw.githubusercontent.com/AdguardTeam/AdGuardCLI/release/install.sh | sh -s -- -v -u

Beta版
curl -fsSL https://raw.githubusercontent.com/AdguardTeam/AdGuardCLI/beta/install.sh | sh -s -- -v -u

Nightly版
curl -fsSL https://raw.githubusercontent.com/AdguardTeam/AdGuardCLI/nightly/install.sh | sh -s -- -v -u

削除前にサービスとして常駐させている場合は、停止してから実行する。

任意のインストールディレクトリへのインストール

既定の /opt/adguard-cli 以外のディレクトリへインストールする場合は、-o オプションを使用する。

curl -fsSL https://raw.githubusercontent.com/AdguardTeam/AdGuardCLI/release/install.sh | sh -s -- -o <任意のインストールディレクトリ> -v

-o オプションの挙動は以下の通りである。

オプションを省略した場合
既定で /opt/adguard-cli へインストールされる。
-o /opt または -o . を指定した場合
自動的に /adguard-cli が付加される。
その他のパスを指定した場合
指定したパスがそのままインストール先となる。サブディレクトリは自動付加されない。

任意のディレクトリへインストールする際の注意事項を以下に示す。

/usr/local/bin へのリンク作成
インストール時に確認が表示される。リンクを作成しない場合は、インストール先ディレクトリを PATH 環境変数へ追加する必要がある。
アンインストール
削除時も同じ -o パスを指定する必要がある。指定を忘れると /opt/adguard-cli を参照し、エラーとなる。
サービスファイル
アンインストール時にサービスファイルは削除されない。手動で ~/.local/share/adguard-cli/ から削除する必要がある。
所有権
インストール先ディレクトリは現在のユーザー所有となる。所有権が異なる場合は、スクリプトが修正を提案する。

初期設定

インストール後は、ライセンス認証、設定ウィザード、保護開始の順で進める。

ライセンス認証を開始する。
```
adguard-cli activate
```
必要に応じて試用開始または既存ライセンスの認証を行う。
設定ウィザードを起動する。
```
adguard-cli configure
```
初期設定が完了したら保護を開始する。
```
adguard-cli start
```
状態を確認する。
```
adguard-cli status
```

ライセンス情報の確認は以下に示すコマンドを実行する。

adguard-cli license

ライセンスをリセットする場合は以下に示すコマンドを実行する。

adguard-cli reset-license

設定ファイルの場所を含む現在の構成を確認する場合は以下に示すコマンドを実行する。

adguard-cli config show

proxy.yaml の場所は環境により変わる可能性があるため、必ずこのコマンドで確認する。

基本的な設定

AdGuard CLIの基本操作と設定変更の代表例を以下に示す。

全てのコマンドを確認する。
```
adguard-cli --help-all
```
保護を開始する。
```
adguard-cli start
```
保護を停止する。
```
adguard-cli stop
```
保護を再起動する。
```
adguard-cli restart
```
状態を確認する。
```
adguard-cli status
```
更新を確認する。
```
adguard-cli check-update
```
AdGuard CLIを更新する。
```
adguard-cli update
```
更新スクリプトの詳細出力を表示する。
```
adguard-cli update -v
```

設定をCLIから変更する例を示す。

adguard-cli config get proxy_mode
adguard-cli config set proxy_mode manual
adguard-cli config set listen_ports.http_proxy 3129

現在の設定をまとめて確認する。

adguard-cli config show

設定を初期値へ戻す場合は以下に示すコマンドを実行する。

adguard-cli config reset proxy_mode
adguard-cli config reset --all

自動モードは、必要なiptables機能が揃っている環境でのみ利用する。

フィルタおよびDNS設定

AdGuard CLIでは、通常フィルタとDNSフィルタを個別に管理できる。

通常フィルタ

インストール済みフィルタの一覧を表示する。

adguard-cli filters list
adguard-cli filters list --all

組み込みフィルタを追加または有効化する。

adguard-cli filters add 2
adguard-cli filters enable 2

URLまたはローカルファイルからカスタムフィルタを追加する。

adguard-cli filters install https://example.com/filter.txt --title "My Filter"

フィルタを無効化または削除する。

adguard-cli filters disable 2
adguard-cli filters remove 2

DNSフィルタ

DNSフィルタリングは、v1.3以降で利用できる。
既定では無効であるため、利用時はバージョンと設定状態を確認する。

DNSフィルタ一覧を表示する。

adguard-cli dns filters list
adguard-cli dns filters list --all

DNSフィルタを追加または有効化する。

adguard-cli dns filters add 2
adguard-cli dns filters enable 2

URLまたはローカルファイルからDNSフィルタを追加する。

adguard-cli dns filters install https://example.com/dns-filter.txt --title "My DNS Filter"

user.txt には独自ルールを記述できる。
独自のテキストファイルを使う場合は、proxy.yaml の filters セクションへ追記する。

 filters:
   - 'flm://'
   - 'user.txt'
   - 'my_filter.txt'

アプリ除外およびブラウザー設定

アプリ単位の除外設定は、~/.local/share/adguard-cli/ 配下のファイルで行う。
主に、browsers.yaml と proxy.yaml を使用する。

Webブラウザ設定

browsers.yaml には、Webブラウザごとの挙動を記述する。
Linuxでは、Webブラウザの実行ファイル名を指定する。

default
既定動作でフィルタリングする。
bypass_https
HTTPSフィルタリングのみ無効化する。
bypass
そのアプリを完全に除外する。

例を以下に示す。

 - name: firefox
   action: default
 - name: chrome
   action: bypass_https
 - name: chromium
   action: bypass

一般アプリの除外

一般アプリの除外は、proxy.yaml の apps セクションで行う。
VPN関連プロセスを除外する例を以下に示す。

 apps:
   - include-list: browsers.yaml
   - name: '*vpn*'
     action: 'bypass'
     skip_outbound_proxy: true
   - name: '*'
     action: 'bypass_https'

アプリ除外の設定後は、必要に応じて保護を再起動する。

adguard-cli restart

自動起動の設定

AdGuard CLIを自動起動する場合、公式ドキュメントではsystemdサービスの利用が案内されている。
ログイン時に起動する方法と、システム起動時に起動する方法がある。

ログイン時に自動起動

ユーザ単位のsystemdサービスを作成する。

 [Unit]
 Description=AdGuard CLI
 After=network.target
 
 [Service]
 Type=forking
 WorkingDirectory=/opt/adguard-cli
 ExecStart=/opt/adguard-cli/adguard-cli start
 ExecStop=/opt/adguard-cli/adguard-cli stop
 Restart=always
 TimeoutStartSec=0
 TimeoutStopSec=0
 StandardOutput=journal
 RemainAfterExit=yes
 
 [Install]
 WantedBy=default.target

サービスファイルを ~/.config/systemd/user/adguard-cli.service として保存し、Systemdサービスを有効にする。

systemctl --user daemon-reload
systemctl --user enable --now adguard-cli

システム起動時に自動起動

システム全体のsystemdサービスを作成する。

 [Unit]
 Description=AdGuard CLI
 After=network.target
 
 [Service]
 Type=forking
 WorkingDirectory=/opt/adguard-cli
 ExecStart=/opt/adguard-cli/adguard-cli start
 ExecStop=/opt/adguard-cli/adguard-cli stop
 Restart=always
 TimeoutStartSec=0
 TimeoutStopSec=0
 StandardOutput=journal
 RemainAfterExit=yes
 User=username
 
 [Install]
 WantedBy=multi-user.target

User=username の username は実際のLinuxユーザ名へ置き換える。
サービスファイルを /etc/systemd/system/adguard-cli.service として保存し、Systemdサービスを有効にする。

sudo systemctl daemon-reload
sudo systemctl enable --now adguard-cli

トラブルシューティング

導入または運用時に確認しやすい項目をまとめる。

証明書インストールが失敗する

非Debian系または非Red Hat系の環境では失敗する場合がある。

公式トラブルシューティングと環境差異を確認する。

自動モードで開始できない

iptables、nat テーブル、REDIRECT、QUEUE、sudo の要件を確認する。

VPNと競合する

自動モードでは通信経路の競合が起こる場合がある。
必要に応じてアプリ除外や手動モードを検討する。

DNSフィルタが使用できない

DNSフィルタリングは、v1.3以降で利用可能である。
既定では無効であるため、バージョンと設定状態を確認する。

設定ファイルの場所が分からない

adguard-cli config show コマンドを実行して、proxy.yaml の場所を確認する。

IPv6関連の問題がある

v1.3.41以降または v1.4系で修正済みとされている。

ログや現在の状態の確認

adguard-cli status
adguard-cli config show
systemctl --user status adguard-cli
sudo systemctl status adguard-cli