Skip to content
maraventoPublic

About

Traffic management and auditing tool for Squid proxy server

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Latest commit

 

History

25 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

status-maintained last commit Stargazers Twitter Follow

Traditional tools for monitoring and auditing Squid-Cache traffic—such as sarg, sqstat, lightsquid or squidanalyzer—have been discontinued or without active maintenance for years, leaving a gap in the administration of Linux proxy environments.

Proxymon was created to recover and modernize these capabilities in a single open-source web dashboard. It integrates real-time connection and traffic monitoring, log exploration and historical reports on per-user data usage, most visited sites and blocked requests.

Additionally, it allows daily, weekly and monthly data usage limits to be set, restricts access for devices that exceed their quotas and redirects their requests to a warning page. It also incorporates AI-assisted queries to interpret logs through natural-language questions.

Las herramientas tradicionales para supervisar y auditar el tráfico de Squid-Cache —como sarg, sqstat, lightsquid o squidanalyzer— llevan años discontinuadas o sin mantenimiento activo, lo que ha dejado un vacío en la administración de entornos proxy en Linux.

Proxymon nace para recuperar y modernizar esas capacidades en un único panel web de código abierto. Integra supervisión de conexiones y tráfico en tiempo real, exploración de registros e informes históricos sobre consumo por usuario, sitios más visitados y solicitudes bloqueadas.

Adicionalmente, permite establecer límites de consumo diarios, semanales y mensuales, restringir el acceso de los equipos que superen sus cuotas y redirigir sus solicitudes a una página de aviso. También incorpora consultas asistidas por inteligencia artificial para interpretar los registros mediante preguntas en lenguaje natural.

REQUIREMENTS


Compatibility

Only tested on Ubuntu 24.04/26.04 LTS. Other versions or distributions are not tested and are used at your own risk. Solo probado en Ubuntu 24.04/26.04 LTS. Otras versiones o distribuciones no están probadas y se usan bajo tu responsabilidad.

Network

Installation and update require the following:

  • At least one interface must have an UP link and configured global IPv4.
  • Internet access is required when installing or updating packages and downloading components.
  • The selected LAN IPv4 must be static and persistent.

The operation continues if the applicable requirements above are met; otherwise, it aborts.

La instalación y actualización requieren lo siguiente:

  • Al menos una interfaz debe tener enlace UP e IPv4 global configurada.
  • Se requiere Internet para instalar o actualizar paquetes y descargar componentes.
  • La IPv4 LAN seleccionada debe ser estática y persistente.

La operación continúa si se cumplen los requisitos anteriores que correspondan; de lo contrario, aborta.

Hardware

CPU RAM Storage
Intel Core i5/Xeon/AMD Ryzen 5 (≥ 3.0 GHz) 16 GB 2 GB SSD

Software

Component Version
Squid Cache v6.13
Apache v2.4.58
PHP 8.3.6

• pmsetup.sh installs Apache and PHP when they are missing. --install and --update also install every missing package the project needs. It also installs squid-openssl, the flavour that supports SSL bump, when no Squid is present.

• An existing Squid is left untouched, including its squid.conf. Only a Squid installed by the installer receives the bundled template.

• The installer sets weekly rotation in /etc/logrotate.d/squid in both cases. It also sets rotate 7 in /etc/logrotate.d/apache2, backing it up first.

• The installer installs missing supporting packages listed below.

• The Squid, PHP and Apache blocks below are optional tuning, not prerequisites.

• pmsetup.sh instala Apache y PHP cuando faltan. --install y --update también instalan todos los paquetes que falten al proyecto. También instala squid-openssl, la variante que admite SSL bump, cuando no hay ningún Squid presente.

• Un Squid existente no se modifica, tampoco su squid.conf. Solo un Squid instalado por el instalador recibe la plantilla incluida.

• El instalador fija la rotación semanal en /etc/logrotate.d/squid en ambos casos. También fija rotate 7 en /etc/logrotate.d/apache2, con respaldo previo.

• El instalador instala los paquetes auxiliares que falten de la lista siguiente.

• Los bloques de Squid, PHP y Apache de abajo son ajustes opcionales, no requisitos.

# other required packages (checked by pmsetup.sh, no extra setup needed)
apt install -y wget curl git zip unzip ipset nbtscan libcgi-pm-perl libgd-perl libjson-xs-perl \
                coreutils fonts-lato fonts-liberation fonts-dejavu \
                perl python3 python3-yaml cron sudo util-linux iproute2 passwd findutils sed \
                grep hostname ncurses-bin systemd libc-bin iptables \
                gzip procps logrotate diffutils

# squid
apt install -y squid-openssl squid-langpack squid-common squidclient squid-purge
mkdir -p /var/log/squid &>/dev/null
touch /var/log/squid/{access,cache,store,deny}.log &>/dev/null
chown proxy:proxy /var/log/squid/*.log
chmod 640 /var/log/squid/*.log
for cache_type in rock ufs; do
    mkdir -p /var/spool/squid/${cache_type} 2>/dev/null
done
chown -R proxy:proxy /var/spool/squid
chmod -R 700 /var/spool/squid
usermod -aG proxy www-data
systemctl enable squid.service
squid -z
cp -f /etc/logrotate.d/squid{,.bak} &>/dev/null
sed -i '/sharedscripts/a \    create 0644 proxy proxy' /etc/logrotate.d/squid
sed -i 's/rotate 2/rotate 7/' /etc/logrotate.d/squid
sed -i -E 's/^([[:space:]]*)(hourly|daily|monthly|yearly)$/\1weekly/' /etc/logrotate.d/squid

# php
apt install -y php libapache2-mod-php php-cli php-curl
# Detect PHP version
if command -v php &>/dev/null; then
    PHP_VERSION=$(php -r "echo PHP_MAJOR_VERSION.'.'.PHP_MINOR_VERSION;" 2>/dev/null)
    echo "PHP version detected: $PHP_VERSION"
else
    echo "Error: PHP not installed"
    exit 1
fi
# Ensure php.ini exists for Apache
if [ ! -f /etc/php/$PHP_VERSION/apache2/php.ini ]; then
    if [ -f /etc/php/$PHP_VERSION/cli/php.ini ]; then
        mkdir -p /etc/php/$PHP_VERSION/apache2
        cp /etc/php/$PHP_VERSION/cli/php.ini /etc/php/$PHP_VERSION/apache2/php.ini
        echo "php.ini copied to /etc/php/$PHP_VERSION/apache2/"
    else
        echo "Error: php.ini not found"
        exit 1
    fi
fi
cp -f /etc/php/$PHP_VERSION/apache2/php.ini{,.bak} &>/dev/null
sed -i \
  -e 's/^\s*;*\s*max_execution_time\s*=.*/max_execution_time = 120/' \
  -e 's/^\s*max_input_time\s*=.*/max_input_time = 120/' \
  -e 's/^;\s*max_input_time\s*=.*/max_input_time = 120/' \
  -e 's/^\s*memory_limit\s*=.*/memory_limit = 1024M/' \
  -e 's/^\s*post_max_size\s*=.*/post_max_size = 64M/' \
  -e 's/^\s*upload_max_filesize\s*=.*/upload_max_filesize = 64M/' \
  -e 's/^\s*;*\s*opcache.memory_consumption\s*=.*/opcache.memory_consumption = 256/' \
  -e 's/^\s*;*\s*realpath_cache_size\s*=.*/realpath_cache_size = 16M/' \
  /etc/php/$PHP_VERSION/apache2/php.ini

# apache
apt install -y apache2 apache2-doc apache2-utils apache2-dev \
                apache2-suexec-pristine libaprutil1t64 libaprutil1-dev \
                libtest-fatal-perl
systemctl enable apache2.service
apt -qq install -y --reinstall apache2-doc
cp -f /etc/apache2/mods-available/mpm_prefork.conf{,.bak} &>/dev/null
sed -i \
  -e 's/^\(StartServers[[:space:]]*\)5/\110/' \
  -e 's/^\(MinSpareServers[[:space:]]*\)5/\110/' \
  -e 's/^\(MaxSpareServers[[:space:]]*\)10/\115/' \
  -e 's/^\(MaxRequestWorkers[[:space:]]*\)150/\1200/' \
  -e 's/^\(MaxConnectionsPerChild[[:space:]]*\)0/\11000/' \
  /etc/apache2/mods-available/mpm_prefork.conf
# Enable modules
a2dismod -q mpm_event || true
a2enmod -q mpm_prefork || true
a2enmod -q php || true

REPOSITORY STRUCTURE


proxymon/
├── modules/                              # deployed to: /var/www/proxymon [0755 root:root]
│   ├── ProxymonEnv.pm                    # shared Perl configuration reader [0644 root:root]
│   ├── index.html                        # main page with module tabs [0644 root:root]
│   ├── logview/                          # access logs and live requests [0755 root:root]
│   │   ├── LICENSE-SqStat                # SqStat license [0644 root:root]
│   │   ├── access.php                    # access log view [0644 root:root]
│   │   ├── api.php                       # log and traffic API [0644 root:root]
│   │   ├── connections.php               # live connections view [0644 root:root]
│   │   ├── env.php                       # configuration reader [0644 root:root]
│   │   ├── index.php                     # LogView entry point [0644 root:root]
│   │   ├── sqstat-dark.css               # dark theme styles [0644 root:root]
│   │   ├── sqstat.class.php              # SqStat PHP class [0644 root:root]
│   │   ├── sqstat.css                    # SqStat styles [0644 root:root]
│   │   └── theme.js                      # theme controls [0644 root:root]
│   ├── squidai/                          # conversational assistant [0755 root:root]
│   │   ├── dataset.md                    # assistant reference data [0644 root:root]
│   │   ├── index.html                    # assistant interface [0644 root:root]
│   │   └── worker.php                    # assistant backend [0644 root:root]
│   ├── squidmon/                         # real-time traffic monitor [0755 root:root]
│   │   ├── CHANGELOG                     # Squidmon change history [0644 root:root]
│   │   ├── config.cgi                    # configuration interface [0755 root:root]
│   │   ├── etc/                          # configuration directory [0755 root:root]
│   │   │   └── config                    # editable Squidmon settings [0644 www-data:www-data]
│   │   ├── lang/                         # translations [0755 root:root]
│   │   │   ├── en                        # English strings [0644 root:root]
│   │   │   └── es                        # Spanish strings [0644 root:root]
│   │   ├── pdf_report.cgi                # PDF report generator [0755 root:root]
│   │   ├── squidmon-standalone.pl        # standalone support [0644 root:root]
│   │   └── squidmon.cgi                  # Squidmon entry point [0755 root:root]
│   ├── squidreports/                     # traffic reports and web assets [0755 root:root]
│   │   ├── assets/
│   │   │   └── global/
│   │   │       └── plugins/
│   │   │           └── bootstrap-switch/
│   │   │               └── js/           # example asset directory [0755 root:root]
│   │   ├── report/                       # generated reports [0755 www-data:www-data]
│   │   ├── reportstats/                  # generated report statistics [0755 www-data:www-data]
│   │   └── tpl/
│   │       └── metro_tpl/
│   │           └── graph.html            # example report template [0644 root:root]
│   └── warning/                          # usage quota warning page [0755 root:root]
│       └── warning.html                  # warning page [0644 root:root]
├── config/                               # deployed configuration under /etc/proxymon [0750 root:www-data]
│   ├── .env                              # generated LLM settings [0640 root:www-data]
│   ├── proxymon.env                      # generated project settings [0640 root:www-data]
│   ├── update-files.txt                  # required web files checked during updates
│   ├── bandata/                          # deployed to: /etc/proxymon/bandata [0755 root:root]
│   │   ├── bandata.sh                    # enforces data usage quotas [0750 root:root]
│   │   └── acl/                          # Bandata ACL files [0700 root:root]
│   │       ├── allowdata.txt             # quota exceptions [0600 root:root]
│   │       ├── banday.txt                # daily blocks [0600 root:root]
│   │       ├── banmonth.txt              # monthly blocks [0600 root:root]
│   │       └── banweek.txt               # weekly blocks [0600 root:root]
│   ├── tools/                            # deployed to: /etc/proxymon/tools [0755 root:root]
│   │   ├── pmbk.sh                       # configuration backup [0750 root:root]
│   │   ├── proxymonenv.sh                # shared Bash configuration reader [0644 root:root]
│   │   ├── reports/                      # traffic report tools [0755 root:root]
│   │   └── squidtool.sh                  # log search and traffic reports [0750 root:root]
│   ├── squid/                            # Squid configuration for fresh installations
│   └── web/                              # Apache virtual host templates
│       ├── proxymon.conf                 # deployed to: /etc/apache2/sites-available/proxymon.conf [0644 root:root]
│       └── warning.conf                  # deployed to: /etc/apache2/sites-available/warning.conf [0644 root:root]
└── pmsetup.sh                            # installer, updater and uninstaller

Additional Installed Paths

etc/
├── acl/                                  # administrator ACL directory [0700 root:root]
├── apache2/
│   └── sites-enabled/
│       ├── proxymon.conf                 # link to ../sites-available/proxymon.conf [0777 root:root]
│       └── warning.conf                  # link to ../sites-available/warning.conf [0777 root:root]
├── bak/
│   └── proxymon                          # configuration backups [0700 root:root]
├── cron.d/
│   ├── proxymon                          # ProxyMon scheduled tasks [0644 root:root]
│   └── proxymon.lock                     # cron writer lock [0600 root:root]
├── logrotate.d/
│   └── proxymon                          # ProxyMon log rotation policy [0644 root:root]
└── squid/
    └── acl/                              # Squid ACL directory, read by the proxy user [0755 root:root]
        ├── blockdomains.txt              # blocked domains [0644 root:root]
        ├── blockpatterns.txt             # blocked URL patterns [0644 root:root]
        └── blocktlds.txt                 # blocked top-level domains [0644 root:root]

var/
└── log/
    ├── apache2/
    │   ├── proxymon_access.log           # panel access log [0640 root:adm]
    │   ├── proxymon_error.log            # panel error log [0640 root:adm]
    │   ├── warning_access.log            # warning page access log [0640 root:adm]
    │   └── warning_error.log             # warning page error log [0640 root:adm]
    └── proxymon.log                      # ProxyMon application log [0640 root:adm]

HOW TO USE


git clone --depth=1 https://github.com/maravento/proxymon.git
cd proxymon

