Squid Description

squid is a high-performance proxy caching server for web clients, supporting FTP, gopher, ICAP, ICP, HTCP and HTTP data objects. Unlike traditional caching software, Squid handles all requests in a single, non-blocking process.

Squid keeps meta data and especially hot objects cached in RAM, caches DNS lookups, supports non-blocking DNS lookups, and implements negative caching of failed requests.

Squid supports SSL, extensive access controls, and full request logging. By using the lightweight Internet Cache Protocols ICP, HTCP or CARP, Squid caches can be arranged in a hierarchy or mesh for additional bandwidth savings.

Squid consists of a main server program squid, some optional programs for custom processing and authentication, and some management and client tools. When squid starts up, it spawns a configurable number of helper processes, each of which can perform parallel lookups. This reduces the amount of time the cache waits for results.

Squid is derived from the ARPA-funded Harvest Project.

Squid reduces bandwidth and improves response times by caching and reusing frequently-requested web pages. Squid has extensive access controls and makes a great server accelerator. It runs on most available operating systems, including Windows and is licensed under the GNU GPL.

Making the most of your Internet Connection

Squid is used by hundreds of Internet Providers world-wide to provide their users with the best possible web access. Squid optimises the data flow between client and server to improve performance and caches frequently-used content to save bandwidth. Squid can also route content requests to servers in a wide variety of ways to build cache server hierarchies which optimise network throughput.

Website Content Acceleration and Distribution

Thousands of web-sites around the Internet use Squid to drastically increase their content delivery. Squid can reduce your server load and improve delivery speeds to clients. Squid can also be used to deliver content from around the world - copying only the content being used, rather than inefficiently copying everything. Finally, Squid's advanced content routing configuration allows you to build content clusters to route and load balance requests via a variety of web servers.

The Squid systems are currently running at a hit-rate of approximately 75%, effectively quadrupling the capacity of the Apache servers behind them. This is particularly noticeable when a large surge of traffic arrives directed to a particular page via a web link from another site, as the caching efficiency for that page will be nearly 100%.

Homepage: http://www.squid-cache.org/

GitHub: https://github.com/squid-cache/squid/

Authors: Duane Wessels, Henrik Nordstrom, Amos Jeffries and many more

License: GPLv2

Squid Help


squid [-cdzCFNRVYX] [-n name] [-s | -l facility] [-f config-file] [-[au] port] [-k signal]


    -h | --help       Print help message.
    -v | --version    Print version details.

       -a port   Specify HTTP port number (default: 3128).
       -d level  Write debugging to stderr also.
       -f file   Use given config-file instead of
       -k reconfigure|rotate|shutdown|restart|interrupt|kill|debug|check|parse
                 Parse configuration file, then send signal to 
                 running copy (except -k parse) and exit.
       -n name   Specify service name to use for service operations
                 default is: squid.
       -s | -l facility
                 Enable logging to syslog.
       -u port   Specify ICP port number (default: 3130), disable with 0.
       -z        Create missing swap directories and then exit.
       -C        Do not catch fatal signals.
       -D        OBSOLETE. Scheduled for removal.
       -F        Don't serve any requests until store is rebuilt.
       -N        Master process runs in foreground and is a worker. No kids.
                 Master process runs in foreground and creates worker kids.
       --kid role-ID
                 Play a given SMP kid process role, with a given ID. Do not use
                 this option. It is meant for the master process use only.
       -R        Do not set REUSEADDR on port.
       -S        Double-check swap during rebuild.
       -X        Force full debugging.
       -Y        Only return UDP_HIT or UDP_MISS_NOFETCH during fast reload.

Options specific to the Windows version of Squid:

       -i          Install as a Windows Service (see -n option).
       -n name     Specify Windows Service name to use for service operations, default is: Squid
       -O options  Set Windows Service Command line options in Registry.

       -r          Remove a Windows Service (see -n option).

Squid manual

Explanation of some options

-a port

Specify HTTP port number where Squid should listen for requests, in addition to any http_port specifications in squid.conf

-f file

Use the given config-file instead of /etc/squid/squid.conf . If the file name starts with a ! or | then it is assumed to be an external command or command line.

Can for example be used to pre-process the configuration before it is being read by Squid. To facilitate this Squid also understands the common #line notion to indicate the real source file.

-k reconfigure | rotate | shutdown | interrupt | kill | debug | check | parse

Parse configuration file, then send signal to running copy (except -k parse ) and exit.


facility Use specified syslog facility. Implies -s


Enable logging to syslog. Also configurable in /etc/squid/squid.conf


No daemon mode.


Parent process does not exit until its children have finished. It has no effect with -N which does not fork/exit at startup.


Create missing swap directories and other missing cache_dir structures, then exit. All cache_dir types create the configured top-level directory if it is missing.

Other actions are type-specific. For example, ufs-based storage systems create missing L1 and L2 directories while Rock creates the missing database file.

This option does not enable validation of any present swap structures. Its focus is on creation of missing pieces. If nothing is missing, squid -z just exits. If you suspect cache_dir corruption, you must delete the top-level cache_dir directory before running squid -z.

By default, squid -z runs in daemon mode (so that configuration macros and other SMP features work as expected), returning control to the caller before cache_dirs are fully initialized. If run from init scripts or daemon managers, the caller often needs to wait for the initialization to complete before proceeding further. Use --foreground option to prevent premature exits. To disable daemon mode, use -N option.

Squid files

Squid configuration files located in /etc/squid/:


The main configuration file. You must initially make changes to this file for squid to work. For example, the default configuration only allows access from RFC private LAN networks. Some packaging distributions block even that.


Reference copy of the configuration file. Always kept up to date with the version of Squid you are using.

Use this to look up the default configuration settings and syntax after upgrading.


Reference copy of the configuration file. Always kept up to date with the version of Squid you are using.

Use this to read the documentation for configuration options available in your build of Squid. The online configuration manual is also available for a full reference of options. seehttp://www.squid-cache.org/Doc/config/


The main configuration file for the web cachemgr.cgi tools.


The main configuration file for the Sample MSNT authenticator.


CSS Stylesheet to control the display of generated error pages. Use this to set any company branding you need, it will apply to every language Squid provides error pages for.

Some files also located elsewhere:

/etc/squid/mime.conf (mime_table)

MIME type mappings for FTP gatewaying


Location of Squid error pages and templates.

Squid Proxy Documentation

Squid proxy documentation is located at: http://www.squid-cache.org/Doc/config/

The following is a description of only some of the most commonly used directives. For full documentation, see the link above.

Options for authentication


Default Value: none

Suggested Config:

#auth_param negotiate program <uncomment and complete this line to activate>
#auth_param negotiate children 20 startup=0 idle=1
#auth_param digest program <uncomment and complete this line to activate>
#auth_param digest children 20 startup=0 idle=1
#auth_param digest realm Squid proxy-caching web server
#auth_param digest nonce_garbage_interval 5 minutes
#auth_param digest nonce_max_duration 30 minutes
#auth_param digest nonce_max_count 50
#auth_param ntlm program <uncomment and complete this line to activate>
#auth_param ntlm children 20 startup=0 idle=1
#auth_param basic program <uncomment and complete this line>
#auth_param basic children 5 startup=5 idle=1
#auth_param basic credentialsttl 2 hours

This is used to define parameters for the various authentication schemes supported by Squid.

format: auth_param scheme parameter [setting]

The order in which authentication schemes are presented to the client is dependent on the order the scheme first appears in config file. IE has a bug (it's not RFC 2617 compliant) in that it will use the basic scheme if basic is the first entry presented, even if more secure schemes are presented. For now use the order in the recommended settings section below. If other browsers have difficulties (don't recognize the schemes offered even if you are using basic) either put basic first, or disable the other schemes (by commenting out their program entry).

Once an authentication scheme is fully configured, it can only be shutdown by shutting squid down and restarting. Changes can be made on the fly and activated with a reconfigure. I.E. You can change to a different helper, but not unconfigure the helper completely.

Please note that while this directive defines how Squid processes authentication it does not automatically activate authentication. To use authentication you must in addition make use of ACLs based on login name in http_access (proxy_auth, proxy_auth_regex or external with %LOGIN used in the format tag). The browser will be challenged for authentication on the first such acl encountered in http_access processing and will also be re-challenged for new login credentials if the request is being denied by a proxy_auth type acl.

WARNING: authentication can't be used in a transparently intercepting proxy as the client then thinks it is talking to an origin server and not the proxy. This is a limitation of bending the TCP/IP protocol to transparently intercepting port 80, not a limitation in Squid. Ports flagged 'transparent', 'intercept', or 'tproxy' have authentication disabled.

=== Parameters common to all schemes. ===

"program" cmdline

Specifies the command for the external authenticator.

By default, each authentication scheme is not used unless a program is specified.

See http://wiki.squid-cache.org/Features/AddonHelpers for more details on helper operations and creating your own.

"key_extras" format

Specifies a string to be append to request line format for the authentication helper. "Quoted" format values may contain spaces and logformat %macros. In theory, any logformat %macro can be used. In practice, a %macro expands as a dash (-) if the helper request is sent before the required macro information is available to Squid.

By default, Squid uses request formats provided in scheme-specific examples below (search for %credentials).

The expanded key_extras value is added to the Squid credentials cache and, hence, will affect authentication. It can be used to autenticate different users with identical user names (e.g., when user authentication depends on http_port).

Avoid adding frequently changing information to key_extras. For example, if you add user source IP, and it changes frequently in your environment, then max_user_ip ACL is going to treat every user+IP combination as a unique "user", breaking the ACL and wasting a lot of memory on those user records. It will also force users to authenticate from scratch whenever their IP changes.

"realm" string

Specifies the protection scope (aka realm name) which is to be reported to the client for the authentication scheme. It is commonly part of the text the user will see when prompted for their username and password.

For Basic the default is "Squid proxy-caching web server".

For Digest there is no default, this parameter is mandatory.

For NTLM and Negotiate this parameter is ignored.

"children" numberofchildren [startup=N] [idle=N] [concurrency=N] [queue-size=N] [on-persistent-overload=action] [reservation-timeout=seconds]

The maximum number of authenticator processes to spawn. If you start too few Squid will have to wait for them to process a backlog of credential verifications, slowing it down. When password verifications are done via a (slow) network you are likely to need lots of authenticator processes.

The startup= and idle= options permit some skew in the exact amount run. A minimum of startup=N will begin during startup and reconfigure. Squid will start more in groups of up to idle=N in an attempt to meet traffic needs and to keep idle=N free above those traffic needs up to the maximum.

The concurrency= option sets the number of concurrent requests the helper can process. The default of 0 is used for helpers who only supports one request at a time. Setting this to a number greater than 0 changes the protocol used to include a channel ID field first on the request/response line, allowing multiple requests to be sent to the same helper in parallel without waiting for the response.

Concurrency must not be set unless it's known the helper supports the input format with channel-ID fields.

The queue-size option sets the maximum number of queued requests. A request is queued when no existing child can accept it due to concurrency limit and no new child can be started due to numberofchildren limit. The default maximum is 2*numberofchildren. Squid is allowed to temporarily exceed the configured maximum, marking the affected helper as "overloaded". If the helper overload lasts more than 3 minutes, the action prescribed by the on-persistent-overload option applies.

The on-persistent-overload=action option specifies Squid reaction to a new helper request arriving when the helper has been overloaded for more that 3 minutes already. The number of queued requests determines whether the helper is overloaded (see the queue-size option).

Two actions are supported:


Squid worker quits. This is the default behavior.


Squid treats the helper request as if it was immediately submitted, and the helper immediately replied with an ERR response. This action has no effect on the already queued and in-progress helper requests.

NOTE: NTLM and Negotiate schemes do not support concurrency in the Squid code module even though some helpers can.

The reservation-timeout=seconds option allows NTLM and Negotiate helpers to forget about clients that abandon their in-progress connection authentication without closing the connection. The timeout is measured since the last helper response received by Squid for the client. Fractional seconds are not supported.

After the timeout, the helper will be used for other clients if there are no unreserved helpers available. In the latter case, the old client attempt to resume authentication will not be forwarded to the helper (and the client should open a new HTTP connection and retry authentication from scratch).

