release-notes-1.1.txt

-

Store Hash Configuration Options
==============================================================================
Squid's internal hash table for holding objects has a couple of
configuration options (thanks to Mark Treacy).  Given the following
configuration parameters:

	cache_swap
	store_avg_object_size		# default 20K
	store_objects_per_bucket	# default 20

We first estimate the number of objects your cache can hold:

	NUM_OBJ = cache_swap / store_avg_object_size

Then we estimate the number of hash buckets needed:

	NUM_BUCKETS = NUM_OBJ / store_objects_per_bucket

We want Squid to scan the entire hash table, one bucket at a time, over
the course of about a day.  We also need NUM_BUCKETS to be a prime
number for optimal distribution of the hash table.  NUM_BUCKETS is
rounded off so that the number of buckets and maintenance rate are
taken from this table:

	store_buckets	store_maintain_rate
	     7951		10 sec
	    12149		 7 sec
	    16231		 5 sec
	    33493		 2 sec
	    65357		 1 sec

If you want to increase the maintenance rate then decrease the
store_objects_per_bucket parameter.

GNU malloc
==============================================================================
Many users have reported significant performance improvements when Squid
is linked with the GNU malloc library.  A check for 'libgnumalloc.a'
has therefore been added to the configure script.  If libgnumalloc.a
is found, it is automatically linked in.

GNU regex
==============================================================================
Squid's configure script attempts to determine whether or not it should
compile the GNU regex functions supplied in the source distribution.
If your system appears to have its own POSIX compliant regex functions
then configure may decide to use those instead of GNU regex.

Access Log Fields
==============================================================================
The native access.log has ten (10) fields.  There is one entry here for
each HTTP (client) request and each ICP Query.  HTTP requests are
logged when the client socket is closed.  A single dash ('-') indicates
unavailable data.

 1) Timestamp
	The time when the client socket is closed.  The format is "Unix
	time" (seconds since Jan 1, 1970) with millisecond resolution.
 2) Elapsed Time
	The elapsed time of the request, in milliseconds.  This is time
	time between the accept() and close() of the client socket.
 3) Client Address
	The IP address of the connecting client, or the FQDN if the
	'log_fqdn' option is enabled in the config file.
 4) Log Tag / HTTP Code
	The Log Tag describes how the request was treated locally (hit,
	miss, etc).  All the tags are described below.  The HTTP code
	is the reply code taken from the first line of the HTTP reply
	header.  Non-HTTP requests may have zero reply codes.
 5) Size
	The number of bytes written to the client.
 6) Request Method
	The HTTP request method, or ICP_QUERY for ICP requests.
 7) URL
	The requested URL.
 8) Ident
	If 'ident_lookup' is on, this field may contain the username
	associated with the client connection as derived from the
	ident service.
 9) Hierarchy Data / Hostname
	A description of how and where the requested object was
	fetched.  
10) Content Type
	The Content-type field from the HTTP reply.

Access Log Tags
==============================================================================
"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_REFRESH_HIT		The object was in the cache, but STALE.
				An If-Modified-Since request was made and
				a "304 Not Modified" reply was received.
	TCP_REF_FAIL_HIT	The object was in the cache, but STALE.
				The request to validate the object failed,
				so the old (stale) object was returned.
	TCP_REFRESH_MISS	The object was in the cache, but STALE.
				An If-Modified-Since request was made and
				the reply contained new content.
	TCP_CLIENT_REFRESH	The client issued a request with the
				"no-cache" pragma.
	TCP_IMS_HIT		The client issued an If-Modified-Since
				request and the object was in the cache
				and still fresh.
	TCP_IMS_MISS		The client issued an If-Modified-Since
				request for a stale object.
        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.
	UDP_RELOADING	The ICP request was "refused" because the cache is
			busy reloading its metadata.

"ERR_" refers to various types of errors for HTTP requests.

Hierarchy Data Tags
==============================================================================

        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.
        SIBLING_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.
        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.
        PARENT_UDP_HIT_OBJ      The object was received in a UDP_HIT_OBJ reply
                                from a parent cache.
        SIBLING_UDP_HIT_OBJ     The object was received in a UDP_HIT_OBJ reply
                                from a sibling cache.
	PASSTHROUGH_PARENT	The neighbor or proxy defined in the config
				option 'passthrough_proxy' was used.
	SSL_PARENT_MISS		The neighbor or proxy defined in the config
				option 'ssl_proxy' was used.
	DEFAULT_PARENT		No ICP queries were sent to any parent
				caches.  This parent was chosen because
				it was marked as 'default' in the config
				file.
	ROUNDROBIN_PARENT	No ICP queries were received from any parent
				caches.  This parent was chosen because
				it was marked as 'default' in the config 
				file and it had the lowest round-robin use
				count.
	CLOSEST_PARENT_MISS	This parent was selected because it
				included the lowest RTT measurement to
				the origin server.  This only appears
				with 'query_icmp on' set in the config
				file.
	CLOSEST_DIRECT		The object was fetched directly from the
				origin server because this cache measured
				a lower RTT than any of the parent caches.


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.

