purge(8)

💅 purge(8) — the manual page, but make it slay

okay bestie, welcome to purge, section 8 of the manual (that's the sysadmin section, iykyk). This is the glow-up edition of the page. Grab a strawberry drink 🍓 and let's get into it.

---

🌸 NAME 🌸

purge — a magnifying glass into your squid cache 🔍✨

---

🎀 SYNOPSIS 🎀

purge  [-a] [-c cf] [-d l] [-(f|F) fn | -(e|E) re] [-p h[:p]] [-P #]
[-s] [-v] [-C dir [-H]] [-n]

---

🦋 DESCRIPTION 🦋

So, purge is your little snoop tool. It lets you peek at what URLs are actually stored in which file inside your cache. Iconic behavior, honestly.

It can also release objects whose URLs match regular expressions you hand it. And then there's the messier feature — the ability to remove files that squid doesn't seem to know about any longer. That one's giving chaos, bestie. 💀

This is a tool for expert usage only. Use it under your own responsibility. No cap.

---

✨ OPTIONS ✨

• -a — a kind of "i am alive" flag 💓. It can only be activated if your stdout is a tty. If it's active, it shows a little rotating line so you can tell something is actually happening. Do not use this switch if you capture your stdout into a file, or if your expression list produces many matches. Also: -a is incompatible with the (default) multi cache_dir mode. default: off    See also: -n
• -c cd — lets you point at the location of the squid.conf file. purge understands there's more than one cache_dir, and it figures that out by parsing squid.conf. It knows about both ways of Squid-2 cache_dir specifications and will automatically try to use the correct one. default: /usr/local/squid/etc/squid.conf
• -C cf — if you wanna rescue files from your cache, you gotta specify the directory the files get copied into. Heads up: purge will try to establish the original server directory structure. This switch also activates copy-out mode. Please do not use copy-out mode with any purge mode (-P) other than 0. Example time: if you specified "-C /tmp", purge will try to recreate /tmp/www.server.1/url/path/file, and so forth. default: off    See also: -H, -P
• -d l — lets you specify a debug level. Different bits are reserved for different output. default: 0
• -e | -E re — specify one regular expression to search for in the cache. Super useful if there's only a handful of objects you wanna check. Please remember to escape the shell meta characters used in your regex, and using single quotes around your expression is recommended. The capital letter version works case sensitive, the lower caps version does not. default: (no default)
• -f | -F fn — if you have more than a handful of expressions, or you wanna check the same set at regular intervals, the file option might be more your vibe. Each line in the text file gets treated as one regular expression. Again, the capital letter version works case sensitive, the lower caps version does not. default: (no default)
• -H — if you're in copy-out mode (see -C), you can specify to keep the HTTP Header in the recreated file. default: off    See also: -C
• -n — tells purge to process one cache_dir after another instead of doing things in parallel. If you have more than one cache_dir in your config, purge will fork off a worker process for each cache_dir to do the checks for optimum speed, assuming a decently designed cache. Since parallel execution puts quite some load on the system and its controllers, it's sometimes preferred to use fewer resources — though it will take longer. default: parallel mode for more than one cache_dir
• -p h[:p] — some cache admins use a different port than 3128. The purge tool needs to connect to your cache in order to send the PURGE request (see -P). This option lets you specify the host and port to connect to. The port is optional. The port can be a name (check your /etc/services) or a number. It's separated from the host name portion by a single colon, no spaces allowed. default: localhost:3128
• -P # — if you wanna do more than just print your cache content, you'll need this option. Each bit is reserved for a different action. Only the use of the LSB is recommended; the rest should be considered experimental.
  • no bit set: just print
  • bit#0 set: send PURGE for matches
  • bit#1 set: unlink object file for 404 not found PURGEs
  • bit#2 set: unlink weird object files

If you use a value other than 0 or 1, you will need to slow rebuild your cache content. A warning message will remind you of that. If you use bit#1, all unsuccessful PURGEs will result in the object file in your cache directory being removed, because squid does not seem to know about it any longer. Beware that the asyncio might try to remove it after the purge tool, and thus complains bitterly. Bit#1 only makes sense if Bit#0 is also set — otherwise it has no effect (since the HTTP status 404 is never returned).

Bit#2 is reserved for strange files which do not even contain a URL. Beware: these files may indicate a new object squid currently intends to swap onto disk. If the file suddenly went away, or is removed when squid tries to fetch the object, it will complain bitterly. You must slow rebuild your cache if you use this option.

It is recommended that if you dare to use bit#1 or bit#2, you should only grant the purge tool access to your squid — e.g. move the HTTP and ICP listening port of squid to a different non-standard location during the purge. default: 0 (just print)

• -s — if you specify this switch, all commandline parameters will be shown after they were parsed. default: off
• -v — be verbose in the things reported about the file. See the OUTPUT section below.

---

🔧 CONFIGURATION 🔧

To use purge to affect a running proxy with the PURGE method, you have to enable this feature in squid.conf. By default, PURGE is disabled. You should watch closely for whom you enable the PURGE ability — otherwise a total stranger just might wipe your cache content 😭.

Lines similar to the following will need to be added to your squid.conf:

acl purge method PURGE
http_access allow localhost purge
http_access deny purge

Reconfigure or restart (preferred) your squid after changing the configuration file.

---

📊 OUTPUT 📊

In regular mode, the output of purge consists of four columns. If the URL contains not-encoded whitespaces, it may look as if there are more columns, but the last one is the URI.

• 1 file — name of cache file eximed which matches the regular expression.
• 2 status — return result of purge request, " 0" in print mode.
• 3 size — object size including stored headers, not file size.
• 4 uri — perceived uri

Example for non-verbose output in print-mode:

/cache3/00/00/0000004A   0     5682
http://graphics.userfriendly.org/images/slovenia.gif

In verbose mode, additional columns are inserted before the uri. Time stamps are reported using hexadecimal notation, and Squid's standard for reporting "no such timestamp" == -1, and "unparsable timestamp" == -2.

• 1 file — name of cache file eximed which matches the re.
• 2 status — return result of purge request, " 0" in print mode "-P 0".
• 3 size — object size including stored headers, not file size.
• 4 md5 — MD5 of URI from file, or "(no_md5_data_available)" string.
• 5 ts — UTC of Value of Date: header in hex notation
• 6 lr — UTC of last time the object was referenced
• 7 ex — UTC of Expires: header
• 8 lr — UTC of Last-Modified: header
• 9 flags — Value of objects flags field in hex, see: Programmers Guide
• 10 refcnt — number of times the object was referenced.
• 11 uri — STORE_META_URL uri or "strange_file"

Example for verbose output in print-mode:

/cache1/00/00/000000B7   0      406
7CFCB1D319F158ADC9CFD991BB8F6DCE 397d449b 39bf677b ffffffff 3820abfc
0460     1  http://www.netscape.com/images/nc_vera_tile.gif

---

💀 KNOWN ISSUES 💀

Purge does not slow rebuild the cache for you.

It is still relatively slow, especially if your machine is low on memory and/or unable to hold all OS directory cache entries in main memory.

Should never be used on "busy" caches with purge modes higher than 1.

---

🧚 TODO 🧚

1. use the stat() result on weird files to have a look at their ctime and mtime. If they are younger than, lets say 30 seconds, they were just created by squid and should not be removed.
2. Add a query before purging objects or removing files, and add another option to remove nagging for the experienced user.
3. The reported object size may be off by one.

---

👑 AUTHOR 👑

This program and manual was written by Santiago Garcia Mantinan <manty@debian.org> and Amos Jeffries <amosjeffries@squid-cache.org>

Based on original squidpurge README.

---

📜 COPYRIGHT 📜

 * Copyright (C) 1996-2025 The Squid Software Foundation and
contributors
 *
 * Squid software is distributed under GPLv2+ license and includes
 * contributions from numerous individuals and organizations.
 * Please see the COPYING and CONTRIBUTORS files for details.

---

💌 QUESTIONS 💌

Questions on the usage of this program can be sent to the Squid Users mailing list <squid-users@lists.squid-cache.org>

---

🐛 REPORTING BUGS 🐛

See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to include with your bug report.

Report bugs or bug fixes using https://bugs.squid-cache.org/

Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-cache.org>

Report ideas for new improvements to the Squid Developers mailing list <squid-dev@lists.squid-cache.org>

---

🌈 SEE ALSO 🌈

squid(8), squidclient(1) cachemgr.cgi(8)

---

and that's the whole page, bestie 💖 this edition of the purge(8) manual is dated October 12, 2014 — yeah, vintage, but she ate. stay iconic, go peek at your cache, and don't use bit#1 unless you know what you're doing. mwah 💅✨