Different Ways of Running Squid Proxy Server

Kulbir Saini

February 2011


Squid Proxy Server 3.1: Beginner's Guide

Squid Proxy Server 3.1: Beginner's Guide Improve the performance of your network using the caching and access control capabilities of Squid
  • Get the most out of your network connection by customizing Squid's access control lists and helpers
  • Set up and configure Squid to get your website working quicker and more efficiently
  • No previous knowledge of Squid or proxy servers is required
  • Part of Packt's Beginner's Guide series: lots of practical, easy-to-follow examples accompanied by screenshots
        Read more about this book      

(For more resources on Proxy Servers, see here.)

Command line options

Normally, all of the Squid configuration options reside with in the squid.conf file (the main Squid configuration file). To tweak the Squid functionality, the preferred method is to change the options in the squid.conf file. However there are some options which can also be controlled using additional command line options while running Squid.

These options are not very popular and are rarely used, but these are very useful for debugging problems without the Squid proxy server. Before exploring the command line options, let's see how Squid is run from the command line.

The location of the Squid binary file depends on the --prefix option passed to the configure command before compiling. So, depending upon the value of the --prefix option, the location of the Squid executable may be one of /usr/local/sbin/squid or ${prefix}/sbin/squid, where ${prefix} is the value of the option --prefix passed to the configure command. Therefore, to run Squid, we need to run one of the following commands on the terminal:

  • When the --prefix option was not used with the configure command, the default location of the Squid executable will be /usr/local/sbin/squid.
  • When the --prefix option was used and was set to a directory, then the location of the Squid executable will be ${prefix}/sbin/squid.

It's painful to type the absolute path for Squid to run. So, to avoid typing the absolute path, we can include the path to the Squid executable in our PATH shell variable, using the export command as shown in the following example:

$ export PATH=$PATH:/usr/local/sbin/

Alternatively, we can use the following command:

$ export PATH=$PATH:/opt/squid/sbin/

We can also add the preceding command to our ~/.bashrc or ~/.bash_profile file to avoid running the export command every time we enter a new shell.

After setting the PATH shell variable appropriately, we can run Squid by simply typing the following command on shell:

$ squid

This command will run Squid after loading the configuration options from the squid.conf file.

We'll be using the squid command without an absolute path for running the Squid process. Please use the appropriate path according to the installation prefix which you have chosen.

Now that we know how to run Squid from the command line, let's have a look at the various command line options.

Getting a list of available options

Before actually moving forward, we should firstly check the available set of options for our Squid installation.

Time for action – listing the options

Like a lot of other Linux programs, Squid also provides the option -h which can be used to retrieve a list of options:

squid -h

The previous command will result in the following output:

Usage: squid [-cdhvzCFNRVYX] [-s | -l facility] [-f config-file] [-[au] port] [-k signal]
-a port Specify HTTP port number (default: 3128).
-d level Write debugging to stderr also.
-f file Use given config-file instead of
-h Print help message.
-k reconfigure|rotate|shutdown|interrupt|kill|debug|check|parse
Parse configuration file, then send signal to
running copy (except -k parse) and exit.
-s | -l facility
Enable logging to syslog.
-u port Specify ICP port number (default: 3130), disable with 0.
-v Print version.
-z Create swap directories.
-C Do not catch fatal signals.
-F Don't serve any requests until store is rebuilt.
-N No daemon mode.
-R Do not set REUSEADDR on port.
-S Double-check swap during rebuild.

We will now have a look at a few important options from the preceding list. We will also, have a look at the squid(8) man page or http://linux.die.net/man/8/squid for more details.

What just happened?

We have just used the squid command to list the available options which we can use on the command line.

Getting information about our Squid installation

Various features may vary across different versions of Squid. Before proceeding any further, it's a good idea to know the version of Squid installed on our machine.

Time for action – finding out the Squid version

Just in case we want to check which version of Squid we are using or the options we used with the configure command before compiling, we can use the option -v on the command line. Let's run Squid with this option:

squid -v

If we try to run the preceding command in the terminal, it will produce an output similar to the following:

configure options: '--config-cache' '--prefix=/opt/squid/' '--enable-storeio=ufs,aufs' '--enable-removal-policies=lru,heap' '--enable-icmp' '--enable-useragent-log' '--enable-referer-log' '--enable-cache-digests' '--with-large-files' --enable-ltdl-convenience

What just happened?

We used the squid command with the -v option to find out the version of Squid installed on our machine, and the options used with the configure command before compiling Squid.

Creating cache or swap directories

The cache directories specified using the cache_dir directive in the squid.conf file, must already exist before Squid can actually use them.

Time for action – creating cache directories

Squid provides the -z command line option to create the swap directories. Let's see an example:

squid -z

If this option is used and the cache directories don't exist already, the output will look similar to the following:

2010/07/20 21:48:35| Creating Swap Directories
2010/07/20 21:48:35| Making directories in /squid_cache/00
2010/07/20 21:48:35| Making directories in /squid_cache/01
2010/07/20 21:48:35| Making directories in /squid_cache/02
2010/07/20 21:48:35| Making directories in /squid_cache/03

We should use this option whenever we add new cache directories in the Squid configuration file.

What just happened?

When the squid command is run with the option -z, Squid reads all the cache directories from the configuration file and checks if they already exist. It will then create the directory structure for all the cache directories that don't exist.

Have a go hero – adding cache directories

Add two or three test cache directories with different values of level 1 (8, 16, and 32) and level 2 (64, 256, and 512) to the configuration file. Then try creating them using the squid command. Now study the difference in the directory structure.

Using a different configuration file

The default location for Squid's main configuration file is ${prefix}/etc/squid/squid.conf. Whenever we run Squid, the main configuration is read from the default location. While testing or deploying a new configuration, we may want to use a different configuration file just to check whether it will work or not. We can achieve this by using the option -f, which allows us to specify a custom location for the configuration file. Let's see an example:

squid -f /etc/squid.minimal.conf
# OR
squid -f /etc/squid.alternate.conf

If Squid is run this way, Squid will try to load the configuration from /etc/squid.minimal.conf or /etc/squid.alternate.conf, and it will completely ignore the squid.conf from the default location.

Getting verbose output

When we run Squid from the terminal without any additional command line options, only warnings and errors are displayed on the terminal (or stderr). However, while testing, we would like to get a verbose output on the terminal, to see what is happening when Squid starts up.

Time for action – debugging output in the console

To get more information on the terminal, we can use the option -d. The following is an example:

squid -d 2

We must specify an integer with the option -d to indicate the verbosity level. Let's have a look at the meaning of the different levels:

  • Only critical and fatal errors are logged when level 0 (zero) is used.
  • Level 1 includes the logging of important problems.
  • Level 2 and higher includes the logging of informative details and other actions.

Higher levels result in more output on the terminal. A sample output on the terminal with level 2 would look similar to the following:

2010/07/20 21:40:53| Starting Squid Cache version 3.1.10 for i686-pc-linux-gnu...
2010/07/20 21:40:53| Process ID 15861
2010/07/20 21:40:53| With 1024 file descriptors available
2010/07/20 21:40:53| Initializing IP Cache...
2010/07/20 21:40:53| DNS Socket created at [::], FD 7
2010/07/20 21:40:53| Adding nameserver from /etc/resolv.conf
2010/07/20 21:40:53| User-Agent logging is disabled.
2010/07/20 21:40:53| Referer logging is disabled.
2010/07/20 21:40:53| Unlinkd pipe opened on FD 13
2010/07/20 21:40:53| Local cache digest enabled; rebuild/rewrite every 3600/3600 sec
2010/07/20 21:40:53| Store logging disabled
2010/07/20 21:40:53| Swap maxSize 0 + 262144 KB, estimated 20164 objects
2010/07/20 21:40:53| Target number of buckets: 1008
2010/07/20 21:40:53| Using 8192 Store buckets
2010/07/20 21:40:53| Max Mem size: 262144 KB
2010/07/20 21:40:53| Max Swap size: 0 KB
2010/07/20 21:40:53| Using Least Load store dir selection
2010/07/20 21:40:53| Current Directory is /opt/squid/sbin
2010/07/20 21:40:53| Loaded Icons.