Using Multicast ICP
==============================================================================
As of Squid-1.1.6, ICP queries can be sent via multicast.  Use of multicast
requires the following config file entries:

    1) A cache which wants to *receive* multicast ICP queries must
       be configured to join a multicast address.  This is done with
       the 'mcast_groups' directive.    For example:

	mcast_groups  224.9.9.9

    2) A cache which wants to *send* multicast ICP queries must add
       a "multicast group" neighbor.  For example:

	cache_host 224.9.9.9 multicast 3128 3130 ttl=64

       In this situation, the HTTP port (3128) is ignored, but the ICP
       port (3130) must be correct.  All multicast group members must
       use the same ICP port number.  The 'ttl=' option specifies the
       IP Multicast TTL value to be used when sending a multicast
       datagram.

    3) Because Squid does not trust ICP replies received from unknown
       peers, you must specify all acceptable neighbors which might
       respond to your multicast query.  These appear as normal parents
       or siblings, but with the special 'multicast-responder' option.
       For example:

	cache_host foo.sample.com sibling 3128 3130 multicast-responder

Use of multicast creates an interesting dilemma; normally Squid sends N
queries and expects N replies.  But with multicast Squid doesn't really
know how many replies to expect.  Somehow Squid must know roughly how
many ICP replies to expect, but at the same time it must be careful to
not over-estimate and therefore incur many ICP query timeouts.

The current approach is this: Squid periodically (every 15 minutes)
sends fake ICP queries to only multicast peers.  The replies are
counted, up until the 'neighbor_timeout' time.  The count is averaged
over time with a fast decay so that it adjusts relatively quickly.
The number of replies to expect is rounded down to the nearest whole
integer to minimize the chance of suffering the neighbor timeout
on real ICP queries.

Store.log Fields
==============================================================================
The file store.log consists of the following fields:

    time action code date lastmod expires type expect-len/real-len method key

    time       The time this entry was logged.  The value is the
               raw Unix time plus milliseconds.

    action     One of RELEASE, SWAPIN, or SWAPOUT.
               RELEASE means the object has been removed from the cache.
               SWAPOUT means the object has been saved to disk.
               SWAPIN  means the object existed on disk and has been
                       swapped into memory.

    code       The HTTP reply code.

    The following three fields are timestamps parsed from the HTTP
    reply headers.  All are expressed in Unix time.  A missing header
    is represented with -2 and an unparsable header is represented as -1.

    date       The value of the HTTP Date reply header.  If the Date
               header is missing or invalid, the time of the request
               is used instead.

    lastmod    The value of the HTTP Last-Modified: reply header.

    expires    The value of the HTTP Expires: reply header.

    type       The HTTP Content-Type reply header.

    expect-len The value of the HTTP Content-Length reply header.
               Zero if Content-Length was missing.

    real-len   The number of bytes of content actually read.  If the
               expect-len is non-zero, and not equal to the real-len,
               the object will be released from the cache.

    method     HTTP request method

    key        The cache key.  Often this is simply the URL.  Cache objects
               which never become public will have cache keys that include
               a unique integer sequence number, the request method, and
               then the URL.


Notes for running Squid under NEXTSTEP
==============================================================================
When running Squid under NEXTSTEP 3.x, and when that NEXTSTEP system
runs a BIND named process (most NEXTSTEPS handle that through netinfo
and netinfo might contact a BIND named on another system) squid can
trigger an error in the older BIND named that comes with NEXTSTEP 3.x.
It is therefore necessary for systems running NEXTSTEP 3.x, which run
their own BIND named, to run a more recent version of BIND. Luckily you
don't have to compile BIND yourself, a fat (m68k i486 hppa sparc)
Installer package for BIND-4.9.5 is available through
ftp://ftp.nluug.nl/pub/comp/next/Internet.

NB: It might be necessary to have BIND running to run Squid under
NEXTSTEP releases before NEXTSTEP 3.3+patch. Earlier releases of
NEXTSTEP did not have a multithreaded netinfo resolver, which means
that Squid's use of multiple dnsserver processes to prevent blocking is
thwarted by netinfo blocking on every request.

Gerben Wierda <[e-mail]>