lissy93/AdGuardian-Term

AdGuardian-Term

Terminal-based, real-time traffic monitoring and statistics for your AdGuard Home instance

About

AdGuardian Terminal Eddition - Keep an eye on your traffic, with this (unofficial) buddy for your AdGuard Home instance

Features

• Real-time Query Monitoring: Fetches and displays all DNS queries in real time, letting you see exactly what's happening on your network at any given moment
• Block and Allow Stats: Get a quick overview of the number of queries that have been allowed, filtered or blocked by AdGuard
• Historical Query Counts: Analyze network activity over time with historical query count data. This lets you track trends and spot any unusual activity
• Filter Lists: AdGuardian displays your active filter lists, showing which ones are doing the most work
• Top Domain Statistics: See which domains are getting the most queries (blocked, allowed and otherwise) in your network
• Easy and Lightweight: AdGuardian can be run either with a super tiny Docker image, or directly with the zero-dependency executable
• Good and Safe: Written in Rust and unit tested, the app runs locally with no external requests, and (of course) it's fully open source

About AdGuard

AdGuard Home is a free and open source self-hosted (or managed) network-wide ad + tracker blocker. It operates as a DNS server that re-routes tracking domains to a "black hole", thus preventing your devices from connecting to those servers. It makes your internet, faster, safer and gives you a bunch of useful features, like encrypted DNS (DoH, DoT, DNSCrypt), parental controls, blocking of malware / phishing, per-device configs, custom DNS rules, etc.

Getting Started

There are several options for running...

Docker

docker run -it lissy93/adguardian

You may also pass in your AdGuard info with env vars (using -e), see the Configuring section for an example, and list of available config params.
If you experience issues with DockerHub, or would rather use a different registry, the image is also available via GHCR - just replace the image name with: ghcr.io/lissy93/adguardian. Alternatively, if you'd like to build it yourself from source, you can do so with docker buildx build -t adguardian . then run it with docker run -it adguardian.

Executable

curl -L -o adguardian https://github.com/Lissy93/AdGuardian-Term/releases/latest/download/adguardian-linux && \
chmod +x adguardian && \
./adguardian

In the above example, don't forget to update the URL to download the latest stable version for your operating system
You may also just head over the the Releases tab, download the latest executable, and double-click on it to run

Install from Crates.io

cargo install adguardian
adguardian

AdGuardian is published as a crate to crates.io/crates/adguardian. So providing you've got Cargo installed, you can pull the binary directly, and then execute it as above. Again, see the Configuring section below for how to pass in your AdGuard info.

Build from Source

git clone [email protected]:Lissy93/AdGuardian-Term.git && \
cd AdGuardian-Term && \
make

You'll need git, cargo and make (see here for installation notes). You can also run the cargo commands defined in the Makefile directly, e.g. cargo run

Scoop

scoop install extras/adguardian

For Windows users, AdGuardian is available via the Scoop package manager, as part of the extras bucket - You'll need Scoop installed, then follow these instructions. This was contributed by @kzshantonu in ScoopInstaller/Extras#11386

AUR

paru -Syu adguardian
# or
yay -Syu adguardian
# or
git clone https://aur.archlinux.org/adguardian.git && cd adguardian && makepkg -si

One-Liner

