Squid Proxy Cache Server

intermediate

Web proxy and cache with Squid, HTTPS inspection, and monitoring.

Overview

Squid is a full-featured HTTP/HTTPS proxy server and web cache daemon that has been optimizing network performance since 1996. Originally developed for Unix-like systems, Squid acts as an intermediary between client browsers and web servers, caching frequently requested content to reduce bandwidth usage and improve response times. Its robust access control lists (ACLs) and content filtering capabilities make it a cornerstone of enterprise network security and performance optimization. This stack combines Squid with a comprehensive monitoring solution using squid-exporter to extract proxy metrics, Prometheus to collect and store time-series data, and Grafana to visualize cache hit rates, bandwidth usage, and client access patterns. The squid-exporter specifically monitors Squid's cache performance, request patterns, and response codes, feeding this data to Prometheus for long-term storage and alerting. Grafana transforms these metrics into actionable dashboards showing cache efficiency, top requested domains, and bandwidth savings. Network administrators managing corporate internet access, ISPs looking to reduce upstream bandwidth costs, and organizations requiring content filtering will find this stack invaluable. The monitoring layer provides visibility into proxy performance that's essential for optimizing cache policies and identifying network usage patterns. This combination is particularly valuable in environments where internet bandwidth is expensive or limited, as Squid's caching can dramatically reduce external traffic while the monitoring stack proves ROI through detailed bandwidth savings reports.

Key Features

HTTP/HTTPS transparent and explicit proxy with SSL bump capabilities for HTTPS inspection
Intelligent web caching with configurable storage limits and cache replacement policies
Advanced ACL system supporting IP ranges, domains, time-based rules, and user authentication
Real-time Squid metrics export including cache hit ratios, request rates, and storage utilization
PromQL-powered analysis of proxy performance trends and bandwidth usage patterns
Grafana dashboards for cache efficiency monitoring and client access visualization
Content filtering with support for blacklists, whitelists, and custom URL patterns
Bandwidth throttling and QoS controls for different user groups or destinations

Common Use Cases

1Corporate internet gateway with employee web access control and bandwidth management
2ISP transparent proxy deployment to reduce upstream bandwidth costs through aggressive caching
3Educational institution content filtering with detailed reporting on student internet usage
4Remote office proxy server with monitoring to optimize WAN link utilization
5Development environment proxy for API caching and request debugging with metrics tracking
6Content delivery optimization for organizations with multiple branch offices sharing cached content
7Compliance monitoring setup requiring detailed logs and reports of all web traffic patterns

Prerequisites

Minimum 2GB RAM (1GB for Squid cache, 256MB each for Prometheus and Grafana, plus overhead)
Available ports 3128 (Squid), 9090 (Prometheus), 3000 (Grafana), and 9301 (squid-exporter)
Understanding of proxy configuration concepts including explicit vs transparent proxy modes
Basic knowledge of Squid ACL syntax for implementing access control and filtering rules
Network configuration access to set up client proxy settings or transparent interception
Environment variable GRAFANA_PASSWORD set for Grafana admin authentication

For development & testing. Review security settings, change default credentials, and test thoroughly before production use. See Terms

docker-compose.yml

1services: 
2  squid: 
3    image: ubuntu/squid:latest
4    ports: 
5      - "3128:3128"
6    volumes: 
7      - ./squid.conf:/etc/squid/squid.conf:ro
8      - squid_cache:/var/spool/squid
9      - squid_logs:/var/log/squid
10    networks: 
11      - squid_net
12
13  squid-exporter: 
14    image: boynux/squid-exporter:latest
15    ports: 
16      - "9301:9301"
17    environment: 
18      - SQUID_HOSTNAME=squid
19      - SQUID_PORT=3128
20    depends_on: 
21      - squid
22    networks: 
23      - squid_net
24
25  prometheus: 
26    image: prom/prometheus:latest
27    ports: 
28      - "9090:9090"
29    volumes: 
30      - ./prometheus.yml:/etc/prometheus/prometheus.yml
31      - prometheus_data:/prometheus
32    networks: 
33      - squid_net
34
35  grafana: 
36    image: grafana/grafana:latest
37    ports: 
38      - "3000:3000"
39    environment: 
40      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
41    volumes: 
42      - grafana_data:/var/lib/grafana
43    networks: 
44      - squid_net
45
46volumes: 
47  squid_cache: 
48  squid_logs: 
49  prometheus_data: 
50  grafana_data: 
51
52networks: 
53  squid_net:

