release-notes-1.0.txt

-

$Id: Release-Notes-1.0.txt,v 1.5 1997/07/16 20:31:49 wessels Exp $

Release Notes for version 1.0 of the Squid cache.

TABLE OF CONTENTS:

	Private Objects
	Proper parsing of HTTP reply codes
	Support for If-Modified-Since GET
	Improvements to the access log
	Metadata reloads in the background
	Unlinking swap files on restart and the -U option
	Changes to debugging
	New Access Control scheme
	Using SIGHUP to reconfigure the cache
	ftpget server
	Changes to cache shutdown
	Assigning weights to cache neighbors
	Converting 'cache/log' from cached-1.4.pl3
	Notes on stoplists vs ttl_pattern
        SIGUSR1 now rotates log files
	``no-query'' option for cache_host lines


Private Objects
==============================================================================

The Squid cache uses the notions of ``private'' and ``public''
objects.  An object can start out as being private, but may later be
given public status.  Private objects are associated with only a single
client whereas a public object may be sent to multiple clients at the
same time.  When the cache finishes retrieving an object, if the object
is private it will be ejected from the cache.  Only public objects
are saved on disk.

There are a few ways to determine whether an object should be private
or public.  One is the request method.  Only URLs requested with
the ``GET'' method can be public.  Another way is by examining the 
URL string.  URLs which match one of the stoplist entries will 
always be private objects.  Usually this includes ``cgi-bin'' scripts.
A third way is by checking the HTTP request and reply headers.  For 
example, if the request includes user authentication information, then
the object should never be made public.  Additionally, some HTTP
replies such as ``401 Unauthorized'' should also never be made public.

For these reasons, Squid starts all objects out as private and changes
them to public only after the HTTP reply headers have been read.

Unfortunately, this causes some problems with the UDP-based Internet
Cache Protocol (ICP) used to query neighboring caches.  Specifically, when
an ICP reply packet is received, it only contains the object URL which
is not sufficient enough to locate private objects in the cache metadata.
To get the additional information needed to locate private objects, we
decided to use the ``reqnum'' field of the ICP packet.  This is an
acceptable solution, except that as implemented in cached-1.4.pl3 and
earlier, all ICP replies have the reqnum field reset to zero!

Squid will make use of private objects until it notices that one of
its neighbors is sending ICP replies with the reqnum field set to zero.
It will then only use private keys for objects which are not going to
be queried for via ICP.  These include objects in the stoplist and
If-Modified-Since requests.  

Proper parsing of HTTP reply codes
==============================================================================

Squid parses HTTP replies to extract the reply code.  The codes are used
to determine which objects should be cached, which should be ejected,
and which should be negative-cached. 

See HTTP-codes.txt for a list of HTTP response codes, and how they are
cached.

The HTTP codes are now logged to "access.log" in the native format 
(ie with 'emulate_httpd_log off').

Support for If-Modified-Since GET
==============================================================================
Squid supports IMS GET retrievals, but not through any neighbor caches.
Whenever an IMS GET request is received, Squid handles the requst in
one of three ways:

    * if the object is not in the cache, the request is treated as
      a regular MISS.
    * if the object is in the cache, and it has a more recent timestamp,
      it is treated as a regular HIT.
    * otherwise the cached object is assumed to be valid, and Squid
      returns a NOT MODIFIED response.

This means you should chose your TTL settings very carefully. 

Improvements to the access log
==============================================================================
The "access.log" file has been improved in a number of ways.  There is now
only one log entry per client request and the size is always correct. 
The format is now

   timestamp  elapsed  src-address  type/code/hierarchy  size  method  URL

	- timestamp:	When the request is completed with millisecond
			resolution.
	- elapsed:	elapsed time of the request, in milliseconds.
	- src-address: 	IP address of the requesting client.
	- type:		An indication of how the request was handled
			by the cache.  These are described further below.
	- code: 	The HTTP reply code when available.  For ICP
			requests this is always "000."  If the reply code
			was not given, it will be logged as "555."
	- hierarchy:	The code from the hierarchy.log file.
	- size:		For TCP requests, the amount of data written
			to the client.  For UDP requests, the size
			of the request (in bytes).
	- method:	The request method (GET, POST, etc).
	- URL:		The URL of the request.

