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 127.0.0.1/32 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 1.2.3.4 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. # #Default: # 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.