1purge(8) purge(8)
2
6 purge - magnifying glass into your squid cache
7
9 purge [-a] [-c cf] [-d l] [-(f|F) fn | -(e|E) re] [-p h[:p]] [-P #]
10 [-s] [-v] [-C dir [-H]] [-n]
11
13 purge is used to have a look at what URLs are stored in which file
14 within your cache. The purge tool can also be used to release objects
15 which URLs match user specified regular expressions. A more troublesome
16 feature is the ability to remove files squid does not seem to know
17 about any longer.
18 This is a tool for expert usage only, use it under your own responsi‐
20 bility.
21
23 -a a kind of "i am alive" flag. It can only be activated, if
24 your stdout is a tty. If active, it will display a little
25 rotating line to indicate that there is actually something
26 happening. You should not use this switch if you capture
27 your stdout in a file or if your expression list produces
28 many matches. The -a flag is also incompatible with the
29 (default) multi cache_dir mode.
30 default: off See also: -n
31 -c cd this option lets you specify the location of the squid.conf
33 file. Purge understands about more than one cache_dir, and
34 does so by parsing squid.conf. It knows about both ways of
35 Squid-2 cache_dir specifications, and will automatically
36 try to use the correct one.
37 default: /usr/local/squid/etc/squid.conf
38 -C cf if you want to rescue files from your cache, you need to
40 specify the directory into which the files will be copied.
41 Please note that purge will try to establish the original
42 server directory structure. This switch also activates
43 copy-out mode. Please do not use copy-out mode with any
44 purge mode (-P) other than 0.
45 For instance, if you specified "-C /tmp", purge will try to
46 recreate /tmp/www.server.1/url/path/file, and so forth.
47 default: off See also: -H, -P
48 -d l lets you specify a debug level. Different bits are reserved
50 for different output.
51 default: 0
52 -e|-E re Specify one regular expression to be searched for in the
54 cache. This is useful if there is only a handful of ob‐
55 jects you want to check. Please remember to escape the
56 shell meta characters used in your regular expression. The
57 use of single quotes around your expression is recommended.
58 The capital letter version works case sensitive, the lower
59 caps version does not.
60 default: (no default)
61 -f|-F fn if you have more than a handful of expressions, or want to
63 check the same set at regular intervals, the file option
64 might be more useful to you. Each line in the text file
65 will be regarded as one regular expression. Again, the
66 capital letter version works case sensitive, the lower caps
67 version does not.
68 default: (no default)
69 -H if in copy-out mode (see: -C), you can specify to keep the
71 HTTP Header in the recreated file.
72 default: off See also: -C
73 -n tell purge to process one cache_dir after another, instead
75 of doing things in parallel. If you have more than one
76 cache_dir in your configuration purge will fork off a
77 worker process for each cache_dir to do the checks for op‐
78 timum speed, assuming a decently designed cache. Since par‐
79 allel execution will put quite some load on the system and
80 its controllers, it is sometimes preferred to use less re‐
81 sources, though it will take longer.
82 default: parallel mode for more than one cache_dir
83 -p h[:p] Some cache admins use a different port than 3128. The purge
85 tool will need to connect to your cache in order to send
86 the PURGE request (see -P). This option lets you specify
87 the host and port to connect to. The port is optional. The
88 port can be a name (check your /etc/services) or number. It
89 is separated from the host name portion by a single colon,
90 no spaces allowed.
91 default: localhost:3128
92 -P # If you want to do more than just print your cache content,
94 you will need to specify this option. Each bit is reserved
95 for a different action. Only the use of the LSB is recom‐
96 mended, the rest should be considered experimental.
97 no bit set: just print
99 bit#0 set: send PURGE for matches
100 bit#1 set: unlink object file for 404 not found PURGEs
101 bit#2 set: unlink weird object files
102 If you use a value other than 0 or 1, you will need to slow rebuild
104 your cache content. A warning message will remind you of that. If you
105 use bit#1, all unsuccessful PURGEs will result in the object file in
106 your cache directory to be removed, because squid does not seem to know
107 about it any longer. Beware that the asyncio might try to remove it af‐
108 ter the purge tool, and thus complains bitterly. Bit#1 only makes
109 sense, if Bit#0 is also set, otherwise it has no effect (since the HTTP
110 status 404 is never returned).
111 Bit#2 is reserved for strange files which do not even contain a URL.
113 Beware that these files may indicate a new object squid currently in‐
114 tends to swap onto disk. If the file suddenly went away, or is removed
115 when squid tries to fetch the object, it will complain bitterly. You
116 must slow rebuild your cache, if you use this option.
117 It is recommended that if you dare to use bit#1 or bit#2, you should
119 only grant the purge tool access to your squid, e.g. move the HTTP and
120 ICP listening port of squid to a different non-standard location during
121 the purge.
122 default: 0 (just print)
123 -s If you specify this switch, all commandline parameters will be
125 shown after they were parsed.
126 default: off
127 -v be verbose in the things reported about the file. See the output
129 section below.
130
132 In order to use purge to affect a running proxy with PURGE method, you
133 will have to enable this feature in squid.conf. By default, PURGE is
134 disabled. You should watch closely for whom you enable the PURGE abil‐
135 ity, otherwise a total stranger just might wipe your cache content.
136 Lines similar to the following will need to be added to your
137 squid.conf:
138 acl purge method PURGE
140 http_access allow localhost purge
141 http_access deny purge
142 Reconfigure or restart (preferred) your squid after changing the con‐
144 figuration file.
145
147 In regular mode, the output of purge consists of four columns. If the
148 URL contains not encoded whitespaces, it may look as if there are more
149 columns, but the last one is the URI.
150 # name meaning
151 = ====== ===========================================================
152 1 file name of cache file eximed which matches the regular expres‐
153 sion.
154 2 status return result of purge request, " 0" in print mode.
155 3 size object size including stored headers, not file size.
156 4 uri perceived uri
157 Example for non-verbose output in print-mode:
159 /cache3/00/00/0000004A 0 5682 http://graphics.user‐
161 friendly.org/images/slovenia.gif
162 In verbose mode, additional columns are inserted before the uri. Time
164 stamps are reported using hexadecimal notation, and Squid's standard
165 for reporting "no such timestamp" == -1, and "unparsable timestamp" ==
166 -2.
167 # name meaning
168 = ====== ===========================================================
169 1 file name of cache file eximed which matches the re.
170 2 status return result of purge request, " 0" in print mode "-P 0".
171 3 size object size including stored headers, not file size.
172 4 md5 MD5 of URI from file, or "(no_md5_data_available)" string.
173 5 ts UTC of Value of Date: header in hex notation
174 6 lr UTC of last time the object was referenced
175 7 ex UTC of Expires: header
176 8 lr UTC of Last-Modified: header
177 9 flags Value of objects flags field in hex, see: Programmers Guide
178 10 refcnt number of times the object was referenced. 11 uri
179 STORE_META_URL uri or "strange_file" Example for verbose output in
180 print-mode: /cache1/00/00/000000B7 0 406
181 7CFCB1D319F158ADC9CFD991BB8F6DCE 397d449b 39bf677b ffffffff 3820abfc
182 0460 1 http://www.netscape.com/images/nc_vera_tile.gif
183
185 Purge does not slow rebuild the cache for you.
186 It is still relatively slow, especially if your machine is low on mem‐
188 ory and/or unable to hold all OS directory cache entries in main mem‐
189 ory.
190 Should never be used on "busy" caches with purge modes higher than 1.
192
194 1) use the stat() result on weird files to have a look at their ctime
195 and mtime. If they are younger than, lets say 30 seconds, they were
196 just created by squid and should not be removed.
197 2) Add a query before purging objects or removing files, and add an‐
199 other option to remove nagging for the experienced user.
200 3) The reported object size may be off by one.
202
204 This program and manual was written by Santiago Garcia Mantinan
205 <manty@debian.org> Amos Jeffries <amosjeffries@squid-cache.org>
206 Based on original squidpurge README.
208
210 * Copyright (C) 1996-2023 The Squid Software Foundation and contribu‐
211 tors
212 *
213 * Squid software is distributed under GPLv2+ license and includes
214 * contributions from numerous individuals and organizations.
215 * Please see the COPYING and CONTRIBUTORS files for details.
216
218 Questions on the usage of this program can be sent to the Squid Users
219 mailing list <squid-users@lists.squid-cache.org>
220
222 See https://wiki.squid-cache.org/SquidFaq/BugReporting for details of
223 what you need to include with your bug report.
224 Report bugs or bug fixes using https://bugs.squid-cache.org/
226 Report serious security bugs to Squid Bugs <squid-bugs@lists.squid-
228 cache.org>
229 Report ideas for new improvements to the Squid Developers mailing list
231 <squid-dev@lists.squid-cache.org>
232
234 squid(8), squidclient(1) cachemgr.cgi(8)
235 October 12, 2014 purge(8)
