Squid: The Definitive Guide

Chapter 5. Running Squid

Now that you have Squid installed, and maybe even configured, you need to learn the ins and outs of running Squid. Although most of the configuration occurs in squid.conf, you may find some of Squid’s command-line options useful. For example, one of the first things you must do is use the -z option to initialize the cache directories. You may also find the -d option useful for debugging.

Squid normally runs as a daemon process. If you are new to Squid, however, I recommend running Squid in the foreground from a terminal window until you are confident that it is working properly. Following that, you can run Squid as a daemon, in the background. Most likely, you’ll want to start Squid each time your system boots. Different operating systems have different approaches to startup scripts. I’ll show you how to make it happen in three different ways.

You can send signals to the running Squid process to execute various tasks, such as halting and reconfiguring Squid, and rotating the log files. Although you can use the kill command to send signals, it is easier to use the squid -k commands.

Squid Command-Line Options

Before getting too far into other things, let’s look at Squid’s command-line options. Many of these you will never use and some are useful only when debugging problems:

-a port

Specifies a new http_port value. This option always overrides the value from squid.conf. Note, however, that you can specify multiple values in squid.conf. The -a option overrides only the first value from the config file. (This option uses the letter “a” because in the Harvest cache, the HTTP port was called the ASCII port.)

-d level

Makes Squid write its debugging messages to stderr (as well as cache.log and syslog, if configured). The level argument specifies the maximum level for messages that should be shown on stderr. In most cases -d1 works well. See Section 16.2 for a description of debugging levels.

-f file

Specifies an alternate configuration file.

-h

Displays the usage information.

-k function

Signals Squid to perform various administrative functions. The function argument may be one of the following: reconfigure, rotate, shutdown, interrupt, kill, debug, check, or parse. reconfigure causes the running Squid process to reread its configuration file. rotate causes Squid to rotate its log files, which involves closing them, possibly renaming them, and opening them again. shutdown sends the signal to shut down the Squid process. interrupt also shuts down Squid but does so immediately, without waiting for active transactions to finish. kill sends the unstoppable KILL signal to Squid, which should only be used as a last resort. debug puts Squid into full debugging mode. It can quickly fill up your disk space if your cache is busy. check simply checks for a running Squid process. The process return value indicates whether Squid is running or not. Finally, parse simply parses the squid.conf file. The process return value is non-zero if the configuration file contains errors.

-s

Enables logging to the syslog daemon. Squid uses the LOCAL4 syslog facility. Level 0 debug messages are logged with priority LOG_WARNING, and level 1 messages are logged with LOG_NOTICE. Higher level debugging messages aren’t sent to syslogd. You might use an entry like this in /etc/syslogd.conf:

local4.warning                /var/log/squid.log

-u port

Specifies an alternate ICP port number, overriding icp_port in squid.conf.

-v

Prints the version string.

-z

Initializes cache, or swap, directories. You must use this option when running Squid for the first time or whenever you add a new cache directory.

-C

Prevents the installation of signal handlers that trap certain fatal signals such as SIGBUS and SIGSEGV. Normally, the signals are trapped by Squid so that it can attempt a clean shutdown. However, trapping the signal may make it harder to debug the problem afterwards. With this option, the fatal signals cause their default actions, which is usually to dump core.

-D

Disables initial DNS tests. Normally, Squid won’t start until it verifies that its DNS server is working. This option prevents that check. You can also alter or remove the dns_testnames option in squid.conf.

-F

Makes Squid refuse all requests until it rebuilds the storage metadata. If your cache is busy, this option may shorten the time required to rebuild the metadata. If your cache is large, however, the rebuild procedure may take a long time anyway.

-N

Prevents Squid from becoming a background daemon process.

-R

Prevents Squid from using the SO_REUSEADDR option before binding to the HTTP port.

-V

Enables virtual host surrogate mode. Similar to entering httpd_accel_host virtual in squid.conf.

-X

Forces full debugging, as though you had specified debug_options ALL,9 in squid.conf.

-Y

Returns ICP_MISS_NOFETCH instead of ICP_MISS when rebuilding store metadata. For busy parent caches, this option may result in less load while the cache is rebuilding. See Section 10.6.1.2.

Check Your Configuration File for Errors

Before trying to start Squid, you should verify that your squid.conf file makes sense. This is easy to do. Just run the following command:

% squid -k parse

If you see no output, the configuration file is valid, and you can proceed to the next step.

