3.4 The configure Script

Like many other Unix software packages, Squid uses a ./configure script to learn about an operating system before compiling. The ./configure script is generated by the popular GNU autoconf program. When the script runs, it probes the system in various ways to find out about libraries, functions, types, parameters, and features that may or may not be present. One of the first things that ./configure does is look for a working C compiler. If the compiler can't be found or fails to compile a simple test program, the ./configure script can't proceed.

The ./configure script has a number of different options. The most important is the installation prefix. Before running ./configure , you need to decide where Squid should live. The installation prefix determines the default locations for the Squid logs, binaries, and configuration files. You can change the location for those files after installing, but it's easier if you decide now.

The default installation prefix is /usr/local/squid . Squid puts files in seven different subdirectories under the prefix:

 % ls -l /usr/local/squid total 5 drwxr-x---  2 wessels  wheel  512 Apr 28 20:42 bin drwxr-x---  2 wessels  wheel  512 Apr 28 20:42 etc drwxr-x---  2 wessels  wheel  512 Apr 28 20:42 libexec drwxr-x---  3 wessels  wheel  512 Apr 28 20:43 man drwxr-x---  2 wessels  wheel  512 Apr 28 20:42 sbin drwxr-x---  4 wessels  wheel  512 Apr 28 20:42 share drwxr-x---  4 wessels  wheel  512 Apr 28 20:43 var 

Squid uses the bin , etc , libexec , man , sbin , and share directories for a few, relatively small files (or other directories) that don't change very often. The files under the var directory, however, are a different story. This is where you'll find Squid's log files, which may grow quite large (tens or hundreds of megabytes). var is also the default location for the actual disk cache. You may want to put var on a different partition with plenty of space. One easy way to do this is with the ”localstatedir option:

 % ./configure --localstatedir=/bigdisk/var 

You don't need to worry too much about pathnames when configuring Squid. You can always change the pathnames later, in the squid.conf file.

3.4.1 configure Options

The ./configure script has a number of different options that all start with ” . You can see the full list of options by typing ./configure --help . Some of these options are common to all configure scripts, and some are unique to Squid. Here are the standard options that you might find useful:

--prefix = PREFIX

This sets the installation prefix directory, as described earlier. The installation prefix is the default directory for all executables, logs, and configuration files. Throughout this book, $prefix refers to your choice for the installation prefix.

--localstatedir = DIR

This option allows you to change the location for the var directory. The default is $prefix/var , but you might want to change it so that Squid's disk cache and log files are stored elsewhere.

--sysconfdir = DIR

This option allows you to change the location for the etc directory. The default is $prefix/etc . If you like to use /usr as the installation prefix, you might want to set ”sysconfdir to /etc .

Here are the Squid-specific ./configure options:

--enable-dlmalloc [= LIB ]

On some systems, the built-in memory allocation (malloc) functions have poor performance characteristics when used with Squid. Using the ”enable-dlmalloc option builds and links with the dlmalloc package included in the Squid source code. If you already have dlmalloc built on your system, you can specify the library's pathname as the =LIB argument. See http://g.oswego.edu/dl/html/malloc.html for more information on dlmalloc .

--enable-gnuregex

Squid uses regular expressions for pattern matching in access control lists and other configuration directives. The GNU regular expression library comes with the Squid source code; it can be used on operating systems that don't have built-in regular expression functions. The ./configure script probes your system for a regular expression library and enables the use of GNU regex if necessary. If, for some reason, you want to force the usage of GNU regex, you can add this option to the ./configure command.

--enable-carp

The Cache Array Routing Protocol (CARP) is useful for forwarding cache misses to an array, or cluster, of parent caches. There's more about CARP in Section 10.9.

--enable-async-io [= N_THREADS ]

Async I/O refers to one of Squid's techniques for improved storage performance. The aufs storage module uses a number of thread processes to perform disk I/O operations. This code works only on Linux and Solaris systems. The =N_THREADS argument changes the number of thread processes Squid uses. aufs and Async I/O are discussed in Section 8.4.

Note that the ”enable-async-io option is a shortcut that turns on three other ./configure options. It is equivalent to specifying:

 --with-aufs-threads=N_THREADS --with-pthreads --enable-storeio=ufs,aufs 

