Chapter 4. Configuration Guide for the Eager

After compiling and installing Squid, your next task is to delve into the configuration file. If you’re new to Squid, you’re likely to find it a bit overwhelming. The most recent version has approximately 200 configuration file directives and 2700 lines of comments. I certainly don’t expect you to read about, and configure, every directive before starting Squid. This chapter can help you get Squid running quickly.

All the squid.conf directives have default values. You might be able to get Squid going without even touching the configuration file. However, I don’t recommend trying that. You’ll be much happier if you read the following sections first.

If you are really turned off by Squid’s configuration file syntax, you might want to try the Webmin graphical user interface. It allows you to configure Squid (and numerous other programs) from your web browser. See http://www.webmin.com and The Book of Webmin by Joe Cooper (No Starch Press) for more information.

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.

User IDs

As you probably know, Unix processes and files have user and group ownership attributes. You need to select a user and group for Squid. This user and group combination must have read and write access to most of the Squid-related files and directories.

I highly recommend creating a dedicated squid user and group. This minimizes the chance that someone can exploit Squid to read other files on the system. If more than one person has administrative authority over Squid, you can add them to the squid group.

Unix processes inherit their parent process’ ownership attributes. That is, if you start Squid as user joe, Squid also runs as user joe. If you don’t want Squid to run as joe, you need to change your user ID beforehand. This is typically accomplished with the su command. For example:

joe% su - squid
squid% /usr/local/squid/sbin/squid

Unfortunately, running Squid isn’t always so simple. In some cases, you may need to start Squid as root, depending on your configuration. For example, only root can bind a TCP socket to privileged ports like port 80. If you need to start Squid as root, you must set the cache_effective_user directive. It tells Squid which user to become after performing the tasks that require special privileges. For example:

cache_effective_user squid

The name that you provide must be a valid user (i.e., in the /etc/passwd file). Furthermore, note that this directive is used only when you start Squid as root. Only root has the ability to become another user. If you start Squid as joe, it can’t switch to user squid.

You might be tempted to just run Squid as root without setting cache_effective_user. If you try, you’ll find that Squid refuses to run. This, again, is due to security concerns. If an outsider were somehow able to compromise or exploit Squid, he could gain full access to your system. Although we strive to make Squid secure and bug-free, this requirement provides some extra insurance, just in case.

If you start Squid as root without setting cache_effective_user, Squid uses nobody as the default value. Whatever user ID you choose for Squid, make sure it has read access to the files installed in $prefix/etc, $prefix/libexec, and $prefix/share. The user ID must also have write access to the log files and cache directory.

Squid also has a cache_effective_group directive, but you probably don’t need to set it. By default, Squid uses the cache_effective_user’s default group (from the password file).

Port Numbers

The http_port directive tells Squid which port number to listen on for HTTP requests. The default is port 3128:

http_port 3128

If you are running Squid as a surrogate (see Chapter 15), you should probably set this to 80.

You can instruct Squid to listen on multiple ports with additional http_port lines. This is often useful if you must support groups of clients that have been configured differently. For example, the browsers from one department may be sending requests to port 3128, while another department uses port 8080. Simply list both port numbers as follows:

http_port 3128
http_port 8080

You can also use the http_port directive to make Squid listen on specific interface addresses. When Squid is used on a firewall, it should have two network interfaces: one internal and one external. You probably don’t want to accept HTTP requests coming from the external side. To make Squid listen on only the internal interface, simply put the IP address in front of the port number:

http_port 192.168.1.1:3128

Log File Pathnames

I’ll discuss all the details of Squid’s log files in Chapter 13. For now the only thing you may need to worry about is where you want Squid to put its log files. The default location is a directory named logs under the installation prefix. For example, if you don’t use the —prefix= option with ./configure, the default log file directory is /usr/local/squid/var/logs.

You need to make sure that log files are stored on a disk partition with enough space. When Squid receives a write error for a log file, it exits and restarts. The primary reason for this behavior is to grab your attention. Squid wants to make sure you don’t miss any important logging information, especially if your system is being abused or attacked.

Squid has three main log files: cache.log, access.log, and store.log. The first of these, cache.log, contains informational and debugging messages. When you start Squid the first few times, you should closely watch this file. If Squid refuses to run, the reason is probably at the end of cache.log. Under normal conditions, this log file doesn’t become large enough to warrant any special attention. Also note that if you start Squid with the -s option, the important cache.log messages are also sent to your syslog daemon. You can change the location for this log file with the cache_log directive:

cache_log /squid/logs/cache.log

The access.log file contains a single line for each client request made to Squid. On average, each line is about 150 bytes. In other words, it takes about 150 MB to log one million client requests. Use the cache_access_log directive to change the location of this log file:

cache_access_log /squid/logs/access.log

If, for some reason, you don’t want Squid to log client requests, you can specify the log file pathname as /dev/null.

The store.log file is probably not very useful to most cache administrators. It contains a record for each object that enters and leaves the cache. The average record size is typically 175-200 bytes. However, Squid doesn’t create an entry in store.log for cache hits, so it contains fewer records than access.log. Use the cache_store_log directive to change the location:

cache_store_log /squid/logs/store.log

You can easily disable store.log altogether by specifying the location as none:

cache_store_log none

If you’re not careful, Squid’s log files increase in size without limit. Some operating systems enforce a 2-GB file size limit, even if you have plenty of free disk space. Exceeding this limit results in a write error, which then causes Squid to exit. To keep log file sizes reasonable, you should create a cron job that regularly renames and archives the log files. Squid has a built-in feature to make this easy. See Section 13.7 for an explanation of log file rotation.

