4.1 The squid.conf Syntax

Squid's configuration file is relatively straightforward. It is similar in style to many other Unix programs. Each line begins with a configuration directive, followed by some number of values and/or keywords. Squid ignores empty lines and comment lines (beginning with #) when reading the configuration file. Here are some sample configuration lines:

cache_log /squid/var/cache.log

# define the localhost ACL

acl Localhost src

connect_timeout 2 minutes

log_fqdn on

Some directives take a single value. For these, repeating the directive with a different value overwrites the previous value. For example, there is only one connect_timeout value. The first line in the following example has no effect because the second line overwrites it:

connect_timeout 2 minutes

connect_timeout 1 hour

On the other hand, some directives are actually lists of values. For these, each occurrence of the directive adds a new value to the list. The extension_methods directive works this way:

extension_methods UNGET

extension_methods UNPUT

extension_methods UNPOST

For these list-based directives, you can also usually put multiple values on the same line:

extension_methods UNGET UNPUT UNPOST

Many of the directives have common types. For example, connect_timeout is a time specification that has a number followed by a unit of time. For example:

connect_timeout 3 hours

client_lifetime 4 days

negative_ttl 27 minutes

Similarly, a number of directives refer to the size of a file or chunk of memory. For these, you can write a size specification as a decimal number, followed by bytes, KB, MB, or GB. For example:

minimum_object_size 12 bytes

request_header_max_size 10 KB

maximum_object_size 187 MB

Another type worth mentioning is the toggle, which can be either on or off. Many directives use this type. For example:

server_persistent_connections on

strip_query_terms off

prefer_direct on

In general, the configuration file directives may appear in any order. However, the order is important when one directive makes reference to something defined by another. Access controls are a good example. An acl must be defined before it can be used in an http_access rule:

acl Foo src

http_access deny Foo

Many things in squid.conf are case-sensitive, such as directive names. You can't write HTTP_port instead of http_port.

The default squid.conf file contains comments describing each directive, as well as the default values. For example:

#  TAG: persistent_request_timeout

#       How long to wait for the next HTTP request on a persistent

#       connection after the previous request completes.



# persistent_request_timeout 1 minute

Each time you install Squid, the current default configuration file is saved as squid.conf.default in the $prefix/etc directory. Since directives change from time to time, you can refer to this file for the most up-to-date documentation on squid.conf.

The rest of this chapter is about the handful of directives you need to know before running Squid for the very first time.

    Appendix A. Config File Reference