--with-pthread s

The ”with-pthreads option causes the compilation procedure to link with your system's Pthreads library. The aufs storage module is the only part of Squid that uses threads. Normally, you don't specify this option on the ./configure command line because it's enabled automatically when you use ”enable-async-io .

--enable-storeio = LIST

Squid supports a number of different storage modules. With this option, you tell ./configure which modules to compile. The ufs , aufs , diskd , coss , and null modules are supported in Squid-2.5. You can also get a list by looking at the directories under src/fs .

LIST is a comma-separated list of module names . For example:

 % ./configure --enable-storeio=afus,diskd,ufs 

The ufs module is the default and least likely to cause problems. Unfortunately, it also has limited performance characteristics. The other modules may not necessarily compile on your particular operating system. For a complete description of Squid's storage modules, see Chapter 8.

--with-aufs-threads = N_THREADS

Specifies the number of threads to use for the aufs storage scheme (see Section 8.4). By default, Squid automatically calculates how many threads to use, based on the number of cache directories.

--enable-heap-replacement

This option has been deprecated but remains for backward compatibility. You should always use the ”enable-removal-policies option instead.

--enable-removal-policies = LIST

Removal policies are the algorithms Squid uses to eject cached objects when making room for new ones. Squid-2.5 supports three removal policies: least recently used (LRU), greed dual size (GDS), and least frequently used (LFU).

However, for some reason, the ./configure options blur the distinction between a particular replacement policy and the underlying data structures required to implement them. LRU, which is the default, is implemented with a doubly linked list. The GDS and LFU implementations use a data structure known as a heap .

To use the GDS or LFU policies, you specify:

 % ./configure --enable-removal-policies=heap 

You then select between GDS and LFU in the Squid configuration file. If you want to retain the option of using LRU, specify:

 % ./configure --enable-removal-policies=heap,lru 

There's more about replacement policies in Section 7.5.

--enable-icmp

As you'll see in Section 10.5, Squid can make round-trip time measurements with ICMP messages, much like the ping program. You can use this option to enable these features.

--enable-delay-pools

Delay pools are Squid's technique for traffic shaping or bandwidth limiting. The pools consist of groups of client IP addresses. When requests from these clients are cache misses, their responses may be artificially delayed. See more about delay pools in Appendix C.

--enable- useragent -log

This option enables logging of the HTTP User -Agent header from client requests. See more about this in Section 13.5.

--enable-referer - log

This option enables logging of the HTTP referer header from client requests. See more about this in Section 13.4.

--disable-wccp

The Web Cache Coordination Protocol (WCCP) is Cisco's once-proprietary protocol for intercepting and distributing HTTP requests to one or more caches. WCCP is enabled by default, but you can use this option to prevent compilation of the WCCP code if you like.

--enable-snmp

The Simple Network Management Protocol (SNMP) is a popular way to monitor network devices and servers. This option causes the build procedure to compile all of the SNMP- related code, including a cut-down version of the CMU SNMP library.

--enable-cachemgr - hostname [= hostname ]

cachemgr is a CGI program you can use to administratively query Squid. By default, cachemgr 's hostname field is blank, but you can create a default value with this option. For example:

 % ./configure --enable-cachemgr-hostname=mycache.myorg.net 

--enable-arp-acl

Squid supports ARP, or Ethernet address, access control lists on some operating systems. The code to implement ARP ACLs uses nonstandard function interfaces, so it is disabled by default. If you run Squid on Linux or Solaris, you may be able to use this feature.

--enable-htcp

HTCP is the Hypertext Caching Protocol ”an intercache protocol similar to ICP. See Section 10.8 for more information.

--enable-ssl

Use this option to give Squid the ability to terminate SSL/TLS connections. Note this only works for accelerated requests in surrogate mode. See Section 15.2.2 for more information.

--with-openssl [= DIR ]

This option exists so that you can tell the compiler where to find the OpenSSL libraries and header files, if necessary. If they aren't in the default location, enter the parent directory after this option. For example:

 % ./configure --enable-ssl --with-ssl=/opt/foo/openssl 