# Install
sudo bash pmsetup.sh --install

# Update
sudo bash pmsetup.sh --update

# Uninstall
sudo bash pmsetup.sh --uninstall

# Interactive menu
sudo bash pmsetup.sh

# Help
sudo bash pmsetup.sh --help   # or -h

Installer Options

Command Description Descripción
sudo ./pmsetup.sh Opens the interactive menu with options to install, update, uninstall or exit. Abre el menú interactivo con opciones para instalar, actualizar, desinstalar o salir.
sudo ./pmsetup.sh --install Installs and configures Proxy Monitor, including Apache rules, proxymon.env, ACL lists, Apache and PHP settings, and scheduled tasks. Stops if the configured WEB_ROOT already exists; use --update or --uninstall in that case. Instala y configura Proxy Monitor, incluidas las reglas de Apache, proxymon.env, las listas ACL, los ajustes de Apache y PHP y las tareas programadas. Se detiene si el directorio configurado en WEB_ROOT ya existe; en ese caso, use --update o --uninstall.
sudo ./pmsetup.sh --update Updates code and permissions without prompting for input. Preserves configuration and operational data. Actualiza el código y los permisos sin solicitar datos. Conserva la configuración y los datos de operación.
sudo ./pmsetup.sh --uninstall Requests confirmation before uninstalling Proxy Monitor. It removes the project only and never uninstalls APT packages: other projects and the system may share them. Solicita confirmación antes de desinstalar Proxy Monitor. Elimina solo el proyecto y nunca desinstala paquetes APT, porque otros proyectos y el sistema pueden compartirlos.
sudo ./pmsetup.sh -h / sudo ./pmsetup.sh --help Displays help with the available installer options. Muestra la ayuda con las opciones disponibles del instalador.

Traffic that bypasses Squid does not appear in its reports. The results in Squidmon Search and Traffic Search are examples. Actual results vary with your environment, the amount of log history, and the resources available to process ACLs.

El tráfico que no pase por Squid no aparecerá en sus informes. Los resultados de Squidmon Search y Traffic Search son ejemplos. Los resultados reales dependen del entorno, la cantidad de registros históricos y los recursos disponibles para procesar las ACL.

SCOPE


SCOPE ALCANCE
  • Monitoring of traffic recorded by Squid through recent-activity views, historical reports, log searches and AI-assisted natural-language queries.
  • Daily, weekly and monthly data quotas based on Squidreports data, with IPv4 blocking lists and redirection to a warning page through Bandata.
  • Display names associated with client identifiers through realname.cfg, without replacing the identifiers used for quotas.
  • Access to active and uncompressed rotated logs according to each module’s coverage; command-line searches of compressed rotations through squidtool.sh.
  • Supervisión del tráfico registrado por Squid mediante vistas de actividad reciente, informes históricos, búsquedas en registros y consultas en lenguaje natural asistidas por IA.
  • Cuotas de consumo diarias, semanales y mensuales basadas en los datos de Squidreports, con listas de bloqueo IPv4 y redirección a una página de aviso mediante Bandata.
  • Nombres visibles asociados a los identificadores de clientes mediante realname.cfg, sin sustituir los identificadores utilizados para las cuotas.
  • Acceso a registros activos y rotados sin comprimir según la cobertura de cada módulo; búsqueda de rotados comprimidos mediante squidtool.sh desde la terminal.
OUT OF SCOPE FUERA DE ALCANCE
  • Monitoring traffic that does not pass through Squid.
  • Reading DHCP server configuration or leases as a source of client names.
  • Full IPv6 support, including IPv6 quota enforcement through Bandata. Individual modules can process IPv6 addresses for specific reporting and query functions.
  • Direct reading of compressed Squid logs by Squidmon, Logview or SquidAI.
  • Supervisión del tráfico que no pasa por Squid.
  • Lectura de configuraciones o concesiones de servidores DHCP como fuente de nombres de clientes.
  • Soporte completo de IPv6, incluida la aplicación de cuotas IPv6 mediante Bandata. Algunos módulos procesan direcciones IPv6 para funciones concretas de informes y consultas.
  • Lectura directa de registros comprimidos de Squid desde Squidmon, Logview o SquidAI.

HOW IT WORKS


Update checks

Step Description Descripción
Before copying The installer checks all required source files and destinations, write access, available space, immutable attributes and relevant locks. El instalador comprueba todos los orígenes y destinos, escritura, espacio disponible, atributos inmutables y bloqueos relevantes.
Backup The installer invokes pmbk.sh. If pmbk.sh fails, the installer aborts before pausing consumers or replacing files, without writing done. El instalador invoca pmbk.sh. Si pmbk.sh falla, el instalador aborta antes de pausar procesos o reemplazar archivos, sin escribir done.
Pause The installer pauses its cron file and stops affected services and daemons. It verifies they have stopped and waits for running jobs before replacing files. If a pause fails before any replacement, the installer attempts to resume the previous consumers and schedule. El instalador pausa su archivo cron y detiene los servicios y demonios afectados. Comprueba su detención y espera que terminen las tareas en ejecución antes de reemplazar archivos. Si falla una pausa antes de reemplazar archivos, el instalador intenta reanudar los procesos y la programación anteriores.
Copy The installer repeats the checks immediately before copying. It verifies every replacement and its file contents. If a replacement fails, it aborts without done; it does not resume the consumers or restore the backup. The paused schedule remains at /etc/cron.d/proxymon.update-disabled. El instalador repite las comprobaciones inmediatamente antes de copiar. Comprueba cada reemplazo y el contenido copiado. Si falla un reemplazo, aborta sin done; no reanuda los procesos ni restaura el respaldo. La programación pausada permanece en /etc/cron.d/proxymon.update-disabled.
Finish The installer regenerates its complete cron file and resumes the consumers that were active. It writes done only after successful completion. El instalador regenera su archivo cron completo y reanuda los procesos que estaban activos. Escribe done únicamente si termina correctamente.

Installer behavior

Only interfaces with an UP link and global IPv4 are candidates. With none, abort; with one, select LAN automatically; with several, ask for LAN and omit the others. A caller can provide PROXYMON_LAN; validate it against the candidates and reuse it without asking for the interface. With several LAN IPv4 addresses, ask which to use unless PROXYMON_SERVER_IP supplies a configured address. Ask for BANDATA_DNS, the one or two resolvers that blocked clients may query, with no default; an unattended caller passes it in PROXYMON_BANDATA_DNS, or the install aborts. An existing proxymon.env is preserved without repeating network selection. Derive the network and mask from the selected address and its actual prefix. The installer does not configure network interfaces. Solo son candidatas las interfaces con enlace UP e IPv4 global. Sin candidatas, aborta; con una, selecciona LAN automáticamente; con varias, pregunta LAN y omite las demás. Otro instalador puede proporcionar PROXYMON_LAN; se valida contra las candidatas y se reutiliza sin preguntar la interfaz. Con varias IPv4 en LAN, pregunta cuál utilizar salvo que PROXYMON_SERVER_IP indique una dirección configurada. Pregunta BANDATA_DNS, los uno o dos resolvers que pueden consultar los clientes bloqueados, sin valor por defecto; un instalador desatendido la pasa en PROXYMON_BANDATA_DNS, o la instalación aborta. Un proxymon.env existente se conserva sin repetir la selección de red. Calcula red y máscara desde la dirección seleccionada y su prefijo real. El instalador no configura las interfaces de red.

update Behavior

• update updates the web content under WEB_ROOT, the root scripts under CONFIG_DIR and their permissions.

• Preserves PHP configuration, ACL lists and both configuration files (proxymon.env and the LLM .env) unchanged. Applies these values to Apache paths, Listen directives and the parser, Bandata and backup cron entries; retains other virtualhost directives.

• Creates a backup with pmbk.sh before stopping Apache, replaces the code and resumes Apache according to its recorded state.

• Application code and its directories are owned by root; preserved data and configuration retain their ownership.

• Repairs the owner and mode that install sets on the ACL directories (ACL_PATH, ACL_SQUID_PATH, ACL_BANDATA_PATH) and on their lists, without rewriting their content.

• Does not change the ownership or permissions of the shared /var/www directory.

• Rejects symbolic links in code directories and replaces code files without following destination links.

• The copy excludes the preserved files and directories listed below.
• update actualiza el contenido web de WEB_ROOT, los scripts ejecutados como root de CONFIG_DIR y sus permisos.

• Conserva la configuración de PHP, las listas ACL y ambos archivos de configuración (proxymon.env y .env del LLM) sin modificaciones. Aplica estos valores a las rutas de Apache, sus directivas Listen y las entradas de cron del parser, Bandata y copias; mantiene las demás directivas de los virtualhosts.

• Crea una copia de seguridad con pmbk.sh antes de detener Apache, reemplaza el código y reanuda Apache según su estado registrado.

• El código de la aplicación y sus directorios pertenecen a root; los datos y la configuración preservados conservan sus propietarios.

• Repara el propietario y los permisos que install fija en las carpetas ACL (ACL_PATH, ACL_SQUID_PATH, ACL_BANDATA_PATH) y en sus listas, sin reescribir su contenido.

• No cambia el propietario ni los permisos del directorio compartido /var/www.

• Rechaza enlaces simbólicos en directorios de código y reemplaza archivos de código sin seguir enlaces de destino.

• La copia excluye los archivos y directorios preservados que se enumeran a continuación.
Path Description Descripción
squidreports/report Daily Squidreports reports Informes diarios de Squidreports
squidreports/reportstats Additional statistics; preserved by update and included in the pmbk.sh backup Estadísticas adicionales; conservadas por update e incluidas en la copia de pmbk.sh
squidreports/realname.cfg Hostname mappings Correspondencia entre IP y nombres de equipo
squidreports/skipuser.cfg Excluded users Usuarios excluidos
squidreports/squidreports.cfg Squidreports configuration Configuración de Squidreports
squidreports/group.cfg User groups Grupos de usuarios
squidmon/etc/config Squidmon configuration file Archivo de configuración de Squidmon
warning/warning.html Captive portal warning page Página de aviso del portal cautivo
/etc/proxymon/bandata/acl Bandata quota lists Listas de cuota de Bandata

⚠️ WARNING -- Update interruptions: An interrupted update can leave code incomplete and Apache stopped. Review the installer log and backup before recovery.

⚠️ WARNING -- Update interruptions: Una actualización interrumpida puede dejar código incompleto y Apache detenido. Revise el log del instalador y el respaldo antes de recuperarla.

Uninstall behavior

Description Descripción
Uninstall preserves the shared ACL directory (ACL_PATH, /etc/acl by default). It does not offer to delete it. La desinstalación conserva el directorio compartido de ACL (ACL_PATH, /etc/acl por defecto). No ofrece eliminarlo.
After uninstalling, restart the computer to clear any remaining temporary Bandata rules. Después de desinstalar, reinicie el equipo para eliminar las reglas temporales de Bandata restantes.

Panel access

Access Proxymon: http://localhost:18770

Warning for Bandata: http://SERVER_IP:18771

The panel listens on port 18770 and the warning page on port 18771, registered by IANA as Unassigned.

El panel escucha en el puerto 18770 y la página de aviso en el puerto 18771, registrados por IANA como Sin asignar.

proxymon.env

Keys

Keys are grouped by use: General, Network, Squid, ACL, Squidreports, Squidmon, SquidAI, Squidtool, Bandata and Backup. Installation generates this layout; update leaves .env unchanged. All keys precede the final separator.

• pmsetup.sh creates /etc/proxymon/proxymon.env during installation.

• It provides shared settings for bandata.sh, squidtool.sh, logview/api.php, logview/connections.php, squidai/worker.php, Squidreports, Squidmon and pmbk.sh.

• Installation generates the keys. Existing configuration files must be adjusted manually when new keys are needed.

• The update option preserves its existing values.
Las claves se agrupan por uso: General, Network, Squid, ACL, Squidreports, Squidmon, SquidAI, Squidtool, Bandata y Backup. La instalación genera esta estructura; update conserva .env sin modificaciones. Todas las claves preceden al separador final.

• pmsetup.sh crea /etc/proxymon/proxymon.env durante la instalación.

• Contiene la configuración compartida que utilizan bandata.sh, squidtool.sh, logview/api.php, logview/connections.php, squidai/worker.php, Squidreports, Squidmon y pmbk.sh.

• La instalación genera las claves. Los archivos de configuración existentes deben ajustarse manualmente cuando se necesitan claves nuevas.

