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
reading the configuration file. Here are some sample configuration
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
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
off. Many directives use this type. For
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 220.127.116.11 http_access deny Foo
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.
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:
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).
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:
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:
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:
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:
You can easily disable store.log altogether by specifying the
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.
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
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
Viaheader of cache misses that Squid forwards. When the request arrives at the origin server, the
Viaheader contains a list of all proxies involved in the transaction. Squid also uses the
Viaheader 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-Cacheheader. 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-Cacheheader 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,
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:
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:
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.
Parse Squid’s configuration file with
parseand check the process exit status.
Intentionally introduce a some errors into the configuration file and run
parseagain. 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?