TYPE: acl
LOC: Config.aclList
DEFAULT: all src all
+DEFAULT: manager url_regex -i ^cache_object:// +i ^https?://[^/]+/squid-internal-mgr/
+DEFAULT: localhost src 127.0.0.1/32 ::1
+DEFAULT: to_localhost dst 127.0.0.0/8 0.0.0.0/32 ::1
+DEFAULT_DOC: ACLs all, manager, localhost, and to_localhost are predefined.
DOC_START
Defining an Access List
***** ACL TYPES AVAILABLE *****
- acl aclname src ip-address/netmask ... # clients IP address [fast]
- acl aclname src addr1-addr2/netmask ... # range of addresses [fast]
- acl aclname dst ip-address/netmask ... # URL host's IP address [slow]
- acl aclname myip ip-address/netmask ... # local socket IP address [fast]
+ acl aclname src ip-address/mask ... # clients IP address [fast]
+ acl aclname src addr1-addr2/mask ... # range of addresses [fast]
+ acl aclname dst 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 ... (xx:xx:xx:xx:xx:xx notation)
# The arp ACL requires the special configure option --enable-arp-acl.
acl aclname port 80 70 21 0-1024... # destination TCP port [fast]
# ranges are alloed
- acl aclname myport 3128 ... # local socket TCP port [fast]
+ acl aclname localport 3128 ... # TCP port the client connected to [fast]
+ # NP: for interception mode this is usually '80'
+
acl aclname myportname 3128 ... # http(s)_port name [fast]
acl aclname proto HTTP FTP ... # request protocol [fast]
#
# Recommended minimum configuration:
#
-acl manager proto cache_object
-acl localhost src 127.0.0.1/32 ::1
-acl to_localhost dst 127.0.0.0/8 0.0.0.0/32 ::1
# Example rule allowing access from your local networks.
# Adapt to list your (internal) IP networks from where browsing
# Recommended minimum Access Permission configuration:
#
# Only allow cachemgr access from localhost
-http_access allow manager localhost
+http_access allow localhost manager
http_access deny manager
# Deny requests to certain unsafe ports
NAME: miss_access
TYPE: acl_access
LOC: Config.accessList.miss
-DEFAULT: allow all
+DEFAULT: none
DOC_START
Use to force your neighbors to use you as a sibling instead of
a parent. For example:
connections using the client IP address.
NP: disables authentication and maybe IPv6 on the port.
- accel Accelerator mode. Also needs at least one of
- vhost / vport / defaultsite.
+ accel Accelerator / reverse proxy mode
ssl-bump Intercept each CONNECT request matching ssl_bump ACL,
establish secure connection with the client and with
Accelerator Mode Options:
- allow-direct Allow direct forwarding in accelerator mode. Normally
- accelerated requests are denied direct forwarding as if
- never_direct was used.
-
defaultsite=domainname
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.
- Implies accel.
- vhost Using the Host header for virtual domain support.
- Also uses the port as specified in Host: header.
+ no-vhost Disable using HTTP/1.1 Host header for virtual domain support.
+
+ protocol= Protocol to reconstruct accelerated requests with.
+ Defaults to http for http_port and https for
+ https_port
- vport IP based virtual host support. Using the http_port number
- in passed on Host: headers.
+ vport Virtual host port support. Using the http_port number
+ instead of the port passed on Host: headers.
- vport=NN Uses the specified port number rather than the
- http_port number.
+ vport=NN Virtual host port support. Using the specified port
+ number instead of the port passed on Host: headers.
- protocol= Protocol to reconstruct accelerated requests with.
- Defaults to http://.
+ act-as-origin
+ 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-cc Ignore request Cache-Control headers.
- Warning: This option violates HTTP specifications if
+ WARNING: This option violates HTTP specifications if
used in non-accelerator setups.
+ allow-direct 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:
DEFAULT: none
LOC: Config.Sockaddr.https
DOC_START
- Usage: [ip:]port cert=certificate.pem [key=key.pem] [options...]
+ Usage: [ip:]port cert=certificate.pem [key=key.pem] [mode] [options...]
The socket address where Squid will listen for HTTPS client
requests.
You may specify multiple socket addresses on multiple lines,
each with their own SSL certificate and/or options.
- Options:
+ Modes:
- accel Accelerator mode. Also needs at least one of
- defaultsite or vhost.
+ accel Accelerator / reverse proxy mode
- defaultsite= The name of the https site presented on
- this port. Implies accel.
+ Omitting the mode flag causes default forward proxy mode to be used.
- vhost Accelerator mode using Host header for virtual
- domain support. Requires a wildcard certificate
- or other certificate valid for more than one domain.
- Implies accel.
- protocol= Protocol to reconstruct accelerated requests with.
- Defaults to https.
+ See http_port for a list of generic options
+
+
+ SSL Options:
cert= Path to SSL certificate (PEM format).
sslcontext= SSL session ID context identifier.
- vport Accelerator with IP based virtual host support.
-
- vport=NN As above, but uses specified port number rather
- than the https_port number. Implies accel.
-
- name= Specifies a internal name for the port. Defaults to
- the port specification (port or addr:port)
-
DOC_END
NAME: tcp_outgoing_tos tcp_outgoing_ds tcp_outgoing_dscp
tcp_outgoing_address ipaddr [[!]aclname] ...
- Example where requests from 10.0.0.0/24 will be forwarded
- with source address 10.1.0.1, 10.0.2.0/24 forwarded with
- source address 10.1.0.2 and the rest will be forwarded with
- source address 10.1.0.3.
+ For example;
+ Forwarding clients with dedicated IPs for certain subnets.
- acl normal_service_net src 10.0.0.0/24
- acl good_service_net src 10.0.2.0/24
- tcp_outgoing_address 10.1.0.1 normal_service_net
- tcp_outgoing_address 10.1.0.2 good_service_net
- tcp_outgoing_address 10.1.0.3
+ acl normal_service_net src 10.0.0.0/24
+ acl good_service_net src 10.0.2.0/24
+
+ tcp_outgoing_address 2001:db8::c001 good_service_net
+ tcp_outgoing_address 10.1.0.2 good_service_net
+
+ tcp_outgoing_address 2001:db8::beef normal_service_net
+ tcp_outgoing_address 10.1.0.1 normal_service_net
+
+ tcp_outgoing_address 2001:db8::1
+ tcp_outgoing_address 10.1.0.3
Processing proceeds in the order specified, and stops at first fully
matching line.
- Note: The use of this directive using client dependent ACLs is
+ 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
+ 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 to
- re-enable normal forwarding such as this.
-
- IPv6 Magic:
-
- Squid is built with a capability of bridging the IPv4 and IPv6
- internets.
- tcp_outgoing_address as exampled above breaks this bridging by forcing
- all outbound traffic through a certain IPv4 which may be on the wrong
- side of the IPv4/IPv6 boundary.
-
- To operate with tcp_outgoing_address and keep the bridging benefits
- an additional ACL needs to be used which ensures the IPv6-bound traffic
- is never forced or permitted out the IPv4 interface.
-
- # IPv6 destination test along with a dummy access control to perofrm the required DNS
- # This MUST be place before any ALLOW rules.
- acl to_ipv6 dst ipv6
- http_access deny ipv6 !all
-
- tcp_outgoing_address 2001:db8::c001 good_service_net to_ipv6
- tcp_outgoing_address 10.1.0.2 good_service_net !to_ipv6
+ 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.
- tcp_outgoing_address 2001:db8::beef normal_service_net to_ipv6
- tcp_outgoing_address 10.1.0.1 normal_service_net !to_ipv6
-
- tcp_outgoing_address 2001:db8::1 to_ipv6
- tcp_outgoing_address 10.1.0.3 !to_ipv6
-
- WARNING:
- 'dst ipv6' bases its selection assuming DIRECT access.
- If peers are used the peername ACL are needed to select outgoing
- address which can link to the peer.
+DOC_END
- 'dst ipv6' is a slow ACL. It will only work here if 'dst' is used
- previously in the http_access rules to locate the destination IP.
- Some more magic may be needed for that:
- http_access allow to_ipv6 !all
- (meaning, allow if to IPv6 but not from anywhere ;)
+NAME: client_dst_passthru
+TYPE: onoff
+DEFAULT: on
+LOC: Config.onoff.client_dst_passthru
+DOC_START
+ With NAT or TPROXY intercepted traffic Squid may pass the request
+ directly to the original client destination IP or seek a faster
+ source.
+
+ This option (on by default) prevents cache_peer and alternative DNS
+ entries being used on intercepted traffic. Both of which lead to
+ the security vulnerability outlined below.
+
+ SECURITY WARNING:
+
+ This directive should only be disabled if cache_peer are required.
+
+ As described in CVE-2009-0801 when the Host: header alone is used
+ to determine the destination of a request it becomes trivial for
+ malicious scripts on remote websites to bypass browser same-origin
+ security policy and sandboxing protections.
+
+ The cause of this is that such applets are allowed to perform their
+ own HTTP stack, in which case the same-origin policy of the browser
+ sandbox only verifies that the applet tries to contact the same IP
+ as from where it was loaded at the IP level. The Host: header may
+ be different from the connected IP and approved origin.
DOC_END
than the Squid default location.
+ ==== CARP OPTIONS ====
+
+ carp-key=key-specification
+ use a different key than the full URL to hash against the peer.
+ the key-specification is a comma-separated list of the keywords
+ scheme, host, port, path, params
+ Order is not important.
+
==== ACCELERATOR / REVERSE-PROXY OPTIONS ====
originserver Causes this parent to be contacted as an origin server.
The first principal from the default keytab or defined by
the environment variable KRB5_KTNAME will be used.
+ WARNING: The connection may transmit requests from multiple
+ clients. Negotiate often assumes end-to-end authentication
+ and a single-client. Which is not strictly true here.
+
login=NEGOTIATE:principal_name
If this is a personal/workgroup proxy and your parent
requires a secure proxy authentication.
defined by the environment variable KRB5_KTNAME will be
used.
+ WARNING: The connection may transmit requests from multiple
+ clients. Negotiate often assumes end-to-end authentication
+ and a single-client. Which is not strictly true here.
+
connection-auth=on|off
Tell Squid that this peer does or not support Microsoft
connection oriented authentication, and any such
be handled directly by this cache. In other words, use this
to not query neighbor caches for certain objects. You may
list this option multiple times.
- Note: never_direct overrides this option.
-NOCOMMENT_START
-# We recommend you to use at least the following line.
-hierarchy_stoplist cgi-bin ?
-NOCOMMENT_END
+ Example:
+ hierarchy_stoplist cgi-bin ?
+
+ Note: never_direct overrides this option.
DOC_END
COMMENT_START
>a Client source IP address
>A Client FQDN
>p Client source port
- >eui Client EUI (MAC address, EUI-48 or EUI-64 identifier)
- <A Server IP address or peer name
- la Local IP address (http_port)
- lp Local port number (http_port)
+ >eui Client source EUI (MAC address, EUI-48 or EUI-64 identifier)
+ >la Local IP address the client connected to
+ >lp Local port number the client connected to
+
+ <a Server IP address of the last server or peer connection
+ <A Server FQDN or peer name
+ <p Server port number of the last server or peer connection
<la Local IP address of the last server or peer connection
<lp Local port number of the last server or peer connection
tr Response time (milliseconds)
dt Total time spent making DNS lookups (milliseconds)
- HTTP cache related format codes:
+ Access Control related format codes:
+
+ et Tag returned by external acl
+ ea Log string returned by external acl
+ un User name (any available)
+ ul User name from authentication
+ ue User name from external acl helper
+ ui User name from ident
+ us User name from SSL
+
+ HTTP related format codes:
[http::]>h Original request header. Optional header name argument
on the format header[:[separator]element]
Optional header name argument as for >h
[http::]<h Reply header. Optional header name argument
as for >h
- [http::]un User name
- [http::]ul User name from authentication
- [http::]ui User name from ident
- [http::]us User name from SSL
- [http::]ue User name from external acl helper
[http::]>Hs HTTP status code sent to the client
[http::]<Hs HTTP status code received from the next hop
[http::]<bs Number of HTTP-equivalent message body bytes
transfer encoding and control messages.
Generated FTP/Gopher listings are treated as
received bodies.
- [http::]Ss Squid request status (TCP_MISS etc)
- [http::]Sh Squid hierarchy status (DEFAULT_PARENT etc)
[http::]mt MIME content type
[http::]rm Request method (GET/POST etc)
- [http::]ru Request URL
+ [http::]>rm Request method from client
+ [http::]<rm Request method sent to server or peer
+ [http::]ru Request URL from client (historic, filtered for logging)
+ [http::]>ru Request URL from client
+ [http::]<ru Request URL sent to server or peer
[http::]rp Request URL-Path excluding hostname
+ [http::]>rp Request URL-Path excluding hostname from client
+ [http::]<rp Request URL-Path excluding hostname sento to server or peer
[http::]rv Request protocol version
- [http::]et Tag returned by external acl
- [http::]ea Log string returned by external acl
+ [http::]>rv Request protocol version from client
+ [http::]<rv Request protocol version sent to server or peer
[http::]<st Sent reply size including HTTP headers
[http::]>st Received request size including HTTP headers. In the
case of chunked requests the chunked encoding metadata
sent to the first selected peer. The timer stops
with the last I/O with the last peer.
+ Squid handling related format codes:
+
+ Ss Squid request status (TCP_MISS etc)
+ Sh Squid hierarchy status (DEFAULT_PARENT etc)
+
If ICAP is enabled, the following code becomes available (as
well as ICAP log codes documented with the icap_log option):
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 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"
- 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: 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.
- 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.
DOC_END
NAME: access_log cache_access_log
DOC_END
NAME: log_ip_on_direct
-COMMENT: on|off
-TYPE: onoff
-DEFAULT: on
-LOC: Config.onoff.log_ip_on_direct
+TYPE: obsolete
DOC_START
- Log the destination IP address in the hierarchy log tag when going
- direct. Earlier Squid versions logged the hostname here. If you
- prefer the old way set this to off.
+ Remove this option from your config. To log server or peer names use %<A in the log format.
DOC_END
NAME: mime_table
DOC_NONE
NAME: announce_port
-TYPE: ushort
+TYPE: u_short
DEFAULT: 3131
LOC: Config.Announce.port
DOC_START
NAME: delay_initial_bucket_level
COMMENT: (percent, 0-100)
-TYPE: ushort
+TYPE: u_short
DEFAULT: 50
IFDEF: USE_DELAY_POOLS
LOC: Config.Delay.initial
NAME: client_delay_initial_bucket_level
COMMENT: (percent, 0-no_limit)
-TYPE: ushort
+TYPE: u_short
DEFAULT: 50
IFDEF: USE_DELAY_POOLS
LOC: Config.ClientDelay.initial
COMMENT_END
NAME: snmp_port
-TYPE: ushort
+TYPE: u_short
LOC: Config.Port.snmp
DEFAULT: 0
IFDEF: SQUID_SNMP
COMMENT_END
NAME: icp_port udp_port
-TYPE: ushort
+TYPE: u_short
DEFAULT: 0
LOC: Config.Port.icp
DOC_START
NAME: htcp_port
IFDEF: USE_HTCP
-TYPE: ushort
+TYPE: u_short
DEFAULT: 0
LOC: Config.Port.htcp
DOC_START
NAME: mcast_miss_ttl
IFDEF: MULTICAST_MISS_STREAM
-TYPE: ushort
+TYPE: u_short
LOC: Config.mcast_miss.ttl
DEFAULT: 16
DOC_START
NAME: mcast_miss_port
IFDEF: MULTICAST_MISS_STREAM
-TYPE: ushort
+TYPE: u_short
LOC: Config.mcast_miss.port
DEFAULT: 3135
DOC_START
(HTTPS URLs terminate with *)
%u - Full canonical URL from client
%w - Admin email from squid.conf
+ %x - Error name
%% - Literal percent (%) code
DOC_END
is to use IPv4-only connections. When set to 'on' this option will
make Squid use IPv6-only connections to contact this ICAP service.
+ on-overload=block|bypass|wait|force
+ If the service Max-Connections limit has been reached, do
+ one of the following for each new ICAP transaction:
+ * block: send an HTTP error response to the client
+ * bypass: ignore the "over-connected" ICAP service
+ * wait: wait (in a FIFO queue) for an ICAP connection slot
+ * force: proceed, ignoring the Max-Connections limit
+
+ In SMP mode with N workers, each worker assumes the service
+ connection limit is Max-Connections/N, even though not all
+ workers may use a given service.
+
+ The default value is "bypass" if service is bypassable,
+ otherwise it is set to "wait".
+
+
+ max-conn=number
+ Use the given number as the Max-Connections limit, regardless
+ of the Max-Connections value given by the service, if any.
+
Older icap_service format without optional named parameters is
deprecated but supported for backward compatibility.