Given this example, your compiler looks for the OpenSSL header files in /opt/foo/openssl/include , and for libraries in /opt/foo/openssl/lib .

--enable-cache-digests

Cache Digests are another alternative to ICP, but with significantly different characteristics. See Section 10.7.

--enable-err-languages =" lang1 lang2 ..."

Squid supports customizable error messages and comes with error messages in many different languages. This option determines the languages that are copied to the installation directory ( $prefix/share/errors ). If you don't use this option, all available languages are installed. To see which languages are available, look at a directory listing of the errors directory in the source distribution. Here's how to enable more than one language:

 % ./configure --enable-err-languages="Dutch German French" ... 

--enable-default-err-language = lang

This option sets the default value for the error_directory directive. For example, if you want to use Dutch error messages, you can use this ./configure option:

 % ./configure --enable-default-err-language=Dutch 

You can also set the error_directory directive in squid.conf , as described in Appendix A. English is the default error language if you omit this option.

--with-coss-membuf-size = N

The Cyclic Object Storage System ( coss ) is an experimental storage scheme for Squid. This option sets the memory buffer size for coss cache directories. Note that in order to use coss , you must specify it as a storage type in the ”enable-storeio option.

The argument is given in bytes. The default is 1,048,576 bytes or 1 MB. You can specify a 2-MB buffer like this:

 % ./configure --with-coss-membuf-size=2097152 

--enable-poll

Unix provides two similar functions that scan open file descriptors for I/O events: select( ) and poll( ) . The ./configure script usually does a very good job of figuring out when to use poll( ) over select( ) . Use this option if you want to override the ./configure script and force it to use poll( ) .

--disable-poll

Similarly, Unix gurus may want to force ./configure to not use poll( ) .

--disable-http-violations

By default, Squid can be configured to violate the HTTP protocol specifications. You can use this option to remove the code completely that would violate HTTP.

--enable-ipf-transparent

In Chapter 9, I'll describe how to configure Squid for interception caching. Some operating systems use the IP Filter package to assist with the interception. In these cases you should use this ./configure option. If you enable this option and get compiler errors on the src/client_side.c file, chances are that the IP Filter package isn't actually (or correctly) installed on your system.

--enable-pf-transparent

You may need this option to use HTTP interception on systems that use the PF packet filter. PF is the standard packet filter for OpenBSD and may have been ported to other systems as well. If you enable this option and get compiler errors on the src/client_side.c file, chances are that PF isn't actually installed on your system.

--enable-linux-netfilter

Netfilter is the name of the Linux packet filter for the 2.4 kernel series. Enable this option if you want to use HTTP interception with Linux 2.4 or later.

--disable-ident-lookups

ident is a simple protocol that allows a server to find the username associated with a client's particular TCP connection. If you use this option, the compiler excludes completely the code that performs such lookups. Even if you leave the code enabled at compile time, Squid doesn't make ident lookups unless you configure them in squid.conf .

--disable-internal-dns

The Squid source code includes two different DNS resolution implementations, called internal and external . Internal lookups are the default, but some people prefer the external technique. This option disables the internal functionality and reverts to the older method.

Internal lookups use Squid's own implementation of the DNS protocol. That is, Squid generates raw DNS queries and sends them to a resolver. It retransmits queries that time out, and you can specify any number of resolvers . One of the benefits to this implementation is that Squid gets accurate TTLs for DNS replies.

External lookups use the C library's gethostbyname( ) and gethostbyaddr( ) functions. Since these routines block the process until the answer comes back, they must be called from external, helper processes. Squid uses a pool of external processes to make queries in parallel. The primary drawback to external DNS resolution is that you need more helper processes as Squid's load increases . Another annoyance is that the C library functions don't convey TTLs with the answers, in which case Squid uses a constant value supplied by the positive_dns_ttl directive.

--enable-truncate

The truncate( ) system call is an alternative to using unlink( ) . While unlink( ) removes a cache file altogether, truncate( ) sets the file size to zero. This frees the disk space associated with the file but leaves the directory entry in place. This option exists because some people believed (or hoped) that truncate( ) would produce better performance than unlink( ) . However, benchmarks have shown little or no real difference.

--disable-hostname-checks

