Go to main content

man pages section 1: User Commands

Exit Print View

Updated: Wednesday, July 27, 2022
 
 

purge (1)

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(8)                                                              purge(8)



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  responsi-
       bility.

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 recom-
                   mended, 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  bit-
       terly. 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  abil-
       ity,  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 con-
       figuration 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  expres-
       sion.
        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.user-
       friendly.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  mem-
       ory  and/or  unable to hold all OS directory cache entries in main mem-
       ory.

       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-2021 The Squid Software Foundation and  contribu-
       tors
        *
        * 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>


ATTRIBUTES
       See attributes(7) for descriptions of the following attributes:


       +---------------+------------------+
       |ATTRIBUTE TYPE | ATTRIBUTE VALUE  |
       +---------------+------------------+
       |Availability   | web/proxy/squid  |
       +---------------+------------------+
       |Stability      | Uncommitted      |
       +---------------+------------------+

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



NOTES
       Source  code  for open source software components in Oracle Solaris can
       be found at https://www.oracle.com/downloads/opensource/solaris-source-
       code-downloads.html.

       This     software     was    built    from    source    available    at
       https://github.com/oracle/solaris-userland.   The  original   community
       source    was    downloaded    from     http://www.squid-cache.org/Ver-
       sions/v4/squid-4.15.tar.xz.

       Further information about this software can be found on the open source
       community website at http://www.squid-cache.org/.



                               October 12, 2014                       purge(8)