By default, reservations do not expire and clients that keep their connections open without completing authentication may exhaust all NTLM and Negotiate helpers.

"keep_alive" on|off

If you experience problems with PUT/POST requests when using the NTLM or Negotiate schemes then you can try setting this to off. This will cause Squid to forcibly close the connection on the initial request where the browser asks which schemes are supported by the proxy.

For Basic and Digest this parameter is ignored.

"utf8" on|off

Useful for sending credentials to authentication backends that expect UTF-8 encoding (e.g., LDAP).

When this option is enabled, Squid uses HTTP Accept-Language request header to guess the received credentials encoding (ISO-Latin-1, CP1251, or UTF-8) and then converts the first two encodings into UTF-8.

When this option is disabled and by default, Squid sends credentials in their original (i.e. received) encoding.

This parameter is only honored for Basic and Digest schemes. For Basic, the entire username:password credentials are checked and, if necessary, re-encoded. For Digest -- just the username component. For NTLM and Negotiate schemes, this parameter is ignored.

=== Basic authentication parameters ===

"credentialsttl" timetolive

Specifies how long squid assumes an externally validated username:password pair is valid for - in other words how often the helper program is called for that user. Set this low to force revalidation with short lived passwords.

NOTE: setting this high does not impact your susceptibility to replay attacks unless you are using an one-time password system (such as SecureID). If you are using such a system, you will be vulnerable to replay attacks unless you also use the max_user_ip ACL in an http_access rule.

"casesensitive" on|off

Specifies if usernames are case sensitive. Most user databases are case insensitive allowing the same username to be spelled using both lower and upper case letters, but some are case sensitive. This makes a big difference for user_max_ip ACL processing and similar.

=== Digest authentication parameters ===

"nonce_garbage_interval" timeinterval

Specifies the interval that nonces that have been issued to client_agent's are checked for validity.

"nonce_max_duration" timeinterval

Specifies the maximum length of time a given nonce will be valid for.

"nonce_max_count" number

Specifies the maximum number of times a given nonce can be used.

"nonce_strictness" on|off

Determines if squid requires strict increment-by-1 behavior for nonce counts, or just incrementing (off - for use when user agents generate nonce counts that occasionally miss 1 (ie, 1,2,4,6)). Default off.

"check_nonce_count" on|off

This directive if set to off can disable the nonce count check completely to work around buggy digest qop implementations in certain mainstream browser versions. Default on to check the nonce count to protect from authentication replay attacks.

"post_workaround" on|off

This is a workaround to certain buggy browsers who send an incorrect request digest in POST requests when reusing the same nonce as acquired earlier on a GET request.

=== Example Configuration ===

This configuration displays the recommended authentication scheme order from most to least secure with recommended minimum configuration settings for each scheme:

auth_param negotiate program <uncomment and complete this line to activate>
auth_param negotiate children 20 startup=0 idle=1
auth_param negotiate keep_alive on

auth_param digest program <uncomment and complete this line to activate>
auth_param digest children 20 startup=0 idle=1
auth_param digest realm Squid proxy-caching web server
auth_param digest nonce_garbage_interval 5 minutes
auth_param digest nonce_max_duration 30 minutes
auth_param digest nonce_max_count 50

auth_param ntlm program <uncomment and complete this line to activate>
auth_param ntlm children 20 startup=0 idle=1
auth_param ntlm keep_alive on

auth_param basic program <uncomment and complete this line>
auth_param basic children 5 startup=5 idle=1
auth_param basic realm Squid proxy-caching web server
auth_param basic credentialsttl 2 hours

Access controls


Default Value: ACLs all, manager, localhost, to_localhost, and CONNECT are predefined.

Suggested Config:

Recommended minimum configuration:

# Example rule allowing access from your local networks.
# Adapt to list your (internal) IP networks from where browsing
# should be allowed
acl localnet src	# RFC 1122 "this" network (LAN)
acl localnet src		# RFC 1918 local private network (LAN)
acl localnet src		# RFC 6598 shared address space (CGN)
acl localnet src 	# RFC 3927 link-local (directly plugged) machines
acl localnet src		# RFC 1918 local private network (LAN)
acl localnet src		# RFC 1918 local private network (LAN)
acl localnet src fc00::/7       	# RFC 4193 local private network range
acl localnet src fe80::/10      	# RFC 4291 link-local (directly plugged) machines

acl SSL_ports port 443
acl Safe_ports port 80		# http
acl Safe_ports port 21		# ftp
acl Safe_ports port 443		# https
acl Safe_ports port 70		# gopher
acl Safe_ports port 210		# wais
acl Safe_ports port 1025-65535	# unregistered ports
acl Safe_ports port 280		# http-mgmt
acl Safe_ports port 488		# gss-http
acl Safe_ports port 591		# filemaker
acl Safe_ports port 777		# multiling http

Defining an Access List

Every access list definition must begin with an aclname and acltype, followed by either type-specific arguments or a quoted filename that they are read from.

acl aclname acltype argument ...
acl aclname acltype "file" ...

When using "file", the file should contain one item per line.

ACL Options

Some acl types supports options which changes their default behaviour:


By default, regular expressions are CASE-SENSITIVE. To make them case-insensitive, use the -i option. To return case-sensitive use the +i option between patterns, or make a new ACL line without -i.


Disable lookups and address type conversions. If lookup or conversion is required because the parameter type (IP or domain name) does not match the message address type (domain name or IP), then the ACL would immediately declare a mismatch without any warnings or lookups.


Perform a list membership test, interpreting values as comma-separated token lists and matching against individual tokens instead of whole values.

The optional "delimiters" parameter specifies one or more alternative non-alphanumeric delimiter characters.


Used to stop processing all options, in the case the first acl value has '-' character as first character (for example the '-' is a valid domain name)

Some acl types require suspending the current request in order to access some external data source. Those which do are marked with the tag [slow], those which don't are marked as [fast]. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for further information


acl aclname src ip-address/mask …

clients IP address [fast]

acl aclname src addr1-addr2/mask …

range of addresses [fast]

acl aclname dst [-n] ip-address/mask …

URL host's IP address [slow]

acl aclname localip ip-address/mask … 

IP address the client connected to [fast]

acl aclname arp

mac-address …

acl aclname eui64

eui64-address … [fast]

MAC (EUI-48) and EUI-64 addresses use xx:xx:xx:xx:xx:xx notation.

The 'arp' ACL code is not portable to all operating systems.

It works on Linux, Solaris, Windows, FreeBSD, and some other BSD variants.

The eui_lookup directive is required to be 'on' (the default) and Squid built with --enable-eui for MAC/EUI addresses to be available for this ACL.

Squid can only determine the MAC/EUI address for IPv4 clients that are on the same subnet. If the client is on a different subnet, then Squid cannot find out its address.

IPv6 protocol does not contain ARP. MAC/EUI is either encoded directly in the IPv6 address or not available.

acl aclname clientside_mark mark[/mask] …

matches CONNMARK of an accepted connection [fast]

DEPRECATED. Use the 'client_connection_mark' instead.

acl aclname client_connection_mark mark[/mask] …

matches CONNMARK of an accepted connection [fast]

mark and mask are unsigned integers (hex, octal, or decimal). If multiple marks are given, then the ACL matches if at least one mark matches.

Uses netfilter-conntrack library.

Requires building Squid with --enable-linux-netfilter.

The client, various intermediaries, and Squid itself may set CONNMARK at various times. The last CONNMARK set wins. This ACL checks the mark present on an accepted connection or set by Squid afterwards, depending on the ACL check timing. This ACL effectively ignores any mark set by other agents after Squid has accepted the connection.

acl aclname srcdomain .foo.com …

reverse lookup, from client IP [slow]

acl aclname dstdomain [-n] .foo.com …

Destination server from URL [fast]

acl aclname srcdom_regex [-i] \.foo\.com …

regex matching client name [slow]

acl aclname dstdom_regex [-n] [-i] \.foo\.com …

regex matching server [fast]

For dstdomain and dstdom_regex a reverse lookup is tried if a IP based URL is used and no match is found. The name "none" is used if the reverse lookup fails.

acl aclname src_as number …

acl aclname dst_as number …


Except for access control, AS numbers can be used for routing of requests to specific caches. Here's an example for routing all requests for AS#1241 and only those to mycache.mydomain.net:

acl asexample dst_as 1241
cache_peer_access mycache.mydomain.net allow asexample
cache_peer_access mycache_mydomain.net deny all

acl aclname peername myPeer …

acl aclname peername_regex [-i] regex-pattern …


match against a named cache_peer entry

set unique name= on cache_peer lines for reliable use.

acl aclname time [day-abbrevs] [h1:m1-h2:m2]



  • S - Sunday
  • M - Monday
  • T - Tuesday
  • W - Wednesday
  • H - Thursday
  • F - Friday
  • A - Saturday

h1:m1 must be less than h2:m2

acl aclname url_regex [-i] ^http:// …

regex matching on whole URL [fast]

acl aclname urllogin [-i] [^a-zA-Z0-9] …

regex matching on URL login field

acl aclname urlpath_regex [-i] \.gif$ …

regex matching on URL path [fast]

acl aclname port 80 70 21 0-1024…

destination TCP port [fast]

ranges are allowed

acl aclname localport 3128 …

TCP port the client connected to [fast]

NP: for interception mode this is usually '80'

acl aclname myportname 3128 …

*_port name [fast]

acl aclname proto HTTP FTP …

request protocol [fast]

acl aclname method GET POST …

HTTP request method [fast]

acl aclname http_status 200 301 500- 400-403 …

status code in reply [fast]

acl aclname browser [-i] regexp …

pattern match on User-Agent header (see also req_header below) [fast]

acl aclname referer_regex [-i] regexp …

pattern match on Referer header [fast]

Referer is highly unreliable, so use with care

acl aclname ident [-i] username …

acl aclname ident_regex [-i] pattern …

string match on ident output [slow]

use REQUIRED to accept any non-null ident.

acl aclname proxy_auth [-i] username …

acl aclname proxy_auth_regex [-i] pattern …

perform http authentication challenge to the client and match against supplied credentials [slow]

takes a list of allowed usernames.

use REQUIRED to accept any valid username.

Will use proxy authentication in forward-proxy scenarios, and plain http authentication in reverse-proxy scenarios

NOTE: when a Proxy-Authentication header is sent but it is not needed during ACL checking the username is NOT logged in access.log.

NOTE: proxy_auth requires a EXTERNAL authentication program to check username/password combinations (see auth_param directive).

NOTE: proxy_auth can't be used in a transparent/intercepting proxy as the browser needs to be configured for using a proxy in order to respond to proxy authentication.

acl aclname snmp_community string …

A community string to limit access to your SNMP Agent [fast]


acl snmppublic snmp_community public

acl aclname maxconn number

This will be matched when the client's IP address has more than <number> TCP connections established. [fast]

NOTE: This only measures direct TCP links so X-Forwarded-For indirect clients are not counted.

acl aclname max_user_ip [-s] number

This will be matched when the user attempts to log in from more than <number> different ip addresses. The authenticate_ip_ttl parameter controls the timeout on the ip entries. [fast] If -s is specified the limit is strict, denying browsing from any further IP addresses until the ttl has expired. Without -s Squid will just annoy the user by "randomly" denying requests (the counter is reset each time the limit is reached and a request is denied).

NOTE: in acceleration mode or where there is mesh of child proxies, clients may appear to come from multiple addresses if they are going through proxy farms, so a limit of 1 may cause user problems.

acl aclname random probability

Pseudo-randomly match requests. Based on the probability given.

Probability may be written as a decimal (0.333), fraction (1/3) or ratio of matches:non-matches (3:5).

acl aclname req_mime_type [-i] mime-type …

regex match against the mime type of the request generated by the client. Can be used to detect file upload or some types HTTP tunneling requests [fast]

NOTE: This does NOT match the reply. You cannot use this to match the returned file type.

acl aclname req_header header-name [-i] any\.regex\.here

regex match against any of the known request headers. May be thought of as a superset of "browser", "referer" and "mime-type" ACL [fast]

acl aclname rep_mime_type [-i] mime-type …