• La opción update conserva sus valores existentes.
Variable Read by Description Descripción
WEB_ROOT, CONFIG_DIR pmsetup.sh, pmbk.sh Web application and root-script directories. Defaults: /var/www/proxymon and /etc/proxymon. Directorios de la aplicación web y los scripts de root. Valores iniciales: /var/www/proxymon y /etc/proxymon.
PANEL_PORT, WARNING_PORT pmsetup.sh, squidtool.sh, worker.php, bandata.sh Panel and warning ports. Defaults: 18770 and 18771. Apache keeps the panel on loopback and the warning page on SERVER_IP. Puertos del panel y los avisos. Valores iniciales: 18770 y 18771. Apache mantiene el panel en localhost y los avisos en SERVER_IP.
PANEL_DOMAINS worker.php Public HTTPS panel domains accepted by SquidAI, separated by commas. Empty by default: only local panel origins are allowed. Use bare domains, without a scheme, port or path, for example proxy.example.com. See the SquidAI section. Dominios públicos HTTPS del panel admitidos por SquidAI, separados por comas. Vacío por defecto: solo se autorizan los orígenes locales del panel. Escriba dominios sin esquema, puerto ni ruta, por ejemplo proxy.example.com. Ver la sección SquidAI.
BACKUP_DIR pmbk.sh Backup destination. It must be /etc/bak/proxymon, a directory exclusive to pmbk.sh. Any other value aborts the backup. Destino de las copias de seguridad. Debe ser /etc/bak/proxymon, un directorio exclusivo de pmbk.sh. Cualquier otro valor aborta el respaldo.
TOOL_REPORT_DIR pmsetup.sh, squidtool.sh, pmbk.sh Directory for generated traffic and log-search HTML reports, served through Apache's Squidtool alias. Directorio de informes HTML de tráfico y búsqueda, publicado mediante el alias Squidtool de Apache.
SQUIDTOOL_MIN_HITS squidtool.sh Minimum requests per row in traffic reports without an IP filter. Default: 20, written automatically without a prompt. Changing this default is not recommended. Reports for one IP show all rows. Accepts nonnegative integers without leading zeros. Mínimo de solicitudes por fila en informes de tráfico sin filtro de IP. Valor inicial: 20, escrito automáticamente sin preguntas. No se recomienda modificar este valor. Los informes de una IP muestran todas las filas. Acepta enteros no negativos sin ceros iniciales.
SQUIDTOOL_ALERT_THRESHOLD squidtool.sh Request threshold for highlighting and counting traffic rows as alerts. Default: 300, written automatically without a prompt. Changing this default is not recommended. Accepts nonnegative integers without leading zeros. Umbral de solicitudes para resaltar y contar filas de tráfico como alertas. Valor inicial: 300, escrito automáticamente sin preguntas. No se recomienda modificar este valor. Acepta enteros no negativos sin ceros iniciales.
SQUIDMON_CONFIG pmsetup.sh, Squidmon, pmbk.sh Squidmon settings file. Its log source comes from SQUID_LOG_FILE. Archivo de configuración de Squidmon. Su registro de origen proviene de SQUID_LOG_FILE.
LLM_ENV_FILE pmsetup.sh, worker.php, pmbk.sh SquidAI credential file. Default: /etc/proxymon/.env. Archivo de credenciales de SquidAI. Valor inicial: /etc/proxymon/.env.
REPORT_STATS_PATH pmsetup.sh, Squidreports, SquidAI, pmbk.sh Additional Detail and Analyze statistics. Default: the original report directory followed by stats. Remains separate from Bandata's original reports. Estadísticas adicionales de Detail y Analyze. Valor inicial: directorio de informes originales seguido de stats. Permanece separado de los informes originales utilizados por Bandata.
LAN bandata.sh LAN interface the quota rules apply to Interfaz LAN a la que se aplican las reglas de cuota
SERVER_IP pmsetup.sh, worker.php Server's own IPv4; excluded from the reports IPv4 del servidor; se excluye de los informes
RANGE pmsetup.sh, squidreports.pl, analytics.cgi LAN network in CIDR notation. Used by Analyze and regenerated subnet statistics. Unmatched addresses remain individual. Missing, empty or invalid values stop these consumers. Does not configure Apache access. Red LAN en formato CIDR. La utilizan Analyze y las estadísticas por subred regeneradas. Las direcciones sin coincidencia permanecen individuales. Un valor ausente, vacío o inválido detiene estos consumidores. No configura el acceso de Apache.
REPORT_IP_GLOB bandata.sh Filename glob derived from the actual LAN prefix: /16 → 192.168.*.*, /24 or /25 → 192.168.10.* in these examples. Bandata applies RANGE as an exact network filter Patrón calculado desde el prefijo LAN real: /16 → 192.168.*.*, /24 o /25 → 192.168.10.* en estos ejemplos. Bandata aplica RANGE como filtro exacto de red
SQUIDREPORTS_DIR bandata.sh, Squidreports Squidreports installation directory Directorio de instalación de Squidreports
REPORT_PATH bandata.sh, worker.php, Squidreports, pmbk.sh Directory holding the daily Squidreports reports Directorio con los informes diarios de Squidreports
REALNAME_CFG, SKIPUSERS_CFG bandata.sh, worker.php, Squidreports Squidreports hostname mappings and excluded-user list Correspondencia entre IP y nombres de equipo, y lista de usuarios excluidos de Squidreports
ACL_PATH, ACL_SQUID_PATH pmsetup.sh, bandata.sh, worker.php Shared ACL directory (/etc/acl), containing mac-*.txt, and Squid ACL directory (/etc/squid/acl) Directorio ACL compartido (/etc/acl), que contiene mac-*.txt, y directorio ACL de Squid (/etc/squid/acl)
ACL_BANDATA_PATH bandata.sh Directory holding Bandata's own quota lists Directorio con las listas de cuota propias de Bandata
ALLOW_LIST bandata.sh allowdata.txt: IPs exempt from every quota. This is the only Bandata ACL the administrator edits, manually on the server. The web interface does not provide an editor. allowdata.txt: IP exentas de toda cuota. Es la única ACL de Bandata que edita el administrador, manualmente en el servidor. La interfaz web no permite editarla.
BLOCK_LIST_DAY, BLOCK_LIST_WEEK, BLOCK_LIST_MONTH bandata.sh banday.txt, banweek.txt and banmonth.txt: block lists managed automatically by Bandata. Do not edit them manually; the web interface does not provide an editor. banday.txt, banweek.txt y banmonth.txt: listas de bloqueo administradas automáticamente por Bandata. No deben editarse manualmente; la interfaz web no permite editarlas.
SQUID_LOG_DIR, SQUID_LOG_FILE pmsetup.sh, squidtool.sh, api.php, worker.php, Squidreports, Squidmon Squid log directory and access.log path Directorio de logs de Squid y ruta de access.log
SQUID_MGR_HOST, SQUID_MGR_PORT connections.php Where Squid's cache manager answers; Logview reads the requests in flight from it. SQUID_MGR_PORT defaults to 3128 and is shared with other projects Dirección y puerto del administrador de caché de Squid; Logview consulta allí las solicitudes en curso. SQUID_MGR_PORT tiene valor inicial 3128 y se comparte con otros proyectos
SQUID_INTERCEPT_PORT Other projects Squid intercept port, default 3129. Shared key for other projects. Puerto transparente de Squid, valor inicial 3129. Clave compartida para otros proyectos.
SQUID_MGR_PASSWD connections.php Empty by default. Set it only if squid.conf declares cachemgr_passwd mypassword all, and use the very same value Vacía de forma predeterminada. Defínala únicamente si squid.conf declara cachemgr_passwd mipassword all, y utilice el mismo valor
WARNING_HTML bandata.sh Captive portal page where Bandata writes the current quota values Página del portal cautivo donde Bandata escribe los valores de cuota vigentes
CACHE_PATH pmsetup.sh, worker.php SquidAI cache directory, owned by www-data with mode 750 Directorio de caché de SquidAI, propiedad de www-data con permisos 750
MAX_BANDWIDTH_DAY, MAX_BANDWIDTH_WEEK, MAX_BANDWIDTH_MONTH bandata.sh The three quota limits; see Bandata below. Write a number followed by an uppercase K, M, G or T, such as 500M, 1G or 1.5G (1,5G also works). Lowercase letters (1g), 1GB, 1Gi or a number without a letter are rejected Los tres límites de cuota; consulte Bandata. Escriba un número seguido de K, M, G o T en mayúscula, como 500M, 1G o 1.5G (también vale 1,5G). Se rechazan las minúsculas (1g), 1GB, 1Gi y un número sin letra
BANDATA_HOTSPOT, HOTSPOT_PATH bandata.sh Bandata integration switch and UHM installation path. ProxyMon enables it at setup only if the voucher ACL exists and UHM uses UNIFI_HOTSPOT_ENABLED=true. Bandata checks both conditions on each run. Opción de integración de Bandata y ruta de instalación de UHM. ProxyMon la habilita durante la instalación solo si existe la ACL de vouchers y UHM usa UNIFI_HOTSPOT_ENABLED=true. Bandata vuelve a comprobar ambas condiciones en cada ejecución.
BANDATA_DNS bandata.sh DNS resolvers that a blocked client may query: one or two IPv4 separated by a comma, such as 192.168.0.1 or 8.8.8.8,1.1.1.1. Use the resolver your clients receive, whether it runs on this server, on another host of the LAN or on the internet. No default: if it is missing, empty or invalid, Bandata aborts without changing blocks or rules. Only UDP is accepted, in packets of up to 128 bytes and at most 5 queries per second per client. Port 53 to any other destination stays closed for blocked clients. Resolvers DNS que puede consultar un cliente bloqueado: una o dos IPv4 separadas por una coma, como 192.168.0.1 o 8.8.8.8,1.1.1.1. Use el resolver que reciben sus clientes, ya esté en este servidor, en otro equipo de la LAN o en internet. Sin valor por defecto: si falta, está vacía o es inválida, Bandata aborta sin cambiar bloqueos ni reglas. Solo se acepta UDP, en paquetes de hasta 128 bytes y con un máximo de 5 consultas por segundo por cliente. El puerto 53 hacia cualquier otro destino queda cerrado para los clientes bloqueados.
UPDATE_REALNAME bandata.sh Whether Bandata refreshes Squidreports' names, exclusions and ACL groups on each run Indica si Bandata actualiza los nombres, exclusiones y grupos por ACL de Squidreports en cada ejecución

⚠️ WARNING -- Configuration defaults: Changing the default values in proxymon.env is at the sysadmin's own risk.

⚠️ WARNING -- Configuration defaults: El administrador del sistema cambia los valores predeterminados de proxymon.env bajo su propia responsabilidad.

Configuration

• The installer establishes paths and ports in proxymon.env. Runtime modules read these settings; legacy paths in preserved squidreports.cfg files no longer override them. Configure Squidmon's log source through SQUID_LOG_FILE; its form displays this value read-only.

• Run pmsetup.sh --update after changing ports to apply Apache's configuration. Changing a data path does not move existing files: relocate the data and retain its permissions before using the new path. pmbk.sh backs up the configured original reports and additional statistics.

• /etc/proxymon/proxymon.env remains the fixed configuration entry point. Installation defaults are declared by the installer. Project-relative library paths and operating-system paths remain independent of environment settings.

• The installation sets two fixed Squid ports: 3128 for the cache and 3129 for intercept. SQUID_MGR_PORT and SQUID_INTERCEPT_PORT record these values; they do not configure Squid. To change a port, edit proxymon.env and squid.conf with the same value.
• El instalador establece las rutas y los puertos en proxymon.env. Los módulos leen estos valores; las rutas antiguas de archivos squidreports.cfg preservados ya no los reemplazan. Configure el registro de Squidmon mediante SQUID_LOG_FILE; su formulario muestra este valor sin permitir editarlo.

• Ejecute pmsetup.sh --update después de cambiar puertos para aplicar la configuración de Apache. Cambiar una ruta de datos no mueve los archivos existentes: traslade los datos y conserve sus permisos antes de utilizar la nueva ruta. pmbk.sh respalda los informes originales y las estadísticas adicionales configurados.

• /etc/proxymon/proxymon.env permanece como punto fijo de entrada a la configuración. El instalador declara los valores iniciales de instalación. Las rutas relativas de bibliotecas y las rutas del sistema operativo permanecen independientes de la configuración del entorno.

• La instalación fija dos puertos de Squid: 3128 para la caché y 3129 para intercept. SQUID_MGR_PORT y SQUID_INTERCEPT_PORT registran estos valores; no configuran Squid. Para cambiar un puerto, edite proxymon.env y squid.conf con el mismo valor.

LLM_ENV_FILE points to a second file, .env by default, with the SquidAI credentials LLM_URL, LLM_API_KEY, LLM_MODEL and LLM_RESPONSE_FORMAT. The installer creates this file only if absent, using a template embedded in pmsetup.sh. Existing content is preserved. See API Configuration.

LLM_ENV_FILE indica un segundo archivo, .env por defecto, con las credenciales de SquidAI LLM_URL, LLM_API_KEY, LLM_MODEL y LLM_RESPONSE_FORMAT. El instalador crea este archivo únicamente si no existe, utilizando una plantilla incluida en pmsetup.sh. Conserva el contenido existente. Ver «API Configuration».

proxymonenv.sh

  • Shared Bash file installed at CONFIG_DIR/tools/proxymonenv.sh. It is loaded automatically with source by pmsetup.sh, bandata.sh, squidtool.sh and pmbk.sh. Do not run it separately or schedule it in cron.
  • Reads general configuration from proxymon.env, resolves references between keys and checks the file owner and permissions. It does not modify configuration files or load the LLM credentials file.
  • Archivo Bash compartido instalado en CONFIG_DIR/tools/proxymonenv.sh. Lo cargan automáticamente mediante source los scripts pmsetup.sh, bandata.sh, squidtool.sh y pmbk.sh. No se ejecuta por separado ni se programa en cron.
  • Lee la configuración general de proxymon.env, resuelve referencias entre claves y comprueba el propietario y los permisos del archivo. No modifica archivos de configuración ni carga el archivo de credenciales del LLM.

LOGS

Each module reads the Squid log according to what it does, so their historical coverage differs. The retention on disk is set by rotate in /etc/logrotate.d/squid, which the installer sets to seven weekly rotations. Cada módulo lee el registro de Squid según su función, así que su cobertura histórica es distinta. La retención en disco la define rotate en /etc/logrotate.d/squid, que el instalador fija en siete rotaciones semanales.
Module Reads Lee Coverage / Cobertura
Squidmon access.log, supplemented by access.log.1 when needed access.log, completado con access.log.1 cuando hace falta Recent activity / Actividad reciente
Logview access.log, supplemented by access.log.1 on initial load when needed; searches include both access.log, completado con access.log.1 en la carga inicial cuando hace falta; las búsquedas incluyen ambos Recent activity and searches / Actividad reciente y búsquedas
SquidAI Squidreports reports, access.log and available uncompressed access.log.N files Informes de Squidreports, access.log y archivos access.log.N disponibles sin comprimir Available report history and uncompressed logs / Histórico disponible en informes y registros sin comprimir
squidtool.sh access.log and every rotated file access.log y todos los rotados Full retention / Retención completa

SquidAI uses the daily Squidreports .denied file for blocked domains, patterns, TLDs and direct IPv4 incidents. If the report is missing or empty, it reads the active and uncompressed rotated logs. Denied reports do not include byte counts.

SquidAI usa el archivo diario .denied de Squidreports para consultar bloqueos por dominio, patrón, TLD y acceso directo a IPv4. Si el informe falta o está vacío, lee el registro activo y los rotados sin comprimir. Los informes de solicitudes denegadas no incluyen los bytes.

Modules

MAIN MENU

proxymon_main

MONITOR (Squidmon)

squidmon

Monitor (Squidmon) monitors Squid traffic in real time. It shows blocked domains and clients, traffic patterns, and ACL matches. Filter the activity to generate reports on network traffic and blocked content. Monitor (Squidmon) ofrece análisis del tráfico de Squid en tiempo real. Muestra estadísticas sobre dominios y clientes bloqueados, patrones de tráfico y coincidencias con las ACL. También permite filtrar la actividad y generar informes detallados sobre el tráfico de red y el contenido bloqueado.
Configuration

