๐Ÿ›ก๏ธ Terminal-based, real-time traffic monitoring and statistics for your AdGuard Home instance

Overview

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.

Contents

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 availible 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 -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

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

Not sure which method to choose?

  • Docker is the easiest but needs to be installed, and adds a bit of overhead (12Mb, to be precise)
  • Where as using the executable won't require any additional dependencies
  • If you've got Rust installed, fetching from crates.io will also be both easy and performant
  • If your system architecture isn't supported you'll need to build from source, as you also will if you wish to run a fork or make amendments to the code

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)
Examples

With Flags

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

With Env Vars

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

In Docker

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.

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

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!


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 availible 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:

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.

View Current Workflow Status
  • Build Docker image and push to registry
    • Build Docker Image ๐Ÿณ
  • Compile binaries and upload artifacts to release
    • Compile Release ๐Ÿš€
  • Publish compiled app to crates.io
    • Publish to Crates.io ๐Ÿ“ฆ
  • Generate documentation from Rustdoc, upload to GH pages
    • Generate Rust Docs ๐Ÿ“
  • Sync repo with downstream codeberg mirror
    • Mirror to Codeberg ๐Ÿชž
  • Insert list of contributors + sponsors into readme
    • Insert Contributors ๐Ÿ‘ฅ

Credits

Contributors

Lissy93
Alicia Sykes
liss-bot
Alicia Bot
tromcho
Null

Sponsors

peng1can
Null
emlazzarin
Eddy Lazzarin
AnandChowdhary
Anand Chowdhary
davidpaulyoung
David Young
k-rol
Carol Ouellet
bile0026
Zach Biles
UlisesGascon
Ulises Gascรณn
bmcgonag
Brian McGonagill
vlad-timofeev
Vlad Timofeev
iJasonWade
Jason Ash
DRXAquosus
Null
ratty222
Brent
jtfinley72
Null

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


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 guide or the git docs may help you get started, 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

Expand License
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 :)

