Table of contents
- About the Project
- Getting Started
- Accessing the Admin Panel
- Multi-Proxy Mode (Load Balancing)
- Telegram Notifications Setup
- Resetting Forgotten Password
- Update Project
- Run on System Startup
- Testing Information
- Uninstall SquidStats
- Upcoming Features
- Contributing
- License
- Contact
- Technologies Used
- Special thanks
A modern tool for parsing and analyzing Squid logs, providing a user-friendly dashboard to visualize real-time connection data. This project helps network administrators monitor and manage Squid proxy connections effectively.
You can view the example here.
- Real-time Log Parsing: Parses active Squid connections and displays detailed information.
- User Monitoring: Identifies connections by username, URI, and log type.
- Metrics Overview:
- Total read and written data for each connection.
- Number of requests per connection.
- Delay pool usage.
- Interactive Dashboard: Clean interface for easy data interpretation.
- Squid Cache Statistics:
- Stored entries.
- Used and free capacity
- Maximum and current cache size
- Disk space and inode usage
- Age of cached objects
- Logs Users:
- User activity monitoring 👥
- Beautiful visualizations 📊
- Advanced filtering & search 🔍
- Paginated results 📄
- Top Graphs:
- Top 20 Users Activity
- Top 20 Users Data Usage
- Total Users
- Total Transmitted Data
- Total Request
- And More...
- Quota System:
- Quota per users
- Quota per group
- Cautive Portal
- And More
The entire installation process in more detail can be found here.
- Python 3.14+
- Squid proxy server
apt install git python3 python3-pip python3-venv libmariadb-dev curlSquidStats requires proper Cache Manager configuration to function correctly. Please follow the official Squid Cache Manager documentation for complete setup.
Essential Configuration Steps(Versions higher than 7 do not require the ACL, only the Access Manager part):
-
Configure Cache Manager Access Controls in
/etc/squid/squid.conf:# Allow localhost access to cache manager acl manager proto cache_object acl localhost src 127.0.0.1/32 ::1 # Basic cache manager access http_access allow localhost manager http_access deny manager
-
Configure Remote Access (if SquidStats runs on different server):
# Replace 192.168.1.100 with your SquidStats server IP acl managerAdmin src 192.168.1.100 http_access allow managerAdmin manager -
Verify Cache Manager is Working:
# Test cache manager access curl http://127.0.0.1:3128/squid-internal-mgr/menu # Or using squidclient squidclient -h 127.0.0.1 -p 3128 mgr:info
Why This Configuration is Critical:
- Real-time Statistics: SquidStats uses Cache Manager to retrieve live proxy statistics, active connections, and performance metrics
- Cache Information: Provides data about cached objects, memory usage, disk utilization, and hit ratios
- Connection Monitoring: Enables monitoring of active client connections and bandwidth usage
- Administrative Functions: Allows SquidStats to perform cache management operations like cache refresh and statistics retrieval
When Cache Manager authentication is enabled, set SQUID_MGR_PASS in SquidStats' .env.
Common Issues Without Proper Configuration:
- Empty or missing statistics in SquidStats dashboard
- "Connection refused" errors when accessing cache data
- Missing real-time connection information
- Incomplete bandwidth and user activity reports
Kerberos uses HTTP Negotiate, so Squid must operate as an explicit/forward proxy, not a transparent/intercepting proxy. Configure the browser or PAC file with the proxy FQDN, for example http://inutil.cu:3128; that exact name must match the SPN.
Before applying it, verify that the installed Squid package includes negotiate_kerberos_auth, confirm the helper path for your distribution, and install the Kerberos client tools. This setup uses auth_param, available in auth-enabled Squid releases through v7; Squid v8 no longer supports that directive. In Active Directory, HTTP/inutil.cu must be a unique SPN on the service account; the keytab must contain the exact matching principal, HTTP/inutil.cu@INUTIL.CU, and be readable by the user that runs Squid. The panel uses cache_effective_user or the default user reported by the runtime to check this; declare cache_effective_user if it cannot determine one. DNS, the FQDN configured on clients, and the realm must also agree. Do not use an IP address or an alias without a corresponding SPN. The full @REALM form is preferred; HTTP/inutil.cu without a realm is also helper syntax when Kerberos has the correct default realm.
Add one active negotiate helper and adjust the paths, FQDN, realm, and allowed network:
# Do not enable an NTLM alternative or a second negotiate helper at the same time.
auth_param negotiate program /usr/lib/squid/negotiate_kerberos_auth -k /var/run/squid/HTTP.keytab -s HTTP/inutil.cu@INUTIL.CU
auth_param negotiate children 10 startup=5 idle=3
auth_param negotiate keep_alive on
# Any valid Kerberos identity satisfies this ACL.
acl kerberos_auth proxy_auth REQUIRED
# Keep port/security denies and Cache Manager exceptions above this rule.
# This challenges unauthenticated clients before an allow such as localnet.
http_access deny !kerberos_auth
http_access allow localnet
http_access deny allhttp_access order is critical: Cache Manager exceptions (http_access allow ... manager and http_access deny manager) and existing port/security denies must remain before the Kerberos rule, which must be before the first client allow and the final http_access deny all. The negated rule http_access deny !kerberos_auth makes Squid issue the authentication challenge before a later allow localnet; a lone allow kerberos_auth is not enough for all clients. The example is literal squid.conf syntax: use auth_param and keep_alive, not Markdown-escaped auth_param or keep_alive.
In the administration panel, open /admin/kerberos-config to set helper_path, keytab_path, service_principal, children/startup/idle, keep_alive, optional realm stripping, the ACL, and its access rule. Review the generated block, apply the rule, and reload Squid only after sudo squid -f /path/to/squid.conf -k parse succeeds; then run sudo systemctl reload squid (or your distribution's reload mechanism). Realm stripping changes the identity seen by logs and quotas: with -r it is normally user; without it it is normally user@REALM, so keep quota entries consistent with that choice.
Debian package: the bundled unit runs the application without privileges and protects /etc/squid with ProtectSystem=full. The Kerberos page is therefore manual-only: it can generate and copy a preview, but cannot write squid.conf or keytabs. Apply the block through a controlled administrative procedure. Other deployments retain managed mode unless they set this variable. SQUIDSTATS_SQUID_CONFIG_WRITE_MODE=managed is an explicit opt-in only after deploying a separate, narrowly scoped and audited privileged mechanism; changing that variable alone does not grant permission. Do not give the web process broad write access to /etc/squid or broad access to keytabs.
When Squid runs in Docker, the SQUID_CONFIG_PATH edited by SquidStats must be mounted at the configuration file actually loaded by the container (for example, ./squid.conf:/etc/squid/squid.conf). If the configuration is modular, mount the directory containing 50_auth.conf and 120_http_access.conf too; mounting only the main file is not enough. Set SQUID_RUNTIME=docker so checks and reloads run inside the container; this is required rather than relying on auto when a host Squid binary also exists. SQUID_DOCKER_CONTAINER=squid_proxy is the default, and SQUID_CONTAINER_CONFIG_PATH is only needed when Squid uses a different internal path. SquidStats needs Docker CLI/socket access for those checks. Mount the keytab securely in the container—the panel never copies it.
Do not use the squid.conf split operation while Kerberos/Negotiate is active. SquidStats blocks it to avoid changing include order or separating managed blocks; migrate or disable Kerberos from this screen before splitting the configuration.
- Install with script:
curl -fsSL https://github.com/kaelthasmanu/SquidStats/releases/download/2.6.1/install.sh | sudo bashor
wget -qO- https://github.com/kaelthasmanu/SquidStats/releases/download/2.6.1/install.sh | sudo bashThe installer now supports multiple modes:
# Full installation (interactive)
sudo ./install.sh
# Update existing installation
sudo ./install.sh --update
# Show help
./install.sh --helpSquidStats can be installed using prebuilt .deb packages or by using the official Ubuntu PPA repository.
Important: The .deb package installations are not compatible with the script-based installation. You must choose one or the other — do not combine them. Install SquidStats using only one of the two methods.
- Visit the project's Releases page: https://github.com/kaelthasmanu/SquidStats/releases
- Download the package that matches your distribution and version. Currently available packages include:
- Debian 12
- Debian 13
- Ubuntu 24.04 LTS
- Ubuntu 26.04 LTS
Note: Package names include the SquidStats version number and may change between releases. Always download the latest version available for your distribution.
- Install the downloaded package:
sudo dpkg -i squidstats_*.deb- If the system reports unmet dependencies, install them with:
sudo apt install -fThe recommended way to install SquidStats on Ubuntu is via the official PPA, which allows you to receive updates automatically through the system package manager.
sudo add-apt-repository ppa:kaelthasmanu/squidstats
sudo apt updatesudo apt install squidstatsIf SquidStats was installed from the PPA, new versions will be available through the system updates:
sudo apt update
sudo apt upgradeTo verify the installation was successful:
squidstats --versionIf the command returns the installed version, SquidStats is ready to use.
- Clone the repository:
mkdir -p /opt/SquidStats git clone https://github.com/kaelthasmanu/SquidStats.git /opt/SquidStats
- Creating a virtual environment (venv):
cd /opt/SquidStats/
python3 -m venv "/opt/SquidStats/venv"
source venv/bin/activate
pip install --upgrade pip- Install requeriments python with pip or pip3:
pip install -r /opt/SquidStats/requirements.txt- Create a .env file in the project root and add the following content:
Note: for use MARIADB need your own database running# Application Version VERSION="2.6.1" # Security Keys # Generate with: python3 -c 'import secrets; print(secrets.token_hex(32))' SECRET_KEY="your-secret-key-here" # Squid Configuration SQUID_HOST="127.0.0.1" SQUID_PORT="3128" SQUID_LOG="/var/log/squid/access.log" SQUID_CACHE_LOG="/var/log/squid/cache.log" SQUID_CONFIG_PATH="/etc/squid/squid.conf" ACL_FILES_DIR="/etc/squid/acls" # Optional Cache Manager credentials (use an empty user for password-only auth) SQUID_MGR_PASS="" # Database Configuration # Options: SQLITE or MARIADB or MYSQL or POSTGRESQL DATABASE_TYPE="SQLITE" # For SQLite: directory path DATABASE_STRING_CONNECTION="/opt/SquidStats/squidstats.db" # For MariaDB/MySQL: connection string -> mysql+pymysql://user:pass@host:port/db # For Postgresql: connection string -> postgresql+psycopg2://user:pass@127.0.0.1:5432/squidstats # Flask Application Settings FLASK_DEBUG="False" # Set to True only for development LISTEN_HOST="0.0.0.0" LISTEN_PORT="5000" REFRESH_INTERVAL="60" # Authentication & Security # Initial admin password (change after first login) FIRST_PASSWORD="mipassword" JWT_EXPIRY_HOURS="24" MAX_LOGIN_ATTEMPTS="5" LOCKOUT_DURATION_MINUTES="15" # Blacklist Configuration BLACKLIST_DOMAINS="facebook.com,twitter.com,instagram.com,tiktok.com,youtube.com,netflix.com" # Proxy Configuration (Optional) # Example: http://proxy.example.com:8080 HTTP_PROXY="" # Example: https://proxy.example.com:8443 HTTPS_PROXY="" # Comma-separated list of hosts to bypass proxy NO_PROXY=""
If you install SquidStats on a different machine than the Squid proxy (i.e. Squid is not local on the SquidStats server), you must ensure that the Squid access log (/var/log/squid/access.log) is available on the SquidStats server. The recommended and reliable way to do this is to forward Squid's log entries via syslog (rsyslog or syslog-ng) from the proxy host to the SquidStats host.
Below are example configurations for both sending (on the Squid proxy host) and receiving (on the SquidStats server). Adjust IP addresses, ports and file paths to your environment.
NOTE: forwarding logs avoids copying files and ensures live updates for the dashboard.
-
Using rsyslog (proxy = 192.168.1.10, squidstats = 192.168.1.20)
On the Squid proxy (send): edit
/etc/rsyslog.d/30-squid.confand add:# rsyslog - forward squid access log lines to remote host # create a local file watch (imfile) to read Squid access.log module(load="imfile" PollingInterval="10") input(type="imfile" File="/var/log/squid/access.log" Tag="squid_access:" Severity="info" Facility="local0") # forward to remote syslog collector *.* @@192.168.1.20:514
On the SquidStats server (receive): enable UDP/TCP syslog reception and store to file. Example
/etc/rsyslog.d/10-remote.conf:# rsyslog - accept remote logs module(load="imudp") input(type="imudp" port="514") # store squid forwarded logs if $programname == 'squid_access' or $syslogtag contains 'squid_access' then { /var/log/remote/squid/access.log stop }
Create the directory and set permissions:
sudo mkdir -p /var/log/remote/squid sudo chown syslog:adm /var/log/remote/squid sudo systemctl restart rsyslog
-
Using syslog-ng (proxy send):
Edit
/etc/syslog-ng/conf.d/squid-forward.confon the proxy host:source s_squid { file("/var/log/squid/access.log" follow-freq(1)); }; destination d_remote { tcp("192.168.1.20" port(514)); }; log { source(s_squid); destination(d_remote); };On the SquidStats server (receive) with syslog-ng, accept and write to disk:
source s_network { tcp(port(514)); }; destination d_squid { file("/var/log/remote/squid/access.log"); }; filter f_squid { program("squid_access") or match("^\d+\.\d+\.\d+\.\d+ .*squid" type("regexp")); }; log { source(s_network); filter(f_squid); destination(d_squid); }; -
Firewall and permissions
- Open port 514 (or the port you choose) on the SquidStats server and allow the proxy host to connect.
- Use TCP if you care about delivery guarantees; UDP is faster but lossy.
- Ensure the syslog daemon user can write to the destination directory (
/var/log/remote/squid).
-
Update
SQUID_HOSTin.env- If you forward logs, set
SQUID_HOSTin the SquidStats.envto the IP of the original Squid host or keep it as127.0.0.1if SquidStats will process them as local files (i.e., they are written under/var/log/remote/squid/access.loglocally).
- If you forward logs, set
Examples & notes
- This approach is preferred over mounting remote filesystems or using scp/rsync cron jobs because it provides near real-time updates and is resilient to log rotation when configured correctly.
- Run App with python or python3 🚀:
python3 app.py- With your preferred browser, visit the installation URL:
http://ip/hostname:5000SquidStats can monitor multiple Squid proxies simultaneously, aggregating their active connections into a single unified dashboard view.
When SQUID_HOSTS is set, SquidStats queries all listed proxies in parallel on every refresh. It then:
- Merges the active connections from all nodes into one view.
- Shows a status bar at the top of the dashboard indicating whether each proxy is reachable (green) or not (red).
- Adds filter buttons so you can isolate connections by proxy node.
- Tags each user/connection row with the originating proxy.
If SQUID_HOSTS is not set, SquidStats falls back to the single SQUID_HOST / SQUID_PORT values (fully backward-compatible).
Edit your .env file and set SQUID_HOSTS as a comma-separated list of host:port entries:
# Single proxy (default behaviour — keep using these)
SQUID_HOST="192.168.1.10"
SQUID_PORT="3128"
# Multi-proxy: uncomment and list all your Squid nodes.
# This overrides SQUID_HOST / SQUID_PORT for the connections page.
# Supports plain IPv4, hostnames, and IPv6 literals ([::1]:3128).
SQUID_HOSTS="192.168.1.10:3128,192.168.1.11:3128,192.168.1.12:3128"Note: Each Squid node must be configured to allow Cache Manager access from the SquidStats server IP. See the Cache Manager Configuration section above.
| Feature | Description |
|---|---|
| Proxy status bar | At the top of the connections page, each proxy shows a green ✅ or red ❌ badge. |
| Filter tabs | Click a proxy label to show only the connections coming from that node. |
| Proxy badge per user | Each user accordion shows which proxy their connections were fetched from. |
| Proxy column in table | Each individual connection row has a "Proxy" column identifying its source node. |
| Squid status card | Replaced by the status bar in multi-proxy mode to avoid redundancy. |
To access the admin panel, you need to configure the initial password and restart the service.
-
Edit the
.envfile using your preferred editor (vi, vim, or nano). Here's an example using nano:nano .env
Add or modify the following line in the
.envfile:FIRST_PASSWORD="mipassword"Save the file and exit the editor (in nano, press Ctrl+X, then Y, then Enter).
-
Restart the SquidStats service:
sudo systemctl restart squidstats.service
-
Access the admin panel by visiting
http://your-ip:your-port/adminin your browser. -
Log in with the username
adminand the password you set inFIRST_PASSWORD(in this example, "mipassword").
SquidStats supports sending notifications via Telegram. This feature allows you to receive real-time alerts about security events, system status, and important activities directly on your Telegram account or groups.
- A Telegram account
- Telegram API credentials (from my.telegram.org)
- Optional: A Telegram Bot Token (from @BotFather)
- Visit https://my.telegram.org
- Log in with your phone number
- Go to API development tools
- Create a new application
- Copy your
api_idandapi_hash
Edit your .env file and configure the Telegram variables:
# Enable Telegram notifications
TELEGRAM_ENABLED="true"
# API Credentials from my.telegram.org
TELEGRAM_API_ID="your_api_id"
TELEGRAM_API_HASH="your_api_hash"
# Optional: Bot Token from @BotFather (recommended for production)
TELEGRAM_BOT_TOKEN="123456789:ABCdefGHIjklMNOpqrsTUVwxyz"
# Optional: Your phone number (format: +1234567890)
TELEGRAM_PHONE="+1234567890"
# Session name for storing Telegram connection
TELEGRAM_SESSION_NAME="squidstats_bot"
# Recipients (comma-separated)
# Can be: usernames (@username), phone numbers (+1234567890), or chat IDs (-1001234567890)
TELEGRAM_RECIPIENTS="@your_username,-1001234567890"To send notifications to groups or channels, you need their chat ID:
- Add your bot to the group/channel
- Send a message in the group
- Visit:
https://api.telegram.org/bot<YOUR_BOT_TOKEN>/getUpdates - Look for
"chat":{"id":-1001234567890}in the response
If SquidStats runs behind a proxy, configure the proxy settings:
HTTP_PROXY="http://proxy.example.com:8080"
HTTPS_PROXY="https://proxy.example.com:8443"
NO_PROXY="localhost,127.0.0.1"If you lose the admin password, you can reset it from the server where SquidStats runs (localhost only):
- Make sure the app is running (default listens on
127.0.0.1:5000, or theLISTEN_PORTyou set in.env). - Run this from the SquidStats host:
curl -X POST http://127.0.0.1:5000/auth/reset-password \
-H "Content-Type: application/json" \
-d '{"username": "admin", "new_password": "NewSecurePass123"}'Notes:
- Must be executed on localhost; remote calls are rejected.
new_passwordmust be at least 8 characters.- You can also send form data if preferred:
curl -X POST http://127.0.0.1:5000/auth/reset-password \ -d "username=admin" \ -d "new_password=NewSecurePass123"
The Reset connections action in a user's menu terminates the active network states associated with that user's IP address. This is an operating system operation, not a Squid reconfiguration, and requires root-equivalent privileges:
- Linux: install
conntrack(apt install conntrack) and grant SquidStats the required access to the binary. SquidStats runsconntrack -D -s IP. - macOS/BSD: the action uses
pfctl -k IP; PF must be enabled, and the process must be allowed to runpfctlwith administrative privileges. - Other systems: the interface reports that this capability is not available without modifying any connections.
On Linux, add the following iptables rules on the Squid proxy host so that
conntrack can track the proxy connections on port 3128:
iptables -t filter -I INPUT -p tcp --dport 3128 -m state --state NEW,ESTABLISHED -j ACCEPT
iptables -t filter -I OUTPUT -p tcp --sport 3128 -m state --state ESTABLISHED -j ACCEPT
iptables -t filter -I FORWARD -p tcp --dport 3128 -j ACCEPT
iptables -t filter -I FORWARD -p tcp --sport 3128 -j ACCEPTResetting only affects states tracked by the host firewall. In a Docker installation, or when Squid is behind another NAT device, the operation must run on the host that actually maintains those states; otherwise, client connections cannot be closed by IP address.
Warning: 🚨 The first execution may cause high CPU usage.
- Get Script With curl o wget:
wget https://github.com/kaelthasmanu/SquidStats/releases/download/2.6.1/install.sh- Add permission execution:
sudo chmod +x install.sh- Execute the script with parameters update:
sudo ./install.sh --update🕒 Run on System Startup To ensure the application starts automatically when the system boot :
- Copy file service:
cp ./utils/squidstats.service /etc/systemd/system/squidstats.service- Restart daemons:
systemctl daemon-reload- Enable service:
systemctl enable squidstats.service- Start service:
systemctl start squidstats.serviceThis software has been thoroughly tested and is compatible with Squid version 6.12+ in the following distributions:
- Ubuntu: 24.04 LTS and 26.04 LTS
- Debian: 12 and 13
- Alpine Linux: 3.23.3
Please ensure your Squid installation matches this version or newer for optimal performance. For Docker container environments, Alpine Linux 3.23.3 is recommended due to its small size and compatibility.
The installation script now includes a complete uninstall option that cleans all system components:
- Get the installation script (if you don't have it):
wget https://github.com/kaelthasmanu/SquidStats/releases/download/1.0/install.sh
chmod +x install.sh- Run the uninstallation:
sudo ./install.sh --uninstallThe COMPLETE uninstallation performs the following actions:
- 🛑 Stops and disables the systemd service
squidstats.service - 🗑️ Removes files from the
/opt/squidstatsdirectory ⚠️ Requires confirmation from user before proceeding
If you prefer to uninstall manually:
# Stop and disable service
sudo systemctl stop squidstats.service
sudo systemctl disable squidstats.service
sudo rm -f /etc/systemd/system/squidstats.service
sudo systemctl daemon-reload
# Remove project files
sudo rm -rf /opt/squidstats- Uninstallation will permanently delete all SquidStats data and configurations
- It's recommended to backup any custom configurations before uninstalling
- Optimization and Performance ⚡
- Enhanced data caching
- Historical log compression
Multi-proxy support✅ Implemented — see Multi-Proxy Mode
- Fork the repository:
2.Create a new branch for your feature or fix:
git checkout -b feature-name
git checkout -b feature-name3.Commit your changes and push the branch:
git push origin feature-name4.Open a pull request.
The SquidStats project is released under the MIT license.
Need help? Feel free to contact me 📨 manuelalberto.gorrin@gmail.com You can also reach me on Telegram: @king_0f_deathhh
Backend: Python, Flask
Frontend: HTML, CSS, JavaScript
- To the Cuban Sysadmins community.
- To everyone who gave me his help when I had doubts.