regex match against the mime type of the reply received by squid. Can be used to detect file download or some types HTTP tunneling requests. [fast]

NOTE: This has no effect in http_access rules. It only has effect in rules that affect the reply data stream such as http_reply_access.

acl aclname rep_header header-name [-i] any\.regex\.here

regex match against any of the known reply headers. May be thought of as a superset of "browser", "referer" and "mime-type" ACLs [fast]

acl aclname external class_name [arguments…]

external ACL lookup via a helper class defined by the external_acl_type directive [slow]

acl aclname user_cert attribute values…

match against attributes in a user SSL certificate attribute is one of DN/C/O/CN/L/ST or a numerical OID [fast]

acl aclname ca_cert attribute values…

match against attributes a users issuing CA SSL certificate attribute is one of DN/C/O/CN/L/ST or a numerical OID [fast]

acl aclname ext_user [-i] username …

acl aclname ext_user_regex [-i] pattern …

string match on username returned by external acl helper [slow]

use REQUIRED to accept any non-null user name.

acl aclname tag tagvalue …

string match on tag returned by external acl helper [fast]

DEPRECATED. Only the first tag will match with this ACL. Use the 'note' ACL instead for handling multiple tag values.

acl aclname hier_code codename …

string match against squid hierarchy code(s); [fast]


NOTE: This has no effect in http_access rules. It only has effect in rules that affect the reply data stream such as http_reply_access.

acl aclname note [-m[=delimiters]] name [value …]

match transaction annotation [fast]

Without values, matches any annotation with a given name.

With value(s), matches any annotation with a given name that also has one of the given values.

If the -m flag is used, then the value of the named annotation is interpreted as a list of tokens, and the ACL matches individual name=token pairs rather than whole name=value pairs. See "ACL Options" above for more info.

Annotation sources include note and adaptation_meta directives as well as helper and eCAP responses.

acl aclname annotate_transaction [-m[=delimiters]] key=value …

acl aclname annotate_transaction [-m[=delimiters]] key+=value …

Always matches. [fast]

Used for its side effect: This ACL immediately adds a key=value annotation to the current master transaction.

The added annotation can then be tested using note ACL and logged (or sent to helpers) using %note format code.

Annotations can be specified using replacement and addition formats. The key=value form replaces old same-key annotation value(s). The key+=value form appends a new value to the old same-key annotation. Both forms create a new key=value annotation if no same-key annotation exists already. If -m flag is used, then the value is interpreted as a list and the annotation will contain key=token pair(s) instead of the whole key=value pair.

This ACL is especially useful for recording complex multi-step ACL-driven decisions. For example, the following configuration avoids logging transactions accepted after aclX matched:

First, mark transactions accepted after aclX matched

acl markSpecial annotate_transaction special=true
http_access allow acl001
http_access deny acl100
http_access allow aclX markSpecial

Second, do not log marked transactions:

acl markedSpecial note special true
access_log ... deny markedSpecial

Note that the following would not have worked because aclX alone does not determine whether the transaction was allowed:

access_log ... deny aclX # Wrong!

Warning: This ACL annotates the transaction even when negated and even if subsequent ACLs fail to match. For example, the following three rules will have exactly the same effect as far as annotations set by the "mark" ACL are concerned:

some_directive acl1 ... mark # rule matches if mark is reached
some_directive acl1 ... !mark # rule never matches
some_directive acl1 ... mark !all # rule never matches

acl aclname annotate_client [-m[=delimiters]] key=value …

acl aclname annotate_client [-m[=delimiters]] key+=value …

Always matches. [fast]

Used for its side effect: This ACL immediately adds a key=value annotation to the current client-to-Squid connection. Connection annotations are propagated to the current and all future master transactions on the annotated connection.

See the annotate_transaction ACL for details.

For example, the following configuration avoids rewriting URLs of transactions bumped by SslBump:

First, mark bumped connections:

acl markBumped annotate_client bumped=true
ssl_bump peek acl1
ssl_bump stare acl2
ssl_bump bump acl3 markBumped
ssl_bump splice all

Second, do not send marked transactions to the redirector:

acl markedBumped note bumped true
url_rewrite_access deny markedBumped

Note that the following would not have worked because acl3 alone does not determine whether the connection is going to be bumped:

url_rewrite_access deny acl3 # Wrong!

acl aclname adaptation_service service …

Matches the name of any icap_service, ecap_service, adaptation_service_set, or adaptation_service_chain that Squid has used (or attempted to use) for the master transaction. This ACL must be defined after the corresponding adaptation service is named in squid.conf. This ACL is usable with adaptation_meta because it starts matching immediately after the service has been selected for adaptation.

acl aclname transaction_initiator initiator …

Matches transaction's initiator [fast]

Supported initiators are:

  • esi: matches transactions fetching ESI resources certificate-fetching: matches transactions fetching a missing intermediate TLS certificate cache-digest: matches transactions fetching Cache Digests from a cache_peer
  • htcp: matches HTCP requests from peers
  • icp: matches ICP requests to peers
  • icmp: matches ICMP RTT database (NetDB) requests to peers
  • asn: matches asns db requests
  • internal: matches any of the above
  • client: matches transactions containing an HTTP or FTP
  • client request received at a Squid *_port
  • all: matches any transaction, including internal transactions without a configurable initiator and hopefully rare transactions without a known-to-Squid initiator

Multiple initiators are ORed.

acl aclname has component

matches a transaction "component" [fast]

Supported transaction components are:

  • request: transaction has a request header (at least)
  • response: transaction has a response header (at least)

ALE: transaction has an internally-generated Access Log Entry structure; bugs notwithstanding, all transaction have it

For example, the following configuration helps when dealing with HTTP clients that close connections without sending a request header:

acl hasRequest has request
acl logMe note important_transaction
# avoid "logMe ACL is used in context without an HTTP request" warnings
access_log ... logformat=detailed hasRequest logMe
# log request-less transactions, instead of ignoring them
access_log ... logformat=brief !hasRequest

Multiple components are not supported for one "acl" rule, but can be specified (and are ORed) using multiple same-name rules:

# OK, this strange logging daemon needs request or response,
# but can work without either a request or a response:
# acl hasWhatMyLoggingDaemonNeeds has request
# acl hasWhatMyLoggingDaemonNeeds has response

acl aclname at_step step

match against the current request processing step [fast]

Valid steps are:

  • GeneratingCONNECT: Generating HTTP CONNECT request headers
  • The following ssl_bump processing steps are recognized:
  • SslBump1: After getting TCP-level and HTTP CONNECT info.
  • SslBump2: After getting SSL Client Hello info.
  • SslBump3: After getting SSL Server Hello info.

acl aclname ssl_error errorname

match against SSL certificate validation error [fast]

For valid error names see in /usr/local/squid/share/errors/templates/error-details.txt template file.

The following can be used as shortcuts for certificate properties:

  • [ssl::]certHasExpired: the "not after" field is in the past
  • [ssl::]certNotYetValid: the "not before" field is in the future
  • [ssl::]certUntrusted: The certificate issuer is not to be trusted.
  • [ssl::]certSelfSigned: The certificate is self signed.
  • [ssl::]certDomainMismatch: The certificate CN domain does not match the name the name of the host we are connecting to.

The ssl::certHasExpired, ssl::certNotYetValid, ssl::certDomainMismatch, ssl::certUntrusted, and ssl::certSelfSigned can also be used as predefined ACLs, just like the 'all' ACL.

NOTE: The ssl_error ACL is only supported with sslproxy_cert_error, sslproxy_cert_sign, and sslproxy_cert_adapt options.

acl aclname server_cert_fingerprint [-sha1] fingerprint

match against server SSL certificate fingerprint [fast]

The fingerprint is the digest of the DER encoded version of the whole certificate. The user should use the form: XX:XX:…

Optional argument specifies the digest algorithm to use.

The SHA1 digest algorithm is the default and is currently the only algorithm supported (-sha1).

acl aclname ssl::server_name [option] .foo.com …

matches server name obtained from various sources [fast]

The ACL computes server name(s) using such information sources as CONNECT request URI, TLS client SNI, and TLS server certificate subject (CN and SubjectAltName). The computed server name(s) usually change with each SslBump step, as more info becomes available:

  • SNI is used as the server name instead of the request URI,
  • subject name(s) from the server certificate (CN and SubjectAltName) are used as the server names instead of SNI.

When the ACL computes multiple server names, matching any single computed name is sufficient for the ACL to match.

The "none" name can be used to match transactions where the ACL could not compute the server name using any information source that was both available and allowed to be used by the ACL options at the ACL evaluation time.

Unlike dstdomain, this ACL does not perform DNS lookups.

An ACL option below may be used to restrict what information sources are used to extract the server names from:


The server name is SNI regardless of what the server says.


The server name(s) are the certificate subject name(s), regardless of what the client has requested. If the server certificate is unavailable, then the name is "none".


The server name is either SNI (if SNI matches at least one of the certificate subject names) or "none" (otherwise). When the server certificate is unavailable, the consensus server name is SNI.

Combining multiple options in one ACL is a fatal configuration error.

For all options: If no SNI is available, then the CONNECT request target (a.k.a. URI) is used instead of SNI (for an intercepted connection, this target is the destination IP address).

acl aclname ssl::server_name_regex [-i] \.foo\.com …

regex matches server name obtained from various sources [fast]

acl aclname connections_encrypted

matches transactions with all HTTP messages received over TLS transport connections. [fast]

The master transaction deals with HTTP messages received from various sources. All sources used by the master transaction in the past are considered by the ACL. The following rules define whether a given message source taints the entire master transaction, resulting in ACL mismatches:

  • The HTTP client transport connection is not TLS.
  • An adaptation service connection-encryption flag is off.
  • The peer or origin server transport connection is not TLS.

Caching currently does not affect these rules. This cache ignorance implies that only the current HTTP client transport and REQMOD services status determine whether this ACL matches a from-cache transaction. The source of the cached response does not have any effect on future transaction that use the cached response without revalidation. This may change.

DNS, ICP, and HTCP exchanges during the master transaction do not affect these rules.

acl aclname any-of acl1 acl2 …

match any one of the acls [fast or slow]

The first matching ACL stops further ACL evaluation.

ACLs from multiple any-of lines with the same name are ORed.

For example, A = (a1 or a2) or (a3 or a4) can be written as

acl A any-of a1 a2
acl A any-of a3 a4

This group ACL is fast if all evaluated ACLs in the group are fast and slow otherwise.

acl aclname all-of acl1 acl2 …

match all of the acls [fast or slow]

The first mismatching ACL stops further ACL evaluation.

ACLs from multiple all-of lines with the same name are ORed.

For example, B = (b1 and b2) or (b3 and b4) can be written as

acl B all-of b1 b2
acl B all-of b3 b4

This group ACL is fast if all evaluated ACLs in the group are fast and slow otherwise.


acl macaddress arp 09:00:2b:23:45:67
acl myexample dst_as 1241
acl password proxy_auth REQUIRED
acl fileupload req_mime_type -i ^multipart/form-data$
acl javascript rep_mime_type -i ^application/x-javascript$


Default Value: Deny, unless rules exist in squid.conf.

Suggested Config:

# Recommended minimum Access Permission configuration:
# Deny requests to certain unsafe ports
http_access deny !Safe_ports

# Deny CONNECT to other than secure SSL ports
http_access deny CONNECT !SSL_ports

# Only allow cachemgr access from localhost
http_access allow localhost manager
http_access deny manager

# We strongly recommend the following be uncommented to protect innocent
# web applications running on the proxy server who think the only
# one who can access services on "localhost" is a local user
#http_access deny to_localhost


# Example rule allowing access from your local networks.
# Adapt localnet in the ACL section to list your (internal) IP networks
# from where browsing should be allowed
http_access allow localnet
http_access allow localhost

# And finally deny all other access to this proxy
http_access deny all

Allowing or Denying access based on defined access lists

To allow or deny a message received on an HTTP, HTTPS, or FTP port:

http_access allow|deny [!]aclname ...

NOTE on default values:

If there are no "access" lines present, the default is to deny the request.

If none of the "access" lines cause a match, the default is the opposite of the last line in the list. If the last line was deny, the default is allow. Conversely, if the last line is allow, the default will be deny. For these reasons, it is a good idea to have an "deny all" entry at the end of your access lists to avoid potential confusion.