However, if your configuration file contains an error, Squid tells you about it:

squid.conf line 62: http_access allow okay2
aclParseAccessLine: ACL name 'okay2' not found.

Here you can see that the http_access directive on line 62 references an ACL that doesn’t exist. Sometimes the error messages are less informative:

FATAL: Bungled squid.conf line 76: memory_pools

In this case, we forgot to put either on or off after the memory_pools directive on line 76.

It’s a good idea to develop the habit of using squid -k parse every time you modify your configuration file. If you don’t bother, and your file has some errors, Squid tells you about them and refuses to start anyway. If you end up managing a number of caches, it is likely that you’ll develop some scripts to automate starting, stopping, and reconfiguring Squid. You can use this feature in your scripts to ensure that the configuration files are always valid.

Initializing Cache Directories

Before running Squid for the first time, and whenever you add a new cache_dir, you must initialize the cache directories. The command is simply:

% squid -z

For the UFS-related storage schemes (ufs, aufs, and diskd; see Chapter 8), this command creates the subdirectories needed under each cache_dir. You don’t need to worry that Squid will wipe out your current cache directories (if any).

Ownership and permissions are a common problem at this stage. Squid runs under a certain user ID, specified with cache_effective_user in squid.conf. This user ID must have read and write permission under each cache_dir directory. If not, you’ll see a message like this:

Creating Swap Directories
FATAL: Failed to make swap directory /usr/local/squid/var/cache/00:
    (13) Permission denied

In this case, you should make sure that all components of /usr/local/squid/var/cache are accessible to the user ID given in squid.conf. The final component—the cache directory—must be writable by this user ID as well.

Cache directory initialization may take a couple of minutes, depending on the size and number of cache directories, and the speed of your disk drives. If you want to watch the progress, use the -X option:

% squid -zX

Testing Squid in a Terminal Window

Once you’ve initialized the cache directories, you should run Squid in a terminal window with logging to stderr. This way, you can easily spot any errors or problems and make sure that Squid successfully starts. Use the -N option to keep Squid in the foreground and the -d1 option to display level 1 debugging on stderr:

% squid -N -d1

You should see output like this:

2003/09/29 12:57:52| Starting Squid Cache 
version 2.5.STABLE4 for i386-unknown-freebsd4.8...
2003/09/29 12:57:52| Process ID 294
2003/09/29 12:57:52| With 1064 file descriptors available
2003/09/29 12:57:52| DNS Socket created on FD 4
2003/09/29 12:57:52| Adding nameserver 206.107.176.2 from /etc/resolv.conf
2003/09/29 12:57:52| Adding nameserver 205.162.184.2 from /etc/resolv.conf
2003/09/29 12:57:52| Unlinkd pipe opened on FD 9
2003/09/29 12:57:52| Swap maxSize 102400 KB, estimated 7876 objects
2003/09/29 12:57:52| Target number of buckets: 393
2003/09/29 12:57:52| Using 8192 Store buckets
2003/09/29 12:57:52| Max Mem  size: 8192 KB
2003/09/29 12:57:52| Max Swap size: 102400 KB
2003/09/29 12:57:52| Rebuilding storage in /usr/local/squid/var/cache (DIRTY)
2003/09/29 12:57:52| Using Least Load store dir selection
2003/09/29 12:57:52| Set Current Directory to /usr/local/squid/var/cache
2003/09/29 12:57:52| Loaded Icons.
2003/09/29 12:57:52| Accepting HTTP connections at 0.0.0.0, port 3128, FD 11.
2003/09/29 12:57:52| Accepting ICP messages at 0.0.0.0, port 3130, FD 12.
2003/09/29 12:57:52| WCCP Disabled.
2003/09/29 12:57:52| Ready to serve requests.

If you see an error message, you need to fix it before proceeding. Be sure to check the first few lines of output for warning messages. The most common errors are file/directory permissions and configuration file syntax errors. If you see an error message that doesn’t make sense, have a look at Chapter 16 for advice and information on troubleshooting Squid. If that doesn’t help, check the Squid FAQ, or search the mailing list archives for an explanation.

Once you see the Ready to serve requests message, test Squid with a few HTTP requests. You can do this by configuring your browser to use Squid as a proxy and then open a web page. If Squid is working correctly, the page should load as quickly as it would without using Squid. Alternatively, you can use the squidclient program that comes with Squid:

% squidclient http://www.squid-cache.org/

