725
NAME: follow_x_forwarded_for
727
IFDEF: FOLLOW_X_FORWARDED_FOR
728
LOC: Config.accessList.followXFF
730
DEFAULT_IF_NONE: deny all
732
Allowing or Denying the X-Forwarded-For header to be followed to
733
find the original source of a request.
735
Requests may pass through a chain of several other proxies
736
before reaching us. The X-Forwarded-For header will contain a
737
comma-separated list of the IP addresses in the chain, with the
738
rightmost address being the most recent.
740
If a request reaches us from a source that is allowed by this
741
configuration item, then we consult the X-Forwarded-For header
742
to see where that host received the request from. If the
743
X-Forwarded-For header contains multiple addresses, and if
744
acl_uses_indirect_client is on, then we continue backtracking
745
until we reach an address for which we are not allowed to
746
follow the X-Forwarded-For header, or until we reach the first
747
address in the list. (If acl_uses_indirect_client is off, then
748
it's impossible to backtrack through more than one level of
749
X-Forwarded-For addresses.)
751
The end result of this process is an IP address that we will
752
refer to as the indirect client address. This address may
753
be treated as the client address for access control, ICAP, delay
754
pools and logging, depending on the acl_uses_indirect_client,
755
icap_uses_indirect_client, delay_pool_uses_indirect_client and
756
log_uses_indirect_client options.
758
This clause only supports fast acl types.
759
See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details.
761
SECURITY CONSIDERATIONS:
763
Any host for which we follow the X-Forwarded-For header
764
can place incorrect information in the header, and Squid
765
will use the incorrect information as if it were the
766
source address of the request. This may enable remote
767
hosts to bypass any access control restrictions that are
768
based on the client's source addresses.
772
acl localhost src 127.0.0.1
773
acl my_other_proxy srcdomain .proxy.example.com
774
follow_x_forwarded_for allow localhost
775
follow_x_forwarded_for allow my_other_proxy
778
NAME: acl_uses_indirect_client
781
IFDEF: FOLLOW_X_FORWARDED_FOR
783
LOC: Config.onoff.acl_uses_indirect_client
785
Controls whether the indirect client address
786
(see follow_x_forwarded_for) is used instead of the
787
direct client address in acl matching.
790
NAME: delay_pool_uses_indirect_client
793
IFDEF: FOLLOW_X_FORWARDED_FOR&&DELAY_POOLS
795
LOC: Config.onoff.delay_pool_uses_indirect_client
797
Controls whether the indirect client address
798
(see follow_x_forwarded_for) is used instead of the
799
direct client address in delay pools.
802
NAME: log_uses_indirect_client
805
IFDEF: FOLLOW_X_FORWARDED_FOR
807
LOC: Config.onoff.log_uses_indirect_client
809
Controls whether the indirect client address
810
(see follow_x_forwarded_for) is used instead of the
811
direct client address in the access log.
659
814
NAME: http_access
661
816
LOC: Config.accessList.http
1282
1666
LOC: Config.peers
1284
1668
To specify other caches in a hierarchy, use the format:
1286
1670
cache_peer hostname type http-port icp-port [options]
1291
1675
# hostname type port port options
1292
1676
# -------------------- -------- ----- ----- -----------
1293
cache_peer parent.foo.net parent 3128 3130 proxy-only default
1677
cache_peer parent.foo.net parent 3128 3130 default
1294
1678
cache_peer sib1.foo.net sibling 3128 3130 proxy-only
1295
1679
cache_peer sib2.foo.net sibling 3128 3130 proxy-only
1297
type: either 'parent', 'sibling', or 'multicast'.
1299
proxy-port: The port number where the cache listens for proxy
1302
icp-port: Used for querying neighbor caches about
1303
objects. To have a non-ICP neighbor
1304
specify '7' for the ICP port and make sure the
1305
neighbor machine has the UDP echo port
1306
enabled in its /etc/inetd.conf file.
1307
NOTE: Also requires icp_port option enabled to send/receive
1308
requests via this method.
1318
weighted-round-robin
1327
login=user:password | PASS | *:password
1338
sslcert=/path/to/ssl/certificate
1339
sslkey=/path/to/ssl/key
1343
front-end-https[=on|auto]
1345
use 'proxy-only' to specify objects fetched
1346
from this cache should not be saved locally.
1348
use 'weight=n' to affect the selection of a peer
1349
during any weighted peer-selection mechanisms.
1350
The weight must be an integer; default is 1,
1351
larger weights are favored more.
1352
This option does not affect parent selection if a peering
1353
protocol is not in use.
1355
use 'basetime=n' to specify a base amount to
1356
be subtracted from round trip times of parents.
1357
It is subtracted before division by weight in calculating
1358
which parent to fectch from. If the rtt is less than the
1359
base time the rtt is set to a minimal value.
1361
use 'ttl=n' to specify a IP multicast TTL to use
1362
when sending an ICP queries to this address.
1363
Only useful when sending to a multicast group.
1364
Because we don't accept ICP replies from random
1365
hosts, you must configure other group members as
1366
peers with the 'multicast-responder' option below.
1368
use 'no-query' to NOT send ICP queries to this
1371
use 'background-ping' to only send ICP queries to this
1372
neighbor infrequently. This is used to keep the neighbor
1373
round trip time updated and is usually used in
1374
conjunction with weighted-round-robin.
1376
use 'default' if this is a parent cache which can
1377
be used as a "last-resort" if a peer cannot be located
1378
by any of the peer-selection mechanisms.
1379
If specified more than once, only the first is used.
1381
use 'round-robin' to define a set of parents which
1382
should be used in a round-robin fashion in the
1383
absence of any ICP queries.
1385
use 'weighted-round-robin' to define a set of parents
1386
which should be used in a round-robin fashion with the
1387
frequency of each parent being based on the round trip
1388
time. Closer parents are used more often.
1389
Usually used for background-ping parents.
1391
use 'carp' to define a set of parents which should
1392
be used as a CARP array. The requests will be
1393
distributed among the parents based on the CARP load
1394
balancing hash function based on their weight.
1396
use 'userhash' to load-balance amongst a set of parents
1397
based on the client proxy_auth or ident username.
1399
use 'sourcehash' to load-balance amongst a set of parents
1400
based on the client source ip.
1402
'multicast-responder' indicates the named peer
1403
is a member of a multicast group. ICP queries will
1404
not be sent directly to the peer, but ICP replies
1405
will be accepted from it.
1407
'closest-only' indicates that, for ICP_OP_MISS
1408
replies, we'll only forward CLOSEST_PARENT_MISSes
1409
and never FIRST_PARENT_MISSes.
1411
use 'no-digest' to NOT request cache digests from
1414
'no-netdb-exchange' disables requesting ICMP
1415
RTT database (NetDB) from the neighbor.
1417
use 'no-delay' to prevent access to this neighbor
1418
from influencing the delay pools.
1420
use 'login=user:password' if this is a personal/workgroup
1421
proxy and your parent requires proxy authentication.
1422
Note: The string can include URL escapes (i.e. %20 for
1423
spaces). This also means % must be written as %%.
1425
use 'login=PASS' if users must authenticate against
1426
the upstream proxy or in the case of a reverse proxy
1427
configuration, the origin web server. This will pass
1428
the users credentials as they are to the peer.
1429
This only works for the Basic HTTP authentication scheme.
1430
Note: To combine this with proxy_auth both proxies must
1431
share the same user database as HTTP only allows for
1432
a single login (one for proxy, one for origin server).
1433
Also be warned this will expose your users proxy
1434
password to the peer. USE WITH CAUTION
1436
use 'login=*:password' to pass the username to the
1437
upstream cache, but with a fixed password. This is meant
1438
to be used when the peer is in another administrative
1439
domain, but it is still needed to identify each user.
1440
The star can optionally be followed by some extra
1441
information which is added to the username. This can
1442
be used to identify this proxy to the peer, similar to
1443
the login=username:password option above.
1445
use 'connect-timeout=nn' to specify a peer
1446
specific connect timeout (also see the
1447
peer_connect_timeout directive)
1449
use 'digest-url=url' to tell Squid to fetch the cache
1450
digest (if digests are enabled) for this host from
1451
the specified URL rather than the Squid default
1454
use 'allow-miss' to disable Squid's use of only-if-cached
1455
when forwarding requests to siblings. This is primarily
1456
useful when icp_hit_stale is used by the sibling. To
1457
extensive use of this option may result in forwarding
1458
loops, and you should avoid having two-way peerings
1459
with this option. (for example to deny peer usage on
1460
requests from peer by denying cache_peer_access if the
1463
use 'max-conn=n' to limit the amount of connections Squid
1464
may open to this peer.
1466
use 'htcp' to send HTCP, instead of ICP, queries
1467
to the neighbor. You probably also want to
1468
set the "icp port" to 4827 instead of 3130.
1469
You MUST also set htcp_access expicitly. The default of
1470
deny all will prevent peer traffic.
1472
use 'htcp-oldsquid' to send HTCP to old Squid versions
1473
You MUST also set htcp_access expicitly. The default of
1474
deny all will prevent peer traffic.
1476
'originserver' causes this parent peer to be contacted as
1477
a origin server. Meant to be used in accelerator setups.
1479
use 'name=xxx' if you have multiple peers on the same
1480
host but different ports. This name can be used to
1481
differentiate the peers in cache_peer_access and similar
1484
use 'forceddomain=name' to forcibly set the Host header
1485
of requests forwarded to this peer. Useful in accelerator
1486
setups where the server (peer) expects a certain domain
1487
name and using redirectors to feed this domain name
1490
use 'ssl' to indicate connections to this peer should
1491
be SSL/TLS encrypted.
1493
use 'sslcert=/path/to/ssl/certificate' to specify a client
1494
SSL certificate to use when connecting to this peer.
1496
use 'sslkey=/path/to/ssl/key' to specify the private SSL
1497
key corresponding to sslcert above. If 'sslkey' is not
1498
specified 'sslcert' is assumed to reference a
1499
combined file containing both the certificate and the key.
1501
use sslversion=1|2|3|4 to specify the SSL version to use
1502
when connecting to this peer
1503
1 = automatic (default)
1508
use sslcipher=... to specify the list of valid SSL ciphers
1509
to use when connecting to this peer.
1511
use ssloptions=... to specify various SSL engine options:
1512
NO_SSLv2 Disallow the use of SSLv2
1513
NO_SSLv3 Disallow the use of SSLv3
1514
NO_TLSv1 Disallow the use of TLSv1
1515
See src/ssl_support.c or the OpenSSL documentation for
1516
a more complete list.
1518
use sslcafile=... to specify a file containing
1519
additional CA certificates to use when verifying the
1522
use sslcapath=... to specify a directory containing
1523
additional CA certificates to use when verifying the
1526
use sslcrlfile=... to specify a certificate revocation
1527
list file to use when verifying the peer certificate.
1529
use sslflags=... to specify various flags modifying the
1680
cache_peer example.com parent 80 0 no-query default
1681
cache_peer cdn.example.com sibling 3128 0
1683
type: either 'parent', 'sibling', or 'multicast'.
1685
proxy-port: The port number where the peer accept HTTP requests.
1686
For other Squid proxies this is usually 3128
1687
For web servers this is usually 80
1689
icp-port: Used for querying neighbor caches about objects.
1690
Set to 0 if the peer does not support ICP or HTCP.
1691
See ICP and HTCP options below for additional details.
1694
==== ICP OPTIONS ====
1696
You MUST also set icp_port and icp_access explicitly when using these options.
1697
The defaults will prevent peer traffic using ICP.
1700
no-query Disable ICP queries to this neighbor.
1703
Indicates the named peer is a member of a multicast group.
1704
ICP queries will not be sent directly to the peer, but ICP
1705
replies will be accepted from it.
1707
closest-only Indicates that, for ICP_OP_MISS replies, we'll only forward
1708
CLOSEST_PARENT_MISSes and never FIRST_PARENT_MISSes.
1711
To only send ICP queries to this neighbor infrequently.
1712
This is used to keep the neighbor round trip time updated
1713
and is usually used in conjunction with weighted-round-robin.
1716
==== HTCP OPTIONS ====
1718
You MUST also set htcp_port and htcp_access explicitly when using these options.
1719
The defaults will prevent peer traffic using HTCP.
1722
htcp Send HTCP, instead of ICP, queries to the neighbor.
1723
You probably also want to set the "icp-port" to 4827
1726
htcp-oldsquid Send HTCP to old Squid versions.
1728
htcp-no-clr Send HTCP to the neighbor but without
1729
sending any CLR requests. This cannot be used with
1732
htcp-only-clr Send HTCP to the neighbor but ONLY CLR requests.
1733
This cannot be used with htcp-no-clr.
1736
Send HTCP to the neighbor including CLRs but only when
1737
they do not result from PURGE requests.
1740
Forward any HTCP CLR requests this proxy receives to the peer.
1743
==== PEER SELECTION METHODS ====
1745
The default peer selection method is ICP, with the first responding peer
1746
being used as source. These options can be used for better load balancing.
1749
default This is a parent cache which can be used as a "last-resort"
1750
if a peer cannot be located by any of the peer-selection methods.
1751
If specified more than once, only the first is used.
1753
round-robin Load-Balance parents which should be used in a round-robin
1754
fashion in the absence of any ICP queries.
1755
weight=N can be used to add bias.
1757
weighted-round-robin
1758
Load-Balance parents which should be used in a round-robin
1759
fashion with the frequency of each parent being based on the
1760
round trip time. Closer parents are used more often.
1761
Usually used for background-ping parents.
1762
weight=N can be used to add bias.
1764
carp Load-Balance parents which should be used as a CARP array.
1765
The requests will be distributed among the parents based on the
1766
CARP load balancing hash function based on their weight.
1768
userhash Load-balance parents based on the client proxy_auth or ident username.
1770
sourcehash Load-balance parents based on the client source IP.
1773
To be used only for cache peers of type "multicast".
1774
ALL members of this multicast group have "sibling"
1775
relationship with it, not "parent". This is to a mulicast
1776
group when the requested object would be fetched only from
1777
a "parent" cache, anyway. It's useful, e.g., when
1778
configuring a pool of redundant Squid proxies, being
1779
members of the same multicast group.
1782
==== PEER SELECTION OPTIONS ====
1784
weight=N use to affect the selection of a peer during any weighted
1785
peer-selection mechanisms.
1786
The weight must be an integer; default is 1,
1787
larger weights are favored more.
1788
This option does not affect parent selection if a peering
1789
protocol is not in use.
1791
basetime=N Specify a base amount to be subtracted from round trip
1793
It is subtracted before division by weight in calculating
1794
which parent to fectch from. If the rtt is less than the
1795
base time the rtt is set to a minimal value.
1797
ttl=N Specify a IP multicast TTL to use when sending an ICP
1798
queries to this address.
1799
Only useful when sending to a multicast group.
1800
Because we don't accept ICP replies from random
1801
hosts, you must configure other group members as
1802
peers with the 'multicast-responder' option.
1804
no-delay To prevent access to this neighbor from influencing the
1807
digest-url=URL Tell Squid to fetch the cache digest (if digests are
1808
enabled) for this host from the specified URL rather
1809
than the Squid default location.
1812
==== ACCELERATOR / REVERSE-PROXY OPTIONS ====
1814
originserver Causes this parent to be contacted as an origin server.
1815
Meant to be used in accelerator setups when the peer
1819
Set the Host header of requests forwarded to this peer.
1820
Useful in accelerator setups where the server (peer)
1821
expects a certain domain name but clients may request
1822
others. ie example.com or www.example.com
1824
no-digest Disable request of cache digests.
1827
Disables requesting ICMP RTT database (NetDB).
1830
==== AUTHENTICATION OPTIONS ====
1833
If this is a personal/workgroup proxy and your parent
1834
requires proxy authentication.
1836
Note: The string can include URL escapes (i.e. %20 for
1837
spaces). This also means % must be written as %%.
1840
Send login details received from client to this peer.
1841
Authentication is not required, nor changed.
1843
Note: This will pass any form of authentication but
1844
only Basic auth will work through a proxy unless the
1845
connection-auth options are also used.
1847
login=PASS Send login details received from client to this peer.
1848
Authentication is not required by this option.
1849
If there are no client-provided authentication headers
1850
to pass on, but username and password are available
1851
from either proxy login or an external ACL user= and
1852
password= result tags they may be sent instead.
1854
Note: To combine this with proxy_auth both proxies must
1855
share the same user database as HTTP only allows for
1856
a single login (one for proxy, one for origin server).
1857
Also be warned this will expose your users proxy
1858
password to the peer. USE WITH CAUTION
1861
Send the username to the upstream cache, but with a
1862
fixed password. This is meant to be used when the peer
1863
is in another administrative domain, but it is still
1864
needed to identify each user.
1865
The star can optionally be followed by some extra
1866
information which is added to the username. This can
1867
be used to identify this proxy to the peer, similar to
1868
the login=username:password option above.
1870
connection-auth=on|off
1871
Tell Squid that this peer does or not support Microsoft
1872
connection oriented authentication, and any such
1873
challenges received from there should be ignored.
1874
Default is auto to automatically determine the status
1878
==== SSL / HTTPS / TLS OPTIONS ====
1880
ssl Encrypt connections to this peer with SSL/TLS.
1882
sslcert=/path/to/ssl/certificate
1883
A client SSL certificate to use when connecting to
1886
sslkey=/path/to/ssl/key
1887
The private SSL key corresponding to sslcert above.
1888
If 'sslkey' is not specified 'sslcert' is assumed to
1889
reference a combined file containing both the
1890
certificate and the key.
1893
The SSL version to use when connecting to this peer
1894
1 = automatic (default)
1899
sslcipher=... The list of valid SSL ciphers to use when connecting
1902
ssloptions=... Specify various SSL engine options:
1903
NO_SSLv2 Disallow the use of SSLv2
1904
NO_SSLv3 Disallow the use of SSLv3
1905
NO_TLSv1 Disallow the use of TLSv1
1906
See src/ssl_support.c or the OpenSSL documentation for
1907
a more complete list.
1909
sslcafile=... A file containing additional CA certificates to use
1910
when verifying the peer certificate.
1912
sslcapath=... A directory containing additional CA certificates to
1913
use when verifying the peer certificate.
1915
sslcrlfile=... A certificate revocation list file to use when
1916
verifying the peer certificate.
1918
sslflags=... Specify various flags modifying the SSL implementation:
1531
1920
DONT_VERIFY_PEER
1532
1921
Accept certificates even if they fail to
2003
2438
ts Seconds since epoch
2004
2439
tu subsecond time (milliseconds)
2005
2440
tl Local time. Optional strftime format argument
2006
default %d/%b/%Y:%H:%M:%S %z
2441
default %d/%b/%Y:%H:%M:%S %z
2007
2442
tg GMT time. Optional strftime format argument
2008
default %d/%b/%Y:%H:%M:%S %z
2443
default %d/%b/%Y:%H:%M:%S %z
2009
2444
tr Response time (milliseconds)
2010
>h Request header. Optional header name argument
2011
on the format header[:[separator]element]
2012
<h Reply header. Optional header name argument
2015
ul User name from authentication
2016
ui User name from ident
2017
us User name from SSL
2018
ue User name from external acl helper
2020
Ss Squid request status (TCP_MISS etc)
2021
Sh Squid hierarchy status (DEFAULT_PARENT etc)
2022
mt MIME content type
2023
rm Request method (GET/POST etc)
2025
rp Request URL-Path excluding hostname
2026
rv Request protocol version
2027
et Tag returned by external acl
2028
ea Log string returned by external acl
2029
<st Reply size including HTTP headers
2030
>st Request size including HTTP headers
2031
st Request+Reply size including HTTP headers
2032
<sH Reply high offset sent
2033
<sS Upstream object size
2034
% a literal % character
2445
dt Total time spent making DNS lookups (milliseconds)
2447
HTTP cache related format codes:
2449
[http::]>h Original request header. Optional header name argument
2450
on the format header[:[separator]element]
2451
[http::]>ha The HTTP request headers after adaptation and redirection.
2452
Optional header name argument as for >h
2453
[http::]<h Reply header. Optional header name argument
2455
[http::]un User name
2456
[http::]ul User name from authentication
2457
[http::]ui User name from ident
2458
[http::]us User name from SSL
2459
[http::]ue User name from external acl helper
2460
[http::]>Hs HTTP status code sent to the client
2461
[http::]<Hs HTTP status code received from the next hop
2462
[http::]Ss Squid request status (TCP_MISS etc)
2463
[http::]Sh Squid hierarchy status (DEFAULT_PARENT etc)
2464
[http::]mt MIME content type
2465
[http::]rm Request method (GET/POST etc)
2466
[http::]ru Request URL
2467
[http::]rp Request URL-Path excluding hostname
2468
[http::]rv Request protocol version
2469
[http::]et Tag returned by external acl
2470
[http::]ea Log string returned by external acl
2471
[http::]<st Sent reply size including HTTP headers
2472
[http::]>st Received request size including HTTP headers. In the
2473
case of chunked requests the chunked encoding metadata
2475
[http::]>sh Received HTTP request headers size
2476
[http::]<sh Sent HTTP reply headers size
2477
[http::]st Request+Reply size including HTTP headers
2478
[http::]<sH Reply high offset sent
2479
[http::]<sS Upstream object size
2480
[http::]<pt Peer response time in milliseconds. The timer starts
2481
when the last request byte is sent to the next hop
2482
and stops when the last response byte is received.
2483
[http::]<tt Total server-side time in milliseconds. The timer
2484
starts with the first connect request (or write I/O)
2485
sent to the first selected peer. The timer stops
2486
with the last I/O with the last peer.
2488
If ICAP is enabled, the following two codes become available (as
2489
well as ICAP log codes documented with the icap_log option):
2491
icap::tt Total ICAP processing time for the HTTP
2492
transaction. The timer ticks when ICAP
2493
ACLs are checked and when ICAP
2494
transaction is in progress.
2496
icap::<last_h The header of the last ICAP response
2497
related to the HTTP transaction. Like
2498
<h, accepts an optional header name
2499
argument. Will not change semantics
2500
when multiple ICAP transactions per HTTP
2501
transaction are supported.
2503
If adaptation is enabled the following two codes become available:
2505
adapt::sum_trs Summed adaptation transaction response
2506
times recorded as a comma-separated list in
2507
the order of transaction start time. Each time
2508
value is recorded as an integer number,
2509
representing response time of one or more
2510
adaptation (ICAP or eCAP) transaction in
2511
milliseconds. When a failed transaction is
2512
being retried or repeated, its time is not
2513
logged individually but added to the
2514
replacement (next) transaction. See also:
2517
adapt::all_trs All adaptation transaction response times.
2518
Same as adaptation_strs but response times of
2519
individual transactions are never added
2520
together. Instead, all transaction response
2521
times are recorded individually.
2523
You can prefix adapt::*_trs format codes with adaptation
2524
service name in curly braces to record response time(s) specific
2525
to that service. For example: %{my_service}adapt::sum_trs
2036
2527
The default formats available (which do not need re-defining) are:
2038
logformat squid %ts.%03tu %6tr %>a %Ss/%03Hs %<st %rm %ru %un %Sh/%<A %mt
2039
logformat squidmime %ts.%03tu %6tr %>a %Ss/%03Hs %<st %rm %ru %un %Sh/%<A %mt [%>h] [%<h]
2040
logformat common %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %Hs %<st %Ss:%Sh
2041
logformat combined %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh
2529
logformat squid %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %un %Sh/%<A %mt
2530
logformat squidmime %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %un %Sh/%<A %mt [%>h] [%<h]
2531
logformat common %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st %Ss:%Sh
2532
logformat combined %>a %ui %un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh
2044
2535
NAME: access_log cache_access_log
2045
2536
TYPE: access_log
2046
2537
LOC: Config.Log.accesslogs
2539
DEFAULT_IF_NONE: @DEFAULT_ACCESS_LOG@ squid
2049
2541
These files log client request activities. Has a line every HTTP or
2050
2542
ICP request. The format is:
2068
2560
And priority could be any of:
2069
2561
err, warning, notice, info, debug.
2071
access_log @DEFAULT_ACCESS_LOG@ squid
2564
access_log @DEFAULT_ACCESS_LOG@ squid
2570
LOC: Config.Log.icaplogs
2573
ICAP log files record ICAP transaction summaries, one line per
2576
The icap_log option format is:
2577
icap_log <filepath> [<logformat name> [acl acl ...]]
2578
icap_log none [acl acl ...]]
2580
Please see access_log option documentation for details. The two
2581
kinds of logs share the overall configuration approach and many
2584
ICAP processing of a single HTTP message or transaction may
2585
require multiple ICAP transactions. In such cases, multiple
2586
ICAP transaction log lines will correspond to a single access
2589
ICAP log uses logformat codes that make sense for an ICAP
2590
transaction. Header-related codes are applied to the HTTP header
2591
embedded in an ICAP server response, with the following caveats:
2592
For REQMOD, there is no HTTP response header unless the ICAP
2593
server performed request satisfaction. For RESPMOD, the HTTP
2594
request header is the header sent to the ICAP server. For
2595
OPTIONS, there are no HTTP headers.
2597
The following format codes are also available for ICAP logs:
2599
icap::<A ICAP server IP address. Similar to <A.
2601
icap::<service_name ICAP service name from the icap_service
2602
option in Squid configuration file.
2604
icap::ru ICAP Request-URI. Similar to ru.
2606
icap::rm ICAP request method (REQMOD, RESPMOD, or
2607
OPTIONS). Similar to existing rm.
2609
icap::>st Bytes sent to the ICAP server (TCP payload
2610
only; i.e., what Squid writes to the socket).
2612
icap::<st Bytes received from the ICAP server (TCP
2613
payload only; i.e., what Squid reads from
2616
icap::tr Transaction response time (in
2617
milliseconds). The timer starts when
2618
the ICAP transaction is created and
2619
stops when the transaction is completed.
2622
icap::tio Transaction I/O time (in milliseconds). The
2623
timer starts when the first ICAP request
2624
byte is scheduled for sending. The timers
2625
stops when the last byte of the ICAP response
2628
icap::to Transaction outcome: ICAP_ERR* for all
2629
transaction errors, ICAP_OPT for OPTION
2630
transactions, ICAP_ECHO for 204
2631
responses, ICAP_MOD for message
2632
modification, and ICAP_SAT for request
2633
satisfaction. Similar to Ss.
2635
icap::Hs ICAP response status code. Similar to Hs.
2637
icap::>h ICAP request header(s). Similar to >h.
2639
icap::<h ICAP response header(s). Similar to <h.
2641
The default ICAP log format, which can be used without an explicit
2642
definition, is called icap_squid:
2644
logformat icap_squid %ts.%03tu %6icap::tr %>a %icap::to/%03icap::Hs %icap::<size %icap::rm %icap::ru% %un -/%icap::<A -
2646
See also: logformat, log_icap, and %icap::<last_h
2075
2649
NAME: log_access
4923
5743
NAME: icap_service
4924
5744
TYPE: icap_service_type
4925
5745
IFDEF: ICAP_CLIENT
4929
Defines a single ICAP service
4931
icap_service servicename vectoring_point bypass service_url
5746
LOC: Adaptation::Icap::TheConfig
5749
Defines a single ICAP service using the following format:
5751
icap_service service_name vectoring_point [options] service_url
5754
an opaque identifier which must be unique in squid.conf
5756
vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
5757
This specifies at which point of transaction processing the
5758
ICAP service should be activated. *_postcache vectoring points
5759
are not yet supported.
5761
service_url: icap://servername:port/servicepath
5762
ICAP server and service location.
5764
ICAP does not allow a single service to handle both REQMOD and RESPMOD
5765
transactions. Squid does not enforce that requirement. You can specify
5766
services with the same service_url and different vectoring_points. You
5767
can even specify multiple identical services as long as their
5768
service_names differ.
5771
Service options are separated by white space. ICAP services support
5772
the following name=value options:
5775
If set to 'on' or '1', the ICAP service is treated as
5776
optional. If the service cannot be reached or malfunctions,
5777
Squid will try to ignore any errors and process the message as
5778
if the service was not enabled. No all ICAP errors can be
5779
bypassed. If set to 0, the ICAP service is treated as
5780
essential and all ICAP errors will result in an error page
5781
returned to the HTTP client.
5783
Bypass is off by default: services are treated as essential.
5786
If set to 'on' or '1', the ICAP service is allowed to
5787
dynamically change the current message adaptation plan by
5788
returning a chain of services to be used next. The services
5789
are specified using the X-Next-Services ICAP response header
5790
value, formatted as a comma-separated list of service names.
5791
Each named service should be configured in squid.conf and
5792
should have the same method and vectoring point as the current
5793
ICAP transaction. Services violating these rules are ignored.
5794
An empty X-Next-Services value results in an empty plan which
5795
ends the current adaptation.
5797
Routing is not allowed by default: the ICAP X-Next-Services
5798
response header is ignored.
5800
Older icap_service format without optional named parameters is
5801
deprecated but supported for backward compatibility.
5804
icap_service svcBlocker reqmod_precache bypass=0 icap://icap1.mydomain.net:1344/reqmod
5805
icap_service svcLogger reqmod_precache routing=on icap://icap2.mydomain.net:1344/respmod
5809
TYPE: icap_class_type
5814
This deprecated option was documented to define an ICAP service
5815
chain, even though it actually defined a set of similar, redundant
5816
services, and the chains were not supported.
5818
To define a set of redundant services, please use the
5819
adaptation_service_set directive. For service chains, use
5820
adaptation_service_chain.
5824
TYPE: icap_access_type
5829
This option is deprecated. Please use adaptation_access, which
5830
has the same ICAP functionality, but comes with better
5831
documentation, and eCAP support.
5836
-----------------------------------------------------------------------------
5843
LOC: Adaptation::Ecap::TheConfig.onoff
5846
Controls whether eCAP support is enabled.
5850
TYPE: ecap_service_type
5852
LOC: Adaptation::Ecap::TheConfig
5855
Defines a single eCAP service
5857
ecap_service servicename vectoring_point bypass service_url
4933
5859
vectoring_point = reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache
4934
5860
This specifies at which point of transaction processing the
4935
ICAP service should be activated. *_postcache vectoring points
5861
eCAP service should be activated. *_postcache vectoring points
4936
5862
are not yet supported.
4938
If set to 1, the ICAP service is treated as optional. If the
5864
If set to 1, the eCAP service is treated as optional. If the
4939
5865
service cannot be reached or malfunctions, Squid will try to
4940
5866
ignore any errors and process the message as if the service
4941
was not enabled. No all ICAP errors can be bypassed.
4942
If set to 0, the ICAP service is treated as essential and all
4943
ICAP errors will result in an error page returned to the
5867
was not enabled. No all eCAP errors can be bypassed.
5868
If set to 0, the eCAP service is treated as essential and all
5869
eCAP errors will result in an error page returned to the
4945
service_url = icap://servername:port/service
4948
icap_service service_1 reqmod_precache 0 icap://icap1.mydomain.net:1344/reqmod
4949
icap_service service_2 respmod_precache 0 icap://icap2.mydomain.net:1344/respmod
4953
TYPE: icap_class_type
4958
Defines an ICAP service chain. Eventually, multiple services per
4959
vectoring point will be supported. For now, please specify a single
4962
icap_class classname servicename
4965
icap_class class_1 service_1
4966
icap class class_2 service_1
4967
icap class class_3 service_3
4971
TYPE: icap_access_type
4976
Redirects a request through an ICAP service class, depending
4979
icap_access classname allow|deny [!]aclname...
4981
The icap_access statements are processed in the order they appear in
4982
this configuration file. If an access list matches, the processing stops.
4983
For an "allow" rule, the specified class is used for the request. A "deny"
4984
rule simply stops processing without using the class. You can also use the
4985
special classname "None".
4987
For backward compatibility, it is also possible to use services
4990
icap_access class_1 allow all
5871
service_url = ecap://vendor/service_name?custom&cgi=style¶meters=optional
5874
ecap_service service_1 reqmod_precache 0 ecap://filters-R-us/leakDetector?on_error=block
5875
ecap_service service_2 respmod_precache 1 icap://filters-R-us/virusFilter?config=/etc/vf.cfg
5878
NAME: loadable_modules
5880
IFDEF: USE_LOADABLE_MODULES
5881
LOC: Config.loadable_module_names
5884
Instructs Squid to load the specified dynamic module(s) or activate
5885
preloaded module(s).
5887
loadable_modules @DEFAULT_PREFIX@/lib/MinimalAdapter.so
5891
MESSAGE ADAPTATION OPTIONS
5892
-----------------------------------------------------------------------------
5895
NAME: adaptation_service_set
5896
TYPE: adaptation_service_set_type
5897
IFDEF: USE_ADAPTATION
5902
Configures an ordered set of similar, redundant services. This is
5903
useful when hot standby or backup adaptation servers are available.
5905
adaptation_service_set set_name service_name1 service_name2 ...
5907
The named services are used in the set declaration order. The first
5908
applicable adaptation service from the set is used first. The next
5909
applicable service is tried if and only if the transaction with the
5910
previous service fails and the message waiting to be adapted is still
5913
When adaptation starts, broken services are ignored as if they were
5914
not a part of the set. A broken service is a down optional service.
5916
The services in a set must be attached to the same vectoring point
5917
(e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
5919
If all services in a set are optional then adaptation failures are
5920
bypassable. If all services in the set are essential, then a
5921
transaction failure with one service may still be retried using
5922
another service from the set, but when all services fail, the master
5923
transaction fails as well.
5925
A set may contain a mix of optional and essential services, but that
5926
is likely to lead to surprising results because broken services become
5927
ignored (see above), making previously bypassable failures fatal.
5928
Technically, it is the bypassability of the last failed service that
5931
See also: adaptation_access adaptation_service_chain
5934
adaptation_service_set svcBlocker urlFilterPrimary urlFilterBackup
5935
adaptation service_set svcLogger loggerLocal loggerRemote
5938
NAME: adaptation_service_chain
5939
TYPE: adaptation_service_chain_type
5940
IFDEF: USE_ADAPTATION
5945
Configures a list of complementary services that will be applied
5946
one-by-one, forming an adaptation chain or pipeline. This is useful
5947
when Squid must perform different adaptations on the same message.
5949
adaptation_service_chain chain_name service_name1 svc_name2 ...
5951
The named services are used in the chain declaration order. The first
5952
applicable adaptation service from the chain is used first. The next
5953
applicable service is applied to the successful adaptation results of
5954
the previous service in the chain.
5956
When adaptation starts, broken services are ignored as if they were
5957
not a part of the chain. A broken service is a down optional service.
5959
Request satisfaction terminates the adaptation chain because Squid
5960
does not currently allow declaration of RESPMOD services at the
5961
"reqmod_precache" vectoring point (see icap_service or ecap_service).
5963
The services in a chain must be attached to the same vectoring point
5964
(e.g., pre-cache) and use the same adaptation method (e.g., REQMOD).
5966
A chain may contain a mix of optional and essential services. If an
5967
essential adaptation fails (or the failure cannot be bypassed for
5968
other reasons), the master transaction fails. Otherwise, the failure
5969
is bypassed as if the failed adaptation service was not in the chain.
5971
See also: adaptation_access adaptation_service_set
5974
adaptation_service_chain svcRequest requestLogger urlFilter leakDetector
5977
NAME: adaptation_access
5978
TYPE: adaptation_access_type
5979
IFDEF: USE_ADAPTATION
5983
Sends an HTTP transaction to an ICAP or eCAP adaptation service.
5985
adaptation_access service_name allow|deny [!]aclname...
5986
adaptation_access set_name allow|deny [!]aclname...
5988
At each supported vectoring point, the adaptation_access
5989
statements are processed in the order they appear in this
5990
configuration file. Statements pointing to the following services
5991
are ignored (i.e., skipped without checking their ACL):
5993
- services serving different vectoring points
5994
- "broken-but-bypassable" services
5995
- "up" services configured to ignore such transactions
5996
(e.g., based on the ICAP Transfer-Ignore header).
5998
When a set_name is used, all services in the set are checked
5999
using the same rules, to find the first applicable one. See
6000
adaptation_service_set for details.
6002
If an access list is checked and there is a match, the
6003
processing stops: For an "allow" rule, the corresponding
6004
adaptation service is used for the transaction. For a "deny"
6005
rule, no adaptation service is activated.
6007
It is currently not possible to apply more than one adaptation
6008
service at the same vectoring point to the same HTTP transaction.
6010
See also: icap_service and ecap_service
6013
adaptation_access service_1 allow all
6016
NAME: adaptation_service_iteration_limit
6018
IFDEF: USE_ADAPTATION
6019
LOC: Adaptation::Config::service_iteration_limit
6022
Limits the number of iterations allowed when applying adaptation
6023
services to a message. If your longest adaptation set or chain
6024
may have more than 16 services, increase the limit beyond its
6025
default value of 16. If detecting infinite iteration loops sooner
6026
is critical, make the iteration limit match the actual number
6027
of services in your longest adaptation set or chain.
6029
Infinite adaptation loops are most likely with routing services.
6031
See also: icap_service routing=1
6034
NAME: adaptation_masterx_shared_names
6036
IFDEF: USE_ADAPTATION
6037
LOC: Adaptation::Config::masterx_shared_name
6040
For each master transaction (i.e., the HTTP request and response
6041
sequence, including all related ICAP and eCAP exchanges), Squid
6042
maintains a table of metadata. The table entries are (name, value)
6043
pairs shared among eCAP and ICAP exchanges. The table is destroyed
6044
with the master transaction.
6046
This option specifies the table entry names that Squid must accept
6047
from and forward to the adaptation transactions.
6049
An ICAP REQMOD or RESPMOD transaction may set an entry in the
6050
shared table by returning an ICAP header field with a name
6051
specified in adaptation_masterx_shared_names. Squid will store
6052
and forward that ICAP header field to subsequent ICAP
6053
transactions within the same master transaction scope.
6055
Only one shared entry name is supported at this time.
6058
# share authentication information among ICAP services
6059
adaptation_masterx_shared_names X-Subscriber-ID
6065
LOC: Adaptation::Icap::TheConfig.repeat
6067
DEFAULT_IF_NONE: deny all
6069
This ACL determines which retriable ICAP transactions are
6070
retried. Transactions that received a complete ICAP response
6071
and did not have to consume or produce HTTP bodies to receive
6072
that response are usually retriable.
6074
icap_retry allow|deny [!]aclname ...
6076
Squid automatically retries some ICAP I/O timeouts and errors
6077
due to persistent connection race conditions.
6079
See also: icap_retry_limit
6082
NAME: icap_retry_limit
6085
LOC: Adaptation::Icap::TheConfig.repeat_limit
6088
Limits the number of retries allowed. When set to zero (default),
6089
no retries are allowed.
6091
Communication errors due to persistent connection race
6092
conditions are unavoidable, automatically retried, and do not
6093
count against this limit.
6095
See also: icap_retry