Comments
  • Docker container error - missing field last_updated

    Docker container error - missing field last_updated

    Connection is successful:

    Verifying connection to your AdGuard instance... AdGuard connection successful!

    Then, container fails to run:

    Failed to run: error decoding response body: missing field last_updated at line 1 column 348 thread 'main' panicked at 'called Result::unwrap() on an Err value: Custom { kind: Other, error: "Failed to run" }', src/main.rs:93:12 note: run with RUST_BACKTRACE=1 environment variable to display a backtrace

    opened by brandonleegit 9
  • Support HTTPS connections

    Support HTTPS connections

    I expose my Adguard instances over https and right now it doesn't appear possible to connect regardless of the IP/hostname or port provided.

    I don't know Rust well, but I'm guessing this is hardcoding http as the protocol scheme https://github.com/Lissy93/AdGuardian-Term/blob/main/src/main.rs#L27

    opened by thespad 5
  • Pass the variables to exectubale?

    Pass the variables to exectubale?

    This is awesome like all your other works. But I can not find how to pass the environmental variables to the executable.

    Tried with : --ADGUARD_IP="192.168.1.10" or ADGUARD_IP="192.168.1.10" or -ADGUARD_IP="192.168.1.10" or ...

    adguardian-linux --ADGUARD_IP="192.168.1.10"  --ADGUARD_PORT="3000"
    Starting initialization checks...
    The ADGUARD_IP environmental variable is not yet set
    
    

    Whatever I do it keep asking me for them

    Edit: Solved by exporting them, but still cant find out how to use them with flag

    opened by papampi 2
  • Avg processing time mis-labelled?

    Avg processing time mis-labelled?

    In the top left box, 'Avg Processing Time' is shown currently as 0.008633ms. The AGH webUI shows it as 9ms, which if we account for rounding could easily be 0.008633 seconds (as opposed to ms). Is this a mis-label of units in the TUI, or have I missed something? It seems it should be labelled 's'; or, better yet, fettled to read 8.633ms.

    Awesome software, btw. Thanks!

    opened by RainmakerRaw 1
  • [Fix] Processing Time Incorrect

    [Fix] Processing Time Incorrect

    Overview: The processing time displayed was incorrect. AdGuard's API was returning the value in seconds, while AdGuardian was displaying it as milliseconds. This has been fixed by dividing by 1000 and converting to a 16-bit integer.

    Ticket: #11

    Screenshot:

    opened by Lissy93 0
  • [Fix] Adds a check to ensure using a compatible version of AdGuard API

    [Fix] Adds a check to ensure using a compatible version of AdGuard API

    Overview: Adds a check that the users AdGuard Home instance is of a valid version - at least 0.107.28. This is called when the app first starts, and a message will be shown to the user if they're running an incompatible version.

    Rationale: Older versions of AdGuard Home have a different API schema. This makes them incompatible. This would cause AdGuardian-Term to panic and crash when it failed to decode the response from the server, which didn't meed the required format.

    Ticked: #5

    Screenshot:

    opened by Lissy93 0
  • [Feature] Support for HTTPS / User-defined protocol

    [Feature] Support for HTTPS / User-defined protocol

    Description: Enables user to set the protocol used, in order to access AdGuard dashboards served over anything other than http (aka https).

    Ticket: #7

    Note: The protocol used will default to http if not defined / so is backwards compatible. You can set ADGUARD_PROTOCOL="https" to use HTTPS. I've tested with a self-signed cert, and seems to work okay (Oh, and if you're using a custom domain, then set that to ADGUARD_IP, and set ADGUARD_PORT to 80 or wherever it's running at).

    opened by Lissy93 0
  • [Feature] Show upstream DNS in query log

    [Feature] Show upstream DNS in query log

    Description This PR introduces a new coloumn to the query log table, which shows the upstream DNS server used to resolve a given query.

    Note: The table got quite cramped on smaller screens, so this colom will be hidden if your terminal width is below 120 chars. Blocked requests do not have an upstream DNS provider, and so will be blank. If you've only got one DNS server configured, the value will be the same for each request.

    Ticket: #2

    Screenshot:

    image

    opened by Lissy93 0
  • Docker error: Failed to run: Failed to send query data

    Docker error: Failed to run: Failed to send query data

    Hi!

    I am running the latest docker and the latest adguard home version (0.107.29) and can't get it working:

    Log:

    Welcome to AdGuardian Terminal Edition!
    Terminal-based, real-time traffic monitoring and statistics for your AdGuard Home instance
    For documentation and support, please visit: https://github.com/lissy93/adguardian-term
    Starting initialization checks...
    ADGUARD_IP is set to 192.168.0.251
    ADGUARD_PORT is set to 3003
    ADGUARD_USERNAME is set to xxx
    ADGUARD_PASSWORD is set to ******
    Verifying connection to your AdGuard instance...
    AdGuard connection successful!
    Failed to run: Failed to send query data
    Error: Failed to run: Failed to send query data
    

    Any idea what it could be?

    Thanks

    URBANsUNITED

    opened by URBANsUNITED 8
  • Long stop time?

    Long stop time?

    Is it for me or does it take long time for it to stop after hitting "q" or "ctrl+c" If it runs for a period of time it takes so much long time to stop and after stop terminal shows some gibberish like this:

    ~$ 184;27M35;183;27M35;182;27M35;180;27M35;178;27M35;175;27M35;172;27M35;170;27M35;169;27M35;168;27M35;168;26M35;167;26M35;167;25M35;166;23M35;165;22M35;164;20M35;163;17M35;163;15M35;162;13M35;162;11M35;162;9M35;162;7M35;162;5M35;162;3M35;163;1M35;188;2M35;186;3M35;184;5M35;182;7M35;181;8M35;180;10M35;178;12M35;177;13M35;176;15M35;175;17M35;175;18M35;174;20M35;174;21M35;174;22M35;173;23M35;173;24M35;173;25M35;173;26M35;173;27M35;173;28M35;174;28M35;174;27M35;175;27M35;175;26M35;176;26M35;177;26M35;177;25M35;178;25M35;179;25M35;180;24M35;181;24M35;182;24M35;183;24M35;184;24M35;185;23M35;186;23M35;188;24M35;187;24M35;186;24M35;186;23M35;187;23M35;188;23M35;190;23M35;191;23M35;194;22M35;196;22M35;199;22M35;202;22M35;204;22M35;205;21M35;207;21M35;210;21M35;212;21M35;214;21M35;216;21M35;218;21M35;219;21M35;221;21M35;222;21M35;223;22M35;225;22M35;226;22M35;227;22M35;228;22M35;229;22M35;230;22M35;231;23M35;232;23M35;233;23M35;234;23M35;235;23M35;235;24M35;236;24M35;237;24M35;237;25M35;238;25M35;239;25M35;239;26M35;240;26M35;239;26M35;238;26M35;237;26M35;235;26M35;233;26M35;231;26M35;228;26M35;226;26M35;223;27M35;219;27M35;215;27M35;211;27M35;207;27M35;203;27M35;199;27M35;195;27M35;190;27M35;187;27M35;183;27M35;179;27M35;175;27M35;172;27M35;169;27M35;166;27M35;164;27M35;162;27M35;160;26M35;159;26M35;158;26M35;157;26M35;156;26M35;155;26M35;154;26M35;154;25M35;154;24M35;154;23M35;154;22M35;154;20M35;155;19M35;155;17M35;156;15M35;157;12M35;158;10M35;159;8M35;160;5M35;161;3M35;162;1M

    opened by papampi 1