This clause supports both fast and slow acl types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.


Allow replies to client requests. This is complementary to http_access.

http_reply_access allow|deny [!] aclname ...

NOTE: if there are no access lines present, the default is to allow all replies.

If none of the access lines cause a match the opposite of the last line will apply. Thus it is good practice to end the rules with an "allow all" or "deny all" entry.

This clause supports both fast and slow acl types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.


Default Value: Unless rules exist in squid.conf, IDENT is not fetched.

A list of ACL elements which, if matched, cause an ident (RFC 931) lookup to be performed for this request. For example, you might choose to always perform ident lookups for your main multi-user Unix boxes, but not for your Macs and PCs. By default, ident lookups are not performed for any requests.

To enable ident lookups for specific client addresses, you can follow this example:

acl ident_aware_hosts src
ident_lookup_access allow ident_aware_hosts
ident_lookup_access deny all

Only src type ACL checks are fully supported. A srcdomain ACL might work at times, but it will not always provide the correct result.

This clause only supports fast acl types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.


Default Value: No limit is applied.

This option specifies the maximum size of a reply body. It can be used to prevent users from downloading very large files, such as MP3's and movies. When the reply headers are received, the reply_body_max_size lines are processed, and the first line where all (if any) listed ACLs are true is used as the maximum body size for this reply.

This size is checked twice. First when we get the reply headers, we check the content-length value. If the content length value exists and is larger than the allowed size, the request is denied and the user receives an error message that says "the request or reply is too large." If there is no content-length, and the reply size exceeds this limit, the client's connection is just closed and they will receive a partial reply.

WARNING: downstream caches probably can not detect a partial reply if there is no content-length header, so they will cache partial responses and give them out as hits. You should NOT use this option if you have downstream caches.

WARNING: A maximum size smaller than the size of squid's error messages will cause an infinite loop and crash squid. Ensure that the smallest non-zero value you use is greater that the maximum header size plus the size of your largest error page.

If you set this parameter none (the default), there will be no limit imposed.

Configuration Format is:

reply_body_max_size SIZE UNITS [acl ...]


reply_body_max_size 10 MB


Default Value: Respond with an error message to unidentifiable traffic

Determines Squid behavior when encountering strange requests at the beginning of an accepted TCP connection or the beginning of a bumped CONNECT tunnel. Controlling Squid reaction to unexpected traffic is especially useful in interception environments where Squid is likely to see connections for unsupported protocols that Squid should either terminate or tunnel at TCP level.

on_unsupported_protocol <action> [!]acl ...

The first matching action wins. Only fast ACLs are supported.

Supported actions are:


Establish a TCP connection with the intended server and blindly shovel TCP packets between the client and server.


Respond with an error message, using the transfer protocol for the Squid port that received the request (e.g., HTTP for connections intercepted at the http_port). This is the default.

Squid expects the following traffic patterns:

http_port: a plain HTTP request
https_port: SSL/TLS handshake followed by an [encrypted] HTTP request
ftp_port: a plain FTP command (no on_unsupported_protocol support yet!)
CONNECT tunnel on http_port: same as https_port
CONNECT tunnel on https_port: same as https_port

Currently, this directive has effect on intercepted connections and bumped tunnels only. Other cases are not supported because Squid cannot know the intended destination of other traffic.

For example:

# define what Squid errors indicate receiving non-HTTP traffic:
acl foreignProtocol squid_error ERR_PROTOCOL_UNKNOWN ERR_TOO_BIG
# define what Squid errors indicate receiving nothing:
acl serverTalksFirstProtocol squid_error ERR_REQUEST_START_TIMEOUT
# tunnel everything that does not look like HTTP:
on_unsupported_protocol tunnel foreignProtocol
# tunnel if we think the client waits for the server to talk first:
on_unsupported_protocol tunnel serverTalksFirstProtocol
# in all other error cases, just send an HTTP "error page" response:
on_unsupported_protocol respond all

See also: squid_error ACL


Default Value: use all auth_param schemes in their configuration order

Use this directive to customize authentication schemes presence and order in Squid's Unauthorized and Authentication Required responses.

auth_schemes scheme1,scheme2,... [!]aclname ...

where schemeN is the name of one of the authentication schemes configured using auth_param directives. At least one scheme name is required. Multiple scheme names are separated by commas. Either avoid whitespace or quote the entire schemes list.

A special "ALL" scheme name expands to all auth_param-configured schemes in their configuration order. This directive cannot be used to configure Squid to offer no authentication schemes at all.

The first matching auth_schemes rule determines the schemes order for the current Authentication Required transaction. Note that the future response is not yet available during auth_schemes evaluation.

If this directive is not used or none of its rules match, then Squid responds with all configured authentication schemes in the order of auth_param directives in the configuration file.

This directive does not determine when authentication is used or how each authentication scheme authenticates clients.

The following example sends basic and negotiate authentication schemes, in that order, when requesting authentication of HTTP requests matching the isIE ACL (not shown) while sending all auth_param schemes in their configuration order to other clients:

auth_schemes basic,negotiate isIE
auth_schemes ALL all # explicit default

This directive supports fast ACLs only.

See also: auth_param.

Network options


Default Value: none

Suggested Config:

# Squid normally listens to port 3128
http_port 3128


port [mode] [options]
hostname:port [mode] [options] [mode] [options]

The socket addresses where Squid will listen for HTTP client requests. You may specify multiple socket addresses.

There are three forms: port alone, hostname with port, and IP address with port. If you specify a hostname or IP address, Squid binds the socket to that specific address. Most likely, you do not need to bind to a specific address, so you can use the port number alone.

If you are running Squid in accelerator mode, you probably want to listen on port 80 also, or instead.

The -a command line option may be used to specify additional port(s) where Squid listens for proxy request. Such ports will be plain proxy ports with no options.

You may specify multiple socket addresses on multiple lines.



Support for IP-Layer NAT interception delivering traffic to this Squid port. NP: disables authentication on the port.


Support Linux TPROXY (or BSD divert-to) with spoofing of outgoing connections using the client IP address. NP: disables authentication on the port.


Accelerator / reverse proxy mode


For each CONNECT request allowed by ssl_bump ACLs, establish secure connection with the client and with the server, decrypt HTTPS messages as they pass through Squid, and treat them as unencrypted HTTP messages, becoming the man-in-the-middle. The ssl_bump option is required to fully enable bumping of CONNECT requests.

Omitting the mode flag causes default forward proxy mode to be used.

Accelerator Mode Options:


What to use for the Host: header if it is not present in a request. Determines what site (not origin server) accelerators should consider the default.


Disable using HTTP/1.1 Host header for virtual domain support.


Protocol to reconstruct accelerated and intercepted requests with. Defaults to HTTP/1.1 for http_port and HTTPS/1.1 for https_port. When an unsupported value is configured Squid will produce a FATAL error. Values: HTTP or HTTP/1.1, HTTPS or HTTPS/1.1


Virtual host port support. Using the http_port number instead of the port passed on Host: headers.


Virtual host port support. Using the specified port number instead of the port passed on Host: headers.


Act as if this Squid is the origin server. This currently means generate new Date: and Expires: headers on HIT instead of adding Age:.


Ignore request Cache-Control headers. WARNING: This option violates HTTP specifications if used in non-accelerator setups.


Allow direct forwarding in accelerator mode. Normally accelerated requests are denied direct forwarding as if never_direct was used. WARNING: this option opens accelerator mode to security vulnerabilities usually only affecting in interception mode. Make sure to protect forwarding with suitable http_access rules when using this.

SSL Bump Mode Options:

In addition to these options ssl-bump requires TLS/SSL options.


Dynamically create SSL server certificates for the destination hosts of bumped CONNECT requests.When enabled, the cert and key options are used to sign generated certificates. Otherwise generated certificate will be selfsigned. If there is a CA certificate lifetime of the generated certificate equals lifetime of the CA certificate. If generated certificate is selfsigned lifetime is three years. This option is enabled by default when ssl-bump is used. See the ssl-bump option above for more information.


Approximate total RAM size spent on cached generated certificates. If set to zero, caching is disabled. The default value is 4MB.

TLS / SSL Options:


Path to file containing an X.509 certificate (PEM format) to be used in the TLS handshake ServerHello. 
If this certificate is constrained by KeyUsage TLS feature it must allow HTTP server usage, along with any additional restrictions imposed by your choice of options= settings. 
When OpenSSL is used this file may also contain a chain of intermediate CA certificates to send in the TLS handshake.
When GnuTLS is used this option (and any paired tls-key= option) may be repeated to load multiple certificates for different domains.
Also, when generate-host-certificates=on is configured the first tls-cert= option must be a CA certificate capable of signing the automatically generated certificates.


Path to a file containing private key file (PEM format) for the previous tls-cert= option.
If tls-key= is not specified tls-cert= is assumed to reference a PEM file containing both the certificate and private key.


Colon separated list of supported ciphers. 
NOTE: some ciphers such as EDH ciphers depend on additional settings. If those settings are omitted the ciphers may be silently ignored by the OpenSSL library.


Various SSL implementation options. The most important being:


Disallow the use of SSLv3


Disallow the use of TLSv1.0


Disallow the use of TLSv1.1


Disallow the use of TLSv1.2


Always create a new key when using temporary/ephemeral DH key exchanges


Enable ephemeral ECDH key exchange. The adopted curve should be specified using the tls-dh option.


Disable use of RFC5077 session tickets. Some servers may have problems understanding the TLS extension due to ambiguous specification in RFC4507.


Enable various bug workarounds suggested as "harmless" by OpenSSL
Be warned that this reduces SSL/TLS strength to some attacks.

See the OpenSSL SSL_CTX_set_options documentation for a more complete list.


File containing the list of CAs to use when requesting a client certificate.


PEM file containing CA certificates to use when verifying client certificates. If not configured clientca will be used. May be repeated to load multiple files.


Directory containing additional CA certificates and CRL lists to use when verifying client certificates. Requires OpenSSL or LibreSSL.


File of additional CRL lists to use when verifying the client certificate, in addition to CRLs stored in the capath. Implies VERIFY_CRL flag below.


File containing DH parameters for temporary/ephemeral DH key exchanges, optionally prefixed by a curve for ephemeral ECDH key exchanges.
See OpenSSL documentation for details on how to create the DH parameter file. Supported curves for ECDH can be listed using the "openssl ecparam -list_curves" command.
WARNING: EDH and EECDH ciphers will be silently disabled if this option is not set.


Various flags modifying the use of SSL:


Don't request client certificates immediately, but wait until acl processing requires a certificate (not yet implemented).


Request a client certificate during the TLS handshake, but ignore certificate absence in the TLS client Hello. If the client does supply a certificate, it is validated.


Don't allow for session reuse. Each connection will result in a new SSL session.


Verify CRL lists when accepting client certificates.


Verify CRL lists for all certificates in the client certificate chain.


Whether to use the system Trusted CAs. Default is OFF.


Do not use the TLS NPN extension to advertise HTTP/1.1.


SSL session ID context identifier.

Other Options:


use connection-auth=off to tell Squid to prevent forwarding Microsoft connection oriented authentication (NTLM, Negotiate and Kerberos)


Control Path-MTU discovery usage:


lets OS decide on what to do (default).


disable PMTU discovery when transparent support is enabled.


disable always PMTU discovery.

In many setups of transparently intercepting proxies Path-MTU discovery can not work on traffic towards the clients. This is the case when the intercepting device does not fully track connections and fails to forward ICMP must fragment messages to the cache server. If you have such setup and experience that certain clients sporadically hang or never complete requests set disable-pmtu-discovery option to 'transparent'.


Specifies a internal name for the port. Defaults to the port specification (port or addr:port)


Enable TCP keepalive probes of idle connections. In seconds; idle is the initial time before TCP starts probing the connection, interval how often to probe, and timeout the time before giving up.


Require PROXY protocol version 1 or 2 connections. The proxy_protocol_access is required to permit downstream proxies which can be trusted.


