1purge(8)                                                              purge(8)
2
3
4

NAME

6       purge - magnifying glass into your squid cache
7

SYNOPSIS

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

DESCRIPTION

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
19       This is a tool for expert usage only, use it under your  own  responsi‐
20       bility.
21

OPTIONS

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
32       -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
39       -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
49       -d l        lets you specify a debug level. Different bits are reserved
50                   for different output.
51                   default: 0
52
53       -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
62       -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
70       -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
74       -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
84       -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
93       -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
98              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
103       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
112       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
118       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
124       -s     If you specify this switch, all commandline parameters  will  be
125              shown after they were parsed.
126              default: off
127
128       -v     be verbose in the things reported about the file. See the output
129              section below.
130

CONFIGURATION

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
139              acl purge method PURGE
140              http_access allow localhost purge
141              http_access deny purge
142
143       Reconfigure  or  restart (preferred) your squid after changing the con‐
144       figuration file.
145

OUTPUT

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
158       Example for non-verbose output in print-mode:
159
160       /cache3/00/00/0000004A        0          5682     http://graphics.user
161       friendly.org/images/slovenia.gif
162
163       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

KNOWN ISSUES

185       Purge does not slow rebuild the cache for you.
186
187       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
191       Should never be used on "busy" caches with purge modes higher than 1.
192

TODO

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
198       2) Add a query before purging objects or removing files,  and  add  an‐
199       other option to remove nagging for the experienced user.
200
201       3) The reported object size may be off by one.
202

AUTHOR

204       This  program  and  manual  was  written  by  Santiago  Garcia Mantinan
205       <manty@debian.org> Amos Jeffries <amosjeffries@squid-cache.org>
206
207       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

QUESTIONS

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

REPORTING BUGS

222       See https://wiki.squid-cache.org/SquidFaq/BugReporting for  details  of
223       what you need to include with your bug report.
224
225       Report bugs or bug fixes using https://bugs.squid-cache.org/
226
227       Report  serious  security  bugs  to Squid Bugs <squid-bugs@lists.squid-
228       cache.org>
229
230       Report ideas for new improvements to the Squid Developers mailing  list
231       <squid-dev@lists.squid-cache.org>
232

SEE ALSO

234       squid(8), squidclient(1) cachemgr.cgi(8)
235
236
237
238                               October 12, 2014                       purge(8)
Impressum