Releases(1.6.0)
Owner
Alicia Sykes
Turning caffeine into code ๐Ÿฅค
Alicia Sykes
zigfi is an open-source stocks, commodities and cryptocurrencies price monitoring CLI app, written fully in Rust, where you can organize assets you're watching easily into watchlists for easy access on your terminal.

zigfi zigfi is an open-source stocks, commodities and cryptocurrencies price monitoring CLI app, written fully in Rust, where you can organize assets

Aldrin Zigmund Cortez Velasco 18 Oct 24, 2022
By mirroring traffic to and from your machine, mirrord surrounds your local service with a mirror image of its cloud environment.

mirrord lets you easily mirror traffic from your Kubernetes cluster to your development environment. It comes as both Visual Studio Code extension and

MetalBear 2.1k Jan 3, 2023
Manage your dotfiles and packages with ease. Define your $HOME as Code ๐Ÿ’ป ๐Ÿš€ โœจ

EnvHub is a simple tool to manage dotfiles and packages accross multiple machines. Written in Rust, internally it uses nix/homebrew/pkgx/devbox to man

Tsiry Sandratraina 8 Oct 27, 2023
A CLI screentime monitoring tool. Shows how much time are you using certain apps.

A screentime monitoring tool, shows how much time are you really using certain apps. It work nicely with i3status or py3status on I3 window manager fo

Piotr Czajka 6 Dec 8, 2022
Simple system monitoring app that runs on terminal. Made purely with Rust.

What is it? RCTOP is a simple WIP system monitoring app that runs purely on terminal and doesn't feature GUI. One can compare it to htop, but more str

Niko Huuskonen 7 Oct 14, 2022
Tokei is a program that displays statistics about your code.

Tokei is a program that displays statistics about your code. Tokei will show the number of files, total lines within those files and code, comments, and blanks grouped by language.

null 7.5k Jan 1, 2023
Revolutionize handheld gaming with adaptive game settings. Optimize graphics and gameplay experience based on real-time system metrics. Open-source project empowering developers to enhance games on portable devices

Welcome to the server-side application for the HarmonyLink project. This innovative software is developed with the Rust programming language and is ai

Jordon Brooks 5 Jun 28, 2023
Display near-real-time satellite imagery on your desktop.

Satpaper Display near-real-time satellite imagery on your desktop. (Click to see full-size version) Satpaper generates live wallpapers for your deskto

null 148 Oct 10, 2023
Conference Monitoring Project based on Image Recognition that uses Rust Language and AWS Rekognition service to get the level of image similarity.

Conference Monitoring System based on Image Recognition in Rust This is a Conference Monitoring Project based on Image Recognition that uses Rust Lang

Pankaj Chaudhary 6 Dec 18, 2022
Deadliner helps you keep track of the time left for your deadline by dynamically updating the wallpaper of your desktop with the time left.

Deadliner Watch the YouTube video What's Deadliner? Deadliner is a cross-platform desktop application for setting deadline for a project and keeping t

Deadliner 34 Dec 16, 2022
Rust Statistics and Vector Algebra Library

Rstats Usage Insert rstats = "^1" in the Cargo.toml file, under [dependencies]. Use in source files any of the following structs, as needed: use rstat

null 16 Oct 9, 2022
Minimal and blazing-fast file server. For real, this time.

Zy Minimal and blazing-fast file server. For real, this time. Features Single Page Application support Partial responses (Range support) Cross-Origin

Miraculous Owonubi 17 Dec 18, 2022
Captures packets and streams them to other devices. Built for home network analysis and A&D CTFs.

?? shiny-donut shiny-donut is a packet capture app that supports streaming packets from a remote system to another device. The main use for this is to

Justin Perez 3 Nov 30, 2022
Display ZFS datasets' I/O in real time

ztop Display ZFS datasets' I/O in real time Overview ztop is like top, but for ZFS datasets. It displays the real-time activity for datasets. The buil

Alan Somers 40 Nov 23, 2022
Real-time CLI level meter built in Rust.

Meter This is a very simple command line utility written in Rust for measuring the gain of a microphone. It displays the values in dBFS. This is usefu

Chris Burgess 16 Sep 8, 2022
An experimental real-time operating system (RTOS) written in Rust

An experimental real-time operating system (RTOS) written in Rust

null 0 Nov 14, 2022
Real-time stock tickers from the command-line. Written in Rust.

ticker-rs Real-time stock tickers from the command-line written in Rust. CLI tool using the Yahoo Finance API as a data source. It features colored ou

Patrick Stadler 4 Nov 17, 2022
Kiomet.com real-time strategy game

Kiomet.com Kiomet.com is an online multiplayer real-time strategy game. Command your forces wisely and prepare for intense battles! Build Instructions

Softbear 26 Oct 10, 2023
A universal load testing framework for Rust, with real-time tui support.

rlt A Rust Load Testing framework with real-time tui support. rlt provides a simple way to create load test tools in Rust. It is designed to be a univ

Wenxuan 129 Jul 20, 2024