Access Controls

I’ll have a lot to say about access controls in Chapter 6. For now, I’ll cover a few controls so that more enthusiastic readers can quickly start using Squid.

Squid’s default configuration file denies every client request. You must place additional access control rules in squid.conf before anyone can use the proxy. The simplest approach is to define an ACL that corresponds to your user’s IP addresses and an access rule that tells Squid to allow HTTP requests from those addresses. Squid has many different ACL types. The src type matches client IP addresses, and the http_access rules are checked for client HTTP requests. Thus, you need to add only two lines:

acl MyNetwork src 192.168.0.0/16
http_access allow MyNetwork

The tricky part is putting these lines in the right place. The order of http_access lines is very important, but the order of acl lines doesn’t matter. You should also be aware that the default configuration file contains some important access controls. You shouldn’t change or disrupt these until you fully comprehend their significance. When you edit squid.conf for the first time, look for this comment:

#
# INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS
#

Insert your new rules below this comment, and before the http_access deny All line.

For the sake of completeness, here is a suitable initial access control configuration, including the recommended default controls and the example earlier:

acl All src 0/0
acl Manager proto cache_object
acl Localhost src 127.0.0.1/32
acl Safe_ports port 80 21 443 563 70 210 280 488 591 777 1025-65535
acl SSL_ports 443 563
acl CONNECT method CONNECT
acl MyNetwork src 192.168.0.0/16

http_access allow Manager Localhost
http_access deny Manager
http_access deny !Safe_ports
http_access deny CONNECT !SSL_ports
http_access allow MyNetwork
http_access deny All

Visible Hostname

Hopefully, you won’t need to worry about the visible_hostname directive. However, you’ll need to set it if Squid can’t figure out the hostname of the machine on which it is running. When this happens, Squid complains and refuses to run:

% squid -Nd1
FATAL: Could not determine fully qualified hostname.  Please set 'visible_hostname'

Squid wants to be sure about its hostname for a number of reasons:

  • The hostname appears in Squid’s error messages. This helps users identify the source of potential problems.

  • The hostname appears in the HTTP Via header of cache misses that Squid forwards. When the request arrives at the origin server, the Via header contains a list of all proxies involved in the transaction. Squid also uses the Via header to detect forwarding loops. I’ll talk about forwarding loops in Chapter 10.

  • Squid uses internal URLs for certain things, such as the icons for FTP directory listings. When Squid generates an HTML page for an FTP directory, it inserts embedded images for little icons that indicate the type of each file in the directory. The icon URLs contain the cache’s hostname so that web browsers request them directly from Squid.

  • Each HTTP reply from Squid includes an X-Cache header. This isn’t an official HTTP header. Rather, it is an extension header that indicates if the response was a cache hit or a cache miss. Since requests and responses may flow through more than one cache, each X-Cache header includes the name of the cache reporting hit or miss. Here’s a sample response that passed through two caches:

    HTTP/1.0 200 OK
Date: Mon, 29 Sep 2003 22:57:23 GMT
Content-type: text/html
Content-length: 733
X-Cache: HIT from bo2.us.ircache.net
X-Cache: MISS from bo1.us.ircache.net

    Squid tries to figure out the hostname automatically at startup. First it calls the gethostname( ) function, which usually returns the correct hostname. Next, Squid attempts a DNS lookup on the hostname with gethostbyname( ). This function typically returns both IP addresses and the canonical name for the system. If gethostbyname( ) succeeds, Squid uses the canonical name in error messages, Via headers, etc.

    Squid may be unable to determine its fully qualified hostname for a number of reasons, including:

  • The hostname may not be set.

  • The hostname may be missing from the DNS zone or /etc/hosts files.

  • The Squid system’s DNS client configuration may be incorrect or missing. On Unix, you should check the /etc/resolv.conf and /etc/host.conf files.

If you see the fatal message mentioned previously, you need either to fix the hostname and DNS information or explicitly configure the hostname for Squid. In most cases, it is sufficient to ensure the hostname command returns a fully qualified hostname and add an entry to /etc/hosts. If that doesn’t work, just set the visible hostname in squid.conf:

visible_hostname squid.packet-pushers.net

Administrative Contact Information

You should set the cache_mgr directive as a favor to your users. The value is an email address users can write to in case a problem surfaces. The cache_mgr address appears in Squid’s error messages by default. For example:

cache_mgr squid@web-cache.net

Next Steps

After creating the minimal configuration file, you’re more or less ready to run Squid for the first time. To do that, just follow the instructions in the next chapter.

When you’ve mastered starting and stopping Squid, you can spend some time beefing up the configuration file. You may want to add more sophisticated access controls, which you’ll find documented in Chapter 6. Since I didn’t say anything about the disk cache yet, you should also spend a fair amount of time in Chapter 7 and Chapter 8.

Exercises

  • Parse Squid’s configuration file with squid -k parse and check the process exit status.

  • Intentionally introduce a some errors into the configuration file and run squid -k parse again. Notice how Squid reports different errors.

  • Insert comments into the configuration file. Can you start a comment anywhere, even after a valid directive?

  • Why do you think some configuration file errors are fatal, but others are not?

Get Squid: The Definitive Guide now with the O’Reilly learning platform.

O’Reilly members experience books, live events, courses curated by job role, and more from O’Reilly and nearly 200 top publishers.

Start your free trial