tools/purge/purge.1

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