Ask TCP stack to maintain a dedicated listening queue for each worker accepting requests at this port. Requires TCP stack that supports the SO_REUSEPORT socket option.
SECURITY WARNING: Enabling worker-specific queues allows any process running as Squid's effective user to easily accept requests destined to this port.

If you run Squid on a dual-homed machine with an internal and an external interface we recommend you to specify the internal address:port in http_port. This way Squid will only be visible on the internal address.


Default Value: none


[ip:]port [mode] tls-cert=certificate.pem [options]

The socket address where Squid will listen for client requests made over TLS or SSL connections. Commonly referred to as HTTPS.

This is most useful for situations where you are running squid in accelerator mode and you want to do the TLS work at the accelerator level.

You may specify multiple socket addresses on multiple lines, each with their own certificate and/or options.

The tls-cert= option is mandatory on HTTPS ports.

See http_port for a list of modes and options.


Allows you to map requests to different outgoing IP addresses based on the username or source address of the user making the request.

tcp_outgoing_address ipaddr [[!]aclname] ...

For example;

Forwarding clients with dedicated IPs for certain subnets.

acl normal_service_net src
acl good_service_net src

tcp_outgoing_address 2001:db8::c001 good_service_net
tcp_outgoing_address good_service_net

tcp_outgoing_address 2001:db8::beef normal_service_net
tcp_outgoing_address normal_service_net

tcp_outgoing_address 2001:db8::1

Processing proceeds in the order specified, and stops at first fully matching line.

Squid will add an implicit IP version test to each line.

Requests going to IPv4 websites will use the outgoing 10.1.0.* addresses.

Requests going to IPv6 websites will use the outgoing 2001:db8:* addresses.

NOTE: The use of this directive using client dependent ACLs is incompatible with the use of server side persistent connections. To ensure correct results it is best to set server_persistent_connections to off when using this directive in such configurations.

NOTE: The use of this directive to set a local IP on outgoing TCP links is incompatible with using TPROXY to set client IP out outbound TCP links.

When needing to contact peers use the no-tproxy cache_peer option and the client_dst_passthru directive re-enable normal forwarding such as this.

This clause only supports fast acl types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.


With NAT or TPROXY intercepted traffic Squid may pass the request directly to the original client destination IP or seek a faster source using the HTTP Host header.

Using Host to locate alternative servers can provide faster connectivity with a range of failure recovery options. But can also lead to connectivity trouble when the client and server are attempting stateful interactions unaware of the proxy.

This option (on by default) prevents alternative DNS entries being located to send intercepted traffic DIRECT to an origin server. The clients original destination IP and port will be used instead.

Regardless of this option setting, when dealing with intercepted traffic Squid will verify the Host: header and any traffic which fails Host verification will be treated as if this option were ON. 

see host_verify_strict for details on the verification process.

Disk cache options


Default Value: No disk cache. Store cache ojects only in memory.

Suggested Config:

# Uncomment and adjust the following to add a disk cache directory.
#cache_dir ufs /usr/local/squid/var/cache/squid 100 16 256


cache_dir Type Directory-Name Fs-specific-data [options]

You can specify multiple cache_dir lines to spread the cache among different disk partitions.

Type specifies the kind of storage system to use. Only "ufs" is built by default. To enable any of the other storage systems see the --enable-storeio configure option.

'Directory' is a top-level directory where cache swap files will be stored. If you want to use an entire disk for caching, this can be the mount-point directory. The directory must exist and be writable by the Squid process. Squid will NOT create this directory for you.

In SMP configurations, cache_dir must not precede the workers option and should use configuration macros or conditionals to give each worker interested in disk caching a dedicated cache directory.

==== The ufs store type ====

"ufs" is the old well-known Squid storage format that has always been there.


cache_dir ufs Directory-Name Mbytes L1 L2 [options]

'Mbytes' is the amount of disk space (MB) to use under this directory. The default is 100 MB. Change this to suit your configuration. Do NOT put the size of your disk drive here. Instead, if you want Squid to use the entire disk drive, subtract 20% and use that value.

'L1' is the number of first-level subdirectories which will be created under the 'Directory'. The default is 16.

'L2' is the number of second-level subdirectories which will be created under each first-level directory. The default is 256.

==== The aufs store type ====

"aufs" uses the same storage format as "ufs", utilizing POSIX-threads to avoid blocking the main Squid process on disk-I/O. This was formerly known in Squid as async-io.


cache_dir aufs Directory-Name Mbytes L1 L2 [options]

see argument descriptions under ufs above

==== The diskd store type ====

"diskd" uses the same storage format as "ufs", utilizing a separate process to avoid blocking the main Squid process on disk-I/O.


cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n]

see argument descriptions under ufs above

Q1 specifies the number of unacknowledged I/O requests when Squid stops opening new files. If this many messages are in the queues, Squid won't open new files. Default is 64

Q2 specifies the number of unacknowledged messages when Squid starts blocking. If this many messages are in the queues, Squid blocks until it receives some replies. Default is 72

When Q1 < Q2 (the default), the cache directory is optimized for lower response time at the expense of a decrease in hit ratio. If Q1 > Q2, the cache directory is optimized for higher hit ratio at the expense of an increase in response time.

==== The rock store type ====


cache_dir rock Directory-Name Mbytes [options]

The Rock Store type is a database-style storage. All cached entries are stored in a "database" file, using fixed-size slots. A single entry occupies one or more slots.

If possible, Squid using Rock Store creates a dedicated kid process called "disker" to avoid blocking Squid worker(s) on disk I/O. One disker kid is created for each rock cache_dir. Diskers are created only when Squid, running in daemon mode, has support for the IpcIo disk I/O module.

swap-timeout=msec: Squid will not start writing a miss to or reading a hit from disk if it estimates that the swap operation will take more than the specified number of milliseconds. By default and when set to zero, disables the disk I/O time limit enforcement. Ignored when using blocking I/O module because blocking synchronous I/O does not allow Squid to estimate the expected swap wait time.

max-swap-rate=swaps/sec: Artificially limits disk access using the specified I/O rate limit. Swap out requests that would cause the average I/O rate to exceed the limit are delayed. Individual swap in requests (i.e., hits or reads) are not delayed, but they do contribute to measured swap rate and since they are placed in the same FIFO queue as swap out requests, they may wait longer if max-swap-rate is smaller. This is necessary on file systems that buffer "too many" writes and then start blocking Squid and other processes while committing those writes to disk. Usually used together with swap-timeout to avoid excessive delays and queue overflows when disk demand exceeds available disk "bandwidth". By default and when set to zero, disables the disk I/O rate limit enforcement. Currently supported by IpcIo module only.

slot-size=bytes: The size of a database "record" used for storing cached responses. A cached response occupies at least one slot and all database I/O is done using individual slots so increasing this parameter leads to more disk space waste while decreasing it leads to more disk I/O overheads. Should be a multiple of your operating system I/O page size. Defaults to 16KBytes. A housekeeping header is stored with each slot and smaller slot-sizes will be rejected. The header is smaller than 100 bytes.



no new objects should be stored to this cache_dir.


the minimum object size in bytes this cache_dir will accept. It's used to restrict a cache_dir to only store large objects (e.g. AUFS) while other stores are optimized for smaller objects (e.g. Rock). Defaults to 0.


the maximum object size in bytes this cache_dir supports. The value in maximum_object_size directive sets the default unless more specific details are available (ie a small store capacity).

Note: To make optimal use of the max-size limits you should order the cache_dir lines with the smallest max-size value first.

Logfile options


Default Value: The format definitions squid, common, combined, referrer, useragent are built in.


logformat <name> <format specification>

Defines an access log format.

The <format specification> is a string with embedded % format codes

% format codes all follow the same basic structure where all components but the formatcode are optional and usually unnecessary, especially when dealing with common codes.

% [encoding] [-] [[0]width] [{arg}] formatcode [{arg}]

encoding escapes or otherwise protects "special" characters:


Quoted string encoding where quote(") and backslash(\) characters are \-escaped while CR, LF, and TAB characters are encoded as \r, \n, and \t two-character sequences.


Custom Squid encoding where percent(%), square brackets([]), backslash(\) and characters with codes outside of [32,126] range are %-encoded. SP is not encoded. Used by log_mime_hdrs.


URL encoding (a.k.a. percent-encoding) where all URL unsafe and control characters (per RFC 1738) are %-encoded.


Shell-like encoding where quote(") and backslash(\) characters are \-escaped while CR and LF characters are encoded as \r and \n two-character sequences. Values containing SP character(s) are surrounded by quotes(").


Raw/as-is encoding with no escaping/quoting.

Default encoding: When no explicit encoding is specified, each %code determines its own encoding. Most %codes use raw/as-is encoding, but some codes use a so called "pass-through URL encoding" where all URL unsafe and control characters (per RFC 1738) are %-encoded, but the percent character(%) is left as is.


left aligned


minimum and/or maximum field width:
When minimum starts with 0, the field is zero-padded. String values exceeding maximum width are truncated.


argument such as header name etc. This field may be placed before or after the token, but not both at once.

Format codes:


a literal % character


Unique sequence number per log line entry


The ID of an error response served by Squid or a similar internal error identifier.


Additional err_code-dependent error information.


The annotation specified by the argument. Also logs the adaptation meta headers set by the adaptation_meta configuration parameter. If no argument given all annotations logged. The argument may include a separator to use with annotation values:


By default, multiple note values are separated with "," and multiple notes are separated with "\r\n". When logging named notes with %{name}note, the explicitly configured separator is used between note values. When logging all notes with %note, the explicitly configured separator is used between individual notes. There is currently no way to specify both value and notes separators when logging all notes with %note.


The master transaction identifier is an unsigned integer. These IDs are guaranteed to monotonically increase within a single worker process lifetime, with higher values corresponding to transactions that were accepted or initiated later. Due to current implementation deficiencies, some IDs are skipped (i.e. never logged). Concurrent workers and restarted workers use similar, overlapping sequences of master transaction IDs.

Connection related format codes:


Client source IP address


Client FQDN


Client source port


Client source EUI (MAC address, EUI-48 or EUI-64 identifier)


Local IP address the client connected to


Local port number the client connected to


Client connection TOS/DSCP value set by Squid


Client connection netfilter packet MARK set by Squid



Local listening IP address the client connection was connected to.


Local listening port number the client connection was connected to.



Server IP address of the last server or peer connection


Server FQDN or peer name


Server port number of the last server or peer connection


Local IP address of the last server or peer connection


Local port number of the last server or peer connection


Server connection TOS/DSCP value set by Squid


Server connection netfilter packet MARK set by Squid



Raw client handshake Initial client bytes received by Squid on a newly accepted TCP connection or inside a just established CONNECT tunnel. Squid stops accumulating handshake bytes as soon as the handshake parser succeeds or fails (determining whether the client is using the expected protocol).

For HTTP clients, the handshake is the request line. For TLS clients, the handshake consists of all TLS records up to and including the TLS record that contains the last byte of the first ClientHello message. For clients using an unsupported protocol, this field contains the bytes received by Squid at the time of the handshake parsing failure.

See the on_unsupported_protocol directive for more information on Squid handshake traffic expectations.

Current support is limited to these contexts:

- http_port connections, but only when the on_unsupported_protocol directive is in use.

- https_port connections (and CONNECT tunnels) that are subject to the ssl_bump peek or stare action.

To protect binary handshake data, this field is always base64-encoded (RFC 4648 Section 4). If logformat field encoding is configured, that encoding is applied on top of base64. Otherwise, the computed base64 value is recorded as is.

Time related format codes:


Seconds since epoch


subsecond time (milliseconds)


Local time. Optional strftime format argument default %d/%b/%Y:%H:%M:%S %z


GMT time. Optional strftime format argument default %d/%b/%Y:%H:%M:%S %z


Response time (milliseconds)


Total time spent making DNS lookups (milliseconds)


Approximate master transaction start time in <full seconds since epoch>.<fractional seconds> format. Currently, Squid considers the master transaction started when a complete HTTP request header initiating the transaction is received from the client. This is the same value that Squid uses to calculate transaction response time when logging %tr to access.log. Currently, Squid uses millisecond resolution for %tS values, similar to the default access.log "current time" field (%ts.%03tu).

Access Control related format codes:


Tag returned by external acl


Log string returned by external acl


User name (any available)


User name from authentication


User name from external acl helper


User name from ident


A user name. Expands to the first available name from the following list of information sources:

- authenticated user name, like %ul

- user name supplied by an external ACL, like %ue

- SSL client name, like %us

- ident user name, like %ui


Client credentials. The exact meaning depends on the authentication scheme: For Basic authentication, it is the password; for Digest, the realm sent by the client; for NTLM and Negotiate, the client challenge or client credentials prefixed with "YR " or "KK ".

HTTP related format codes:



Request method (GET/POST etc)


Request method from client


Request method sent to server or peer



Request URL received (or computed) and sanitized

Logs request URI received from the client, a request adaptation service, or a request redirector (whichever was applied last).

Computed URLs are URIs of internally generated requests and various "error:…" URIs.

Honors strip_query_terms and uri_whitespace.

This field is not encoded by default. Encoding this field using variants of %-encoding will clash with uri_whitespace modifications that also use %-encoding.



Request URL received from the client (or computed)

Computed URLs are URIs of internally generated requests and various "error:…" URIs.

Unlike %ru, this request URI is not affected by request adaptation, URL rewriting services, and strip_query_terms.

Honors uri_whitespace.

This field is using pass-through URL encoding by default. Encoding this field using other variants of %-encoding will clash with uri_whitespace modifications that also use %-encoding.



Request URL sent to server or peer


Request URL scheme from client


Request URL scheme sent to server or peer


Request URL domain from client


Request URL domain sent to server or peer


Request URL port from client


Request URL port sent to server or peer


Request URL path excluding hostname


Request URL path excluding hostname from client


Request URL path excluding hostname sent to server or peer


Request protocol version


Request protocol version from client


Request protocol version sent to server or peer



Original received request header.

Usually differs from the request header sent by Squid, although most fields are often preserved. Accepts optional header field name/value filter argument using name[:[separator]element] format.


Received request header after adaptation and redirection (pre-cache REQMOD vectoring point). Usually differs from the request header sent by Squid, although most fields are often preserved. Optional header name argument as for >h




HTTP status code received from the next hop


HTTP status code sent to the client



Reply header. Optional header name argument as for >h



MIME content type




[http::]st Total size of request + reply traffic with client

[http::]>st Total size of request received from client.

Excluding chunked encoding bytes.

[http::]<st Total size of reply sent to client (after adaptation)


[http::]>sh Size of request headers received from client

[http::]<sh Size of reply headers sent to client (after adaptation)


[http::]<sH Reply high offset sent

[http::]<sS Upstream object size


[http::]<bs Number of HTTP-equivalent message body bytes

received from the next hop, excluding chunked

transfer encoding and control messages.

Generated FTP/Gopher listings are treated as

received bodies.




[http::]<pt Peer response time in milliseconds. The timer starts

when the last request byte is sent to the next hop

and stops when the last response byte is received.

[http::]<tt Total time in milliseconds. The timer

starts with the first connect request (or write I/O)

sent to the first selected peer. The timer stops

with the last I/O with the last peer.


Squid handling related format codes:


Squid request status (TCP_MISS etc)


Squid hierarchy status (DEFAULT_PARENT etc)

SSL-related format codes:


SslBump decision for the transaction:

For CONNECT requests that initiated bumping of a connection and for any request received on an already bumped connection, Squid logs the corresponding SslBump mode ("splice", "bump", "peek", "stare", "terminate", "server-first" or "client-first"). See the ssl_bump option for more information about these modes.

A "none" token is logged for requests that triggered "ssl_bump" ACL evaluation matching a "none" rule.

In all other cases, a single dash ("-") is logged.


SSL client SNI sent to Squid.


The Subject field of the received client SSL certificate or a dash ('-') if Squid has received an invalid/malformed certificate or no certificate at all. Consider encoding the logged value because Subject often has spaces.


The Issuer field of the received client SSL certificate or a dash ('-') if Squid has received an invalid/malformed certificate or no certificate at all. Consider encoding the logged value because Issuer often has spaces.


The Subject field of the received server TLS certificate or a dash ('-') if this is not available. Consider encoding the logged value because Subject often has spaces.


The Issuer field of the received server TLS certificate or a dash ('-') if this is not available. Consider encoding the logged value because Issuer often has spaces.


The received server x509 certificate in PEM format, including BEGIN and END lines (or a dash ('-') if the certificate is unavailable).

WARNING: Large certificates will exceed the current 8KB access.log record limit, resulting in truncated records. Such truncation usually happens in the middle of a record field. The limit applies to all access logging modules.

The logged certificate may have failed validation and may not be trusted by Squid. This field does not include any intermediate certificates that may have been received from the server or fetched during certificate validation process.

Currently, Squid only collects server certificates during step3 of SslBump processing; connections that were not subject to ssl_bump rules or that did not match a peek or stare rule at step2 will not have the server certificate information.

This field is using pass-through URL encoding by default.


The list of certificate validation errors detected by Squid (including OpenSSL and certificate validation helper components). The errors are listed in the discovery order. By default, the error codes are separated by ':'. Accepts an optional separator argument.


The negotiated TLS version of the client connection.


The negotiated TLS version of the last server or peer connection.


The TLS version of the Hello message received from TLS client.


The TLS version of the Hello message received from TLS server.


The maximum TLS version supported by the TLS client.


The maximum TLS version supported by the TLS server.


The negotiated cipher of the client connection.


The negotiated cipher of the last server or peer connection.

If ICAP is enabled, the following code becomes available (as well as ICAP log codes documented with the icap_log option):


Total ICAP processing time for the HTTP transaction. The timer ticks when ICAP ACLs are checked and when ICAP transaction is in progress.

If adaptation is enabled the following codes become available:


The header of the last ICAP response or meta-information from the last eCAP transaction related to the HTTP transaction. Like <h, accepts an optional header name argument.


Summed adaptation transaction response times recorded as a comma-separated list in the order of transaction start time. Each time value is recorded as an integer number, representing response time of one or more adaptation (ICAP or eCAP) transaction in milliseconds. When a failed transaction is being retried or repeated, its time is not logged individually but added to the replacement (next) transaction. See also: adapt::all_trs.


All adaptation transaction response times. Same as adaptation_strs but response times of individual transactions are never added together. Instead, all transaction response times are recorded individually.

You can prefix adapt::*_trs format codes with adaptation service name in curly braces to record response time(s) specific to that service. For example: %{my_service}adapt::sum_trs

Format codes related to the PROXY protocol:


PROXY protocol header, including optional TLVs.

Supports the same field and element reporting/extraction logic as %http::>h. For configuration and reporting purposes, Squid maps each PROXY TLV to an HTTP header field: the TLV type (configured as a decimal integer) is the field name, and the TLV value is the field value. All TLVs of "LOCAL" connections (in PROXY protocol terminology) are currently skipped/ignored.

Squid also maps the following standard PROXY protocol header blocks to pseudo HTTP headers (their names use PROXY terminology and start with a colon, following HTTP tradition for pseudo headers): :command, :version, :src_addr, :dst_addr, :src_port, and :dst_port.

Without optional parameters, this logformat code logs pseudo headers and TLVs.

This format code uses pass-through URL encoding by default.


					# relay custom PROXY TLV #224 to adaptation services
					adaptation_meta Client-Foo "%proxy_protocol::>h{224}"

See also: %http::>h

The default formats available (which do not need re-defining) are:

logformat squid      %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %[un %Sh/%<a %mt
logformat common     %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st %Ss:%Sh
logformat combined   %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh
logformat referrer   %ts.%03tu %>a %{Referer}>h %ru
logformat useragent  %>a [%tl] "%{User-Agent}>h"

NOTE: When the log_mime_hdrs directive is set to ON. The squid, common and combined formats have a safely encoded copy of the mime headers appended to each line within a pair of brackets.

NOTE: The common and combined formats are not quite true to the Apache definition. The logs from Squid contain an extra status and hierarchy code appended.


Replaces: cache_access_log

Default Value: daemon:/usr/local/squid/var/logs/access.log squid Configures whether and how Squid logs HTTP and ICP transactions. If access logging is enabled, a single line is logged for every matching HTTP or ICP request. The recommended directive formats are:

access_log <module>:<place> [option ...] [acl acl ...]
access_log none [acl acl ...]

The following directive format is accepted but may be deprecated:

access_log <module>:<place> [ [acl acl ...]]

In most cases, the first ACL name must not contain the '=' character and should not be equal to an existing logformat name. You can always start with an 'all' ACL to work around those restrictions.

Will log to the specified module:place using the specified format (which must be defined in a logformat directive) those entries which match ALL the acl's specified (which must be defined in acl clauses). If no acl is specified, all requests will be logged to this destination.

===== Available options for the recommended directive format =====


Names log line format (either built-in or defined by a logformat directive). Defaults to 'squid'.


Defines approximate buffering limit for log records (see buffered_logs). Squid should not keep more than the specified size and, hence, should flush records before the buffer becomes full to avoid overflows under normal conditions (the exact flushing algorithm is module-dependent though). The on-error option controls overflow handling.


Defines action on unrecoverable errors. The 'drop' action ignores (i.e., does not log) affected log records. The default 'die' action kills the affected worker. The drop action support has not been tested for modules other than tcp.


Specifies the number of log file rotations to make when you run 'squid -k rotate'. The default is to obey the logfile_rotate directive. Setting rotate=0 will disable the file name rotation, but the log files are still closed and re-opened. This will enable you to rename the logfiles yourself just before sending the rotate signal. Only supported by the stdio module.

===== Modules Currently available =====


Do not log any requests matching these ACL. Do not specify Place or logformat name.


Write each log line to disk immediately at the completion of each request.

Place: the filename and path to be written.


Very similar to stdio. But instead of writing to disk the log line is passed to a daemon helper for asychronous handling instead.

Place: varies depending on the daemon.

log_file_daemon Place: the file name and path to be written.


To log each request via syslog facility.

Place: The syslog facility and priority level for these entries.

Place Format: facility.priority

where facility could be any of:

authpriv, daemon, local0 … local7 or user.

And priority could be any of:

err, warning, notice, info, debug.


To send each log line as text data to a UDP receiver.

Place: The destination host name or IP and port.

Place Format: //host:port


To send each log line as text data to a TCP receiver. Lines may be accumulated before sending (see buffered_logs).

Place: The destination host name or IP and port.

Place Format: //host:port


access_log daemon:/usr/local/squid/var/logs/access.log squid


Default Value: logfile_daemon /usr/local/squid/libexec/log_file_daemon

Specify the path to the logfile-writing daemon. This daemon is used to write the access and store logs, if configured.

Squid sends a number of commands to the log daemon:

L<data>\n - logfile data

R\n - rotate file

T\n - truncate file

O\n - reopen file

F\n - flush file

r<n>\n - set rotate count to <n>

b<n>\n - 1 = buffer output, 0 = don't buffer output

No responses is expected.


Default Value: Allow logging for all transactions.

This options allows you to control which requests gets accounted in performance counters.

This clause only supports fast acl types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.


Default Value: none

Logs the activities of the storage manager. Shows which objects are ejected from the cache, and which objects are saved and for how long. There are not really utilities to analyze this data, so you can safely disable it (the default).

Store log uses modular logging outputs. See access_log for the list of modules supported.


cache_store_log stdio:/usr/local/squid/var/logs/store.log
cache_store_log daemon:/usr/local/squid/var/logs/store.log

Options for troubleshooting


Default Value: /usr/local/squid/var/logs/cache.log

Squid administrative logging file.

This is where general information about Squid behavior goes. You can increase the amount of data logged to this file and how often it is rotated with "debug_options"


Default Value: Log all critical and important messages.

Logging options are set as section,level where each source file is assigned a unique section. Lower levels result in less output, Full debugging (level 9) can result in a very large log file, so be careful.

The magic word "ALL" sets debugging levels for all sections. The default is to run with "ALL,1" to record important warnings.

The rotate=N option can be used to keep more or less of these logs than would otherwise be kept by logfile_rotate. For most uses a single log should be enough to monitor current events affecting Squid.


Default Value: Use the directory from where Squid was started.

Suggested Config:

# Leave coredumps in the first cache dir
coredump_dir /usr/local/squid/var/cache/squid

By default Squid leaves core files in the directory from where it was started. If you set 'coredump_dir' to a directory that exists, Squid will chdir() to that directory at startup and coredump files will be left there.

Options for tuning the cache


Replaces: no_cache

Default Value: By default, this directive is unused and has no effect.

Requests denied by this directive will not be served from the cache and their responses will not be stored in the cache. This directive has no effect on other transactions and on already cached responses.

This clause supports both fast and slow acl types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.

This and the two other similar caching directives listed below are checked at different transaction processing stages, have different access to response information, affect different cache operations, and differ in slow ACLs support:


Checked before Squid makes a hit/miss determination. No access to reply information! Denies both serving a hit and storing a miss. Supports both fast and slow ACLs.


Checked after a hit was detected. Has access to reply (hit) information. Denies serving a hit only. Supports fast ACLs only.


Checked before storing a cachable miss. Has access to reply (miss) information. Denies storing a miss only. Supports fast ACLs only.

If you are not sure which of the three directives to use, apply the following decision logic:

  • If your ACL(s) are of slow type _and_ need response info, redesign. Squid does not support that particular combination at this time. 
  • If your directive ACL(s) are of slow type, use "cache"; and/or * if your directive ACL(s) need no response info, use "cache". 
  • If you do not want the response cached, use store_miss; and/or
  • if you do not want a hit on a cached response, use send_hit.


Suggested Config:

# Add any of your own refresh_pattern entries above these.
refresh_pattern ^ftp:		1440	20%	10080
refresh_pattern ^gopher:	1440	0%	1440
refresh_pattern -i (/cgi-bin/|\?) 0	0%	0
refresh_pattern .		0	20%	4320


refresh_pattern [-i] regex min percent max [options]

By default, regular expressions are CASE-SENSITIVE. To make them case-insensitive, use the -i option.

'Min' is the time (in minutes) an object without an explicit expiry time should be considered fresh. The recommended value is 0, any higher values may cause dynamic applications to be erroneously cached unless the application designer has taken the appropriate actions.

'Percent' is a percentage of the objects age (time since last modification age) an object without explicit expiry time will be considered fresh.

'Max' is an upper limit on how long objects without an explicit expiry time will be considered fresh. The value is also used to form Cache-Control: max-age header for a request sent from Squid to origin/parent.


  • override-expire
  • override-lastmod
  • reload-into-ims
  • ignore-reload
  • ignore-no-store
  • ignore-private
  • max-stale=NN
  • refresh-ims
  • store-stale


enforces min age even if the server sent an explicit expiry time (e.g., with the Expires: header or Cache-Control: max-age). Doing this VIOLATES the HTTP standard. Enabling this feature could make you liable for problems which it causes.

Note: override-expire does not enforce staleness - it only extends freshness / min. If the server returns a Expires time which is longer than your max time, Squid will still consider the object fresh for that period of time.


enforces min age even on objects that were modified recently.


changes a client no-cache or “reload'' request for a cached entry into a conditional request using If-Modified-Since and/or If-None-Match headers, provided the cached entry has a Last-Modified and/or a strong ETag header. Doing this VIOLATES the HTTP standard. Enabling this feature could make you liable for problems which it causes.


ignores a client no-cache or “reload'' header. Doing this VIOLATES the HTTP standard. Enabling this feature could make you liable for problems which it causes.


ignores any “Cache-control: no-store'' headers received from a server. Doing this VIOLATES the HTTP standard. Enabling this feature could make you liable for problems which it causes.


ignores any “Cache-control: private'' headers received from a server. Doing this VIOLATES the HTTP standard. Enabling this feature could make you liable for problems which it causes.


causes squid to contact the origin server when a client issues an If-Modified-Since request. This ensures that the client will receive an updated version if one is available.


stores responses even if they don't have explicit freshness or a validator (i.e., Last-Modified or an ETag) present, or if they're already stale. By default, Squid will not cache such responses because they usually can't be reused. Note that such responses will be stale by default.


provide a maximum staleness factor. Squid won't serve objects more stale than this even if it failed to validate the object. Default: use the max_stale global limit.

Basically a cached object is:

		FRESH if expire > now, else STALE
		STALE if age > max
		FRESH if lm-factor < percent, else STALE
		FRESH if age < min
		else STALE

The refresh_pattern lines are checked in the order listed here. The first entry which matches is used. If none of the entries match the default will be used.

Note, you must uncomment all the default lines if you want to change one. The default setting is only active if none is used.

HTTP options


Default Value: request_header_max_size 64 KB

This specifies the maximum size for HTTP headers in a request. Request headers are usually relatively small (about 512 bytes). Placing a limit on the request header size will catch certain bugs (for example with persistent connections) and possibly buffer-overflow or denial-of-service attacks.


Default Value: reply_header_max_size 64 KB

This specifies the maximum size for HTTP headers in a reply. Reply headers are usually relatively small (about 512 bytes). Placing a limit on the reply header size will catch certain bugs (for example with persistent connections) and possibly buffer-overflow or denial-of-service attacks.


Default Value: No limit.

This specifies the maximum size for an HTTP request body. In other words, the maximum size of a PUT/POST request. A user who attempts to send a request with a body larger than this limit receives an "Invalid Request" error message. If you set this parameter to a zero (the default), there will be no limit imposed.

See also client_request_buffer_max_size for an alternative limitation on client uploads which can be configured.


Default Value: client_request_buffer_max_size 512 KB

This specifies the maximum buffer size of a client request. It prevents squid eating too much memory when somebody uploads a large file.


Default Value: via on

If set (default), Squid will include a Via header in requests and replies as required by RFC2616.

RFC2616 requires proxies to add this header to the request and response. Squid Proxy can be compiled to violate HTTP standards. Previously, this required compiling with the --enable-http-violations option, but now support for violations of standards is enabled by default (to disable it, you need to compile with the --disable-http-violations option). You can add the following directive to the configuration file, as a result of which the HTTP Via header will not be added:

via off


Default Value: request_entities off

Squid defaults to deny GET and HEAD requests with request entities, as the meaning of such requests are undefined in the HTTP standard even if not explicitly forbidden.

Set this directive to on if you have clients which insists on sending request entities in GET or HEAD requests. But be warned that there is server software (both proxies and web servers) which can fail to properly process this kind of request which may make you vulnerable to cache pollution attacks if enabled.


Default Value: No limits.


request_header_access header_name allow|deny [!]aclname ...

WARNING: Doing this VIOLATES the HTTP standard. Enabling this feature could make you liable for problems which it causes.

This option replaces the old 'anonymize_headers' and the older 'http_anonymizer' option with something that is much more configurable. A list of ACLs for each header name allows removal of specific header fields under specific conditions.

This option only applies to outgoing HTTP request headers (i.e., headers sent by Squid to the next HTTP hop such as a cache peer or an origin server). The option has no effect during cache hit detection. The equivalent adaptation vectoring point in ICAP terminology is post-cache REQMOD.

The option is applied to individual outgoing request header fields. For each request header field F, Squid uses the first qualifying sets of request_header_access rules:

  1. Rules with header_name equal to F's name.
  2. Rules with header_name 'Other', provided F's name is not on the hard-coded list of commonly used HTTP header names.
  3. Rules with header_name 'All'.

Within that qualifying rule set, rule ACLs are checked as usual. If ACLs of an "allow" rule match, the header field is allowed to go through as is. If ACLs of a "deny" rule match, the header is removed and request_header_replace is then checked to identify if the removed header has a replacement. If no rules within the set have matching ACLs, the header field is left as is.

For example, to achieve the same behavior as the old 'http_anonymizer standard' option, you should use:

request_header_access From deny all
request_header_access Referer deny all
request_header_access User-Agent deny all

Or, to reproduce the old 'http_anonymizer paranoid' feature you should use:

request_header_access Authorization allow all
request_header_access Proxy-Authorization allow all
request_header_access Cache-Control allow all
request_header_access Content-Length allow all
request_header_access Content-Type allow all
request_header_access Date allow all
request_header_access Host allow all
request_header_access If-Modified-Since allow all
request_header_access Pragma allow all
request_header_access Accept allow all
request_header_access Accept-Charset allow all
request_header_access Accept-Encoding allow all
request_header_access Accept-Language allow all
request_header_access Connection allow all
request_header_access All deny all

HTTP reply headers are controlled with the reply_header_access directive.

By default, all headers are allowed (no anonymizing is performed).


Default Value: No limits.


reply_header_access header_name allow|deny [!]aclname ...

WARNING: Doing this VIOLATES the HTTP standard. Enabling this feature could make you liable for problems which it causes.

This option only applies to reply headers, i.e., from the server to the client.

This is the same as request_header_access, but in the other direction. Please see request_header_access for detailed documentation.

For example, to achieve the same behavior as the old 'http_anonymizer standard' option, you should use:

reply_header_access Server deny all
reply_header_access WWW-Authenticate deny all
reply_header_access Link deny all

Or, to reproduce the old 'http_anonymizer paranoid' feature

you should use:

reply_header_access Allow allow all
reply_header_access WWW-Authenticate allow all
reply_header_access Proxy-Authenticate allow all
reply_header_access Cache-Control allow all
reply_header_access Content-Encoding allow all
reply_header_access Content-Length allow all
reply_header_access Content-Type allow all
reply_header_access Date allow all
reply_header_access Expires allow all
reply_header_access Last-Modified allow all
reply_header_access Location allow all
reply_header_access Pragma allow all
reply_header_access Content-Language allow all
reply_header_access Retry-After allow all
reply_header_access Title allow all
reply_header_access Content-Disposition allow all
reply_header_access Connection allow all
reply_header_access All deny all

HTTP request headers are controlled with the request_header_access directive.

By default, all headers are allowed (no anonymizing is performed).


Replaces: header_replace

Default Value: none


request_header_replace header_name message


request_header_replace User-Agent Nutscrape/1.0 (CP/M; 8-bit)

This option allows you to change the contents of headers denied with request_header_access above, by replacing them with some fixed string.

This only applies to request headers, not reply headers.

By default, headers are removed if denied.


Default Value: none


reply_header_replace header_name message


reply_header_replace Server Foo/1.0

This option allows you to change the contents of headers denied with reply_header_access above, by replacing them with some fixed string.

This only applies to reply headers, not request headers.

By default, headers are removed if denied.


Default Value: none


request_header_add field-name field-value [ acl ... ]


request_header_add X-Client-CA "CA=%ssl::>cert_issuer" all

This option adds header fields to outgoing HTTP requests (i.e., request headers sent by Squid to the next HTTP hop such as a cache peer or an origin server). The option has no effect during cache hit detection. The equivalent adaptation vectoring point in ICAP terminology is post-cache REQMOD.

Field-name is a token specifying an HTTP header name. If a standard HTTP header name is used, Squid does not check whether the new header conflicts with any existing headers or violates HTTP rules. If the request to be modified already contains a field with the same name, the old field is preserved but the header field values are not merged.

Field-value is either a token or a quoted string. If quoted string format is used, then the surrounding quotes are removed while escape sequences and %macros are processed.

One or more Squid ACLs may be specified to restrict header injection to matching requests. As always in squid.conf, all ACLs in the ACL list must be satisfied for the insertion to happen. The request_header_add supports fast ACLs only.

See also: reply_header_add.


Default Value: none


reply_header_add field-name field-value [ acl ... ]


reply_header_add X-Client-CA "CA=%ssl::>cert_issuer" all

This option adds header fields to outgoing HTTP responses (i.e., response headers delivered by Squid to the client). This option has no effect on cache hit detection. The equivalent adaptation vectoring point in ICAP terminology is post-cache RESPMOD. This option does not apply to successful CONNECT replies.

Field-name is a token specifying an HTTP header name. If a standard HTTP header name is used, Squid does not check whether the new header conflicts with any existing headers or violates HTTP rules. If the response to be modified already contains a field with the same name, the old field is preserved but the header field values are not merged.

Field-value is either a token or a quoted string. If quoted string format is used, then the surrounding quotes are removed while escape sequences and %macros are processed.

One or more Squid ACLs may be specified to restrict header injection to matching responses. As always in squid.conf, all ACLs in the ACL list must be satisfied for the insertion to happen. The reply_header_add option supports fast ACLs only.

See also: request_header_add.

Options influencing request forwarding


Default Value: Prevent any cache_peer being used for this request.


always_direct allow|deny [!]aclname ...

Here you can use ACL elements to specify requests which should ALWAYS be forwarded by Squid to the origin servers without using any peers. For example, to always directly forward requests for local servers ignoring any parents or siblings you may have use something like:

acl local-servers dstdomain my.domain.net
always_direct allow local-servers

To always forward FTP requests directly, use

acl FTP proto FTP
always_direct allow FTP

NOTE: There is a similar, but opposite option named 'never_direct'. You need to be aware that "always_direct deny foo" is NOT the same thing as "never_direct allow foo". You may need to use a deny rule to exclude a more-specific case of some other rule. Example:

acl local-external dstdomain external.foo.net
acl local-servers dstdomain .foo.net
always_direct deny local-external
always_direct allow local-servers

NOTE: If your goal is to make the client forward the request directly to the origin server bypassing Squid then this needs to be done in the client configuration. Squid configuration can only tell Squid how Squid should fetch the object.

NOTE: This directive is not related to caching. The replies is cached as usual even if you use always_direct. To not cache the replies see the 'cache' directive.

This clause supports both fast and slow acl types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.

DNS options


Default Value:

check_hostnames off

For security and stability reasons Squid can check hostnames for Internet standard RFC compliance. If you want Squid to perform these checks turn this directive on.


Default Value:

allow_underscore on

Underscore characters is not strictly allowed in Internet hostnames but nevertheless used by many sites. Set this to off if you want Squid to be strict about the standard. This check is performed only when check_hostnames is set to on.


Default Value: dns_retransmit_interval 5 seconds

Initial retransmit interval for DNS queries. The interval is doubled each time all configured DNS servers have been tried.


Default Value: dns_timeout 30 seconds

DNS Query timeout. If no response is received to a DNS query within this time all DNS servers for the queried domain are assumed to be unavailable.


Default Value: EDNS disabled

Maximum number of bytes packet size to advertise via EDNS. Set to "none" to disable EDNS large packet support. 

For legacy reasons DNS UDP replies will default to 512 bytes which is too small for many responses. EDNS provides a means for Squid to negotiate receiving larger responses back immediately without having to failover with repeat requests. Responses larger than this limit will retain the old behaviour of failover to TCP DNS.

Squid has no real fixed limit internally, but allowing packet sizes over 1500 bytes requires network jumbogram support and is usually not necessary.

WARNING: The RFC also indicates that some older resolvers will reply with failure of the whole request if the extension is added. Some resolvers have already been identified which will reply with mangled EDNS response on occasion. Usually in response to many-KB jumbogram sizes being advertised by Squid. Squid will currently treat these both as an unable-to-resolve domain even if it would be resolvable without EDNS.


Default Value: Search for single-label domain names is disabled.

Normally the RES_DEFNAMES resolver option is disabled (see res_init(3)). This prevents caches in a hierarchy from interpreting single-component hostnames locally. To allow Squid to handle single-component names, enable this option.


Default Value: Search for .local and .arpa names is disabled.

When set to on, Squid sends multicast DNS lookups on the local network for domains ending in .local and .arpa. This enables local servers and devices to be contacted in an ad-hoc or zero-configuration network environment.


Default Value: Use operating system definitions

Use this if you want to specify a list of DNS name servers (IP addresses) to use instead of those given in your /etc/resolv.conf file.

On Windows platforms, if no value is specified here or in the /etc/resolv.conf file, the list of DNS name servers are taken from the Windows registry, both static and dynamic DHCP configurations are supported.




Default Value:

hosts_file /etc/hosts

Location of the host-local IP name-address associations database. Most Operating Systems have such a file on different default locations:

- Un*X & Linux:


- Windows NT/2000:

%SystemRoot%\system32\drivers\etc\hosts (%SystemRoot% value install default is c:\winnt)

- Windows XP/2003:

%SystemRoot%\system32\drivers\etc\hosts (%SystemRoot% value install default is c:\windows)

- Windows 9x/Me:

%windir%\hosts (%windir% value is usually c:\windows)

- Cygwin:


The file contains newline-separated definitions, in the form ip_address_in_dotted_form name [name …] names are whitespace-separated. Lines beginning with an hash (#) character are comments.

The file is checked at startup and upon configuration. If set to 'none', it won't be checked. If append_domain is used, that domain will be added to domain-local (i.e. not containing any dot character) host definitions.


Default Value: Use operating system definitions

Appends local domain name to hostnames without any dots in them. append_domain must begin with a period.

Be warned there are now Internet names with no dots in them using only top-domain names, so setting this may cause some Internet sites to become unavailable.


append_domain .yourdomain.com


Default Value:

ignore_unknown_nameservers on

By default Squid checks that DNS responses are received from the same IP addresses they are sent to. If they don't match, Squid ignores the response and writes a warning message to cache.log. You can allow responses from unknown nameservers by setting this option to 'off'.

ICP (Internet Cache Protocol) options


Replaces: udp_port

Default Value: ICP disabled.

The port number where Squid sends and receives ICP queries to and from neighbor caches. The standard UDP port for ICP is 3130.


icp_port 3130


Requires: --enable-htcp

Default Value: HTCP disabled.

The port number where Squid sends and receives HTCP queries to and from neighbor caches. To turn it on you want to set it to 4827.


htcp_port 4827


Default Value: log_icp_queries on

If set, ICP queries are logged to access.log. You may wish do disable this if your ICP load is VERY high to speed things up or to simplify log analysis.


Default Value: Accept packets from all machine interfaces.

udp_incoming_address is used for UDP packets received from other caches.

The default behavior is to not bind to any specific address.

Only change this if you want to have all UDP queries received on a specific interface/address.

NOTE: udp_incoming_address is used by the ICP, HTCP, and DNS modules. Altering it will affect all of them in the same manner.

see also; udp_outgoing_address

NOTE, udp_incoming_address and udp_outgoing_address can not have the same value since they both use the same port.


Default Value: Use udp_incoming_address or an address selected by the operating system.

udp_outgoing_address is used for UDP packets sent out to other caches.

The default behavior is to not bind to any specific address.

Instead it will use the same socket as udp_incoming_address. Only change this if you want to have UDP queries sent using another address than where this Squid listens for UDP queries from other caches.

NOTE: udp_outgoing_address is used by the ICP, HTCP, and DNS modules. Altering it will affect all of them in the same manner.

see also; udp_incoming_address

NOTE, udp_incoming_address and udp_outgoing_address can not have the same value since they both use the same port.



Default Value: forwarded_for on

If set to "on", Squid will append your client's IP address in the HTTP requests it forwards. By default it looks like:


If set to "off", it will appear as

X-Forwarded-For: unknown

If set to "transparent", Squid will not alter the X-Forwarded-For header in any way.

If set to "delete", Squid will delete the entire X-Forwarded-For header.

If set to "truncate", Squid will remove all existing X-Forwarded-For entries, and place the client IP as the sole entry.


Configuration options can be included using the "include" directive. Include takes a list of files to include. Quoting and wildcards are supported.

For example,

include /path/to/included/file/squid.acl.config

Includes can be nested up to a hard-coded depth of 16 levels. This arbitrary restriction is to prevent recursive include references from causing Squid entering an infinite loop whilst trying to load configuration files.


In some cases "none" refers to no default setting at all, while in other cases it refers to the value of the option - the comments for that keyword indicate if this is the case.

Values with byte units

Squid accepts size units on some size related directives. All such directives are documented with a default value displaying a unit.

Units accepted by Squid are:

  • bytes - byte
  • KB - Kilobyte (1024 bytes)
  • MB - Megabyte
  • GB - Gigabyte

Values with time units

Time-related directives marked with either "time-units" or "time-units-small" accept a time unit. The supported time units are:

  • nanosecond (time-units-small only)
  • microsecond (time-units-small only)
  • millisecond
  • second
  • minute
  • hour
  • day
  • week
  • fortnight
  • month - 30 days
  • year - 31557790080 milliseconds (just over 365 days)
  • decade

Values with spaces, quotes, and other special characters

Squid supports directive parameters with spaces, quotes, and other special characters. Surround such parameters with "double quotes". Use the configuration_includes_quoted_values directive to enable or disable that support.

Squid supports reading configuration option parameters from external

files using the syntax:


For example:

acl allowlist dstdomain parameters("/etc/squid/allowlist.txt")

Conditional configuration

If-statements can be used to make configuration directives depend on conditions:

	        ... regular configuration directives ...
	        ... regular configuration directives ...]

The else part is optional. The keywords "if", "else", and "endif" must be typed on their own lines, as if they were regular configuration directives.

NOTE: An else-if condition is not supported.

These individual conditions types are supported:

		Always evaluates to true.
		Always evaluates to false.
	        Equality comparison of two integer numbers.

Options that have been/will be removed


Default Value:

dns_v4_first off

With the IPv6 Internet being as fast or faster than IPv4 Internet for most networks Squid prefers to contact websites over IPv6.

This option reverses the order of preference to make Squid contact dual-stack websites over IPv4 first. Squid will still perform both IPv6 and IPv4 DNS lookups before connecting.

WARNING: This option will restrict the situations under which IPv6 connectivity is used (and tested). Hiding network problems which would otherwise be detected and warned about.

Starting with version 5 of Squid, the dns_v4_first option will be removed. Instead of obeying the dns_v4_first setting, the IP family is now largely controlled by the DNS response time: if the AAAA DNS response comes first while Squid is waiting for IP addresses, then Squid will use the first received IPv6 addresses. For previously cached IP addresses, Squid tries IPv6 addresses first. To manage the family of IP addresses used by Squid, administrators must use firewalls, recursive DNS resolver configuration, and/or --disable-ipv6. When planning configuration changes, keep in mind that the upcoming improvements to Happy Eyeballs will facilitate faster TCP connections while reducing the impact of DNS resolution times.

The fifth version implements the “Happy Eyeballs” algorithm, which uses the received IP as soon as it is needed. Firewall rules that deny IPv6 TCP connections remain the preferred configuration method for “disconnecting” IPv6 connections, with a recursive DNS resolver configuration.

Squid Usage Example

Before starting, you need to configure a proxy server. The setting is done in the configuration file. Below is a link to popular examples of configuring Squid for various tasks.

To start the proxy server run:

sudo systemctl start squid

At this point, your Squid web proxy should already be running and you can check the status of the service with:

systemctl status squid

To add the Squid service to startup, run the command:

sudo systemctl enable squid

How to install Squid

Installation on Kali Linux

sudo apt install squid

Installation on Debian, Linux Mint, Ubuntu

sudo apt update
sudo apt install squid

Installation on BlackArch

sudo pacman -Sy squid

Installation on CentOS

yum -y update
yum -y install squid

Installation on Windows

An open source project https://github.com/diladele/squid-windows provides Windows MSI installer files for Squid Proxy Server. It makes it possible to install Squid in just a few clicks. The current build is based on the latest Squid 3.5 build for Cygwin under Windows 64 bit.

To download the installer, go to the website: https://squid.diladele.com/ and click the link “MSI installer for SQUID FOR WINDOWS”.

Run the downloaded file with a double click and follow the prompts of the installer.

Immediately after the installer completes, an icon will appear next to the clock to control the Squid service:

The path to the configuration file in Windows: C:\Squid\etc\squid\squid.conf.

For the changes made in the configuration file to take effect, you need to restart the Squid service, to do this, stop and start it again.

The Squid service will automatically start when the computer is turned on, and for the icon to appear in the tray for managing Squid, you need to run the file C:\Squid\bin\Diladele.Squid.Tray.exe.

You can do it on the command prompt:

net stop squidsrv
net start squidsrv

See also: How to manage services on Windows

To control the autostart of a service, see the article “How to disable autostart of programs and services in Windows”.

In the config file you can see paths like this: “/cygdrive/d/squid/cache”. To understand them, see How to access disks in Cygwin.

Squid Screenshots

Squid Tutorials

Coming soon…

Related tools

Recommended for you:

Comments are Closed