squidmon conf

This section defines the parameters that Squidmon uses to interpret and display network activity, including data sources (access control lists —ACLs—), the maximum number of lines to analyze from the Squid log, the time range of the data, and the automatic refresh interval. Each list is declared with its full path, one per line, and the module reads exactly that path: it never searches any directory. The default entries are: Aquí se configuran los parámetros que Squidmon usa para mostrar la actividad de la red: las listas de control de acceso (ACL), el máximo de líneas del registro de Squid que se analizarán, el período de consulta y el intervalo de actualización. Cada lista se declara con su ruta completa, una por línea. El módulo lee esa ruta y no busca en ningún directorio. Estas son las entradas predeterminadas:
/etc/squid/acl/blocktlds.txt=Blocked TLD
/etc/squid/acl/blockdomains.txt=Blocked Sites
regex:^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}(:\d+)?(?=[/?#]|$)=Block IPv4
regex:(adlinkfly|announce\.php\?passkey=|info_hash|iptv|jndi:|mtc[0-9]|\.onion|peer_id=|porn|psiphon|torrent|ultrasurf)=Blocked Patterns
To change the lists, enter each full path in the Config section, one per line, followed by = and its label. Squidmon opens exactly that path and searches no directory. If you move a list, edit its line in Config. Para cambiar las listas, indique en la sección Config la ruta completa de cada archivo, una por línea, seguida de = y su etiqueta. Squidmon abre esa ruta y no busca en ninguna carpeta. Si cambia la ubicación de una lista, actualice su entrada en Config.
sudo nano /etc/proxymon/proxymon.env
# path to ACLs folder
ACL_PATH=/etc/acl
ACL_SQUID_PATH=/etc/squid/acl
ACL Rules
For a rule to block traffic, it must be defined in both Squidmon configuration and squid.conf. Here is an example using the default ACLs: Para que una regla bloquee tráfico, debe estar definida tanto en la configuración de Squidmon como en squid.conf. Este es un ejemplo con las ACL predeterminadas:
sudo nano /etc/squid/squid.conf
#
# INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
#
include /etc/squid/conf.d/*.conf
# Block: TLDs
acl blocktlds dstdomain "/etc/squid/acl/blocktlds.txt"
http_access deny workdays blocktlds
# Block: domains
acl blockdomains dstdomain "/etc/squid/acl/blockdomains.txt"
http_access deny workdays blockdomains
# Block: patterns
acl blockpatterns dstdomain "/etc/squid/acl/blockpatterns.txt"
http_access deny workdays blockpatterns

⚠️ WARNING -- Search resource usage: Default values are 24 hours and 50,000 lines from access.log. Increasing these values may slow down the module and raise system resource usage. Refer to the Squidmon Search section. To reset the filters to their default values, press the Reset to Default button.

⚠️ WARNING -- Search resource usage: Los valores predeterminados son 24 horas y 50 000 líneas de access.log. Si los aumenta, el módulo podría tardar más y consumir más recursos. Consulte la sección Squidmon Search. Para restablecer los valores iniciales, pulse Reset to Default.

Top Blocked Domains & Clients

squidmon top_blocked

Description Descripción
Top Blocked Domains: Shows the domains Squid blocks most often, along with the port and number of blocked requests. This helps identify frequently blocked sites or services and adjust access rules. Top Blocked Domains: Muestra los dominios que Squid bloquea con mayor frecuencia, junto con el puerto y el número de solicitudes bloqueadas. Esta información ayuda a identificar qué sitios o servicios se bloquean más y a ajustar las reglas de acceso.
Top Blocked Clients: Shows the client IP addresses with the most blocked requests. Each row includes the total number of requests, how many were blocked, and the percentage they represent. This helps identify clients that often try to access restricted content and may need follow-up. Top Blocked Clients: Muestra las IP de los clientes con más solicitudes bloqueadas. Cada fila incluye el total de solicitudes, cuántas se bloquearon y qué porcentaje representan. Esta información permite identificar equipos que requieren seguimiento por sus intentos de acceso a contenido restringido.
Traffic by Client IP

squidmon traffic

• Expand a client IP to view its traffic statistics, including total, blocked and allowed requests.

• Filter by ACL, search for IP addresses or domains, and select a period of 24 hours, 7 days or 30 days.

• Generate a PDF report for each client.
• Despliegue una IP para consultar el total de solicitudes y cuántas fueron bloqueadas o permitidas.

• Filtre por ACL, busque IP o dominios y seleccione períodos de 24 horas, 7 días o 30 días.

• Genere un informe PDF para cada cliente.
Filtering and Search

squidmon acl

• Squidmon classifies traffic using ACLs (Access Control Lists), such as Blocked TLD, Blocked Sites, Blocked Patterns, Block IPv4 and Unknown ACL. The last one covers rules defined in squid.conf that are not among the ACLs listed in Config.

• Search by IP address or domain, and filter to show only blocked or only allowed traffic.

• Select Clean Filters to clear the filters.
• Squidmon clasifica el tráfico según las ACL, como Blocked TLD, Blocked Sites, Blocked Patterns, Block IPv4 y Unknown ACL. Esta última agrupa las reglas de squid.conf que no aparecen en la sección Config.

• Busque por IP o dominio y filtre para ver solo el tráfico bloqueado o solo el permitido.

• Pulse Clean Filters para borrar los filtros.
Report Generation

squidmon pdf

• Generate PDF traffic reports.

• Select the last 24 hours, 7 days or 30 days. You can also generate a report for a client or domain.

• The Generate PDF Report button appears in the interface.
• Genere informes PDF de tráfico.

• Seleccione las últimas 24 horas, los últimos 7 días o los últimos 30 días. También puede generar un informe para un cliente o dominio.

• El botón Generate PDF Report aparece en la interfaz.
Blocked URLs Analysis

squidmon filter

Expand a client IP to see the blocked URLs, the matching ACL rule (for example, Blocked Sites), and how many times each URL was requested. This helps identify browsing patterns and adjust access rules. Al desplegar una IP, puede consultar las URL bloqueadas, la regla de ACL que coincidió —por ejemplo, Blocked Sites— y cuántas veces se solicitó cada URL. Estos datos ayudan a reconocer patrones de navegación y ajustar las reglas de acceso.
Patterns

squidmon patterns

If a Squid ACL uses url_regex, Squidmon cannot read it from a file. Enter the expression directly in the module's Config section, as shown here: Si una ACL de Squid usa url_regex, Squidmon no puede leerla desde un archivo. Copie su expresión directamente en la sección Config del módulo, como en este ejemplo:
regex:(adlinkfly|announce\.php\?passkey=|info_hash|iptv|jndi:|mtc[0-9]|\.onion|peer_id=|porn|psiphon|torrent|ultrasurf)=Blocked Patterns
regex:^[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}(:\d+)?(?=[/?#]|$)=Block IPv4
Squidmon Search

squidmon search

• Result: 6 clients found in 0.08 seconds. Client IP-based filtering with domain resolution.

• Data source: Squid access logs, /var/log/squid/access.log.

• Search method: Real-time log parsing with ACL filtering.

• Use case: Real-time client activity, immediate threat detection.
• Resultado: 6 clientes encontrados en 0,08 s. Filtrado basado en IP del cliente con resolución de dominio.

• Fuente de datos: Registros de acceso de Squid, /var/log/squid/access.log.

• Método de búsqueda: Análisis de registros en tiempo real con filtrado ACL.

• Caso de uso: Actividad de cliente en tiempo real, detección inmediata de amenazas.
Logrotate
• The installer configures weekly rotation in /etc/logrotate.d/squid. The execution time depends on the system’s logrotate scheduler; the installer does not set it. Do not configure size or maxsize: those split the current day, and Squidreports rebuilds each day from a single file.

• The installer also adds a prerotate hook to /etc/logrotate.d/squid. It closes the previous day's report before access.log is rotated. When that file already defines its own prerotate, the installer reports it and leaves it untouched.

• Disable Squid's internal rotation with logfile_rotate 0.

• In /etc/logrotate.d/squid, you can keep seven rotations with rotate 7.
• El instalador configura la rotación semanal en /etc/logrotate.d/squid. La hora de ejecución depende de la programación de logrotate del sistema; el instalador no la establece. No configure size ni maxsize: parten el día en curso, y Squidreports reconstruye cada día a partir de un solo archivo.

• El instalador añade además un bloque prerotate a /etc/logrotate.d/squid. Cierra el informe del día anterior antes de rotar access.log. Si ese archivo ya define su propio prerotate, el instalador lo informa y no lo modifica.

• Desactive la rotación interna de Squid con logfile_rotate 0.

• En /etc/logrotate.d/squid, puede conservar siete rotaciones con rotate 7.
# Disable Squid internal rotation
sudo nano /etc/squid/squid.conf
#  TAG: logfile_rotate
logfile_rotate 0

# Logrotate (pmsetup.sh already sets weekly; this only restores it)
sudo sed -i -E 's/^([[:space:]]*)(hourly|daily|monthly|yearly)$/\1weekly/' /etc/logrotate.d/squid
# Optional:
sudo sed -i 's/rotate 2/rotate 7/' /etc/logrotate.d/squid

REPORTS (Squidreports)

squidreports report

Squidreports parses access.log and writes one folder per day under /var/www/proxymon/squidreports/report/. The daily view provides user details, top sites, large downloads and the additional reports described below. Squidreports analiza access.log y escribe una carpeta por día en /var/www/proxymon/squidreports/report/. La vista diaria permite consultar detalles por usuario, sitios más visitados, descargas grandes y los informes adicionales descritos a continuación.
Initial Report
The first time you open Reports, reports may not be available yet. This happens if they have not been generated or your network traffic has not passed through Squid. The installer attempts to generate the initial report; if it does not appear, run this command: La primera vez que abra Reports, puede que todavía no haya informes. Esto ocurre si aún no se han generado o si el tráfico de la red no ha pasado por Squid. El instalador intenta generar el informe inicial; si no aparece, ejecute este comando:
sudo /var/www/proxymon/squidreports/squidreports.pl today
Search Bar

squidreports bar

In General Statistics, enter a word or value in the search bar and select SEARCH. The table will show matching rows, so you do not have to scan the entire report. En General Statistics, escriba una palabra o un valor en la barra de búsqueda y pulse SEARCH. La tabla mostrará las filas coincidentes, sin necesidad de recorrer todo el informe.

squidreports bar output

Traffic Search

squidreports search

• Result: 1,323 matches in 5.4 seconds. Searches Squidreports daily reports for the entered term, regardless of letter case.

• Data source: Squidreports reports, /var/www/proxymon/squidreports/report/YYYYMMDD/.

• Search method: Reads report files and searches for the literal term.

• Use case: Historical analysis, domain trends, data usage reports.
• Resultado: 1 323 coincidencias en 5,4 s. Busca el texto indicado en los informes diarios de Squidreports, sin distinguir mayúsculas de minúsculas.

• Fuente de datos: Informes de Squidreports, /var/www/proxymon/squidreports/report/YYYYMMDD/.

• Método de búsqueda: Lectura de los archivos de informes y búsqueda literal del término.

• Caso de uso: Análisis histórico, tendencias de dominios, informes de consumo de datos.
Traffic Cron Job
The installer schedules Squidreports report generation every 10 minutes. To change the frequency, edit its entry in /etc/cron.d/proxymon. A second entry runs yesterday at 00:05, because today stops selecting the previous day at midnight. Its --wait-lock waits for the generator still running instead of giving up. El instalador programa la generación de informes de Squidreports cada 10 minutos. Para cambiar la frecuencia, edite su tarea en /etc/cron.d/proxymon. Una segunda tarea ejecuta yesterday a las 00:05, porque today deja de seleccionar el día anterior a medianoche. Su opción --wait-lock espera al generador que siga activo en lugar de abandonar.
sudo nano /etc/cron.d/proxymon
*/10 * * * * www-data /var/www/proxymon/squidreports/squidreports.pl today
5 0 * * * www-data /var/www/proxymon/squidreports/squidreports.pl yesterday --wait-lock
Add Users
You can add users manually to realname.cfg and exclude IP addresses from reports with skipuser.cfg.

When UPDATE_REALNAME=true—the default for a new installation—Bandata generates realname.cfg from non-excluded MAC ACLs and, when enabled, data from uhm-auth.txt. It also generates skipuser.cfg from the IP addresses in mac-unlimited.txt and IPv4 entries in /etc/hosts. Bandata replaces each file when it finds data, so manual edits may be lost. If Hotspot is disabled and the included mac-*.txt lists contain no MAC entries, Bandata writes an empty realname.cfg. If reading those ACLs fails, Bandata keeps the previous realname.cfg and logs a warning.
Puede añadir usuarios manualmente a realname.cfg y excluir IP de los informes con skipuser.cfg.

Cuando UPDATE_REALNAME=true —valor predeterminado al instalar—, Bandata genera realname.cfg con las ACL MAC no excluidas y, si corresponde, los datos de uhm-auth.txt. También genera skipuser.cfg con las IP de mac-unlimited.txt y las direcciones IPv4 de /etc/hosts. Bandata reemplaza cada archivo cuando encuentra datos, por lo que los cambios manuales pueden perderse. Si Hotspot está desactivado y las listas mac-*.txt incluidas no contienen entradas MAC, Bandata escribe un realname.cfg vacío. Si falla la lectura de esas ACL, conserva el realname.cfg anterior y registra una advertencia.
sudo nano /var/www/proxymon/squidreports/realname.cfg
# example:
192.168.X.2 Client1
192.168.X.24 Client12
sudo nano /var/www/proxymon/squidreports/skipuser.cfg
# example:
192.168.X.3 CEO
Groups

squidreports group

Group summarizes client traffic by ACL membership. When UPDATE_REALNAME=true, Bandata rebuilds group.cfg inside SQUIDREPORTS_DIR on each run. Active IPs from ACL_PATH/mac-limited.txt belong to 01. limited. With BANDATA_HOTSPOT=true, active IPs from HOTSPOT_PATH/acl/uhm-auth.txt belong to 02. hotspot. Only entries beginning with a; are included. Unlimited clients remain excluded from reports.

The installer enables UHM integration when both HOTSPOT_PATH/uhm.env and HOTSPOT_PATH/acl/uhm-auth.txt exist. Without this integration, Bandata generates only the limited assignments. Clients recorded without an assignment appear as Not in group.

Bandata replaces group.cfg, including when no active assignments remain, so manual edits are overwritten. Each generated daily report receives a copy in .group. Existing historical assignments remain unchanged until that date is regenerated. The installer option update preserves the installed file; Bandata updates it on its next run.
Group resume el tráfico de los clientes según su pertenencia a las ACL. Con UPDATE_REALNAME=true, Bandata reconstruye group.cfg dentro de SQUIDREPORTS_DIR en cada ejecución. Las IP activas de ACL_PATH/mac-limited.txt pertenecen a 01. limited. Con BANDATA_HOTSPOT=true, las IP activas de HOTSPOT_PATH/acl/uhm-auth.txt pertenecen a 02. hotspot. Solo se incluyen entradas que comienzan con a;. Los clientes unlimited siguen excluidos de los informes.

El instalador habilita la integración con UHM cuando existen HOTSPOT_PATH/uhm.env y HOTSPOT_PATH/acl/uhm-auth.txt. Sin esta integración, Bandata genera únicamente las asignaciones limited. Los clientes registrados sin asignación aparecen como Not in group.

Bandata reemplaza group.cfg, incluso cuando no quedan asignaciones activas, por lo que sobrescribe los cambios manuales. Cada informe diario generado recibe una copia en .group. Las asignaciones históricas existentes se conservan hasta regenerar esa fecha. La opción update del instalador conserva el archivo instalado; Bandata lo actualiza en su siguiente ejecución.
Exclude Users
To exclude IP addresses from reports, add them to skipuser.cfg. If UPDATE_REALNAME=true, Bandata normally rebuilds this file from mac-unlimited.txt and /etc/hosts, so manual changes may be replaced: Para excluir IP de los informes, añádalas a skipuser.cfg. Si UPDATE_REALNAME=true, Bandata normalmente vuelve a generar este archivo a partir de mac-unlimited.txt y /etc/hosts, por lo que puede reemplazar los cambios manuales:
sudo nano /var/www/proxymon/squidreports/skipuser.cfg
# example
192.168.X.1
Netscan
Use one of the following tools to discover devices on your local network. Replace both the address and prefix with the actual LAN network. The /24 shown below is only an example: Utilice una de las siguientes herramientas para detectar dispositivos en su red local. Sustituya la dirección y el prefijo por la red LAN real. El /24 siguiente es solamente un ejemplo:
# Install required tools
sudo apt install -y nbtscan nmap arp-scan nast sudo netdiscover
# Run the following commands to scan your local network:
# 1. Using nbtscan
sudo nbtscan 192.168.X.0/24
# 2. Using nmap
sudo nmap -sn 192.168.X.0/24
# 3. Using arp-scan
sudo arp-scan --localnet
# 4. Using nast
sudo nast -m
# 5. Using netdiscover
sudo netdiscover
Report Data
Squidreports preserves the base report formats and paths used by Bandata. Additional metrics are stored separately under REPORT_STATS_PATH/YYYYMMDD/ (by default, the original report path followed by stats). Detail reads the original reports and these additional metrics. Existing additional metrics in old report folders remain readable until that date is regenerated. Analyze displays historical statistics and charts. Charts are generated on request, without saving images or HTML pages. Squidreports conserva los formatos y las rutas de los informes base utilizados por Bandata. Las métricas adicionales se guardan por separado en REPORT_STATS_PATH/YYYYMMDD/ (por defecto, la ruta de informes originales seguida de stats). Detail lee los informes originales y estas métricas adicionales. Las métricas adicionales existentes en carpetas antiguas siguen siendo legibles hasta regenerar esa fecha. Analyze muestra estadísticas históricas y gráficos. Los gráficos se generan bajo petición, sin guardar imágenes ni páginas HTML.
Detailed Report

Squidreports Detail

Description Descripción
Detailed Report provides detailed traffic reports within Squidreports. It provides daily, weekly, monthly and yearly summaries, with details by user and site. Detailed Report permite consultar informes detallados de tráfico dentro de Squidreports. Ofrece resúmenes diarios, semanales, mensuales y anuales, con detalles por usuario y sitio.
Daily access: In General Statistics, select View in the Detail column for the required date. The daily User Statistics link also opens this report when its metrics are available. Acceso diario: En General Statistics, pulse View en la columna Detail de la fecha deseada. El enlace diario User Statistics también abre este informe cuando sus métricas están disponibles.
Monthly and yearly access: In the Ranking box, use MONTH or YEAR in the fourth column, Detail. These links open the detailed report for the selected period. Acceso mensual y anual: En el cuadro Ranking, utilice MONTH o YEAR en la cuarta columna, Detail. Estos enlaces abren el informe detallado del período seleccionado.
Weekly access: In Ranking, WEEK opens weekly Top Sites, Total, Group or Detail. Top Sites, Total and Group retain their usual tables and tools. Choose the ISO week and either Full week (Mon–Sun) or Bandata (Mon–Fri). The initial week comes from the latest daily report in the selected month or year. Reports read existing daily data and show missing dates explicitly. Bandata evaluates the previous Monday–Friday on Monday; the report shows consumption, not historical blocking status. Detail includes a daily breakdown for all users or the selected user/IP. Acceso semanal: En Ranking, WEEK abre los informes semanales de Top Sites, Total, Group o Detail. Top Sites, Total y Group conservan sus tablas y herramientas habituales. Seleccione la semana ISO y Full week (Mon–Sun) o Bandata (Mon–Fri). La semana inicial corresponde al último informe diario del mes o año seleccionado. Los informes leen los datos diarios existentes e indican las fechas ausentes. Bandata evalúa el lunes el período de lunes a viernes anterior; el informe muestra consumo, no el estado histórico de bloqueo. Detail incluye el desglose diario de todos los usuarios o del usuario/IP seleccionado.
Users and IP addresses: The initial table summarizes each user's requests, transferred bytes, consumption share, cache HIT/MISS bytes and percentages, accumulated duration, average request duration, time share, throughput and largest object with its URL. With the default configuration, unauthenticated traffic is identified by client IP; authenticated traffic uses the username. It does not create a separate IP breakdown for an authenticated user. Usuarios y direcciones IP: La tabla inicial resume las solicitudes, bytes transferidos, porcentaje de consumo, bytes y porcentajes de caché HIT/MISS, duración acumulada, duración media por solicitud, porcentaje de tiempo, velocidad media y objeto de mayor tamaño con su URL. Con la configuración predeterminada, el tráfico sin autenticación se identifica por la IP del cliente; el autenticado utiliza el nombre de usuario. No crea un desglose independiente por IP para un usuario autenticado.
Site details: Select a user or IP address to view their sites for the same period. The table shows the same traffic, cache and duration metrics by site, excluding the largest-object column. Users returns to the summary for that period. Detalle por sitio: Seleccione un usuario o una IP para consultar sus sitios durante el mismo período. La tabla muestra las mismas métricas de tráfico, caché y duración por sitio, sin la columna del objeto de mayor tamaño. Users vuelve al resumen del período.
Denied Accesses: Opens denied requests for the selected period and, when selected, the user. Each row shows the date, user or IP, time, Squid code and URL. This includes blocked requests and authentication failures recorded as denied by Squid. Denied requests remain outside the traffic totals. Denied Accesses: Abre las solicitudes denegadas del período y, si se ha seleccionado, del usuario. Cada fila muestra fecha, usuario o IP, hora, código de Squid y URL. Incluye solicitudes bloqueadas y fallos de autenticación registrados como denegados por Squid. Las solicitudes denegadas se excluyen de los totales de tráfico.
Metric interpretation: Duration is the sum of request durations, not the user's connected time. Average request duration is expressed in milliseconds. Throughput divides transferred bytes by accumulated request duration; it is not a measurement of the network link's speed. Interpretación de métricas: La duración es la suma de las duraciones de las solicitudes, no el tiempo de conexión del usuario. La duración media por solicitud se expresa en milisegundos. La velocidad media divide los bytes transferidos entre la duración acumulada; no mide la velocidad del enlace de red.
Print and storage: Print opens the browser's print dialog. Tables are generated from existing report data when opened; no duplicate HTML archive or graphs are stored. Impresión y almacenamiento: Print abre el diálogo de impresión del navegador. Las tablas se generan desde los datos de los informes al consultarlas; no se almacena otro archivo histórico de HTML ni gráficos.
Older reports: Daily .sitestat files store cache and duration metrics by user/site under reportstats/YYYYMMDD/, separately from the original reports. Missing detailed metrics appear as —, rather than zero. Regenerate the affected dates from retained Squid logs to recover those metrics. Informes anteriores: Los archivos diarios .sitestat guardan métricas de caché y duración por usuario/sitio en reportstats/YYYYMMDD/, separadas de los informes originales. Las métricas detalladas ausentes aparecen como —, en lugar de cero. Regenere las fechas afectadas desde los registros conservados de Squid para recuperar esas métricas.
Analyze

Squidreports Analyze

Description Descripción
Access: Select Analyze beside the Ranking title or in Detail. This opens the analysis view within Squidreports. Acceso: Pulse Analyze junto al título Ranking o dentro de Detail. Abre la vista de análisis dentro de Squidreports.
Periods: Select Day, Week, Month or Year, fill the corresponding fields and press Apply. Weeks use ISO numbering and the ISO week-year, which may include dates from the adjacent calendar year. Detail opens the same selected period. Períodos: Seleccione Day, Week, Month o Year, complete los campos correspondientes y pulse Apply. Las semanas usan numeración ISO y el año de semana ISO, que puede incluir fechas del año calendario adyacente. Detail abre el mismo período seleccionado.
History: Displays recorded intervals by hour for a day, by day for a week or month, and by month for a year. Select bytes, requests, HIT/MISS bytes, throughput, HIT/MISS throughput or denied requests for the chart. The original report totals appear separately. Missing intervals are not filled with zero. History: Muestra los intervalos registrados por hora para un día, por día para una semana o mes y por mes para un año. Permite graficar bytes, solicitudes, bytes HIT/MISS, velocidad media, velocidad HIT/MISS o solicitudes denegadas. Los totales de los informes originales aparecen por separado. Los intervalos ausentes no se completan con cero.
MIME: Aggregates content types for the selected period, with requests, bytes, cache, duration, throughput, first/last access and largest object. The type comes from Squid's log; HTTPS tunnels do not reveal their enclosed content. MIME: Agrupa tipos de contenido para el período, con solicitudes, bytes, caché, duración, velocidad media, primer/último acceso y objeto de mayor tamaño. El tipo proviene del registro de Squid; los túneles HTTPS no revelan su contenido interno.
Networks: Groups client IPs by configured network, with traffic, cache, duration, throughput and largest object. Select a network to inspect its users/IPs. The main network comes from RANGE in /etc/proxymon/proxymon.env. Unmatched addresses remain individual. In squidreports.cfg, optional additional $analytics_networks entries use [label, CIDR]; IPv4 and IPv6 are supported. The longest matching prefix wins. Networks: Agrupa IP de clientes por red configurada, con tráfico, caché, duración, velocidad media y objeto de mayor tamaño. Seleccione una red para consultar sus usuarios/IP. La red principal se lee de RANGE en /etc/proxymon/proxymon.env. Las direcciones sin coincidencia permanecen individuales. En squidreports.cfg, las entradas opcionales adicionales de $analytics_networks usan [nombre, CIDR]; admite IPv4 e IPv6. Prevalece el prefijo coincidente más específico.
Domains and Sites: Domains combines subdomains and opens their individual sites. Sites opens users for a destination; selecting a user shows their sites within the selected domain. Tables retain first/last access, cache, duration, throughput and largest object. Domain grouping uses the bundled Public Suffix List, including wildcard and exception rules. International suffixes are stored as ASCII/Punycode. Optional $analytics_domain_suffixes adds literal suffixes. Domains y Sites: Domains agrupa subdominios y abre sus sitios individuales. Sites abre los usuarios de un destino; seleccionar un usuario muestra sus sitios dentro del dominio seleccionado. Las tablas conservan primer/último acceso, caché, duración, velocidad media y objeto de mayor tamaño. La agrupación utiliza la Public Suffix List incluida, con comodines y excepciones. Los sufijos internacionales se guardan en ASCII/Punycode. $analytics_domain_suffixes permite añadir sufijos literales.
Denied: Ranks denied destinations by request count. Each destination shows its users, Squid codes and first/last access. Includes authentication failures recorded as denied. These requests remain outside allowed-traffic totals. Denied: Ordena los destinos denegados por cantidad de solicitudes. Cada destino muestra usuarios, códigos de Squid y primer/último acceso. Incluye fallos de autenticación registrados como denegados. Estas solicitudes se excluyen de los totales de tráfico permitido.
Storage and coverage: Original files stay in REPORT_PATH/YYYYMMDD/. Detail's additional files and Analyze's analyzer.json share REPORT_STATS_PATH/YYYYMMDD/, distinguished by filename. The parser replaces each day's aggregates when regenerating it. Dates missing additional metrics produce a coverage notice; regenerate them from retained logs. No additional pages or chart images are stored. Almacenamiento y cobertura: Los archivos originales permanecen en REPORT_PATH/YYYYMMDD/. Los archivos adicionales de Detail y analyzer.json de Analyze comparten REPORT_STATS_PATH/YYYYMMDD/, separados por nombre. El parser reemplaza los agregados del día al regenerarlo. Las fechas sin métricas adicionales muestran un aviso de cobertura; regenérelas desde registros conservados. No se guardan páginas adicionales ni imágenes de gráficos.
Tables and print: Tables show 100 rows per page. Distribution charts show the first 20 rows; History charts show recorded intervals. Print prints the current page. Rates divide summed bytes by summed request durations; zero-duration rates appear as —. Internet cost calculation is excluded. Tablas e impresión: Las tablas muestran 100 filas por página. Los gráficos de distribución muestran las primeras 20 filas; los históricos muestran los intervalos registrados. Print imprime la página actual. Las velocidades dividen los bytes acumulados entre las duraciones acumuladas; con duración cero aparece —. Se excluye el cálculo de costes de Internet.

Analyze reads the installed network configuration automatically; no example network needs copying. Additional network aliases remain optional in squidreports.cfg. Subnet statistics use the same configuration when regenerated.

Analyze lee automáticamente la configuración de red instalada; no necesita copiar una red de ejemplo. Los alias adicionales siguen siendo opcionales en squidreports.cfg. Las estadísticas por subred usan la misma configuración al regenerarse.

Manual Public Suffix List update
Description Descripción
Run domain-suffixes-update.sh manually as root. It is installed beside domain-suffixes.txt; no cron entry is added. Ejecute domain-suffixes-update.sh manualmente como root. Se instala junto a domain-suffixes.txt; no se añade ninguna entrada de cron.
The updater loads SQUIDREPORTS_DIR from /etc/proxymon/proxymon.env through the shared reader. It does not assume the default web directory. Installation and update deploy the reader beside the updater. El actualizador carga SQUIDREPORTS_DIR de /etc/proxymon/proxymon.env mediante el lector compartido. No presupone el directorio web predeterminado. La instalación y la actualización despliegan el lector junto al actualizador.
Downloads the official PSL over HTTPS, validates its metadata, ICANN and PRIVATE sections and every rule, and normalizes international suffixes to ASCII/Punycode. Preserves wildcard and exception rules. Descarga la PSL oficial mediante HTTPS, valida sus metadatos, las secciones ICANN y PRIVATE y cada regla. Normaliza sufijos internacionales a ASCII/Punycode y conserva comodines y excepciones.
Replaces the list only after validation succeeds. Download or validation failures leave the previous list unchanged. An identical list is not rewritten. The configured directory must be root-owned and not writable by group or others. Reemplaza la lista solo después de validarla. Los fallos de descarga o validación conservan la lista anterior. Una lista idéntica no se reescribe. El directorio configurado debe pertenecer a root, sin escritura para grupo u otros.
Logs to /var/log/proxymon.log. Requires curl and python3, included in installer dependencies. Project updates preserve the manually updated list. Registra en /var/log/proxymon.log. Requiere curl y python3, incluidos en las dependencias del instalador. Las actualizaciones del proyecto conservan la lista actualizada manualmente.

Default installation path / Ruta de instalación predeterminada:

sudo bash /var/www/proxymon/squidreports/domain-suffixes-update.sh

Use the updater under your configured SQUIDREPORTS_DIR if this path differs.

Utilice el actualizador situado en su SQUIDREPORTS_DIR configurado si utiliza otra ruta.

Official source / Fuente oficial: Public Suffix List.

User Statistics
The daily User Statistics link opens Detailed Report when the daily metrics are available. It summarizes traffic, cache usage, request durations and the largest object for each user or client IP. Select a user or IP to inspect their sites. El enlace diario User Statistics abre Detailed Report cuando las métricas diarias están disponibles. Resume tráfico, uso de caché, duración de solicitudes y objeto de mayor tamaño por usuario o IP del cliente. Seleccione un usuario o una IP para consultar sus sitios.
Traffic Classification
Traffic is grouped in three views: by content type, by file extension, and by client subnet. Each row gives the bytes, the number of requests and the share of the day's traffic. The three views share one page and differ only in the type parameter. El tráfico se agrupa en tres vistas: por tipo de contenido, por extensión de archivo y por subred del cliente. Cada fila muestra los bytes, el número de solicitudes y el porcentaje del tráfico del día. Las tres vistas comparten una página y solo cambian en el parámetro type.
Denied Accesses
Lists requests denied by Squid during the day, with the user, time, Squid code and URL. It covers both the blocked requests, TCP_DENIED/403, and the authentication failures, TCP_DENIED/407. These lines never enter the traffic totals. Muestra las solicitudes rechazadas por Squid durante el día, con usuario, hora, código de Squid y URL. Incluye tanto las solicitudes bloqueadas, TCP_DENIED/403, como los fallos de autenticación, TCP_DENIED/407. Estas solicitudes se excluyen de los totales de tráfico.
Data Statistics
Squidreports displays traffic statistics and identifies users who exceed the configured threshold. To change that threshold, edit squidreports.cfg: Squidreports muestra las estadísticas de tráfico y señala a los usuarios que superan el umbral configurado. Para cambiar ese umbral, edite squidreports.cfg:
sudo nano /var/www/proxymon/squidreports/squidreports.cfg

# Nomenclature: 10 = 10 MBytes, 512 = 512 Mbytes, 1000 = 1 Gbytes...
# By default it comes in 1000. Do not modify the value 1024.

#user maximum size per day limit (oversize)
$perusertrafficlimit = 1000*1024*1024;
Export Tools

squidreports menu

In General Statistics, open Tools on the right side of the header to copy or print the table, or export it as PDF, XLSX, or CSV. En General Statistics, abra Tools, a la derecha del encabezado, para copiar o imprimir la tabla y exportarla como PDF, XLSX o CSV.
Reports
Squidreports can export reports, but its site view shows a selection of top domains. To collect the domains recorded in the daily reports and create a list for a Squid ACL, run: Squidreports permite exportar informes, pero su vista de sitios muestra una selección de los dominios principales. Para reunir los dominios registrados en los informes diarios y generar una lista para una ACL de Squid, ejecute:
find /var/www/proxymon/squidreports/report -type f -name '[0-9]*.[0-9]*.[0-9]*.[0-9]*' -exec grep -oE '[[:alnum:]_.-]+\.([[:alnum:]_.-]+)+' {} \; | sed 's/^\.//' | sed -r 's/^(www|ftp|ftps|ftpes|sftp|pop|pop3|smtp|imap|http|https)\.//g' | sed -r '/^[0-9]{1,3}(\.[0-9]{1,3}){3}$/d' | tr -d ' ' | awk '{print "." $1}' | sort -u > domains.txt
Bandata

bandata

Bandata is a script that sets data usage limits —daily, weekly, and monthly— for IP addresses on a LAN monitored with Squid, and automatically blocks those that exceed the established quotas.

• Weekends are excluded from the calculation.

• The limits must match those configured in Squid Report.

• Bandata can generate realname.cfg to map IP addresses to names and skipuser.cfg to exclude IP addresses from Squidreports reports. It reads MAC ACLs, /etc/hosts, and, when enabled, the captive portal's uhm-auth.txt.

• On its first run Bandata writes /etc/logrotate.d/bandata if that file is missing, so /var/log/bandata.log never needs a manual truncate. The generated rule rotates the log daily, keeps seven rotations compressed, and recreates it as 640 root adm. An existing file is left untouched, so your own changes are preserved.

Bandata calculates usage from available Squidreports reports. If reports are missing or incomplete, calculated usage may be lower than actual usage.

When reports cannot be read, lists cannot be built or rules cannot be published, Bandata attempts to clear the affected blocks and logs a WARNING: ... -alert. Missing report folders are reported as INFO; usage is calculated from the available days.
Bandata es un script que establece límites de consumo de datos —diario, semanal y mensual— para direcciones IP de una LAN monitorizada con Squid, y bloquea automáticamente aquellas que superan las cuotas establecidas.

• Los fines de semana quedan excluidos del cálculo.

• Los límites deben coincidir con los configurados en Squid Report.

• Bandata puede generar realname.cfg para asociar IP con nombres y skipuser.cfg para excluir IP de los informes de Squidreports. Toma los datos de las ACL MAC, de /etc/hosts y, si está activado, de uhm-auth.txt del portal cautivo.

• En su primera ejecución, Bandata crea /etc/logrotate.d/bandata si ese archivo no existe, por lo que /var/log/bandata.log nunca necesita un truncado manual. La regla generada rota el log a diario, conserva siete rotaciones comprimidas y lo recrea como 640 root adm. Si el archivo ya existe, no lo modifica, por lo que sus cambios se conservan.

Bandata calcula el consumo con los informes disponibles de Squidreports. Si faltan informes o están incompletos, el consumo calculado puede ser inferior al real.

Cuando no puede leer informes, construir listas o publicar reglas, Bandata intenta vaciar los bloqueos afectados y registra WARNING: ... -alert. Las carpetas de informes ausentes se notifican como INFO; el consumo se calcula con los días disponibles.
Warning When it appears Cuándo aparece
WARNING: banday.txt is missing -alert The daily block list is absent when Bandata combines the three quota lists. The message names banweek.txt or banmonth.txt when that list is absent instead. Falta la lista diaria al combinar las tres listas de bloqueos por cuota. El mensaje identifica banweek.txt o banmonth.txt cuando falta esa lista.
WARNING: clearing all Bandata quota blocks -alert Bandata detects a list preparation, set preparation or IP loading failure. It then attempts to clear all quota blocks. This warning does not confirm successful removal. Bandata detecta un fallo al preparar listas, preparar conjuntos o cargar IP. Después intenta retirar todos los bloqueos por cuota. El aviso no confirma su retirada.
File and command failures An unreadable file, a directory instead of a file, or a read error produces a different warning. The warning identifies the affected file; command failures also include the exit code. Un archivo sin permiso de lectura, una carpeta o un error de lectura generan otro aviso. El aviso identifica el archivo afectado. Los fallos de comandos también incluyen su código de salida.
Quota block release after failures
The recovery mechanism clears the active bandata set to release all Bandata quota blocks. It runs when:
  • A daily, weekly or monthly block list is missing, unreadable or not a regular file.
  • Reading, sorting or deduplicating those lists fails.
  • Creating bandata or bandata_new, or clearing bandata_new, fails.
  • Adding an IP address to bandata_new fails.
  • Clearing a quota list after a publication failure fails.
  • Activating the new set with ipset swap fails; this branch logs its own warning.
The warning announces recovery, not successful completion. Block removal depends on ipset flush bandata succeeding.
El mecanismo de recuperación vacía el conjunto activo bandata para liberar todos los bloqueos por cuota. No retira bloqueos ajenos a Bandata. Se activa ante estos fallos:
  • Falta una lista diaria, semanal o mensual, es ilegible o no es un archivo regular.
  • Falla la lectura, la ordenación o la eliminación de duplicados de esas listas.
  • Falla la creación de bandata o bandata_new, o el vaciado de bandata_new.
  • Falla la incorporación de una IP a bandata_new.
  • Falla el vaciado de una lista tras fallar su publicación.
  • Falla la activación mediante ipset swap; esta ruta registra su propio aviso.
El aviso anuncia la recuperación, no su finalización. La liberación requiere que ipset flush bandata termine correctamente.
# The day reports cannot be read
2026-10-17 12:00:00 WARNING: cannot read day reports, day cleared -alert

# A block list cannot be built from the reports
2026-10-17 12:00:00 WARNING: cannot build daily list, day cleared -alert
2026-10-17 12:00:00 WARNING: cannot build weekly list, week cleared -alert
2026-10-17 12:00:00 WARNING: cannot build monthly list, month cleared -alert

# The kernel set is incomplete or cannot be put in service
2026-10-17 12:00:00 WARNING: block set half loaded, all blocks cleared -alert
2026-10-17 12:00:00 WARNING: cannot activate new set, all blocks cleared -alert
Scheduled execution
# Bandata - Monitor bandwidth usage and enforce data limits (every 5 minutes)
sudo nano /etc/cron.d/proxymon
*/5 * * * * root /etc/proxymon/bandata/bandata.sh
Terminal output example
2026-10-19 15:59:56 INFO: bandata start...
2026-10-19 15:59:56 INFO: Running Bandata Day...
2026-10-19 15:59:56 INFO: daily blocked 192.168.0.86
2026-10-19 15:59:56 INFO: Running Bandata Week...
2026-10-19 15:59:57 INFO: weekly blocked 192.168.0.86
2026-10-19 15:59:57 INFO: weekly blocked 192.168.0.101
2026-10-19 15:59:57 INFO: weekly blocked 192.168.0.127
2026-10-19 15:59:57 INFO: Running Bandata Month...
2026-10-19 16:00:01 INFO: monthly blocked 192.168.0.60
2026-10-19 16:00:01 INFO: monthly blocked 192.168.0.68
2026-10-19 16:00:01 INFO: Running Ipset/Iptables Rules...
2026-10-19 16:00:01 INFO: Applying Iptables Rules...
2026-10-19 16:00:01 INFO: Quota rules applied; blocked IPs: 5
2026-10-19 16:00:01 INFO: bandata done
Warning Portal

warning

When an IP address exceeds its daily, weekly, or monthly quota, Bandata redirects its HTTP traffic to the Warning portal. Other traffic is blocked: Cuando una IP supera su cuota diaria, semanal o mensual, Bandata redirige su tráfico HTTP al portal de advertencia (Warning) y bloquea el resto del tráfico:
http://192.168.X.X:18771
Banned IPs
To view the blocked IP addresses: Para consultar las IP bloqueadas:
cat /etc/proxymon/bandata/acl/{banmonth,banweek,banday}.txt | uniq
Data Limit
You can enter limits in gigabytes, megabytes, or bytes; for example, 0.5G, 512M, or 536870912. The default limits are 1 GB per day, 5 GB per week, and 20 GB per month. Puede indicar los límites en gigabytes, megabytes o bytes; por ejemplo, 0.5G, 512M o 536870912. Los valores predeterminados son 1 GB al día, 5 GB a la semana y 20 GB al mes.
By Day
Bandata compares the day's usage with the daily limit and blocks IP addresses that exceed it. On each weekday run, it recalculates the daily list from that day's report; it clears the list on weekends. An IP address is no longer blocked by the daily quota once it disappears from that list, though it may remain blocked if it appears in the weekly or monthly list. To change the daily limit, edit /etc/proxymon/proxymon.env: Bandata compara el consumo del día con el límite diario y bloquea las IP que lo superan. En cada ejecución de lunes a viernes recalcula la lista diaria con el informe de ese día; durante el fin de semana la vacía. La IP deja de estar bloqueada por cuota diaria cuando desaparece de esa lista, aunque puede seguir bloqueada si aparece en la lista semanal o mensual. Para cambiar el límite diario, edite /etc/proxymon/proxymon.env:
MAX_BANDWIDTH_DAY=1G
By Week
Every Monday, Bandata totals the usage recorded from Monday to Friday of the previous week and updates the weekly list. If an IP address exceeds the limit (5 GB by default), it remains blocked under the weekly quota until a later Monday calculation removes it from that list. It may also remain blocked if it appears in the daily or monthly list. To change the weekly limit, edit /etc/proxymon/proxymon.env: Cada lunes, Bandata suma el consumo registrado de lunes a viernes de la semana anterior y actualiza la lista semanal. Si una IP supera el límite —5 GB de forma predeterminada—, permanece bloqueada por cuota semanal hasta que el cálculo de un lunes posterior la quite de esa lista. También puede seguir bloqueada si aparece en la lista diaria o mensual. Para cambiar el límite semanal, edite /etc/proxymon/proxymon.env:
MAX_BANDWIDTH_WEEK=5G
By Month
On every run, Bandata totals usage recorded on weekdays in the current month and updates the monthly list. If an IP address exceeds the limit (20 GB by default), it remains blocked under the monthly quota while it appears on that list. At the start of the next month, the list is calculated from the new month's reports, removing blocks that applied only to the previous month. The IP may remain blocked if it appears in the daily or weekly list. To change the monthly limit, edit /etc/proxymon/proxymon.env: En cada ejecución, Bandata suma el consumo de los días hábiles del mes en curso y actualiza la lista mensual. Si una IP supera el límite —20 GB de forma predeterminada—, permanece bloqueada por cuota mensual mientras figure en esa lista. Al comenzar el mes siguiente, la lista se calcula con los informes del nuevo mes y elimina los bloqueos que solo correspondían al mes anterior. La IP puede seguir bloqueada si aparece en la lista diaria o semanal. Para cambiar el límite mensual, edite /etc/proxymon/proxymon.env:
MAX_BANDWIDTH_MONTH=20G
Bandata builds the blocked IP set by combining the daily, weekly, and monthly lists. An IP address is unblocked only when it no longer appears in any of the three. Bandata forma el conjunto de IP bloqueadas uniendo las listas diaria, semanal y mensual. Una IP deja de estar bloqueada cuando ya no aparece en ninguna de las tres.

LOGVIEW

Logview panel

Logview contains two internal tabs: Log for access logs and Live for active requests. Both views remain inside Logview. The Log/Live buttons share the controls row; the Log search field has a compact width. Logview contiene dos pestañas internas: Log para los registros de acceso y Live para las solicitudes en curso. Ambas vistas permanecen dentro de Logview. Los botones Log/Live comparten la fila de controles; el campo de búsqueda de Log tiene un ancho reducido.
Theme Control

Logview: light and dark themes / temas claro y oscuro

Control Description Descripción
Theme toggle
  • Shared theme toggle at the right of the dashboard header, beside the local date and time. Switches both views between light and dark themes.
  • Dark is the default theme for Log and Live. The shared theme selection is saved in the browser and applied before displaying the content when Logview reloads. Live uses the same selection when opened, including when its refresh is paused.
  • Botón de tema compartido a la derecha de la cabecera, junto a la fecha y hora local. Alterna ambas vistas entre los temas claro y oscuro.
  • El tema oscuro es el predeterminado de Log y Live. La selección de tema compartido se guarda en el navegador y se aplica antes de mostrar el contenido al recargar Logview. Live adopta esa selección al abrirse, incluso con su actualización pausada.
Access Logs (Log)
• Log opens by default and displays new entries from /var/log/squid/access.log in a table that refreshes periodically.

• Search the loaded entries, filter by cache code or HTTP status, and sort columns.
• Log abre por defecto y muestra las nuevas entradas de /var/log/squid/access.log en una tabla que se actualiza periódicamente.

• Puede buscar entre las entradas cargadas, filtrar por código de caché o estado HTTP y ordenar las columnas.
Controls
Message Description Descripción
Filters by Squid cache code: TCP_HIT (cached), TCP_MISS (origin), TCP_MISS_ABORTED (aborted), TCP_DENIED (blocked), TCP_TUNNEL (HTTPS), TCP_MEM_HIT (memory cache), TCP_REFRESH_HIT/MISS (revalidated), TCP_REFRESH_UNMODIFIED/MODIFIED (revalidation result), NONE_NONE (invalid/error request). Filtra por código de caché de Squid: TCP_HIT (caché), TCP_MISS (origen), TCP_MISS_ABORTED (abortado), TCP_DENIED (bloqueado), TCP_TUNNEL (HTTPS), TCP_MEM_HIT (memoria), TCP_REFRESH_HIT/MISS (revalidado), TCP_REFRESH_UNMODIFIED/MODIFIED (resultado de revalidación), NONE_NONE (solicitud inválida/error).
Filters by HTTP response code: 200, 206, 301, 302, 400, 403, 404, 500. Color-coded: green (2xx), yellow (3xx), red (4xx/5xx). Filtra por código de respuesta HTTP: 200, 206, 301, 302, 400, 403, 404, 500. Colores: verde (2xx), amarillo (3xx), rojo (4xx/5xx).
Number of lines loaded from access.log on startup: 200, 500, 1,000, 2,000, or 5,000. Número de líneas cargadas desde access.log al inicio: 200, 500, 1.000, 2.000 o 5.000.
Polling interval for new entries: 1s (default), 3s, 5s, 10s, or 30s. Intervalo de sondeo para nuevas entradas: 1 s (predeterminado), 3 s, 5 s, 10 s o 30 s.
Automatic updates active in Log. New access.log entries appear at the top with a green animation. This indicator is separate from the Live tab. Actualización automática activa en Log. Las nuevas entradas de access.log aparecen al principio con animación verde. Este indicador es independiente de la pestaña Live.
Polling suspended. Indicator turns red and shows PAUSED. Click again to resume. Sondeo suspendido. El indicador cambia a rojo y muestra PAUSED. Haga clic nuevamente para reanudar.
Search Bar

logview_search

The search bar filters loaded entries by IP address, URL, user, HTTP method, cache code, or HTTP response code. La barra filtra las entradas cargadas por IP, URL, usuario, método HTTP, código de caché o código de respuesta HTTP.
Message Description Descripción
Select this option to search the full log. Seleccione esta opción para buscar en el registro completo.
Select this option to return to the live view. Seleccione esta opción para volver a la vista en tiempo real.
Active Requests (Live)

Logview Live

  • Live displays active Squid requests, grouped by client IP, current and average speeds, duration and speed subtotals.
  • Live queries Squid's Cache Manager using SQUID_MGR_HOST, SQUID_MGR_PORT and SQUID_MGR_PASSWD from proxymon.env. Refresh defaults to five seconds; Stop pauses it. Refresh is stored per browser session.
  • Live muestra las solicitudes activas de Squid, agrupadas por IP de cliente, velocidad actual y media, duración y subtotales de velocidad.
  • Live consulta el administrador de caché de Squid mediante SQUID_MGR_HOST, SQUID_MGR_PORT y SQUID_MGR_PASSWD de proxymon.env. Se actualiza cada cinco segundos por defecto; Stop pausa la actualización. El intervalo se conserva por sesión del navegador.

AI

squidai

SquidAI is an assistant for network administrators. It uses BM25 to find relevant information in its data and a language model (LLM) to respond in natural language. It combines data from Squid, Squidreports reports, and ACL lists to help answer questions about user profiles, blocked activity, incidents, and network usage:
  • User profiles: Activity summary, most visited domains and blacklist verification for specific users.
  • Security incidents: Detection of requests sent directly to IP addresses, Torrent/P2P traffic, Log4Shell patterns, .onion sites and other suspicious behaviors.
  • Blocked access: Which IPs attempted to access blocked domains or TLDs.
  • Network summary: Top consumers, most visited domains, total data usage and unique IPs.
  • Consumption thresholds: Users exceeding specific GB limits (e.g. "more than 3 GB").
  • User list: Complete list of registered users from realname.cfg (excluding skipuser.cfg) of Squidreports.
The assistant responds in Spanish or English, matching the language of the question, and presents its findings in tables and detailed analyses.
SquidAI es un asistente especializado para administradores de red. Usa BM25 para localizar información relevante en sus datos y un modelo de lenguaje (LLM) para responder en lenguaje natural. Combina respuestas basadas en datos de Squid, informes de Squidreports y listas ACL. Puede ayudar a consultar perfiles de usuario, actividad bloqueada, incidentes y consumo de la red:
  • Perfiles de usuario: Resumen de actividad, dominios más visitados y verificación en lista negra para usuarios específicos.
  • Incidentes de seguridad: Detección de accesos directos a direcciones IP, tráfico Torrent/P2P, patrones Log4Shell, sitios .onion y otros comportamientos sospechosos.
  • Accesos bloqueados: Qué IP intentaron acceder a dominios o TLDs bloqueados.
  • Resumen de red: Principales consumidores, dominios más visitados, consumo total de datos e IP únicas.
  • Umbrales de consumo: Usuarios que superan límites específicos en GB (por ejemplo, "más de 3 GB").
  • Lista de usuarios: Lista completa de usuarios registrados desde realname.cfg (excluyendo skipuser.cfg) de Squidreports.
El asistente responde en español o inglés, según el idioma de la consulta, y presenta la información en tablas y análisis detallados.
Public panel access (PANEL_DOMAINS)
Panel published through a tunnel or reverse proxy. To send LLM queries from a public HTTPS panel, declare its domain in PANEL_DOMAINS, in /etc/proxymon/proxymon.env. Otherwise, worker.php rejects those POST requests with 403. Enter domains or subdomains separated by commas, without a scheme, port or path. Each valid domain authorizes its HTTPS origin on the default port, 443. A malformed entry is discarded and reported in the Apache error log. An empty value keeps only the local panel origins authorized; this key does not change Apache's loopback listener.
PANEL_DOMAINS=proxy.example.com
Panel publicado por túnel o proxy inverso. Para enviar consultas al LLM desde un panel público HTTPS, declare su dominio en PANEL_DOMAINS, en /etc/proxymon/proxymon.env. Si no lo declara, worker.php rechaza esas peticiones POST con 403. Escriba dominios o subdominios separados por comas, sin esquema, puerto ni ruta. Cada dominio válido autoriza su origen HTTPS en el puerto predeterminado, 443. Los valores malformados se descartan y se registran en el log de errores de Apache. Un valor vacío conserva únicamente los orígenes locales del panel; esta clave no cambia la escucha de Apache en loopback.
PANEL_DOMAINS=proxy.example.com
Examples
Description Descripción
User queries:
"Show me JOHN-SMITH activity"
"What did CARLOS-GARCIA do today?"
"Report for ACCOUNTING-DEPT"
Consultas de usuario:
"Muéstrame la actividad de JOHN-SMITH"
"¿Qué hizo CARLOS-GARCIA hoy?"
"Informe de CONTABILIDAD"
Network queries:
"Top 10 most visited domains today"
"Who consumes the most bandwidth?"
"Users who exceeded 3 GB"
Consultas de red:
"Top 10 dominios más visitados hoy"
"¿Quién consume más ancho de banda?"
"Usuarios que superaron 3 GB"
Security queries:
"Are there security incidents?"
"Detect any threat today?"
"Is there torrent traffic?"
Consultas de seguridad:
"¿Hay incidentes de seguridad?"
"¿Detectas alguna amenaza hoy?"
"¿Hay tráfico de torrents?"
Blocked accesses:
"Which IPs accessed blocked domains?"
"Show blocked TLD accesses"
Accesos bloqueados:
"¿Qué IPs accedieron a dominios bloqueados?"
"Muestra accesos a TLDs bloqueados"
User list:
"List all registered users"
"Show me all users"
Lista de usuarios:
"Lista todos los usuarios registrados"
"Muéstrame todos los usuarios"

Top Domains uses daily Squidreports data and ranks domains by hits. Top Consumers ranks users by bytes transferred.

Top Domains usa los reportes diarios de Squidreports y ordena los dominios por hits. Top Consumers ordena los usuarios por bytes transferidos.

The user names in the examples are illustrative. For the assistant to recognize them, they must exist in realname.cfg (and not be excluded in skipuser.cfg), where Squidreports stores the IP-to-hostname mapping.

Los nombres de usuario en los ejemplos son ilustrativos. Para que el asistente los reconozca, deben existir en realname.cfg (y no estar excluidos en skipuser.cfg), donde Squidreports almacena la correspondencia entre IP y nombres de equipo.

Security Incidents
For security incident detection, SquidAI uses /etc/squid/acl/blockpatterns.txt and direct IPv4 detection. Severity depends on the pattern type and number of matches; results can be classified as CRITICAL, HIGH, MEDIUM, or LOW. Para la detección de incidentes de seguridad, SquidAI utiliza /etc/squid/acl/blockpatterns.txt y detección de IPv4 directa. La severidad depende del tipo de patrón y del número de coincidencias; los resultados pueden clasificarse como CRITICAL, HIGH, MEDIUM o LOW.
API Configuration
Description Descripción
🔧 API Setup: SquidAI requires an LLM provider to function. The configuration file is located outside the webroot for security: sudo nano /etc/proxymon/.env /etc/proxymon/ contains two files: .env (SquidAI LLM credentials) and proxymon.env (shared Proxy Monitor configuration, including Bandata network and quota settings). Do not confuse them. Set your provider URL, API key and response format:
LLM_URL=https://your-provider.com/endpoint
LLM_API_KEY=your_api_key
LLM_MODEL=model-name
LLM_RESPONSE_FORMAT=openai
🔧 Configuración de API: SquidAI requiere un proveedor LLM para funcionar. El archivo de configuración se encuentra fuera del webroot por seguridad: sudo nano /etc/proxymon/.env /etc/proxymon/ contiene dos archivos: .env (credenciales LLM de SquidAI) y proxymon.env (configuración compartida de Proxy Monitor, incluidas la red y las cuotas de Bandata). No los confunda. Configure la URL del proveedor, la clave de API y el formato de respuesta:
LLM_URL=https://su-proveedor.com/endpoint
LLM_API_KEY=su_api_key
LLM_MODEL=nombre-del-modelo
LLM_RESPONSE_FORMAT=openai
The URL format depends on the provider.
  • Some providers include the account ID or the model name in the URL, for example Cloudflare: …/accounts/ACCOUNT_ID/ai/run/MODEL_NAME.
  • Others use a fixed URL with the model in LLM_MODEL, for example OpenAI and Groq.
  • Others embed the API key as a URL parameter, for example Gemini: …?key=YOUR_KEY.
Check the commented examples in the .env file for each provider's exact format. Leave LLM_MODEL empty if the model is already part of the URL.
El formato de la URL depende del proveedor.
  • Algunos proveedores incluyen el identificador de cuenta o el nombre del modelo en la URL, por ejemplo Cloudflare: …/accounts/ACCOUNT_ID/ai/run/NOMBRE_MODELO.
  • Otros usan una URL fija con el modelo en LLM_MODEL, por ejemplo OpenAI y Groq.
  • Otros incrustan la clave de API como parámetro de la URL, por ejemplo Gemini: …?key=SU_CLAVE.
Consulte los ejemplos comentados del archivo .env para ver el formato exacto de cada proveedor. Deje LLM_MODEL vacío si el modelo ya forma parte de la URL.
LLM_RESPONSE_FORMAT tells the worker how to read the response: openai (most providers), ollama (local Ollama), or gemini (Google Gemini passthrough). LLM_RESPONSE_FORMAT indica al worker cómo leer la respuesta: openai (la mayoría de proveedores), ollama (Ollama local) o gemini (Google Gemini passthrough).
The file includes commented examples for: Cloudflare Workers AI, OpenAI, Groq, OpenRouter, Together AI, Ollama (local), LM Studio (local) and Google Gemini. Uncomment one block and fill in your credentials. El archivo incluye ejemplos comentados para: Cloudflare Workers AI, OpenAI, Groq, OpenRouter, Together AI, Ollama (local), LM Studio (local) y Google Gemini. Descomente un bloque y complete sus credenciales.
🔒 Security: The .env file is stored in /etc/proxymon/, outside the Apache webroot. Root and processes in the www-data group, including Apache PHP, can read the file. 🔒 Seguridad: El archivo .env se almacena en /etc/proxymon/, fuera del webroot de Apache. Root y los procesos del grupo www-data, incluido PHP de Apache, pueden leer el archivo.
🔄 Rate Limits & Retries: LLM APIs may experience congestion depending on demand. SquidAI implements an automatic retry mechanism: up to 4 attempts with progressive delays (4s, 8s, 15s) before giving up. If the API is temporarily unavailable, the assistant will display retry messages. If all attempts fail, it displays the notice shown in the following table. 🔄 Límites de solicitudes y reintentos: Las APIs LLM pueden experimentar congestión según la demanda. SquidAI implementa un mecanismo de reintento automático: hasta 4 intentos con esperas progresivas (4 s, 8 s y 15 s) antes de desistir. Si la API no está disponible temporalmente, el asistente mostrará mensajes de reintento. Si todos los intentos fallan, mostrará el aviso de la tabla siguiente.
Message Description Descripción
Example of the automatic retry message. Ejemplo del mensaje de reintento automático.
Example shown when the API is unavailable. Ejemplo de API no disponible.
LLM Status
🔌 LLM Status: The LED indicates whether the connection is checking, connected, or offline. 🔌 Estado LLM: El LED indica si la conexión se está verificando, está conectada o está fuera de línea.
Message Description Descripción
Checking LLM connection Verificando conexión con el LLM
LLM connected and ready LLM conectado y listo
LLM unreachable or offline LLM inaccesible o fuera de línea

TOOLS

Command-line utilities are installed in /etc/proxymon/tools and run from a terminal. The HTML reports they generate can be viewed from the panel. Las utilidades de consola se instalan en /etc/proxymon/tools y se ejecutan desde la terminal. Los informes HTML que generan se pueden consultar desde el panel.

Squidtool

Squidtool is a command-line utility with two functions: generate a traffic report and search Squid logs. Run it with: Squidtool es una utilidad de consola con dos funciones: generar un informe de tráfico y buscar términos en los registros de Squid. Se ejecuta con:
sudo /etc/proxymon/tools/squidtool.sh

Both functions read access.log and every rotated file, compressed or not, so they cover the full retention period set in /etc/logrotate.d/squid.

Each function generates an HTML report and replaces the previous report of the same type, so only the latest result is kept. The reports are written to TOOL_REPORT_DIR (/etc/proxymon/tools/reports by default), outside the Apache webroot, and the panel serves them read-only under the same loopback-only restriction. Tool activity is logged beside the script (CONFIG_DIR/tools/squidtool.log).

Las dos funciones leen access.log y todos los rotados, comprimidos o no, así que cubren todo el periodo de retención definido en /etc/logrotate.d/squid.

Cada función genera un informe HTML y reemplaza el anterior del mismo tipo; solo se conserva el resultado más reciente. Los informes se escriben en TOOL_REPORT_DIR (/etc/proxymon/tools/reports por defecto), fuera del webroot de Apache, y el panel los publica en modo lectura con la misma restricción a loopback. La herramienta registra su actividad junto al script (CONFIG_DIR/tools/squidtool.log).

Traffic Report

squidtool traffic

Analyzes the requests recorded by Squid, grouping them by client IP and requested domain. It allows selecting a single IP or analyzing every IP, and defining the period to review. The analysis covers the current access.log and its rotated or compressed files. Requests are counted and sorted from the most active to the least. When every IP is analyzed, entries below 20 requests are excluded. Entries reaching or exceeding 300 requests are shown as alerts. The result is written to squid_traffic.html. Analiza las solicitudes registradas por Squid, agrupándolas por IP de cliente y dominio solicitado. Permite seleccionar una IP concreta o analizar todas las IP y definir el período que se desea revisar. El análisis incluye el access.log actual y sus archivos rotados o comprimidos. Las solicitudes se contabilizan y se ordenan de mayor a menor actividad. Cuando se analizan todas las IP, se excluyen las entradas con menos de 20 solicitudes. Las entradas que alcanzan o superan las 300 solicitudes se muestran como alertas. El resultado se genera en squid_traffic.html.
Log Search

squidtool search

• Searches for a specific term in the access.log and cache.log records, without distinguishing between uppercase and lowercase. The text is matched literally, not as a regular expression, so characters such as ?, &, = or * are searched as typed. The search includes the current, rotated and compressed files. In access.log it allows filtering by client IP and setting the search period. In cache.log the IP filter does not apply, because that record does not contain the client IP. The results from access.log and cache.log are shown separately, along with the number of matches found in each record. The result is written to squid_search.html.

• For cache.log to record the ACL decisions -- which rule allowed or blocked each request -- Squid must have debug_options ALL,1 33,2 28,9 enabled in squid.conf. Without it the search still works, but that record only holds the usual service messages. Keep in mind that this directive makes cache.log grow considerably.
• Busca un término específico en los registros access.log y cache.log, sin distinguir entre mayúsculas y minúsculas. El texto se busca de forma literal, no como expresión regular, de modo que caracteres como ?, &, = o * se buscan tal cual se escriben. La búsqueda incluye los archivos actuales, rotados y comprimidos. En access.log permite filtrar por IP de cliente y establecer el período de búsqueda. En cache.log no se aplica el filtro por IP porque este registro no contiene la IP del cliente. Los resultados de access.log y cache.log se muestran por separado, junto con la cantidad de coincidencias encontradas en cada registro. El resultado se genera en squid_search.html.

• Para que cache.log registre las decisiones de ACL -- qué regla permitió o bloqueó cada solicitud -- Squid debe tener activada la directiva debug_options ALL,1 33,2 28,9 en squid.conf. Sin ella la búsqueda sigue funcionando, pero ese registro solo contendrá los mensajes habituales del servicio. Tenga en cuenta que esa directiva hace crecer cache.log de forma considerable.

pmbk

pmbk.sh creates a ZIP archive with the Proxy Monitor installation and configuration, including the paths listed below:
  • The project install tree, /var/www/proxymon, and /etc/proxymon.
  • The MAC and Squid ACL lists.
  • The Bandata ACL directory and its quota lists.
  • The Apache vhosts and the Apache and PHP hardening files.
  • The bandata logrotate configuration.
  • The project's /etc/cron.d/proxymon entry and the php.ini in use.
Paths that do not exist are skipped. Only the last 3 archives are kept. pmsetup.sh --update runs this backup before updating project files.
pmbk.sh crea un archivo ZIP con la instalación y configuración de Proxy Monitor, incluidas las rutas que se enumeran a continuación:
  • El árbol de instalación del proyecto, /var/www/proxymon, y /etc/proxymon.
  • Las listas ACL de MAC y de Squid.
  • El directorio ACL de Bandata y sus listas de cuota.
  • Los hosts virtuales de Apache y los archivos de protección de Apache y PHP.
  • La configuración de logrotate de bandata.
  • La entrada /etc/cron.d/proxymon del proyecto y el php.ini en uso.
Las rutas que no existan se omiten. Solo se conservan los 3 últimos archivos. pmsetup.sh --update ejecuta esta copia de seguridad antes de actualizar los archivos del proyecto.
Command Description Descripción
sudo bash pmbk.sh Create a backup now Crear una copia ahora
sudo bash pmbk.sh --install Register the @monthly cron entry Registrar la entrada mensual en cron
sudo bash pmbk.sh --uninstall Remove the cron entry, keeping the archives Quitar la entrada de cron, conservando los archivos ZIP

Backs up Proxymon into BACKUP_DIR/pmbk_<YYYYMMDD_HHMMSS>.zip (BACKUP_DIR must be /etc/bak/proxymon). After publishing, it deletes other contents and keeps the 3 most recent archives. pmsetup.sh --install registers the monthly cron entry automatically; pmsetup.sh --uninstall removes it before removing the project. Restore with sudo unzip -X ARCHIVE.zip -d / to recover the stored Unix ownership and permissions. Validate the archive in an isolated directory before restoring.

Respalda Proxymon en BACKUP_DIR/pmbk_<YYYYMMDD_HHMMSS>.zip (BACKUP_DIR debe ser /etc/bak/proxymon). Tras publicar, elimina el resto del contenido y conserva los tres archivos ZIP más recientes. pmsetup.sh --install registra la entrada mensual de cron automáticamente; pmsetup.sh --uninstall la elimina antes de quitar el proyecto. Restaure con sudo unzip -X ARCHIVO.zip -d / para recuperar propietarios y permisos Unix almacenados. Valide el archivo en un directorio aislado antes de restaurar.

PROXYMON LOGS

Project log: /var/log/proxymon.log. Installation and update configure weekly rotation in /etc/logrotate.d/proxymon, keeping seven previous files plus the active log. Compression starts on the next rotation. Empty logs are not rotated; missing logs are tolerated. Apache is set to rotate 7, and Squid to weekly, rotate 7 and create 0640 proxy proxy, each after saving a .bak copy. Log del proyecto: /var/log/proxymon.log. La instalación y la actualización configuran rotación semanal en /etc/logrotate.d/proxymon. Se conservan siete archivos anteriores y el activo. La compresión comienza en la siguiente rotación. Los logs vacíos no se rotan; los ausentes se toleran. Apache se fija en rotate 7, y Squid en weekly, rotate 7 y create 0640 proxy proxy, cada uno tras guardar una copia .bak.
/var/log/apache2/proxymon_access.log
/var/log/apache2/proxymon_error.log
/var/log/bandata.log                 # Rotated via /etc/logrotate.d/bandata
pmsetup.log                          # In pmsetup.sh's own directory, rewritten on each run
/etc/proxymon/tools/squidtool.log    # In squidtool.sh's own directory, rewritten on each run

Message examples

2026-10-17 12:00:00 INFO: squid.conf deployed for 192.168.10.0/24
2026-10-17 12:00:00 INFO: blockpatterns.txt: download failed; retry 2/3
2026-10-17 12:00:00 WARNING: blockpatterns.txt download failed -alert
2026-10-17 12:00:00 WARNING: pmbk.sh: monthly backup setup failed -alert

ACKNOWLEDGMENTS


Part of Proxy Monitor reimplements selected functions from LightSquid, SARG, SqStat and SquidAnalyzer. These open-source tools no longer receive support or updates (EOL/EOS).

We extend our special thanks to the developers who created these remarkable tools and devoted their time to building them. Without this foundation, the development of Proxy Monitor would not have been possible.

Una parte de Proxy Monitor reimplementa funciones de LightSquid, SARG, SqStat y SquidAnalyzer. Estas herramientas de código abierto ya no reciben soporte ni actualizaciones (EOL/EOS).

Agradecemos especialmente a los programadores que crearon estas magníficas herramientas y dedicaron su tiempo a desarrollarlas. Sin esta base, el desarrollo de Proxy Monitor no habría sido posible.

Original project / Developer Last Official Version Unofficial Update Additional Reimplemented in
LightSquid v1.8-7 (2009) v1.8.1 (2021) Metro_tpl @semofajardo (2020) squidreports
SARG v2.4.0 (2020-01-16) N/A N/A squidreports
Sqstat - Alex Samorukov v1.20 (2006) N/A N/A logview
SquidAnalyzer github v6.6 (2017) N/A N/A squidreports

⚠️ WARNING: NETWORK ACCESS


This project is designed for use on a local network (LAN). It does not include the security hardening needed for direct exposure to the internet. If internet access is required, an on-demand tunnel is recommended instead of opening ports directly. This enables access when needed without leaving the server permanently exposed. Este proyecto está diseñado para usarse en una red local (LAN). No cuenta con las medidas de seguridad necesarias para exponerlo directamente a Internet. Si se requiere acceso desde Internet, se recomienda utilizar un túnel bajo demanda en lugar de abrir puertos directamente. Así, el acceso se habilita cuando hace falta y el servidor no queda expuesto permanentemente.

Optional tunnel:

NOTICE


This repository
  • May include third-party components.
  • Does not accept Pull Requests. Changes must be proposed via Issues.
  • This project does not support backward compatibility. New versions may require configuration changes or reinstallation.
  • Adding custom tasks to the project's cron file is not recommended because each installation or update rewrites it.
Este repositorio
  • Puede incluir componentes de terceros.
  • No acepta Pull Requests. Los cambios deben proponerse mediante Issues.
  • Este proyecto no soporta retrocompatibilidad. Las nuevas versiones pueden requerir cambios de configuración o una reinstalación.
  • No se recomienda programar tareas propias en el cron del proyecto, ya que se reescribe en cada instalación o actualización.

LIMITATIONS


  • Follows a non-standard workflow. Published commits may be rewritten or removed without notice as part of the debugging and improvement process.
  • Utiliza un flujo de trabajo no convencional. Los commits publicados pueden ser reescritos o eliminados sin previo aviso como parte del proceso de depuración y mejora.

SPONSOR THIS PROJECT


Image

PROJECT LICENSES


This project uses a dual-licensing model to balance software freedom with content protection: Este proyecto utiliza un modelo de licencia dual para equilibrar la libertad del software con la protección del contenido:
Content Licensed Under
Scripts, Binaries, Infrastructure GPL-3.0
RAG, Workers, Specialized Modules, Docs CC

DISCLAIMER


THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. 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.

About

Traffic management and auditing tool for Squid proxy server

Topics

Resources

Stars

1 star

Watchers

0 watching

Forks

Contributors

Languages