If this works, Squid’s home page HTML file will scroll across your terminal window. Once you’re confident that Squid works okay, you can interrupt the Squid process (i.e., with Ctrl-C) and run Squid as a daemon.

Running Squid as a Daemon Process

Normally you’ll want to run Squid as a daemon process (i.e., not attached to your terminal window). The easiest way to do this is simply execute Squid as follows:

% squid -s

The -s option causes Squid to write important status and warning messages to syslogd. Squid uses the LOCAL4 facility and the LOG_WARNING and LOG_NOTICE priorities. Your syslog daemon may or may not actually log Squid’s messages, depending on how it is configured. These same messages are written to the cache.log file, so it is safe to omit the -s option if you prefer.

When you start Squid without the -N option (as shown earlier), Squid automatically backgrounds itself and creates a parent/child process pair. The child process is the one that does all the real work. The parent process makes sure that a child process is always running. Thus, if the child process dies unexpectedly, the parent starts another so that Squid remains in operation. You can see this parent/child process interaction by looking at your syslog messages:

Jul 31 14:58:35 zapp squid[294]: Squid Parent: child process 296 started

Here you can see that the parent is process ID 294, and the child is 296. When you look at ps output, you’ll see that the child process is listed as (squid):

% ps ax | grep squid
  294  ??  Is     0:00.01 squid -sD
  296  ??  S      0:00.27 (squid) -sD (squid)

If the child Squid process dies unexpectedly, the parent starts another. For example:

Jul 31 15:02:53 zapp squid[294]: Squid Parent: child process 296 exited due to signal 6
Jul 31 15:02:56 zapp squid[294]: Squid Parent: child process 359 started

In some situations, the child Squid process may die immediately. Rather than constantly spawning new Squid processes, the parent process gives up if the child processes won’t stay running for at least 10 seconds five times in a row:

Jul 31 15:13:48 zapp squid[455]: Squid Parent: child process 474 exited with status 1
Jul 31 15:13:48 zapp squid[455]: Exiting due to repeated, frequent failures

If this happens to you, check syslog and Squid’s cache.log for error messages.

The squid_start Script

When Squid runs as a daemon process, it looks for a file named squid_start in the same directory as the squid binary. If found, this program is executed before the parent process forks to run the child process. You can use this script for certain administrative tasks, such as notifying someone that Squid is starting, managing log files, etc. Squid doesn’t start the child process until the squid_start program exits.

Note

The squid_start script only works when you start Squid by its absolute or relative pathname. In other words, Squid doesn’t use the PATH environment variable to locate squid_start. Thus, you may want to develop the habit of starting Squid like this:

% /usr/local/squid/sbin/squid -sD

rather than starting Squid like this:

% squid -sD

Boot Scripts

Most likely, you’ll want Squid to start automatically every time your computer boots. Different operating systems vary widely in how their boot-up scripts work. I’ll describe some common environments here, but you may need to refer to your particular operating system for specific information.

/etc/rc.local

One of the easiest schemes is the /etc/rc.local script. This is simply a shell script that runs as root each time the system boots. Using this script to start Squid is as easy as adding the following line:

/usr/local/squid/sbin/squid -s

Of course your installation prefix may be different, and you may like to use some other command-line options. Don’t use the -N option here.

If, for some reason, you’re not using the cache_effective_user directive, you can try using su to start Squid as a non-root user:

/usr/bin/su nobody -c '/usr/local/squid/sbin/squid -s'

init.d and rc.d

The init.d and rc.d schemes use a separate shell script to start different services. These scripts are often located in one of the following directories: /sbin/init.d, /etc/init.d, and /usr/local/etc/rc.d. The scripts usually take a single command-line argument, which is either start or stop. Some systems only use the start argument. Here’s a basic script for starting Squid:

#!/bin/sh
#
# this script starts and stops Squid

case "$1" in
start)
          /usr/local/squid/sbin/squid -s
          echo -n ' Squid'
          ;;
stop)
          /usr/local/squid/sbin/squid -k shutdown
          ;;
esac

Note

Linux users may want to add commands that set the file-descriptor limits before running Squid. For example:

echo 8192 > /proc/sys/fs/file-max
limit -HSn 8192

To use this script, find the appropriate directory in which such scripts are stored. Give it a meaningful name, similar to the others. Perhaps S98squid or simply squid.sh. Be sure to test the script by rebooting your computer rather than assuming it will work.

/etc/inittab