Access Log Types:

"TCP_" refers to requests on the HTTP port (3128)

	TCP_HIT		A valid copy of the requested object was in the cache.
	TCP_MISS	The requested object was not in the cache.
	TCP_EXPIRED	The object was in the cache, but it had expired.
	TCP_REFRESH	The user forced a refresh ("reload").
	TCP_IFMODSINCE	An If-Modified-Since GET request.
	TCP_SWAPFAIL	The object was believed to be in the cache,
			but could not be accessed.
	TCP_DENIED	Access was denied for this request.

"UDP_" refers to requests on the ICP port (3130)

	UDP_HIT		A valid copy of the requested object was in the cache.
	UDP_HIT_OBJ	Same as UDP_HIT, but the object data was small enough
			to be sent in the UDP reply packet.  Saves the
			following TCP request.
	UDP_MISS	The requested object was not in the cache.
	UDP_DENIED	Access was denied for this request.
	UDP_INVALID	An invalid request was received.
..............................................................................
Hierarchy Log Types:

	DEAD_NEIGHBOR		A sibling has been detected as dead after
				failing to reply to 20 consecutive ICP
				queries.
	DEAD_PARENT		A parent has been detected as dead.
	DIRECT			The object has been requested from the origin
				server.
	FIREWALL_IP_DIRECT	The object has been requested from the origin
				server because the origin host IP address is
				inside your firewall.
	FIRST_PARENT_MISS	The object has been requested from the
				parent cache with the fastest weighted round
				trip time.
	FIRST_UP_PARENT		The object has been requested from the first
				available parent in your list.
	LOCAL_IP_DIRECT		The object has been requested from the origin
				server because the origin host IP address 
				matched your 'local_ip' list.
	NEIGHBOR_HIT		The object was requested from a sibling cache
				which replied with a UDP_HIT.
	NO_DIRECT_FAIL		The object could not be requested because
				of firewall restrictions and no parent caches
				were available.
	NO_PARENT_DIRECT	The object was requested from the origin server
				because no parent caches exist for the URL.
	PARENT_HIT		The object was requested from a parent cache
				which replied with a UDP_HIT.
	REVIVE_NEIGHBOR		A sibling cache was detected as alive again.
	REVIVE_PARENT		A parent cache was detected as alive again.
	SINGLE_PARENT		The object was requested from the only
				parent cache appropriate for this URL.
	SOURCE_FASTEST		The object was requested from the origin server
				because the 'source_ping' reply arrived first.
	UDP_HIT_OBJ		The object was received in a UDP_HIT_OBJ reply
				from a neighbor cache.

Almost any of these may be preceeded by 'TIMEOUT_' if the two-second
(default) timeout occurs waiting for all ICP replies to arrive from
neighbors.


Metadata reloads in the background
==============================================================================
Upon restart, Squid automatically loads cache metadata in the
background.  It will be able to service new requests immediately.  As
new objects are added, there may be some "clashes" with old objects
using the same swap file on disk.  In these cases you may see a message
in the cache logfile about "Active clash."  This means the old object
has been discarded since it was replaced by a new object.

The -F option causes the old behaviour -- reload all the metadata before
processing any requests,


Unlinking swap files on restart and the -U option
==============================================================================
When the cache reloads object metadata from disk some of the objects
will be expired or otherwise invalid.  In the interest of speed, these
invalid objects will not be removed from the filesystem by default.  They
will eventually be overwritten by new objects as enter the cache and
get saved to disk.

The -U option can be used to actually remove the invalid objects from