bash <(curl -sL https://raw.githubusercontent.com/Lissy93/AdGuardian-Term/main/quick-start.sh)

This will run the quick-start.sh Bash script, which downloads and executes the latest binary for your system type. Be sure to read and understand the file first

Configuring

The app requires the details of an AdGuard instance to connect to. This info can be provided either as environmental variables, or passed in as flag parameters. If any of these fields are missing or incomplete, you'll be prompted to enter a value once the app starts.

The following params are accepted:

• ADGUARD_IP / --adguard-ip - The IP address of your local AdGuard Home instance
• ADGUARD_PORT / --adguard-port - The port that AdGuard is running on
• ADGUARD_USERNAME / --adguard-username - An AdGuard Home username
• ADGUARD_PASSWORD / --adguard-password - An AdGuard Home password

There's also some additional optional environment variables that you may set:

• ADGUARD_PROTOCOL - The protocol to use when connecting to AdGuard (defaults to http)
• ADGUARD_UPDATE_INTERVAL - The rate at which to refresh the UI in seconds (defaults to 2)
• ADGUARD_TIMEOUT - The per-request timeout when contacting AdGuard, in seconds (defaults to 5)
• ADGUARD_QUERYLOG_LIMIT - The number of query log entries to fetch per update (defaults to 100)

adguardian -- \
	--adguard-ip "192.168.180.1" \
	--adguard-port "3000" \
	--adguard-username "admin" \
	--adguard-password "bobs-your-uncle"

ADGUARD_IP="192.168.180.1" ADGUARD_PORT="3000" ADGUARD_USERNAME="admin" ADGUARD_PASSWORD="bobs-your-uncle" adguardian

docker run \
	-e "ADGUARD_IP=192.168.180.1" \
	-e "ADGUARD_PORT=3000" \
	-e "ADGUARD_USERNAME=admin" \
	-e "ADGUARD_PASSWORD=bobs-your-uncle" \
	-it lissy93/adguardian

Web Mode

The terminal dashboard can also be viewed via a browser, thanks to ttyd.

Quick Start with Pre-built Docker Image

The easiest way to run AdGuardian in web mode is using a pre-built Docker image:

Note: This is a third-party Docker image (sdjnmxd/adguardian-web) and is not officially maintained by the AdGuardian-Term project. Use at your own discretion.

🐳 Docker Hub: sdjnmxd/adguardian-web
📚 Source Code: GitHub Repository

docker run -d \
  -p 7681:7681 \
  -e ADGUARD_IP=your.adguard.ip \
  -e ADGUARD_PORT=80 \
  -e ADGUARD_USERNAME=admin \
  -e ADGUARD_PASSWORD=your_password \
  sdjnmxd/adguardian-web

Then access it in your browser at http://localhost:7681

Manual Setup

AdGuardian is fully compatible with ttyd, so once you've installed it, you can just precede your run command with ttyd. E.g. ttyd docker run -it lissy93/adguardian or ttyd adguardian

You can also just use the ttyd-Dockerfile, this will build the latest AdGuardian-Term from github and the latest ttyd and compiles both together into a single dockerfile. So you don't have to install ttyd on the host, due to security reasons.

This might be useful for embedding into another app or dashboard (like Dashy 😉 - although Dashy already has an AdGuard widget!)

Another great option is gotty, which works in a similar way. Note that if you want to allow user input, you'll need to pass the -w option.

You can also combine this with a service like ngrok to forward the port, and access the dashboard from anywhere. But be careful to apply the correct access controls!

Another fun idea, could be to display it on a little screen, either attached or SSH'd into your AdGuard box.

Development

Prerequisites

You'll need Rust installed. Run: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh - see the installation docs. You'll also need Git, if you don't already have it.

Then clone the repo, and cd into it, with: git clone [email protected]:Lissy93/AdGuardian-Term.git && cd AdGuardian-Term

You can view the full list of available project commands in the Makefile

Run

To build and run the project for development, run cargo run

Technical Docs

The documentation can be viewed at: lissy93.github.io/AdGuardian-Term

Testing and Quality

• cargo test - Run unit tests
• cargo check - Ensure app is compilable
• cargo bench - Execute benchmarks
• cargo clippy - Analyse areas for improvement
• cargo doc - Generate the documentation

Building

Once your finished developing, you can build the project for production with: cargo build --release The binaries for your system will then be available in the ./target/release/ directory of the project. You can execute this directly, e.g. by running ./target/release/adguardian (add .exe if on Windows)

CI / CD

The testing, building, and publishing of the app is done with GitHub Actions. Below is an outline + current status of each workflow.

Workflow	Status
Run quality + security checks on each PR and push
Bump version and push git tag on merge to main
Compile binaries and draft a release on each tag
Publish compiled app to crates.io
Build Docker image and push to registry
Generate documentation from Rustdoc, upload to GH pages
Sync repo with downstream codeberg mirror

Credits

Contributors

Sponsors

Dependencies

This project was made possible by the maintainers of the following dependencies

• anyhow - Error objecr for idiomatic error handling
• base64 - Base 64 encoding
• chrono - Date + time parsing and manipulating
• colored - Handling of terminal colors
• crossterm - Term manipulation for kb + mouse events
• futures - Extension of futures for async computation
• reqwest - HTTP client
• serde - Decerilization of JSON responses
• tokio - Improved futures
• tui-rs - Terminal graphing

Mirror

A mirror of this repository is published at: codeberg.org/alicia/adguardian

Alterntives

This project was heavily inspired by PADD - terminal status for Pi-Hole users. If you're running Pi-Hole instead of AdGuard, I highly recommend you check that out, as it's awesome.

Other developers have built similar AdGuard Home monitoring programs for mobile, including:

• iOS app: AdGuard Home Remote by RocketScience IT
• Android app: AdGuard Home Manager by JGeek00

If you're looking for more AdGuard add-ons, then check this section of their repo.

If you're running Dashy (a Homelab Dashboard app (which I am the author of)), then there's also 4 AdGuard Home Widgets.

Before I created this, I first built the same product in Go Lang. You can view that here - it's fully functional, but not as good as the Rust version (There were some valuable lessons that I learnt the hard way about choosing the right tech stack).

Contributing

Contributions of any kind are very welcome (and would be much appreciated!) For Code of Conduct, see Contributor Convent. For project setup, see the Development section.

New here?

To get started, fork the repo, make your changes, add, commit and push the code, then come back here to open a pull request. If you're new to GitHub or open source, this tutorial may help, I've also put some beginner guides together at git-into-open-source - but feel free to reach out if you need any support.

Not a coder?

You can support the project in other ways too, drop us a star, consider sponsoring us on GitHub, share within your network, and report any bugs you come across.

License

Lissy93/AdGuardian-Term is licensed under MIT © Alicia Sykes 2023.
^{For information, see TLDR Legal > MIT}

The MIT License (MIT)
Copyright (c) Alicia Sykes <[email protected]> 

Permission is hereby granted, free of charge, to any person obtaining a copy 
of this software and associated documentation files (the "Software"), to deal 
in the Software without restriction, including without limitation the rights 
to use, copy, modify, merge, publish, distribute, sub-license, and/or sell 
copies of the Software, and to permit persons to whom the Software is furnished 
to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included install 
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED,
INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANT ABILITY, FITNESS FOR A
PARTICULAR PURPOSE AND NON INFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

© Alicia Sykes 2023
Licensed under MIT

^{Thanks for visiting :)}