Another scheme supported on some operating systems is the /etc/inittab file. On these systems, the init process starts and stops services based on the run level. A typical inittab entry looks like this:

sq:2345:once:/usr/local/squid/sbin/squid -s

With this entry, the init process starts Squid just once and then forgets about it. Squid makes sure it stays running as described previously. Alternatively, you can do it like this:

sq:2345:respawn:/usr/local/squid/sbin/squid -Ns

Here, since we use the respawn option, init restarts Squid if the process exits. If you use respawn, be sure to use the -N option.

After editing the inittab file, use this command to make init reread its configuration file and start Squid:

# init q

A chroot Environment

Some people like to run Squid in a chroot environment. This is a Unix feature that gives a process a new root filesystem directory. It provides an extra level of security in the event that Squid is compromised. If an attacker somehow gains access to the operating system through Squid, she can only access files under the chroot filesystem. The other system files, outside of the chroot tree, remain inaccessible.

The easiest way to run Squid in a chroot environment is by specifying the new root directory in the squid.conf file with this directive:

chroot /new/root/directory

Tip

The chroot( ) system call requires superuser privileges, so you must start Squid as root to use this feature.

The chroot environment isn’t for first-time Unix users. It is a little tricky because you must replicate a number of files underneath the new root directory. For example, if the default configuration file is normally /usr/local/squid/etc/squid.conf, and you use the chroot directive, the file must be located at /new/root/directory/usr/local/squid/etc/squid.conf. You must copy all of the files under $prefix/etc, $prefix/share, and $prefix/libexec to the chroot directory. Make sure that $prefix/var and the cache directories exist and are writable under the chroot directory as well.

Chances are that your operating system requires a number of files in the chroot directory, such as /etc/resolv.conf and /dev/null. If you use an external helper program, such as a redirector (see Chapter 11) or an authenticator (see Chapter 12), you’ll also need some shared libraries from /usr/lib. You can use the ldd utility to find out which shared libraries are required for a given program:

% ldd /usr/local/squid/libexec/ncsa_auth
/usr/local/squid/libexec/ncsa_auth:
        libcrypt.so.2 => /usr/lib/libcrypt.so.2 (0x28067000)
        libm.so.2 => /usr/lib/libm.so.2 (0x28080000)
        libc.so.4 => /usr/lib/libc.so.4 (0x28098000)

You can also use the chroot command to test helpers:

# chroot /new/root/directory /usr/local/squid/libexec/ncsa_auth
/usr/libexec/ld-elf.so.1: Shared object "libcrypt.so.2" not found

For more information on chroot, see the chroot( ) manpage on your system.

Stopping Squid

The safest way to shut down Squid is with the squid -k shutdown command:

% squid -k shutdown

This command sends the TERM signal to the running Squid process. Upon receipt of the TERM signal, Squid closes its incoming sockets so that new requests aren’t accepted. It then waits some amount of time for outstanding requests to complete. The default is 30 seconds, which you can change with the shutdown_lifetime directive.

If, for some reason, the squid.pid file is missing or unreadable, the squid -k commands don’t work. In this case, you can manually kill Squid by finding the process ID with ps. For example:

% ps ax | grep squid

If you see more than one Squid process, be sure to kill the one that shows up as (squid). For example:

% ps ax | grep squid
  294  ??  Is     0:00.01 squid -sD
  296  ??  S      0:00.27 (squid) -sD (squid)
% kill -TERM 296

After sending the TERM signal, you may want to watch the log file to double-check that Squid is shutting down:

% tail -f logs/cache.log
2003/09/29 21:49:30| Preparing for shutdown after 9316 requests
2003/09/29 21:49:30| Waiting 10 seconds for active connections to finish
2003/09/29 21:49:30| FD 11 Closing HTTP connection
2003/09/29 21:49:31| Shutting down...
2003/09/29 21:49:31| FD 12 Closing ICP connection
2003/09/29 21:49:31| Closing unlinkd pipe on FD 9
2003/09/29 21:49:31| storeDirWriteCleanLogs: Starting...
2003/09/29 21:49:32| Finished.  Wrote 253 entries.
2003/09/29 21:49:32| Took 0.1 seconds (1957.6 entries/sec).
2003/09/29 21:49:32| Squid Cache (Version 2.5.STABLE4): Exiting normally.

If you use squid -k interrupt, Squid shuts down immediately, without waiting for active requests to complete. This is equivalent to sending the INT signal with kill.

