--- title: "How to Set Up a Squid Caching Proxy on Ubuntu 24.04" description: "Set up Squid on Ubuntu 24.04 as a caching forward proxy with a disk cache, refresh patterns, IP and password access control, and cache hit ratio checks." category: "Caching and CDN" language: en source: https://cubepath.com/docs/caching-and-cdn/squid-proxy-cache-advanced-configuration updated: 2026-09-25 --- # How to Set Up a Squid Caching Proxy on Ubuntu 24.04 Squid is a forward proxy: clients send their web requests to it, Squid fetches the content and keeps a copy so the next client that asks for the same object gets it from the local cache. It is commonly used to cache package downloads for a fleet of servers, to give an office a single controlled exit to the internet, or to restrict which sites a network can reach. In this tutorial you will install Squid on Ubuntu 24.04, give it a disk cache with sensible refresh rules, lock it down with an IP allowlist and password authentication, and measure how well the cache performs. ## Prerequisites To follow this tutorial you need: - A server running Ubuntu 24.04 LTS with at least 2 GB of RAM, for example a CubePath VPS, and a non-root user with `sudo` privileges. - Free disk space for the cache. This guide uses 10 GB; size it to your traffic. - The public IP address or network range of the clients that will use the proxy, referred to as `your_client_ip`. > Warning: A proxy that accepts requests from anyone is an open proxy. It will be found within hours and abused for spam and attacks, and your IP will end up on blocklists. Keep both the IP allowlist and authentication from this guide in place. ## Step 1 - Installing Squid Squid is in the Ubuntu repositories: ```bash sudo apt update sudo apt install squid apache2-utils ``` `apache2-utils` provides `htpasswd`, which you will use in Step 4 to create proxy users. The service starts automatically. Confirm that it is running and listening on its default port, 3128: ```bash systemctl status squid --no-pager sudo ss -tlnp | grep 3128 ``` ```output ● squid.service - Squid Web Proxy Server Loaded: loaded (/usr/lib/systemd/system/squid.service; enabled; preset: enabled) Active: active (running) since Thu 2026-09-24 10:12:03 UTC; 25s ago ... LISTEN 0 256 *:3128 *:* users:(("squid",pid=2143,fd=11)) ``` ## Step 2 - Understanding where your configuration goes The main file, `/etc/squid/squid.conf`, is several thousand lines of commented defaults. Rather than editing it, put your settings in a separate file under `/etc/squid/conf.d/`. Ubuntu's `squid.conf` already includes that directory, at the exact point where local access rules belong: ```bash grep -n -E '^include|^http_access' /etc/squid/squid.conf ``` ```output ...:http_access deny !Safe_ports ...:http_access deny CONNECT !SSL_ports ...:http_access allow localhost manager ...:http_access deny manager ...:http_access allow localhost ...:http_access deny to_localhost ...:http_access deny to_linklocal ...:include /etc/squid/conf.d/*.conf ...:http_access deny all ``` Squid evaluates `http_access` lines from top to bottom and stops at the first match. The defaults above block unusual ports, allow the server itself and stop clients from reaching the server's own loopback and link-local addresses through the proxy. Then your rules from `conf.d` run, and anything they do not allow reaches the final `deny all`. Keep that order in mind when adding rules. ## Step 3 - Configuring the cache By default Squid on Ubuntu only caches in memory. Create your configuration file and add a disk cache: ```bash sudo nano /etc/squid/conf.d/local.conf ``` ```squid # Memory cache for small, frequently requested objects cache_mem 256 MB maximum_object_size_in_memory 1 MB # Disk cache: must come after maximum_object_size maximum_object_size 512 MB cache_dir ufs /var/spool/squid 10000 16 256 # Keep the objects that save the most bandwidth cache_replacement_policy heap LFUDA # Package files never change once published refresh_pattern -i \.(deb|rpm|tar\.gz|tar\.xz|zip)$ 10080 90% 43200 refresh_pattern -i (/Packages|/Release|/InRelease)(\.gz|\.xz)?$ 0 20% 60 ``` Each directive has a purpose: - `cache_mem` is the RAM used for hot objects, in addition to Squid's own memory. Keep it well below the server's free RAM. - `cache_dir ufs /var/spool/squid 10000 16 256` creates a 10,000 MB disk cache with 16 first-level and 256 second-level directories. - `maximum_object_size` lets large downloads such as packages and ISO images be cached. It must appear before `cache_dir`, or the cache directory keeps the 4 MB default. - `refresh_pattern` lines set how long, in minutes, an object without explicit expiry headers counts as fresh (minimum, percentage of its age, maximum). The first line keeps package files for a long time; the second keeps repository index files short so clients see new packages quickly. Ubuntu's default patterns in `squid.conf` still apply to everything else. Restart Squid. The systemd unit runs `squid -z` before every start, which creates any missing cache directories: ```bash sudo systemctl restart squid ``` Verify that the directories exist: ```bash sudo ls /var/spool/squid ``` ```output 00 01 02 03 04 05 06 07 08 09 0A 0B 0C 0D 0E 0F swap.state ``` ## Step 4 - Restricting access by IP and password Create the first proxy user. The `-c` flag creates the file, so leave it out when adding more users: ```bash sudo htpasswd -c /etc/squid/passwords your_user ``` Squid runs as the `proxy` user on Ubuntu, so it needs read access to the file, while other users should not see it: ```bash sudo chown root:proxy /etc/squid/passwords sudo chmod 640 /etc/squid/passwords ``` Add the access rules to the end of `/etc/squid/conf.d/local.conf`: ```bash sudo nano /etc/squid/conf.d/local.conf ``` ```squid # Clients allowed to use the proxy acl trusted_clients src your_client_ip # Username and password authentication auth_param basic program /usr/lib/squid/basic_ncsa_auth /etc/squid/passwords auth_param basic children 5 auth_param basic realm Proxy auth_param basic credentialsttl 2 hours acl authenticated proxy_auth REQUIRED # Optional: block some domains for everyone acl blocked_sites dstdomain .example-blocked.com http_access deny blocked_sites # Allow trusted IPs that also authenticate http_access allow trusted_clients authenticated # Do not reveal client IPs to the sites they visit forwarded_for delete ``` Replace `your_client_ip` with an address or CIDR range such as `203.0.113.0/24`; you can repeat the `acl trusted_clients src` line to add more. Both conditions in the `http_access allow` line must match, so a request from an allowed IP without a password gets a `407` asking for credentials, and a request from any other IP is denied. Validate the configuration before applying it. `squid -k parse` prints any errors and the line they are on: ```bash sudo squid -k parse 2>&1 | grep -iE 'error|warning' || echo "Configuration OK" sudo systemctl reload squid ``` Finally, open the port in the firewall only for your clients: ```bash sudo ufw allow OpenSSH sudo ufw allow from your_client_ip to any port 3128 proto tcp sudo ufw enable ``` ## Step 5 - Testing the proxy from a client From an allowed client, send a request through the proxy without credentials. Squid should refuse it: ```bash curl -sI -x http://your_server_ip:3128 http://example.com | head -n 1 ``` ```output HTTP/1.1 407 Proxy Authentication Required ``` Now authenticate. Replace `your_password` with the password you set with `htpasswd`: ```bash curl -sI -x http://your_user:your_password@your_server_ip:3128 http://example.com | head -n 1 ``` ```output HTTP/1.1 200 OK ``` HTTPS works too. For HTTPS, the client opens an encrypted tunnel through Squid with the `CONNECT` method, so Squid can allow or deny the destination but cannot see or cache the content: ```bash curl -sI -x http://your_user:your_password@your_server_ip:3128 https://example.com | head -n 3 ``` ```output HTTP/1.1 200 Connection established HTTP/2 200 ``` To make command-line tools on a Linux client use the proxy, export the standard variables in the shell: ```bash export http_proxy="http://your_user:your_password@your_server_ip:3128" export https_proxy="$http_proxy" ``` For APT, create `/etc/apt/apt.conf.d/95proxy` on the client with the line `Acquire::http::Proxy "http://your_user:your_password@your_server_ip:3128";`. Package downloads from Ubuntu mirrors use plain HTTP, so they are cached. > Note: Basic authentication sends the password to the proxy encoded but not encrypted. Use it only over networks you trust, or reach the proxy through a VPN such as WireGuard. ## Step 6 - Checking the cache hit ratio Download the same package file twice through the proxy from a client: ```bash URL=http://archive.ubuntu.com/ubuntu/pool/main/h/hello/hello_2.10-3build2_amd64.deb curl -s -o /dev/null -x http://your_user:your_password@your_server_ip:3128 "$URL" curl -s -o /dev/null -x http://your_user:your_password@your_server_ip:3128 "$URL" ``` If that exact file has been removed from the mirror, pick any `.deb` under `http://archive.ubuntu.com/ubuntu/pool/`. On the server, look at the last lines of the access log: ```bash sudo tail -n 2 /var/log/squid/access.log ``` ```output 1790244725.311 412 203.0.113.10 TCP_MISS/200 53218 GET http://archive.ubuntu.com/ubuntu/pool/main/h/hello/hello_2.10-3build2_amd64.deb your_user HIER_DIRECT/185.125.190.83 application/vnd.debian.binary-package 1790244727.902 1 203.0.113.10 TCP_MEM_HIT/200 53226 GET http://archive.ubuntu.com/ubuntu/pool/main/h/hello/hello_2.10-3build2_amd64.deb your_user HIER_NONE/- application/vnd.debian.binary-package ``` The first request is a `TCP_MISS` fetched from the mirror; the second is a `TCP_MEM_HIT` served from memory in 1 ms. Larger objects show `TCP_HIT` when they come from the disk cache. `TCP_TUNNEL` entries are HTTPS connections, which are never cached, and `TCP_DENIED` entries are refused requests. For overall statistics, query Squid's cache manager. It is allowed only from `localhost`, so run this on the server: ```bash curl -s http://localhost:3128/squid-internal-mgr/info | grep -E 'Hits as|Storage Swap size|Storage Mem size' ``` ```output Hits as % of all requests: 5min: 38.2%, 60min: 31.7% Hits as % of bytes sent: 5min: 61.4%, 60min: 55.0% Storage Swap size: 1843212 KB Storage Mem size: 118340 KB ``` The byte hit ratio is the one that tells you how much bandwidth the cache saves. ## Troubleshooting **Squid does not start after a change.** Run `sudo squid -k parse` to find the faulty line, and read `sudo journalctl -u squid -n 50` and `/var/log/squid/cache.log`. **Clients get `403 Forbidden` or `TCP_DENIED/403`.** The client IP does not match `trusted_clients`. The access log shows the IP Squid sees; if clients are behind NAT, allow the public address of the NAT. **Clients get `407` even with the right password.** Check the password file permissions with `ls -l /etc/squid/passwords` (group `proxy`, mode `640`) and test the helper by hand: run `/usr/lib/squid/basic_ncsa_auth /etc/squid/passwords` as root, type `your_user your_password` and press Enter. It answers `OK` or `ERR`. Press `Ctrl+D` to exit. **The cache never shows hits.** Most traffic today is HTTPS, which Squid tunnels without caching. Hits come from plain HTTP content such as package mirrors. Also check that the objects are not larger than `maximum_object_size`. ## Conclusion You now have a Squid proxy that caches HTTP content on disk and in memory, only accepts authenticated clients from known addresses, and reports how much traffic it saves. As next steps, point your servers' APT configuration at the proxy to speed up updates, rotate and archive `/var/log/squid/access.log` for auditing, and grow `cache_dir` if the byte hit ratio shows the cache filling up.