.env Template

.env

1# Squid Proxy
2GRAFANA_PASSWORD=secure_grafana_password
3
4# Proxy at localhost:3128
5# Configure browser/system proxy settings

Usage Notes

1Proxy at localhost:3128
2Configure clients to use proxy
3Customize squid.conf for ACLs
4Cache improves bandwidth usage
5Content filtering capabilities

Individual Services(4 services)

Copy individual services to mix and match with your existing compose files.

squid

squid:
  image: ubuntu/squid:latest
  ports:
    - "3128:3128"
  volumes:
    - ./squid.conf:/etc/squid/squid.conf:ro
    - squid_cache:/var/spool/squid
    - squid_logs:/var/log/squid
  networks:
    - squid_net

squid-exporter

squid-exporter:
  image: boynux/squid-exporter:latest
  ports:
    - "9301:9301"
  environment:
    - SQUID_HOSTNAME=squid
    - SQUID_PORT=3128
  depends_on:
    - squid
  networks:
    - squid_net

prometheus

prometheus:
  image: prom/prometheus:latest
  ports:
    - "9090:9090"
  volumes:
    - ./prometheus.yml:/etc/prometheus/prometheus.yml
    - prometheus_data:/prometheus
  networks:
    - squid_net

grafana

grafana:
  image: grafana/grafana:latest
  ports:
    - "3000:3000"
  environment:
    - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
  volumes:
    - grafana_data:/var/lib/grafana
  networks:
    - squid_net

Quick Start

terminal

1# 1. Create the compose file
2cat > docker-compose.yml << 'EOF'
3services:
4  squid:
5    image: ubuntu/squid:latest
6    ports:
7      - "3128:3128"
8    volumes:
9      - ./squid.conf:/etc/squid/squid.conf:ro
10      - squid_cache:/var/spool/squid
11      - squid_logs:/var/log/squid
12    networks:
13      - squid_net
14
15  squid-exporter:
16    image: boynux/squid-exporter:latest
17    ports:
18      - "9301:9301"
19    environment:
20      - SQUID_HOSTNAME=squid
21      - SQUID_PORT=3128
22    depends_on:
23      - squid
24    networks:
25      - squid_net
26
27  prometheus:
28    image: prom/prometheus:latest
29    ports:
30      - "9090:9090"
31    volumes:
32      - ./prometheus.yml:/etc/prometheus/prometheus.yml
33      - prometheus_data:/prometheus
34    networks:
35      - squid_net
36
37  grafana:
38    image: grafana/grafana:latest
39    ports:
40      - "3000:3000"
41    environment:
42      - GF_SECURITY_ADMIN_PASSWORD=${GRAFANA_PASSWORD}
43    volumes:
44      - grafana_data:/var/lib/grafana
45    networks:
46      - squid_net
47
48volumes:
49  squid_cache:
50  squid_logs:
51  prometheus_data:
52  grafana_data:
53
54networks:
55  squid_net:
56EOF
57
58# 2. Create the .env file
59cat > .env << 'EOF'
60# Squid Proxy
61GRAFANA_PASSWORD=secure_grafana_password
62
63# Proxy at localhost:3128
64# Configure browser/system proxy settings
65EOF
66
67# 3. Start the services
68docker compose up -d
69
70# 4. View logs
71docker compose logs -f

One-Liner

Run this command to download and set up the recipe in one step:

terminal

1curl -fsSL https://docker.recipes/api/recipes/squid-proxy-cache/run | bash

Troubleshooting

Squid 'Access Denied' errors: Check ACL rules in squid.conf and ensure client IPs are in allowed ranges
High memory usage by Squid: Adjust cache_mem and maximum_object_size_in_memory directives in squid.conf
squid-exporter connection refused: Verify SQUID_HOSTNAME environment variable matches service name and port 3128 is accessible
Prometheus 'target down' for squid-exporter: Check that squid-exporter container is running and accessible on port 9301
Grafana showing no data: Verify Prometheus data source configuration points to http://prometheus:9090
SSL/HTTPS sites not loading through proxy: Configure SSL bump in squid.conf or disable HTTPS filtering for affected domains

Community Notes

Loading notes...

Download Recipe Kit

Get all files in a ready-to-deploy package

Includes docker-compose.yml, .env template, README, and license

Components

squidsquid-exporterprometheusgrafana

Related Recipes

Ad Space

Shortcuts: C CopyF FavoriteD Download