Reconfiguring a Running Squid Process

As you learn more about Squid, you’ll probably find yourself making many changes to the squid.conf file. To have the new settings take effect, you can either shut down and restart Squid, or you can reconfigure Squid while it is running.

The best way to reconfigure a running Squid process is with the squid -k reconfigure command:

% squid -k reconfigure

When you run this command, a HUP signal is sent to the running Squid process. Squid then reads and parses the squid.conf file. If the operation is successful, you’ll see this in cache.log:

2003/09/29 22:02:25| Restarting Squid Cache (version 2.5.STABLE4)...
2003/09/29 22:02:25| FD 12 Closing HTTP connection
2003/09/29 22:02:25| FD 13 Closing ICP connection
2003/09/29 22:02:25| Cache dir '/usr/local/squid/var/cache' size remains unchanged
                     at 102400 KB
2003/09/29 22:02:25| DNS Socket created on FD 5
2003/09/29 22:02:25| Adding nameserver 10.0.0.1 from /etc/resolv.conf
2003/09/29 22:02:25| Accepting HTTP connections at 0.0.0.0, port 3128, FD 9.
2003/09/29 22:02:25| Accepting ICP messages at 0.0.0.0, port 3130, FD 11.
2003/09/29 22:02:25| WCCP Disabled.
2003/09/29 22:02:25| Loaded Icons.
2003/09/29 22:02:25| Ready to serve requests.

You need to be a little careful with the reconfigure option because it’s possible to make changes that cause a fatal error. For example, note that Squid closes and reopens the incoming HTTP and ICP sockets. If you change the http_port to a port number that Squid can’t open, it exits with a fatal error message.

Certain options and directives can’t be changed while Squid is running. This includes:

Removal of cache directories (cache_dir directive).
Changes to the store_log directive.
Changing the block-size value for coss cache_dirs. In fact, whenever you change this value, you must reinitialize the coss cache_dir.
The coredump_dir directive isn’t examined during the reconfigure procedure. Thus, you can’t make Squid change its current directory after it has started.

Solaris users may experience a subtle problem when reconfiguring Squid. The fopen( ) call in the Solaris stdio implementation requires an unused file descriptor less than 256. The FILE structure stores the file descriptor as an 8-bit value. Normally this isn’t a problem because Squid uses raw I/O (e.g., open( )) to open cache files. However, certain tasks that occur during the reconfigure procedure use fopen( ). These may fail if the first 256 file descriptors are already allocated.

Rotating the Log Files

Squid writes to a number of log files unless you disable them in squid.conf. You must periodically rotate the log files to prevent them from consuming too much disk space. Squid places a lot of importance on log files and exits with an error message when it can’t write to them. To keep disk space consumption under control, use the following command in a cron job:

% squid -k rotate

For example, this crontab entry rotates the logs every 24 hours, at 4 A.M.:

0 4 * * * /usr/local/squid/sbin/squid -k rotate

This command does two things. First, it closes the currently open log files. Then, it renames the cache.log, store.log, and access.log files by appending a numeric extension. For example, cache.log becomes cache.log.0, cache.log.0 becomes cache.log.1, and so on, up to the value of the logfile_rotate option.

Squid keeps only the last logfile_rotate versions of each log file. The older versions are simply removed during the renaming process. If you want to keep more copies, you need to increase the logfile_rotate limit or write some custom scripts that move the log files to a different location.

See Section 13.7 for additional information about rotating log files.

Exercises

Use Squid’s -s option and verify that its messages are saved by your syslog daemon.
Run squid -X -d9, and examine some of the debugging messages.
Write a shell script that stops Squid but doesn’t exit until all Squid processes exit.
Play with squid -k rotate. What happens if you have tail -f cache.log running when you rotate the log files?

Previous Chapter

4. Configuration Guide for the Eager

Next Chapter

6. All About Access Controls

Table of Contents for Squid: The Definitive Guide

Chapter 5. Running Squid

Squid Command-Line Options

Check Your Configuration File for Errors

Initializing Cache Directories

Testing Squid in a Terminal Window

Running Squid as a Daemon Process

The squid_start Script

Note

Boot Scripts

/etc/rc.local

init.d and rc.d

Note

/etc/inittab

A chroot Environment

Tip

Stopping Squid

Reconfiguring a Running Squid Process

Rotating the Log Files

Exercises

Table of Contents for
Squid: The Definitive Guide