Provided by: squid-purge_5.9-0ubuntu0.22.04.2_amd64 
NAME
purge - 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
purge is used to have a look at what URLs are stored in which file within your cache. The
purge tool can also be used to release objects which URLs match user specified regular
expressions. A more troublesome feature is the ability to remove files squid does not seem
to know about any longer.
This is a tool for expert usage only, use it under your own responsibility.
OPTIONS
-a a kind of "i am alive" flag. It can only be activated, if your stdout is a
tty. If active, it will display a little rotating line to indicate that there
is actually something happening. You should not use this switch if you capture
your stdout in a file or if your expression list produces many matches. The -a
flag is also incompatible with the (default) multi cache_dir mode.
default: off See also: -n
-c cd this option lets you specify the location of the squid.conf file. Purge
understands about more than one cache_dir, and does so 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 want to rescue files from your cache, you need to specify the directory
into which the files will be copied. Please note that 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.
For instance, 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 be searched for in the cache. This is
useful if there is only a handful of objects you want to check. Please
remember to escape the shell meta characters used in your regular expression.
The use of 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 want to check the same set
at regular intervals, the file option might be more useful to you. Each line
in the text file will be regarded as one regular expression. Again, the
capital letter version works case sensitive, the lower caps version does not.
default: (no default)
-H if in copy-out mode (see: -C), you can specify to keep the HTTP Header in the
recreated file.
default: off See also: -C
-n tell purge to process one cache_dir after another, instead of doing things in
parallel. If you have more than one cache_dir in your configuration 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 will put
quite some load on the system and its controllers, it is sometimes preferred
to use less 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 will need 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 number. It is separated from
the host name portion by a single colon, no spaces allowed.
default: localhost:3128
-P # If you want to do more than just print your cache content, you will need to
specify 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 to be 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 that 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
In order to use purge to affect a running proxy with PURGE method, you will 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.
# name meaning
= ====== ===========================================================
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.
# name meaning
= ====== ===========================================================
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> Amos
Jeffries <amosjeffries@squid-cache.org>
Based on original squidpurge README.
COPYRIGHT
* Copyright (C) 1996-2023 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 http://wiki.squid-cache.org/SquidFaq/BugReporting for details of what you need to
include with your bug report.
Report bugs or bug fixes using http://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)
October 12, 2014 purge(8)