By default, Squid requires that URL hostnames conform to the somewhat archaic specifications in RFC 1034:

The labels must follow the rules for ARPANET host names. They must start with a letter, end with a letter or digit, and have as interior characters only letters , digits, and hyphen.

Here, "letter" means the ASCII characters A through Z. Since internationalized domain names are becoming increasingly popular, you may want to use this option to remove the restriction.

--enable-underscores

This option controls Squid's behavior regarding underscore characters in hostnames. General consensus is that hostnames must not include underscore characters, although some people disagree . Squid, by default, generates an error message for requests that have an underscore in a URL hostname. You can use this option to make Squid treat them as valid. However, your DNS resolver may also enforce the no-underscore requirement and fail to resolve such hostnames.

--enable-auth [= LIST ]

This option controls which HTTP authentication schemes to support in the Squid binary. You can select any combination of the following schemes: basic , digest , and ntlm . If you omit the option, Squid supports only basic authentication. If you give the ”enable-auth option without any arguments, the build process adds support for all schemes. Otherwise, you can give a comma-separated list of schemes to support:

 % ./configure --enable-auth=digest,ntlm 

I talk more about authentication in Chapters 6 and 12.

--enable-auth-helpers = LIST

This old option is now deprecated, but still remains for backward compatibility. You should use ”enable-basic-auth-helpers= LIST instead.

--enable-basic-auth-helpers = LIST

With this option, you can build one or more of the HTTP Basic authentication helper programs found in helpers/basic_auth . See Section 12.2 for their names and descriptions.

--enable-ntlm-auth-helpers = LIST

With this option, you can build one or more of the HTTP NTLM authentication helper programs found in helpers/ntlm_auth . See Section 12.4 for their names and descriptions.

--enable-ntlm-fail-open

When you enable this option, Squid's NTLM authentication module defaults to allow access in the event of an error or problem.

--enable-digest-auth-modules = LIST

With this option, you can build one or more of the HTTP Digest authentication helper programs found in helpers/digest_auth . See Section 12.3 for their names and descriptions.

--enable-external-acl-helpers = LIST

With this option, you can build one or more of the external ACL helper programs that I discuss in Section 12.5. For example:

 % ./configure --enable-external-acl-helpers=ip_user,ldap_group 

--disable-unlinkd

Unlinkd is another one of Squid's external helper processes. Its sole job is to execute the unlink( ) (or truncate( ) ) system call on cache files. Squid realizes a significant performance gain by implementing file deletion in an external process. Use this option to disable the external unlink daemon feature.

--enable- stacktrace

Some operating systems support automatic generation of stack trace data in the event of a program crash. When you enable this feature and Squid crashes, the stack trace information is written to the cache.log file. This information is often helpful to developers in tracking down programming bugs .

--enable-x-accelerator-vary

This advanced feature may be used when Squid is configured as a surrogate. It instructs Squid to look for X-Accelerator-Vary headers in responses from backend origin servers. See Section 15.5.

3.4.2 Running configure

Now we're ready to run the ./configure script. Go to the top-level source directory and type ./configure , followed by any of the options mentioned previously. For example:

 % cd squid-2.5.STABLE4 % ./configure --enable-icmp --enable-htcp 

./configure 's job is to probe your operating system and find out which things are available, and which are not. One of the first things it does is make sure your C compiler is working. If ./configure detects a problem with your C compiler, the script exits with this error message:

 configure: error: installation or configuration problem: C compiler cannot create executables. 

Most likely, you'll never see that message. If you do, it means either your system doesn't have a C compiler at all or that the compiler isn't installed correctly. Look at the config.log file for hints as to the exact problem. If your system has more than one C compiler, you can tell ./configure which to use by setting the CC environment variable before running ./configure :

 % setenv CC /usr/local/bin/gcc % ./configure ... 

After ./configure checks out the compiler, it looks for a long list of header files, libraries, and functions. Normally you won't have to worry about this part. In some cases, ./configure pauses to get your attention about something that may be a problem (such as not enough file descriptors). It may also stop if you specify incompatible or unreasonable command-line options. If something does go wrong, check the config.log output. ./configure 's final task is to create Makefile s and other files based on the things it learned about your system. At this point, you're ready to begin compiling.