As we can see, Squid is trying to dump a log of actions that it is performing. The messages shown are mostly startup messages and there will be fewer messages when Squid starts accepting connections.

Starting Squid in debug mode is quite helpful when Squid is up and running and users complain about poor speeds or being unable to connect. We can have a look at the debugging output and the appropriate actions to take.

What just happened?

We started Squid in debugging mode and can now see Squid writing an output on the command line, which is basically a log of the actions which Squid is performing. If Squid is not working, we'll be able to see the reasons on the command line and we'll be able to take actions accordingly.

Full debugging output on the terminal

The option -d specifies the verbosity level of the output dumped by Squid on the terminal. If we require all of the debugging information on the terminal, we can use the option -X, which will force Squid to write debugging information at every single step. If the option -X is used, we'll see information about parsing the squid.conf file and the actions taken by Squid, based on the configuration directives encountered. Let's see a sample output produced when option -X is used:

2010/07/21 21:50:51.515| Processing: 'acl my_machines src'
2010/07/21 21:50:51.515| ACL::Prototype::Registered: invoked for type src
2010/07/21 21:50:51.515| ACL::Prototype::Registered: yes
2010/07/21 21:50:51.515| ACL::FindByName 'my_machines'
2010/07/21 21:50:51.515| ACL::FindByName found no match
2010/07/21 21:50:51.515| aclParseAclLine: Creating ACL 'my_machines'
2010/07/21 21:50:51.515| ACL::Prototype::Factory: cloning an object for type 'src'
2010/07/21 21:50:51.515| aclParseIpData:
2010/07/21 21:50:51.515| aclParseIpData:
2010/07/21 21:50:51.515| aclParseIpData:
2010/07/21 21:50:51.515| aclParseIpData:
2010/07/21 21:50:51.515| aclParseIpData:

Let's see what this output means. In the first line, Squid encountered a line defining an ACL my_machines. The next few lines in the output describe Squid invoking different methods to parse, creating a new ACL, and then assigning values to it. This option can be very helpful while debugging ambiguous ACLs.

Running as a normal process

Sometime during testing, we may not want Squid to run as a daemon. Instead, we may want it to run as a normal process which we can interrupt easily by pressing CTRL-C. To achieve this, we can use the option -N. When this option is used, Squid will not run in the background it will run in the current shell instead.

Parsing the Squid configuration file for errors or warnings

It's a good idea to parse or check the configuration file (squid.conf) for any errors or warnings before we actually try to run Squid, or reload a Squid process which is already running in a production deployment. Squid provides an option -k with an argument parse, which, if supplied, will force Squid to parse the current Squid configuration file and report any errors and warnings. Squid -k is also used to check and report directive and option changes when we upgrade our Squid version.



        Read more about this book      

(For more resources on Proxy Servers, see here.)

Time for action – testing our configuration file

As we learned before, we can use the -k parse option to test our configuration file. Now, we are going to add a test line and see if Squid can catch the error.

  1. For example, let's add the following line to our squid.conf file:
    unknown_directive 1234
  2. Now we'll run Squid with the -k parse option as follows:
    squid -k parse
  3. As unknown_directive is not a valid directive for the Squid configuration file, we should get an error similar to the following:
    2010/07/21 22:28:40| cache_cf.cc(346) squid.conf:945 unrecognized: 'unknown_directive'

So, if we find an error within our configuration file, we can go back and fix the errors and then parse the configuration file again.

What just happened?

We first added an invalid line in to our configuration file and then tried to parse it using a squid command which resulted in an error. It is a good idea to always parse the configuration file before starting Squid.

Sending various signals to a running Squid process

Squid provides the -k option to send various signals to a Squid process which is already running. Using this option, we can send various management signals such as, reload the configuration file, rotate the log files, shut down the proxy server, switch to debug mode, and many more. Let's have a look at some of the important signals which are available.

Please note that when the argument parse is used with the option -k, no signal is sent to the running Squid process.

Reloading a new configuration file in a running process

We may need to make changes to our Squid configuration file sometimes, even when it is deployed in production mode. In such cases, after making changes, we don't want to restart our proxy server because that will introduce a significant downtime and will also interrupt active connections between clients and remote servers. In these situations, we can use the option -k with reconfigure as an argument, to signal Squid to re-read the configuration file and apply the new settings:

squid -k reconfigure

The previous command will force Squid to re-read the configuration file, while serving the requests normally and not terminating any active connections.

It's good practice to parse the configuration file for any errors or warning using the -k parse option before issuing the reconfigure signal.

Shutting down the Squid process

To shut down a Squid process which is already running, we can issue a shutdown signal with the help of the option -k as follows:

squid -k shutdown

Squid tries to terminate connections gracefully when it receives a shutdown signal. It will allow the active connection to finish before the process is completely shut down or terminated.

Interrupting or killing a running Squid process

If we have a lot of clients, Squid can take a significant amount of time before it completely terminates itself on receiving the -k shutdown signal. To get Squid to immediately stop serving requests, we can use the -k interrupt signal. The -k interrupt signal will not allow Squid to wait for active connections to finish and will stop the process immediately.

In some cases, the Squid process may not be stopped using -k shutdown or -k interrupt signals. If we want to terminate the process immediately, we can issue a -k kill signal, which will immediately kill the process. This signal should only be used when Squid can't be stopped with -k shutdown or -k interrupt. For example, to send a -k kill signal to Squid, we can use the following command:

squid -k kill

This command will kill the Squid process immediately.

Please note that shutdown, interrupt, and kill are Squid signals and not the system kill signals which are emulated.

Checking the status of a running Squid process

To know whether a Squid process is already running or not, we can issue a check signal which will tell us the status of the Squid process. Squid will also validate the configuration file and report any fatal problems. If the Squid process is running fine, the following command will exit without printing anything:

squid -k check

Otherwise, if the process has exited, this command will give an error similar to the following error message:

squid: ERROR: Could not send signal 0 to process 25243: (3) No such process

Have a go hero – check the return value

After running squid -k check, find out the return value or status in scenarios when:

  • Squid was running
  • Squid was not running

Solution: The return value or the status of a command can be found out by using the command echo $?. This will print the return status or value of the previous command that was executed in the same shell. Return values should be (1) -> 0, (2) -> 1.

Sending a running process in to debug mode

If we didn't start Squid in debug mode and for testing we don't want to stop an already running Squid process, we can issue a debug signal which will send the already running process into debug mode. The debugging output will then be written to Squid's cache.log file located at ${prefix}/var/logs/cache.log or /var/log/squid/cache.log.

The Squid process running in debug mode may write a log of debugging output to the cache.log file and may quickly consume a lot of disk space.

Rotating the log files

The log files used by Squid grow in size over a period of time and can consume a significant amount of disk space. To get rid of the older logs, Squid provides a rotate signal that can be issued when we want to rotate the existing log files. Upon receiving this signal, Squid will close the current log files, move them to other filenames, or delete them based on the configuration directive logfile_rotate (in squid.conf) then reopen the files to write the logs.

It's quite inconvenient to rotate log files manually. So, we can automate the process of log file rotation with the help of a cron job. Let's say we want to rotate the log files at midnight, the corresponding cron tab entry will be:

59 23 * * * /opt/squid/sbin/squid -k rotate

Please note that the path to Squid executable may differ depending on the installation prefix.

Forcing the storage metadata to rebuild

When Squid starts, it tries to load the storage metadata. If Squid fails to load the storage metadata, then it will try to rebuild it. If it receives any requests during that period, Squid will try to satisfy those requests in parallel, which results in slow rebuild. We can force Squid to rebuild the metadata before it starts processing any requests using the option -F on the command line. This may result in a quick rebuild of storage metadata but clients may have to wait for a significant time, if the cache is large. For large caches, we should try to avoid this option:

squid -F

Squid will now rebuild the cache metadata and will not serve any client requests until the metadata rebuild process is complete.

Double checking swap during rebuild

The option -F determines whether Squid should serve requests while the storage metadata is being rebuilt. We have another option, -S, which can be used to force Squid to double check the cache during rebuild. If we use the -S option along with the option -d as follows:

squid -S -d 1

This will produce a debugging output on the terminal which will look similar to the following:

2010/07/21 21:29:22| Beginning Validation Procedure
2010/07/21 21:29:22| UFSSwapDir::doubleCheck: SIZE MISMATCH
2010/07/21 21:29:22| UFSSwapDir::doubleCheck: ENTRY SIZE: 1332, FILE SIZE: 114
2010/07/21 21:29:22| UFSSwapDir::dumpEntry: FILENO 00000092
2010/07/21 21:29:22| UFSSwapDir::dumpEntry: PATH /squid_cache/00/00/00000092
2010/07/21 21:29:22| StoreEntry->key: 0060E9E547F3A1AAEEDE369C5573F8D9
2010/07/21 21:29:22| StoreEntry->next: 0
2010/07/21 21:29:22| StoreEntry->mem_obj: 0
2010/07/21 21:29:22| StoreEntry->timestamp: 1248375049
2010/07/21 21:29:22| StoreEntry->lastref: 1248375754
2010/07/21 21:29:22| StoreEntry->expires: 1279911049
2010/07/21 21:29:22| StoreEntry->lastmod: 1205097338
2010/07/21 21:29:22| StoreEntry->swap_file_sz: 1332
2010/07/21 21:29:22| StoreEntry->refcount: 1
2010/07/21 21:29:22| StoreEntry->flags: CACHABLE,DISPATCHED
2010/07/21 21:29:22| StoreEntry->swap_dirn: 0
2010/07/21 21:29:22| StoreEntry->swap_filen: 146
2010/07/21 21:29:22| StoreEntry->lock_count: 0
2010/07/21 21:29:22| StoreEntry->mem_status: 0

Squid is basically trying to validate each and every cached object on the disk.

Automatically starting Squid at system startup

Once we have a properly configured and running proxy server, we would like it to start whenever the system is started or rebooted. Next, we'll have a brief look at the most common ways of adding or modifying the boot scripts for popular operating systems. These methods will most probably work on your operating system. If they don't, please refer to the corresponding operating system manual for information on boot scripts.

Adding Squid command to /etc/rc.local file

Adding the full path of the Squid executable file is the easiest way to start Squid on system startup. The file /etc/rc.local is executed after the system boots as the super or root user. We can place the Squid command in this file and it will run every time the system boots up. Add the following line at the end of the /etc/rc.local file:


Please replace ${prefix} with the installation prefix which you used before compiling Squid.

Adding init script

Alternatively, we can add a simple init script which will be a simple shell script to start the Squid process or send various signals to a running Squid process. Init scripts are supported by most operating systems and are generally located at /etc/init.d/, /etc/rc.d/, or /etc/rc.d/init.d/. Any shell script placed in any of these directories is executed at system startup with root privileges.

Time for action – adding the init script

We are going to use a simple shell script, as shown in the following example, which takes a single command line argument and acts accordingly:

# init script to control Squid server
case "$1" in


/opt/squid/sbin/squid -k shutdown

/opt/squid/sbin/squid -k reconfigure

/opt/squid/sbin/squid -k shutdown
sleep 2

echo $"Usage: $0 {start|stop|reload|restart}"
exit 2
exit $?

Please note the absolute path to the Squid executable here and change it accordingly. We can save this shell script to a file with the name squid and then move it to one of the directories we discussed earlier depending on our operating system.

The Squid source carries an init script located at contrib/squid.rc, but it's installed only on a few systems by default.

What just happened?

We added an init script to control the Squid proxy server. Using this script, we can start, stop, restart, or reload the process. It's important that the script is placed in the correct directory, otherwise the Squid proxy server will not start on system startup.


In this article, we learned about the various command line options which can be used while running Squid, how to start the Squid process in a different mode, and how to send signals to a process which is already running. We also learned about creating new cache directories after adding them to the Squid configuration file.

We specifically covered the following:

  • Parsing the Squid configuration file for errors and warnings.
  • Using various options to get suitable debugging outputs while testing.
  • Reloading a new configuration in a Squid process which is already running, without interrupting service.
  • Automatic rotation of log files to recover disk space.

Further resources on this subject:

You've been reading an excerpt of:

Squid Proxy Server 3.1: Beginner's Guide

Explore Title
comments powered by Disqus