1## Copyright (C) 1996-2021 The Squid Software Foundation and contributors 2## 3## Squid software is distributed under GPLv2+ license and includes 4## contributions from numerous individuals and organizations. 5## Please see the COPYING and CONTRIBUTORS files for details. 6## 7 8COMMENT_START 9 WELCOME TO @SQUID@ 10 ---------------------------- 11 12 This is the documentation for the Squid configuration file. 13 This documentation can also be found online at: 14 http://www.squid-cache.org/Doc/config/ 15 16 You may wish to look at the Squid home page and wiki for the 17 FAQ and other documentation: 18 http://www.squid-cache.org/ 19 http://wiki.squid-cache.org/SquidFaq 20 http://wiki.squid-cache.org/ConfigExamples 21 22 This documentation shows what the defaults for various directives 23 happen to be. If you don't need to change the default, you should 24 leave the line out of your squid.conf in most cases. 25 26 In some cases "none" refers to no default setting at all, 27 while in other cases it refers to the value of the option 28 - the comments for that keyword indicate if this is the case. 29 30COMMENT_END 31 32COMMENT_START 33 Configuration options can be included using the "include" directive. 34 Include takes a list of files to include. Quoting and wildcards are 35 supported. 36 37 For example, 38 39 include /path/to/included/file/squid.acl.config 40 41 Includes can be nested up to a hard-coded depth of 16 levels. 42 This arbitrary restriction is to prevent recursive include references 43 from causing Squid entering an infinite loop whilst trying to load 44 configuration files. 45 46 Values with byte units 47 48 Squid accepts size units on some size related directives. All 49 such directives are documented with a default value displaying 50 a unit. 51 52 Units accepted by Squid are: 53 bytes - byte 54 KB - Kilobyte (1024 bytes) 55 MB - Megabyte 56 GB - Gigabyte 57 58 Values with spaces, quotes, and other special characters 59 60 Squid supports directive parameters with spaces, quotes, and other 61 special characters. Surround such parameters with "double quotes". Use 62 the configuration_includes_quoted_values directive to enable or 63 disable that support. 64 65 Squid supports reading configuration option parameters from external 66 files using the syntax: 67 parameters("/path/filename") 68 For example: 69 acl whitelist dstdomain parameters("/etc/squid/whitelist.txt") 70 71 Conditional configuration 72 73 If-statements can be used to make configuration directives 74 depend on conditions: 75 76 if <CONDITION> 77 ... regular configuration directives ... 78 [else 79 ... regular configuration directives ...] 80 endif 81 82 The else part is optional. The keywords "if", "else", and "endif" 83 must be typed on their own lines, as if they were regular 84 configuration directives. 85 86 NOTE: An else-if condition is not supported. 87 88 These individual conditions types are supported: 89 90 true 91 Always evaluates to true. 92 false 93 Always evaluates to false. 94 <integer> = <integer> 95 Equality comparison of two integer numbers. 96 97 98 SMP-Related Macros 99 100 The following SMP-related preprocessor macros can be used. 101 102 ${process_name} expands to the current Squid process "name" 103 (e.g., squid1, squid2, or cache1). 104 105 ${process_number} expands to the current Squid process 106 identifier, which is an integer number (e.g., 1, 2, 3) unique 107 across all Squid processes of the current service instance. 108 109 ${service_name} expands into the current Squid service instance 110 name identifier which is provided by -n on the command line. 111 112 Logformat Macros 113 114 Logformat macros can be used in many places outside of the logformat 115 directive. In theory, all of the logformat codes can be used as %macros, 116 where they are supported. In practice, a %macro expands as a dash (-) when 117 the transaction does not yet have enough information and a value is needed. 118 119 There is no definitive list of what tokens are available at the various 120 stages of the transaction. 121 122 And some information may already be available to Squid but not yet 123 committed where the macro expansion code can access it (report 124 such instances!). The macro will be expanded into a single dash 125 ('-') in such cases. Not all macros have been tested. 126 127COMMENT_END 128 129# options still not yet ported from 2.7 to 3.x 130NAME: broken_vary_encoding 131TYPE: obsolete 132DOC_START 133 This option is not yet supported by Squid-3. 134DOC_END 135 136NAME: cache_vary 137TYPE: obsolete 138DOC_START 139 This option is not yet supported by Squid-3. 140DOC_END 141 142NAME: error_map 143TYPE: obsolete 144DOC_START 145 This option is not yet supported by Squid-3. 146DOC_END 147 148NAME: external_refresh_check 149TYPE: obsolete 150DOC_START 151 This option is not yet supported by Squid-3. 152DOC_END 153 154NAME: location_rewrite_program location_rewrite_access location_rewrite_children location_rewrite_concurrency 155TYPE: obsolete 156DOC_START 157 This option is not yet supported by Squid-3. 158DOC_END 159 160NAME: refresh_stale_hit 161TYPE: obsolete 162DOC_START 163 This option is not yet supported by Squid-3. 164DOC_END 165 166# Options removed in 4.x 167NAME: cache_peer_domain cache_host_domain 168TYPE: obsolete 169DOC_START 170 Replace with dstdomain ACLs and cache_peer_access. 171DOC_END 172 173NAME: ie_refresh 174TYPE: obsolete 175DOC_START 176 Remove this line. The behaviour enabled by this is no longer needed. 177DOC_END 178 179NAME: sslproxy_cafile 180TYPE: obsolete 181DOC_START 182 Remove this line. Use tls_outgoing_options cafile= instead. 183DOC_END 184 185NAME: sslproxy_capath 186TYPE: obsolete 187DOC_START 188 Remove this line. Use tls_outgoing_options capath= instead. 189DOC_END 190 191NAME: sslproxy_cipher 192TYPE: obsolete 193DOC_START 194 Remove this line. Use tls_outgoing_options cipher= instead. 195DOC_END 196 197NAME: sslproxy_client_certificate 198TYPE: obsolete 199DOC_START 200 Remove this line. Use tls_outgoing_options cert= instead. 201DOC_END 202 203NAME: sslproxy_client_key 204TYPE: obsolete 205DOC_START 206 Remove this line. Use tls_outgoing_options key= instead. 207DOC_END 208 209NAME: sslproxy_flags 210TYPE: obsolete 211DOC_START 212 Remove this line. Use tls_outgoing_options flags= instead. 213DOC_END 214 215NAME: sslproxy_options 216TYPE: obsolete 217DOC_START 218 Remove this line. Use tls_outgoing_options options= instead. 219DOC_END 220 221NAME: sslproxy_version 222TYPE: obsolete 223DOC_START 224 Remove this line. Use tls_outgoing_options options= instead. 225DOC_END 226 227# Options removed in 3.5 228NAME: hierarchy_stoplist 229TYPE: obsolete 230DOC_START 231 Remove this line. Use always_direct or cache_peer_access ACLs instead if you need to prevent cache_peer use. 232DOC_END 233 234# Options removed in 3.4 235NAME: log_access 236TYPE: obsolete 237DOC_START 238 Remove this line. Use acls with access_log directives to control access logging 239DOC_END 240 241NAME: log_icap 242TYPE: obsolete 243DOC_START 244 Remove this line. Use acls with icap_log directives to control icap logging 245DOC_END 246 247# Options Removed in 3.3 248NAME: ignore_ims_on_miss 249TYPE: obsolete 250DOC_START 251 Remove this line. The HTTP/1.1 feature is now configured by 'cache_miss_revalidate'. 252DOC_END 253 254# Options Removed in 3.2 255NAME: balance_on_multiple_ip 256TYPE: obsolete 257DOC_START 258 Remove this line. Squid performs a 'Happy Eyeballs' algorithm, this multiple-IP algorithm is not longer relevant. 259DOC_END 260 261NAME: chunked_request_body_max_size 262TYPE: obsolete 263DOC_START 264 Remove this line. Squid is now HTTP/1.1 compliant. 265DOC_END 266 267NAME: dns_v4_fallback 268TYPE: obsolete 269DOC_START 270 Remove this line. Squid performs a 'Happy Eyeballs' algorithm, the 'fallback' algorithm is no longer relevant. 271DOC_END 272 273NAME: emulate_httpd_log 274TYPE: obsolete 275DOC_START 276 Replace this with an access_log directive using the format 'common' or 'combined'. 277DOC_END 278 279NAME: forward_log 280TYPE: obsolete 281DOC_START 282 Use a regular access.log with ACL limiting it to MISS events. 283DOC_END 284 285NAME: ftp_list_width 286TYPE: obsolete 287DOC_START 288 Remove this line. Configure FTP page display using the CSS controls in errorpages.css instead. 289DOC_END 290 291NAME: ignore_expect_100 292TYPE: obsolete 293DOC_START 294 Remove this line. The HTTP/1.1 feature is now fully supported by default. 295DOC_END 296 297NAME: log_fqdn 298TYPE: obsolete 299DOC_START 300 Remove this option from your config. To log FQDN use %>A in the log format. 301DOC_END 302 303NAME: log_ip_on_direct 304TYPE: obsolete 305DOC_START 306 Remove this option from your config. To log server or peer names use %<A in the log format. 307DOC_END 308 309NAME: maximum_single_addr_tries 310TYPE: obsolete 311DOC_START 312 Replaced by connect_retries. The behaviour has changed, please read the documentation before altering. 313DOC_END 314 315NAME: referer_log referrer_log 316TYPE: obsolete 317DOC_START 318 Replace this with an access_log directive using the format 'referrer'. 319DOC_END 320 321NAME: update_headers 322TYPE: obsolete 323DOC_START 324 Remove this line. The feature is supported by default in storage types where update is implemented. 325DOC_END 326 327NAME: url_rewrite_concurrency 328TYPE: obsolete 329DOC_START 330 Remove this line. Set the 'concurrency=' option of url_rewrite_children instead. 331DOC_END 332 333NAME: useragent_log 334TYPE: obsolete 335DOC_START 336 Replace this with an access_log directive using the format 'useragent'. 337DOC_END 338 339# Options Removed in 3.1 340NAME: dns_testnames 341TYPE: obsolete 342DOC_START 343 Remove this line. DNS is no longer tested on startup. 344DOC_END 345 346NAME: extension_methods 347TYPE: obsolete 348DOC_START 349 Remove this line. All valid methods for HTTP are accepted by default. 350DOC_END 351 352# 2.7 Options Removed/Replaced in 3.2 353NAME: zero_buffers 354TYPE: obsolete 355DOC_NONE 356 357# 2.7 Options Removed/Replaced in 3.1 358NAME: incoming_rate 359TYPE: obsolete 360DOC_NONE 361 362NAME: server_http11 363TYPE: obsolete 364DOC_START 365 Remove this line. HTTP/1.1 is supported by default. 366DOC_END 367 368NAME: upgrade_http0.9 369TYPE: obsolete 370DOC_START 371 Remove this line. ICY/1.0 streaming protocol is supported by default. 372DOC_END 373 374NAME: zph_local zph_mode zph_option zph_parent zph_sibling 375TYPE: obsolete 376DOC_START 377 Alter these entries. Use the qos_flows directive instead. 378DOC_END 379 380# Options Removed in 3.0 381NAME: header_access 382TYPE: obsolete 383DOC_START 384 Since squid-3.0 replace with request_header_access or reply_header_access 385 depending on whether you wish to match client requests or server replies. 386DOC_END 387 388NAME: httpd_accel_no_pmtu_disc 389TYPE: obsolete 390DOC_START 391 Since squid-3.0 use the 'disable-pmtu-discovery' flag on http_port instead. 392DOC_END 393 394NAME: wais_relay_host 395TYPE: obsolete 396DOC_START 397 Replace this line with 'cache_peer' configuration. 398DOC_END 399 400NAME: wais_relay_port 401TYPE: obsolete 402DOC_START 403 Replace this line with 'cache_peer' configuration. 404DOC_END 405 406COMMENT_START 407 OPTIONS FOR SMP 408 ----------------------------------------------------------------------------- 409COMMENT_END 410 411NAME: workers 412TYPE: int 413LOC: Config.workers 414DEFAULT: 1 415DEFAULT_DOC: SMP support disabled. 416DOC_START 417 Number of main Squid processes or "workers" to fork and maintain. 418 0: "no daemon" mode, like running "squid -N ..." 419 1: "no SMP" mode, start one main Squid process daemon (default) 420 N: start N main Squid process daemons (i.e., SMP mode) 421 422 In SMP mode, each worker does nearly all what a single Squid daemon 423 does (e.g., listen on http_port and forward HTTP requests). 424DOC_END 425 426NAME: cpu_affinity_map 427TYPE: CpuAffinityMap 428LOC: Config.cpuAffinityMap 429DEFAULT: none 430DEFAULT_DOC: Let operating system decide. 431DOC_START 432 Usage: cpu_affinity_map process_numbers=P1,P2,... cores=C1,C2,... 433 434 Sets 1:1 mapping between Squid processes and CPU cores. For example, 435 436 cpu_affinity_map process_numbers=1,2,3,4 cores=1,3,5,7 437 438 affects processes 1 through 4 only and places them on the first 439 four even cores, starting with core #1. 440 441 CPU cores are numbered starting from 1. Requires support for 442 sched_getaffinity(2) and sched_setaffinity(2) system calls. 443 444 Multiple cpu_affinity_map options are merged. 445 446 See also: workers 447DOC_END 448 449NAME: shared_memory_locking 450TYPE: YesNoNone 451COMMENT: on|off 452LOC: Config.shmLocking 453DEFAULT: off 454DOC_START 455 Whether to ensure that all required shared memory is available by 456 "locking" that shared memory into RAM when Squid starts. The 457 alternative is faster startup time followed by slightly slower 458 performance and, if not enough RAM is actually available during 459 runtime, mysterious crashes. 460 461 SMP Squid uses many shared memory segments. These segments are 462 brought into Squid memory space using an mmap(2) system call. During 463 Squid startup, the mmap() call often succeeds regardless of whether 464 the system has enough RAM. In general, Squid cannot tell whether the 465 kernel applies this "optimistic" memory allocation policy (but 466 popular modern kernels usually use it). 467 468 Later, if Squid attempts to actually access the mapped memory 469 regions beyond what the kernel is willing to allocate, the 470 "optimistic" kernel simply kills Squid kid with a SIGBUS signal. 471 Some of the memory limits enforced by the kernel are currently 472 poorly understood: We do not know how to detect and check them. This 473 option ensures that the mapped memory will be available. 474 475 This option may have a positive performance side-effect: Locking 476 memory at start avoids runtime paging I/O. Paging slows Squid down. 477 478 Locking memory may require a large enough RLIMIT_MEMLOCK OS limit, 479 CAP_IPC_LOCK capability, or equivalent. 480DOC_END 481 482NAME: hopeless_kid_revival_delay 483COMMENT: time-units 484TYPE: time_t 485LOC: Config.hopelessKidRevivalDelay 486DEFAULT: 1 hour 487DOC_START 488 Normally, when a kid process dies, Squid immediately restarts the 489 kid. A kid experiencing frequent deaths is marked as "hopeless" for 490 the duration specified by this directive. Hopeless kids are not 491 automatically restarted. 492 493 Currently, zero values are not supported because they result in 494 misconfigured SMP Squid instances running forever, endlessly 495 restarting each dying kid. To effectively disable hopeless kids 496 revival, set the delay to a huge value (e.g., 1 year). 497 498 Reconfiguration also clears all hopeless kids designations, allowing 499 for manual revival of hopeless kids. 500DOC_END 501 502COMMENT_START 503 OPTIONS FOR AUTHENTICATION 504 ----------------------------------------------------------------------------- 505COMMENT_END 506 507NAME: auth_param 508TYPE: authparam 509IFDEF: USE_AUTH 510LOC: Auth::TheConfig 511DEFAULT: none 512DOC_START 513 This is used to define parameters for the various authentication 514 schemes supported by Squid. 515 516 format: auth_param scheme parameter [setting] 517 518 The order in which authentication schemes are presented to the client is 519 dependent on the order the scheme first appears in config file. IE 520 has a bug (it's not RFC 2617 compliant) in that it will use the basic 521 scheme if basic is the first entry presented, even if more secure 522 schemes are presented. For now use the order in the recommended 523 settings section below. If other browsers have difficulties (don't 524 recognize the schemes offered even if you are using basic) either 525 put basic first, or disable the other schemes (by commenting out their 526 program entry). 527 528 Once an authentication scheme is fully configured, it can only be 529 shutdown by shutting squid down and restarting. Changes can be made on 530 the fly and activated with a reconfigure. I.E. You can change to a 531 different helper, but not unconfigure the helper completely. 532 533 Please note that while this directive defines how Squid processes 534 authentication it does not automatically activate authentication. 535 To use authentication you must in addition make use of ACLs based 536 on login name in http_access (proxy_auth, proxy_auth_regex or 537 external with %LOGIN used in the format tag). The browser will be 538 challenged for authentication on the first such acl encountered 539 in http_access processing and will also be re-challenged for new 540 login credentials if the request is being denied by a proxy_auth 541 type acl. 542 543 WARNING: authentication can't be used in a transparently intercepting 544 proxy as the client then thinks it is talking to an origin server and 545 not the proxy. This is a limitation of bending the TCP/IP protocol to 546 transparently intercepting port 80, not a limitation in Squid. 547 Ports flagged 'transparent', 'intercept', or 'tproxy' have 548 authentication disabled. 549 550 === Parameters common to all schemes. === 551 552 "program" cmdline 553 Specifies the command for the external authenticator. 554 555 By default, each authentication scheme is not used unless a 556 program is specified. 557 558 See http://wiki.squid-cache.org/Features/AddonHelpers for 559 more details on helper operations and creating your own. 560 561 "key_extras" format 562 Specifies a string to be append to request line format for 563 the authentication helper. "Quoted" format values may contain 564 spaces and logformat %macros. In theory, any logformat %macro 565 can be used. In practice, a %macro expands as a dash (-) if 566 the helper request is sent before the required macro 567 information is available to Squid. 568 569 By default, Squid uses request formats provided in 570 scheme-specific examples below (search for %credentials). 571 572 The expanded key_extras value is added to the Squid credentials 573 cache and, hence, will affect authentication. It can be used to 574 autenticate different users with identical user names (e.g., 575 when user authentication depends on http_port). 576 577 Avoid adding frequently changing information to key_extras. For 578 example, if you add user source IP, and it changes frequently 579 in your environment, then max_user_ip ACL is going to treat 580 every user+IP combination as a unique "user", breaking the ACL 581 and wasting a lot of memory on those user records. It will also 582 force users to authenticate from scratch whenever their IP 583 changes. 584 585 "realm" string 586 Specifies the protection scope (aka realm name) which is to be 587 reported to the client for the authentication scheme. It is 588 commonly part of the text the user will see when prompted for 589 their username and password. 590 591 For Basic the default is "Squid proxy-caching web server". 592 For Digest there is no default, this parameter is mandatory. 593 For NTLM and Negotiate this parameter is ignored. 594 595 "children" numberofchildren [startup=N] [idle=N] [concurrency=N] 596 [queue-size=N] [on-persistent-overload=action] 597 598 The maximum number of authenticator processes to spawn. If 599 you start too few Squid will have to wait for them to process 600 a backlog of credential verifications, slowing it down. When 601 password verifications are done via a (slow) network you are 602 likely to need lots of authenticator processes. 603 604 The startup= and idle= options permit some skew in the exact 605 amount run. A minimum of startup=N will begin during startup 606 and reconfigure. Squid will start more in groups of up to 607 idle=N in an attempt to meet traffic needs and to keep idle=N 608 free above those traffic needs up to the maximum. 609 610 The concurrency= option sets the number of concurrent requests 611 the helper can process. The default of 0 is used for helpers 612 who only supports one request at a time. Setting this to a 613 number greater than 0 changes the protocol used to include a 614 channel ID field first on the request/response line, allowing 615 multiple requests to be sent to the same helper in parallel 616 without waiting for the response. 617 618 Concurrency must not be set unless it's known the helper 619 supports the input format with channel-ID fields. 620 621 The queue-size option sets the maximum number of queued 622 requests. A request is queued when no existing child can 623 accept it due to concurrency limit and no new child can be 624 started due to numberofchildren limit. The default maximum is 625 2*numberofchildren. Squid is allowed to temporarily exceed the 626 configured maximum, marking the affected helper as 627 "overloaded". If the helper overload lasts more than 3 628 minutes, the action prescribed by the on-persistent-overload 629 option applies. 630 631 The on-persistent-overload=action option specifies Squid 632 reaction to a new helper request arriving when the helper 633 has been overloaded for more that 3 minutes already. The number 634 of queued requests determines whether the helper is overloaded 635 (see the queue-size option). 636 637 Two actions are supported: 638 639 die Squid worker quits. This is the default behavior. 640 641 ERR Squid treats the helper request as if it was 642 immediately submitted, and the helper immediately 643 replied with an ERR response. This action has no effect 644 on the already queued and in-progress helper requests. 645 646 NOTE: NTLM and Negotiate schemes do not support concurrency 647 in the Squid code module even though some helpers can. 648 649 650IF HAVE_AUTH_MODULE_BASIC 651 === Basic authentication parameters === 652 653 "utf8" on|off 654 HTTP uses iso-latin-1 as character set, while some 655 authentication backends such as LDAP expects UTF-8. If this is 656 set to on Squid will translate the HTTP iso-latin-1 charset to 657 UTF-8 before sending the username and password to the helper. 658 659 "credentialsttl" timetolive 660 Specifies how long squid assumes an externally validated 661 username:password pair is valid for - in other words how 662 often the helper program is called for that user. Set this 663 low to force revalidation with short lived passwords. 664 665 NOTE: setting this high does not impact your susceptibility 666 to replay attacks unless you are using an one-time password 667 system (such as SecureID). If you are using such a system, 668 you will be vulnerable to replay attacks unless you also 669 use the max_user_ip ACL in an http_access rule. 670 671 "casesensitive" on|off 672 Specifies if usernames are case sensitive. Most user databases 673 are case insensitive allowing the same username to be spelled 674 using both lower and upper case letters, but some are case 675 sensitive. This makes a big difference for user_max_ip ACL 676 processing and similar. 677 678ENDIF 679IF HAVE_AUTH_MODULE_DIGEST 680 === Digest authentication parameters === 681 682 "utf8" on|off 683 HTTP uses iso-latin-1 as character set, while some 684 authentication backends such as LDAP expects UTF-8. If this is 685 set to on Squid will translate the HTTP iso-latin-1 charset to 686 UTF-8 before sending the username and password to the helper. 687 688 "nonce_garbage_interval" timeinterval 689 Specifies the interval that nonces that have been issued 690 to client_agent's are checked for validity. 691 692 "nonce_max_duration" timeinterval 693 Specifies the maximum length of time a given nonce will be 694 valid for. 695 696 "nonce_max_count" number 697 Specifies the maximum number of times a given nonce can be 698 used. 699 700 "nonce_strictness" on|off 701 Determines if squid requires strict increment-by-1 behavior 702 for nonce counts, or just incrementing (off - for use when 703 user agents generate nonce counts that occasionally miss 1 704 (ie, 1,2,4,6)). Default off. 705 706 "check_nonce_count" on|off 707 This directive if set to off can disable the nonce count check 708 completely to work around buggy digest qop implementations in 709 certain mainstream browser versions. Default on to check the 710 nonce count to protect from authentication replay attacks. 711 712 "post_workaround" on|off 713 This is a workaround to certain buggy browsers who send an 714 incorrect request digest in POST requests when reusing the 715 same nonce as acquired earlier on a GET request. 716 717ENDIF 718IF HAVE_AUTH_MODULE_NEGOTIATE 719 === Negotiate authentication parameters === 720 721 "keep_alive" on|off 722 If you experience problems with PUT/POST requests when using 723 the this authentication scheme then you can try setting this 724 to off. This will cause Squid to forcibly close the connection 725 on the initial request where the browser asks which schemes 726 are supported by the proxy. 727 728ENDIF 729IF HAVE_AUTH_MODULE_NTLM 730 === NTLM authentication parameters === 731 732 "keep_alive" on|off 733 If you experience problems with PUT/POST requests when using 734 the this authentication scheme then you can try setting this 735 to off. This will cause Squid to forcibly close the connection 736 on the initial request where the browser asks which schemes 737 are supported by the proxy. 738ENDIF 739 740 === Example Configuration === 741 742 This configuration displays the recommended authentication scheme 743 order from most to least secure with recommended minimum configuration 744 settings for each scheme: 745 746#auth_param negotiate program <uncomment and complete this line to activate> 747#auth_param negotiate children 20 startup=0 idle=1 748#auth_param negotiate keep_alive on 749# 750#auth_param digest program <uncomment and complete this line to activate> 751#auth_param digest children 20 startup=0 idle=1 752#auth_param digest realm Squid proxy-caching web server 753#auth_param digest nonce_garbage_interval 5 minutes 754#auth_param digest nonce_max_duration 30 minutes 755#auth_param digest nonce_max_count 50 756# 757#auth_param ntlm program <uncomment and complete this line to activate> 758#auth_param ntlm children 20 startup=0 idle=1 759#auth_param ntlm keep_alive on 760# 761#auth_param basic program <uncomment and complete this line> 762#auth_param basic children 5 startup=5 idle=1 763#auth_param basic realm Squid proxy-caching web server 764#auth_param basic credentialsttl 2 hours 765DOC_END 766 767NAME: authenticate_cache_garbage_interval 768TYPE: time_t 769DEFAULT: 1 hour 770LOC: Config.authenticateGCInterval 771DOC_START 772 The time period between garbage collection across the username cache. 773 This is a trade-off between memory utilization (long intervals - say 774 2 days) and CPU (short intervals - say 1 minute). Only change if you 775 have good reason to. 776DOC_END 777 778NAME: authenticate_ttl 779TYPE: time_t 780DEFAULT: 1 hour 781LOC: Config.authenticateTTL 782DOC_START 783 The time a user & their credentials stay in the logged in 784 user cache since their last request. When the garbage 785 interval passes, all user credentials that have passed their 786 TTL are removed from memory. 787DOC_END 788 789NAME: authenticate_ip_ttl 790TYPE: time_t 791LOC: Config.authenticateIpTTL 792DEFAULT: 1 second 793DOC_START 794 If you use proxy authentication and the 'max_user_ip' ACL, 795 this directive controls how long Squid remembers the IP 796 addresses associated with each user. Use a small value 797 (e.g., 60 seconds) if your users might change addresses 798 quickly, as is the case with dialup. You might be safe 799 using a larger value (e.g., 2 hours) in a corporate LAN 800 environment with relatively static address assignments. 801DOC_END 802 803COMMENT_START 804 ACCESS CONTROLS 805 ----------------------------------------------------------------------------- 806COMMENT_END 807 808NAME: external_acl_type 809TYPE: externalAclHelper 810LOC: Config.externalAclHelperList 811DEFAULT: none 812DOC_START 813 This option defines external acl classes using a helper program 814 to look up the status 815 816 external_acl_type name [options] FORMAT /path/to/helper [helper arguments] 817 818 Options: 819 820 ttl=n TTL in seconds for cached results (defaults to 3600 821 for 1 hour) 822 823 negative_ttl=n 824 TTL for cached negative lookups (default same 825 as ttl) 826 827 grace=n Percentage remaining of TTL where a refresh of a 828 cached entry should be initiated without needing to 829 wait for a new reply. (default is for no grace period) 830 831 cache=n The maximum number of entries in the result cache. The 832 default limit is 262144 entries. Each cache entry usually 833 consumes at least 256 bytes. Squid currently does not remove 834 expired cache entries until the limit is reached, so a proxy 835 will sooner or later reach the limit. The expanded FORMAT 836 value is used as the cache key, so if the details in FORMAT 837 are highly variable, a larger cache may be needed to produce 838 reduction in helper load. 839 840 children-max=n 841 Maximum number of acl helper processes spawned to service 842 external acl lookups of this type. (default 5) 843 844 children-startup=n 845 Minimum number of acl helper processes to spawn during 846 startup and reconfigure to service external acl lookups 847 of this type. (default 0) 848 849 children-idle=n 850 Number of acl helper processes to keep ahead of traffic 851 loads. Squid will spawn this many at once whenever load 852 rises above the capabilities of existing processes. 853 Up to the value of children-max. (default 1) 854 855 concurrency=n concurrency level per process. Only used with helpers 856 capable of processing more than one query at a time. 857 858 queue-size=N The queue-size option sets the maximum number of 859 queued requests. A request is queued when no existing 860 helper can accept it due to concurrency limit and no 861 new helper can be started due to children-max limit. 862 If the queued requests exceed queue size, the acl is 863 ignored. The default value is set to 2*children-max. 864 865 protocol=2.5 Compatibility mode for Squid-2.5 external acl helpers. 866 867 ipv4 / ipv6 IP protocol used to communicate with this helper. 868 The default is to auto-detect IPv6 and use it when available. 869 870 871 FORMAT is a series of %macro codes. See logformat directive for a full list 872 of the accepted codes. Although note that at the time of any external ACL 873 being tested data may not be available and thus some %macro expand to '-'. 874 875 In addition to the logformat codes; when processing external ACLs these 876 additional macros are made available: 877 878 %ACL The name of the ACL being tested. 879 880 %DATA The ACL arguments specified in the referencing config 881 'acl ... external' line, separated by spaces (an 882 "argument string"). see acl external. 883 884 If there are no ACL arguments %DATA expands to '-'. 885 886 If you do not specify a DATA macro inside FORMAT, 887 Squid automatically appends %DATA to your FORMAT. 888 Note that Squid-3.x may expand %DATA to whitespace 889 or nothing in this case. 890 891 By default, Squid applies URL-encoding to each ACL 892 argument inside the argument string. If an explicit 893 encoding modifier is used (e.g., %#DATA), then Squid 894 encodes the whole argument string as a single token 895 (e.g., with %#DATA, spaces between arguments become 896 %20). 897 898 If SSL is enabled, the following formating codes become available: 899 900 %USER_CERT SSL User certificate in PEM format 901 %USER_CERTCHAIN SSL User certificate chain in PEM format 902 %USER_CERT_xx SSL User certificate subject attribute xx 903 %USER_CA_CERT_xx SSL User certificate issuer attribute xx 904 905 906 NOTE: all other format codes accepted by older Squid versions 907 are deprecated. 908 909 910 General request syntax: 911 912 [channel-ID] FORMAT-values 913 914 915 FORMAT-values consists of transaction details expanded with 916 whitespace separation per the config file FORMAT specification 917 using the FORMAT macros listed above. 918 919 Request values sent to the helper are URL escaped to protect 920 each value in requests against whitespaces. 921 922 If using protocol=2.5 then the request sent to the helper is not 923 URL escaped to protect against whitespace. 924 925 NOTE: protocol=3.0 is deprecated as no longer necessary. 926 927 When using the concurrency= option the protocol is changed by 928 introducing a query channel tag in front of the request/response. 929 The query channel tag is a number between 0 and concurrency-1. 930 This value must be echoed back unchanged to Squid as the first part 931 of the response relating to its request. 932 933 934 The helper receives lines expanded per the above format specification 935 and for each input line returns 1 line starting with OK/ERR/BH result 936 code and optionally followed by additional keywords with more details. 937 938 939 General result syntax: 940 941 [channel-ID] result keyword=value ... 942 943 Result consists of one of the codes: 944 945 OK 946 the ACL test produced a match. 947 948 ERR 949 the ACL test does not produce a match. 950 951 BH 952 An internal error occurred in the helper, preventing 953 a result being identified. 954 955 The meaning of 'a match' is determined by your squid.conf 956 access control configuration. See the Squid wiki for details. 957 958 Defined keywords: 959 960 user= The users name (login) 961 962 password= The users password (for login= cache_peer option) 963 964 message= Message describing the reason for this response. 965 Available as %o in error pages. 966 Useful on (ERR and BH results). 967 968 tag= Apply a tag to a request. Only sets a tag once, 969 does not alter existing tags. 970 971 log= String to be logged in access.log. Available as 972 %ea in logformat specifications. 973 974 clt_conn_tag= Associates a TAG with the client TCP connection. 975 Please see url_rewrite_program related documentation 976 for this kv-pair. 977 978 Any keywords may be sent on any response whether OK, ERR or BH. 979 980 All response keyword values need to be a single token with URL 981 escaping, or enclosed in double quotes (") and escaped using \ on 982 any double quotes or \ characters within the value. The wrapping 983 double quotes are removed before the value is interpreted by Squid. 984 \r and \n are also replace by CR and LF. 985 986 Some example key values: 987 988 user=John%20Smith 989 user="John Smith" 990 user="J. \"Bob\" Smith" 991DOC_END 992 993NAME: acl 994TYPE: acl 995LOC: Config.aclList 996IF USE_OPENSSL 997DEFAULT: ssl::certHasExpired ssl_error X509_V_ERR_CERT_HAS_EXPIRED 998DEFAULT: ssl::certNotYetValid ssl_error X509_V_ERR_CERT_NOT_YET_VALID 999DEFAULT: ssl::certDomainMismatch ssl_error SQUID_X509_V_ERR_DOMAIN_MISMATCH 1000DEFAULT: ssl::certUntrusted ssl_error X509_V_ERR_INVALID_CA X509_V_ERR_SELF_SIGNED_CERT_IN_CHAIN X509_V_ERR_UNABLE_TO_VERIFY_LEAF_SIGNATURE X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT X509_V_ERR_UNABLE_TO_GET_ISSUER_CERT_LOCALLY X509_V_ERR_CERT_UNTRUSTED 1001DEFAULT: ssl::certSelfSigned ssl_error X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT 1002ENDIF 1003DEFAULT: all src all 1004DEFAULT: manager url_regex -i ^cache_object:// +i ^https?://[^/]+/squid-internal-mgr/ 1005DEFAULT: localhost src 127.0.0.1/32 ::1 1006DEFAULT: to_localhost dst 127.0.0.0/8 0.0.0.0/32 ::1/128 ::/128 1007DEFAULT_DOC: ACLs all, manager, localhost, and to_localhost are predefined. 1008DOC_START 1009 Defining an Access List 1010 1011 Every access list definition must begin with an aclname and acltype, 1012 followed by either type-specific arguments or a quoted filename that 1013 they are read from. 1014 1015 acl aclname acltype argument ... 1016 acl aclname acltype "file" ... 1017 1018 When using "file", the file should contain one item per line. 1019 1020 1021 ACL Options 1022 1023 Some acl types supports options which changes their default behaviour: 1024 1025 -i,+i By default, regular expressions are CASE-SENSITIVE. To make them 1026 case-insensitive, use the -i option. To return case-sensitive 1027 use the +i option between patterns, or make a new ACL line 1028 without -i. 1029 1030 -n Disable lookups and address type conversions. If lookup or 1031 conversion is required because the parameter type (IP or 1032 domain name) does not match the message address type (domain 1033 name or IP), then the ACL would immediately declare a mismatch 1034 without any warnings or lookups. 1035 1036 -m[=delimiters] 1037 Perform a list membership test, interpreting values as 1038 comma-separated token lists and matching against individual 1039 tokens instead of whole values. 1040 The optional "delimiters" parameter specifies one or more 1041 alternative non-alphanumeric delimiter characters. 1042 non-alphanumeric delimiter characters. 1043 1044 -- Used to stop processing all options, in the case the first acl 1045 value has '-' character as first character (for example the '-' 1046 is a valid domain name) 1047 1048 Some acl types require suspending the current request in order 1049 to access some external data source. 1050 Those which do are marked with the tag [slow], those which 1051 don't are marked as [fast]. 1052 See http://wiki.squid-cache.org/SquidFaq/SquidAcl 1053 for further information 1054 1055 ***** ACL TYPES AVAILABLE ***** 1056 1057 acl aclname src ip-address/mask ... # clients IP address [fast] 1058 acl aclname src addr1-addr2/mask ... # range of addresses [fast] 1059 acl aclname dst [-n] ip-address/mask ... # URL host's IP address [slow] 1060 acl aclname localip ip-address/mask ... # IP address the client connected to [fast] 1061 1062if USE_SQUID_EUI 1063 acl aclname arp mac-address ... 1064 acl aclname eui64 eui64-address ... 1065 # [fast] 1066 # MAC (EUI-48) and EUI-64 addresses use xx:xx:xx:xx:xx:xx notation. 1067 # 1068 # The 'arp' ACL code is not portable to all operating systems. 1069 # It works on Linux, Solaris, Windows, FreeBSD, and some other 1070 # BSD variants. 1071 # 1072 # The eui_lookup directive is required to be 'on' (the default) 1073 # and Squid built with --enable-eui for MAC/EUI addresses to be 1074 # available for this ACL. 1075 # 1076 # Squid can only determine the MAC/EUI address for IPv4 1077 # clients that are on the same subnet. If the client is on a 1078 # different subnet, then Squid cannot find out its address. 1079 # 1080 # IPv6 protocol does not contain ARP. MAC/EUI is either 1081 # encoded directly in the IPv6 address or not available. 1082endif 1083 acl aclname clientside_mark mark[/mask] ... 1084 # matches CONNMARK of an accepted connection [fast] 1085 # 1086 # mark and mask are unsigned integers (hex, octal, or decimal). 1087 # If multiple marks are given, then the ACL matches if at least 1088 # one mark matches. 1089 # 1090 # Uses netfilter-conntrack library. 1091 # Requires building Squid with --enable-linux-netfilter. 1092 # 1093 # The client, various intermediaries, and Squid itself may set 1094 # CONNMARK at various times. The last CONNMARK set wins. This ACL 1095 # checks the mark present on an accepted connection or set by 1096 # Squid afterwards, depending on the ACL check timing. This ACL 1097 # effectively ignores any mark set by other agents after Squid has 1098 # accepted the connection. 1099 1100 acl aclname srcdomain .foo.com ... 1101 # reverse lookup, from client IP [slow] 1102 acl aclname dstdomain [-n] .foo.com ... 1103 # Destination server from URL [fast] 1104 acl aclname srcdom_regex [-i] \.foo\.com ... 1105 # regex matching client name [slow] 1106 acl aclname dstdom_regex [-n] [-i] \.foo\.com ... 1107 # regex matching server [fast] 1108 # 1109 # For dstdomain and dstdom_regex a reverse lookup is tried if a IP 1110 # based URL is used and no match is found. The name "none" is used 1111 # if the reverse lookup fails. 1112 1113 acl aclname src_as number ... 1114 acl aclname dst_as number ... 1115 # [fast] 1116 # Except for access control, AS numbers can be used for 1117 # routing of requests to specific caches. Here's an 1118 # example for routing all requests for AS#1241 and only 1119 # those to mycache.mydomain.net: 1120 # acl asexample dst_as 1241 1121 # cache_peer_access mycache.mydomain.net allow asexample 1122 # cache_peer_access mycache_mydomain.net deny all 1123 1124 acl aclname peername myPeer ... 1125 acl aclname peername_regex [-i] regex-pattern ... 1126 # [fast] 1127 # match against a named cache_peer entry 1128 # set unique name= on cache_peer lines for reliable use. 1129 1130 acl aclname time [day-abbrevs] [h1:m1-h2:m2] 1131 # [fast] 1132 # day-abbrevs: 1133 # S - Sunday 1134 # M - Monday 1135 # T - Tuesday 1136 # W - Wednesday 1137 # H - Thursday 1138 # F - Friday 1139 # A - Saturday 1140 # h1:m1 must be less than h2:m2 1141 1142 acl aclname url_regex [-i] ^http:// ... 1143 # regex matching on whole URL [fast] 1144 acl aclname urllogin [-i] [^a-zA-Z0-9] ... 1145 # regex matching on URL login field 1146 acl aclname urlpath_regex [-i] \.gif$ ... 1147 # regex matching on URL path [fast] 1148 1149 acl aclname port 80 70 21 0-1024... # destination TCP port [fast] 1150 # ranges are alloed 1151 acl aclname localport 3128 ... # TCP port the client connected to [fast] 1152 # NP: for interception mode this is usually '80' 1153 1154 acl aclname myportname 3128 ... # *_port name [fast] 1155 1156 acl aclname proto HTTP FTP ... # request protocol [fast] 1157 1158 acl aclname method GET POST ... # HTTP request method [fast] 1159 1160 acl aclname http_status 200 301 500- 400-403 ... 1161 # status code in reply [fast] 1162 1163 acl aclname browser [-i] regexp ... 1164 # pattern match on User-Agent header (see also req_header below) [fast] 1165 1166 acl aclname referer_regex [-i] regexp ... 1167 # pattern match on Referer header [fast] 1168 # Referer is highly unreliable, so use with care 1169 1170 acl aclname ident [-i] username ... 1171 acl aclname ident_regex [-i] pattern ... 1172 # string match on ident output [slow] 1173 # use REQUIRED to accept any non-null ident. 1174 1175 acl aclname proxy_auth [-i] username ... 1176 acl aclname proxy_auth_regex [-i] pattern ... 1177 # perform http authentication challenge to the client and match against 1178 # supplied credentials [slow] 1179 # 1180 # takes a list of allowed usernames. 1181 # use REQUIRED to accept any valid username. 1182 # 1183 # Will use proxy authentication in forward-proxy scenarios, and plain 1184 # http authenticaiton in reverse-proxy scenarios 1185 # 1186 # NOTE: when a Proxy-Authentication header is sent but it is not 1187 # needed during ACL checking the username is NOT logged 1188 # in access.log. 1189 # 1190 # NOTE: proxy_auth requires a EXTERNAL authentication program 1191 # to check username/password combinations (see 1192 # auth_param directive). 1193 # 1194 # NOTE: proxy_auth can't be used in a transparent/intercepting proxy 1195 # as the browser needs to be configured for using a proxy in order 1196 # to respond to proxy authentication. 1197 1198 acl aclname snmp_community string ... 1199 # A community string to limit access to your SNMP Agent [fast] 1200 # Example: 1201 # 1202 # acl snmppublic snmp_community public 1203 1204 acl aclname maxconn number 1205 # This will be matched when the client's IP address has 1206 # more than <number> TCP connections established. [fast] 1207 # NOTE: This only measures direct TCP links so X-Forwarded-For 1208 # indirect clients are not counted. 1209 1210 acl aclname max_user_ip [-s] number 1211 # This will be matched when the user attempts to log in from more 1212 # than <number> different ip addresses. The authenticate_ip_ttl 1213 # parameter controls the timeout on the ip entries. [fast] 1214 # If -s is specified the limit is strict, denying browsing 1215 # from any further IP addresses until the ttl has expired. Without 1216 # -s Squid will just annoy the user by "randomly" denying requests. 1217 # (the counter is reset each time the limit is reached and a 1218 # request is denied) 1219 # NOTE: in acceleration mode or where there is mesh of child proxies, 1220 # clients may appear to come from multiple addresses if they are 1221 # going through proxy farms, so a limit of 1 may cause user problems. 1222 1223 acl aclname random probability 1224 # Pseudo-randomly match requests. Based on the probability given. 1225 # Probability may be written as a decimal (0.333), fraction (1/3) 1226 # or ratio of matches:non-matches (3:5). 1227 1228 acl aclname req_mime_type [-i] mime-type ... 1229 # regex match against the mime type of the request generated 1230 # by the client. Can be used to detect file upload or some 1231 # types HTTP tunneling requests [fast] 1232 # NOTE: This does NOT match the reply. You cannot use this 1233 # to match the returned file type. 1234 1235 acl aclname req_header header-name [-i] any\.regex\.here 1236 # regex match against any of the known request headers. May be 1237 # thought of as a superset of "browser", "referer" and "mime-type" 1238 # ACL [fast] 1239 1240 acl aclname rep_mime_type [-i] mime-type ... 1241 # regex match against the mime type of the reply received by 1242 # squid. Can be used to detect file download or some 1243 # types HTTP tunneling requests. [fast] 1244 # NOTE: This has no effect in http_access rules. It only has 1245 # effect in rules that affect the reply data stream such as 1246 # http_reply_access. 1247 1248 acl aclname rep_header header-name [-i] any\.regex\.here 1249 # regex match against any of the known reply headers. May be 1250 # thought of as a superset of "browser", "referer" and "mime-type" 1251 # ACLs [fast] 1252 1253 acl aclname external class_name [arguments...] 1254 # external ACL lookup via a helper class defined by the 1255 # external_acl_type directive [slow] 1256 1257 acl aclname user_cert attribute values... 1258 # match against attributes in a user SSL certificate 1259 # attribute is one of DN/C/O/CN/L/ST or a numerical OID [fast] 1260 1261 acl aclname ca_cert attribute values... 1262 # match against attributes a users issuing CA SSL certificate 1263 # attribute is one of DN/C/O/CN/L/ST or a numerical OID [fast] 1264 1265 acl aclname ext_user [-i] username ... 1266 acl aclname ext_user_regex [-i] pattern ... 1267 # string match on username returned by external acl helper [slow] 1268 # use REQUIRED to accept any non-null user name. 1269 1270 acl aclname tag tagvalue ... 1271 # string match on tag returned by external acl helper [fast] 1272 # DEPRECATED. Only the first tag will match with this ACL. 1273 # Use the 'note' ACL instead for handling multiple tag values. 1274 1275 acl aclname hier_code codename ... 1276 # string match against squid hierarchy code(s); [fast] 1277 # e.g., DIRECT, PARENT_HIT, NONE, etc. 1278 # 1279 # NOTE: This has no effect in http_access rules. It only has 1280 # effect in rules that affect the reply data stream such as 1281 # http_reply_access. 1282 1283 acl aclname note [-m[=delimiters]] name [value ...] 1284 # match transaction annotation [fast] 1285 # Without values, matches any annotation with a given name. 1286 # With value(s), matches any annotation with a given name that 1287 # also has one of the given values. 1288 # If the -m flag is used, then the value of the named 1289 # annotation is interpreted as a list of tokens, and the ACL 1290 # matches individual name=token pairs rather than whole 1291 # name=value pairs. See "ACL Options" above for more info. 1292 # Annotation sources include note and adaptation_meta directives 1293 # as well as helper and eCAP responses. 1294 1295 acl aclname adaptation_service service ... 1296 # Matches the name of any icap_service, ecap_service, 1297 # adaptation_service_set, or adaptation_service_chain that Squid 1298 # has used (or attempted to use) for the master transaction. 1299 # This ACL must be defined after the corresponding adaptation 1300 # service is named in squid.conf. This ACL is usable with 1301 # adaptation_meta because it starts matching immediately after 1302 # the service has been selected for adaptation. 1303 1304 acl aclname transaction_initiator initiator ... 1305 # Matches transaction's initiator [fast] 1306 # 1307 # Supported initiators are: 1308 # esi: matches transactions fetching ESI resources 1309 # certificate-fetching: matches transactions fetching 1310 # a missing intermediate TLS certificate 1311 # cache-digest: matches transactions fetching Cache Digests 1312 # from a cache_peer 1313 # htcp: matches HTCP requests from peers 1314 # icp: matches ICP requests to peers 1315 # icmp: matches ICMP RTT database (NetDB) requests to peers 1316 # asn: matches asns db requests 1317 # internal: matches any of the above 1318 # client: matches transactions containing an HTTP or FTP 1319 # client request received at a Squid *_port 1320 # all: matches any transaction, including internal transactions 1321 # without a configurable initiator and hopefully rare 1322 # transactions without a known-to-Squid initiator 1323 # 1324 # Multiple initiators are ORed. 1325 1326 acl aclname has component 1327 # matches a transaction "component" [fast] 1328 # 1329 # Supported transaction components are: 1330 # request: transaction has a request header (at least) 1331 # response: transaction has a response header (at least) 1332 # ALE: transaction has an internally-generated Access Log Entry 1333 # structure; bugs notwithstanding, all transaction have it 1334 # 1335 # For example, the following configuration helps when dealing with HTTP 1336 # clients that close connections without sending a request header: 1337 # 1338 # acl hasRequest has request 1339 # acl logMe note important_transaction 1340 # # avoid "logMe ACL is used in context without an HTTP request" warnings 1341 # access_log ... logformat=detailed hasRequest logMe 1342 # # log request-less transactions, instead of ignoring them 1343 # access_log ... logformat=brief !hasRequest 1344 # 1345 # Multiple components are not supported for one "acl" rule, but 1346 # can be specified (and are ORed) using multiple same-name rules: 1347 # 1348 # # OK, this strange logging daemon needs request or response, 1349 # # but can work without either a request or a response: 1350 # acl hasWhatMyLoggingDaemonNeeds has request 1351 # acl hasWhatMyLoggingDaemonNeeds has response 1352 1353IF USE_OPENSSL 1354 acl aclname ssl_error errorname 1355 # match against SSL certificate validation error [fast] 1356 # 1357 # For valid error names see in @DEFAULT_ERROR_DIR@/templates/error-details.txt 1358 # template file. 1359 # 1360 # The following can be used as shortcuts for certificate properties: 1361 # [ssl::]certHasExpired: the "not after" field is in the past 1362 # [ssl::]certNotYetValid: the "not before" field is in the future 1363 # [ssl::]certUntrusted: The certificate issuer is not to be trusted. 1364 # [ssl::]certSelfSigned: The certificate is self signed. 1365 # [ssl::]certDomainMismatch: The certificate CN domain does not 1366 # match the name the name of the host we are connecting to. 1367 # 1368 # The ssl::certHasExpired, ssl::certNotYetValid, ssl::certDomainMismatch, 1369 # ssl::certUntrusted, and ssl::certSelfSigned can also be used as 1370 # predefined ACLs, just like the 'all' ACL. 1371 # 1372 # NOTE: The ssl_error ACL is only supported with sslproxy_cert_error, 1373 # sslproxy_cert_sign, and sslproxy_cert_adapt options. 1374 1375 acl aclname server_cert_fingerprint [-sha1] fingerprint 1376 # match against server SSL certificate fingerprint [fast] 1377 # 1378 # The fingerprint is the digest of the DER encoded version 1379 # of the whole certificate. The user should use the form: XX:XX:... 1380 # Optional argument specifies the digest algorithm to use. 1381 # The SHA1 digest algorithm is the default and is currently 1382 # the only algorithm supported (-sha1). 1383 1384 acl aclname at_step step 1385 # match against the current step during ssl_bump evaluation [fast] 1386 # Never matches and should not be used outside the ssl_bump context. 1387 # 1388 # At each SslBump step, Squid evaluates ssl_bump directives to find 1389 # the next bumping action (e.g., peek or splice). Valid SslBump step 1390 # values and the corresponding ssl_bump evaluation moments are: 1391 # SslBump1: After getting TCP-level and HTTP CONNECT info. 1392 # SslBump2: After getting SSL Client Hello info. 1393 # SslBump3: After getting SSL Server Hello info. 1394 1395 acl aclname ssl::server_name [option] .foo.com ... 1396 # matches server name obtained from various sources [fast] 1397 # 1398 # The ACL computes server name(s) using such information sources as 1399 # CONNECT request URI, TLS client SNI, and TLS server certificate 1400 # subject (CN and SubjectAltName). The computed server name(s) usually 1401 # change with each SslBump step, as more info becomes available: 1402 # * SNI is used as the server name instead of the request URI, 1403 # * subject name(s) from the server certificate (CN and 1404 # SubjectAltName) are used as the server names instead of SNI. 1405 # 1406 # When the ACL computes multiple server names, matching any single 1407 # computed name is sufficient for the ACL to match. 1408 # 1409 # The "none" name can be used to match transactions where the ACL 1410 # could not compute the server name using any information source 1411 # that was both available and allowed to be used by the ACL options at 1412 # the ACL evaluation time. 1413 # 1414 # Unlike dstdomain, this ACL does not perform DNS lookups. 1415 # 1416 # An ACL option below may be used to restrict what information 1417 # sources are used to extract the server names from: 1418 # 1419 # --client-requested 1420 # The server name is SNI regardless of what the server says. 1421 # --server-provided 1422 # The server name(s) are the certificate subject name(s), regardless 1423 # of what the client has requested. If the server certificate is 1424 # unavailable, then the name is "none". 1425 # --consensus 1426 # The server name is either SNI (if SNI matches at least one of the 1427 # certificate subject names) or "none" (otherwise). When the server 1428 # certificate is unavailable, the consensus server name is SNI. 1429 # 1430 # Combining multiple options in one ACL is a fatal configuration 1431 # error. 1432 # 1433 # For all options: If no SNI is available, then the CONNECT request 1434 # target (a.k.a. URI) is used instead of SNI (for an intercepted 1435 # connection, this target is the destination IP address). 1436 1437 acl aclname ssl::server_name_regex [-i] \.foo\.com ... 1438 # regex matches server name obtained from various sources [fast] 1439 1440 acl aclname connections_encrypted 1441 # matches transactions with all HTTP messages received over TLS 1442 # transport connections. [fast] 1443 # 1444 # The master transaction deals with HTTP messages received from 1445 # various sources. All sources used by the master transaction in the 1446 # past are considered by the ACL. The following rules define whether 1447 # a given message source taints the entire master transaction, 1448 # resulting in ACL mismatches: 1449 # 1450 # * The HTTP client transport connection is not TLS. 1451 # * An adaptation service connection-encryption flag is off. 1452 # * The peer or origin server transport connection is not TLS. 1453 # 1454 # Caching currently does not affect these rules. This cache ignorance 1455 # implies that only the current HTTP client transport and REQMOD 1456 # services status determine whether this ACL matches a from-cache 1457 # transaction. The source of the cached response does not have any 1458 # effect on future transaction that use the cached response without 1459 # revalidation. This may change. 1460 # 1461 # DNS, ICP, and HTCP exchanges during the master transaction do not 1462 # affect these rules. 1463ENDIF 1464 acl aclname any-of acl1 acl2 ... 1465 # match any one of the acls [fast or slow] 1466 # The first matching ACL stops further ACL evaluation. 1467 # 1468 # ACLs from multiple any-of lines with the same name are ORed. 1469 # For example, A = (a1 or a2) or (a3 or a4) can be written as 1470 # acl A any-of a1 a2 1471 # acl A any-of a3 a4 1472 # 1473 # This group ACL is fast if all evaluated ACLs in the group are fast 1474 # and slow otherwise. 1475 1476 acl aclname all-of acl1 acl2 ... 1477 # match all of the acls [fast or slow] 1478 # The first mismatching ACL stops further ACL evaluation. 1479 # 1480 # ACLs from multiple all-of lines with the same name are ORed. 1481 # For example, B = (b1 and b2) or (b3 and b4) can be written as 1482 # acl B all-of b1 b2 1483 # acl B all-of b3 b4 1484 # 1485 # This group ACL is fast if all evaluated ACLs in the group are fast 1486 # and slow otherwise. 1487 1488 Examples: 1489 acl macaddress arp 09:00:2b:23:45:67 1490 acl myexample dst_as 1241 1491 acl password proxy_auth REQUIRED 1492 acl fileupload req_mime_type -i ^multipart/form-data$ 1493 acl javascript rep_mime_type -i ^application/x-javascript$ 1494 1495NOCOMMENT_START 1496# 1497# Recommended minimum configuration: 1498# 1499 1500# Example rule allowing access from your local networks. 1501# Adapt to list your (internal) IP networks from where browsing 1502# should be allowed 1503acl localnet src 0.0.0.1-0.255.255.255 # RFC 1122 "this" network (LAN) 1504acl localnet src 10.0.0.0/8 # RFC 1918 local private network (LAN) 1505acl localnet src 100.64.0.0/10 # RFC 6598 shared address space (CGN) 1506acl localnet src 169.254.0.0/16 # RFC 3927 link-local (directly plugged) machines 1507acl localnet src 172.16.0.0/12 # RFC 1918 local private network (LAN) 1508acl localnet src 192.168.0.0/16 # RFC 1918 local private network (LAN) 1509acl localnet src fc00::/7 # RFC 4193 local private network range 1510acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines 1511 1512acl SSL_ports port 443 1513acl Safe_ports port 80 # http 1514acl Safe_ports port 21 # ftp 1515acl Safe_ports port 443 # https 1516acl Safe_ports port 70 # gopher 1517acl Safe_ports port 210 # wais 1518acl Safe_ports port 1025-65535 # unregistered ports 1519acl Safe_ports port 280 # http-mgmt 1520acl Safe_ports port 488 # gss-http 1521acl Safe_ports port 591 # filemaker 1522acl Safe_ports port 777 # multiling http 1523acl CONNECT method CONNECT 1524NOCOMMENT_END 1525DOC_END 1526 1527NAME: proxy_protocol_access 1528TYPE: acl_access 1529LOC: Config.accessList.proxyProtocol 1530DEFAULT: none 1531DEFAULT_DOC: all TCP connections to ports with require-proxy-header will be denied 1532DOC_START 1533 Determine which client proxies can be trusted to provide correct 1534 information regarding real client IP address using PROXY protocol. 1535 1536 Requests may pass through a chain of several other proxies 1537 before reaching us. The original source details may by sent in: 1538 * HTTP message Forwarded header, or 1539 * HTTP message X-Forwarded-For header, or 1540 * PROXY protocol connection header. 1541 1542 This directive is solely for validating new PROXY protocol 1543 connections received from a port flagged with require-proxy-header. 1544 It is checked only once after TCP connection setup. 1545 1546 A deny match results in TCP connection closure. 1547 1548 An allow match is required for Squid to permit the corresponding 1549 TCP connection, before Squid even looks for HTTP request headers. 1550 If there is an allow match, Squid starts using PROXY header information 1551 to determine the source address of the connection for all future ACL 1552 checks, logging, etc. 1553 1554 SECURITY CONSIDERATIONS: 1555 1556 Any host from which we accept client IP details can place 1557 incorrect information in the relevant header, and Squid 1558 will use the incorrect information as if it were the 1559 source address of the request. This may enable remote 1560 hosts to bypass any access control restrictions that are 1561 based on the client's source addresses. 1562 1563 This clause only supports fast acl types. 1564 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 1565DOC_END 1566 1567NAME: follow_x_forwarded_for 1568TYPE: acl_access 1569IFDEF: FOLLOW_X_FORWARDED_FOR 1570LOC: Config.accessList.followXFF 1571DEFAULT_IF_NONE: deny all 1572DEFAULT_DOC: X-Forwarded-For header will be ignored. 1573DOC_START 1574 Determine which client proxies can be trusted to provide correct 1575 information regarding real client IP address. 1576 1577 Requests may pass through a chain of several other proxies 1578 before reaching us. The original source details may by sent in: 1579 * HTTP message Forwarded header, or 1580 * HTTP message X-Forwarded-For header, or 1581 * PROXY protocol connection header. 1582 1583 PROXY protocol connections are controlled by the proxy_protocol_access 1584 directive which is checked before this. 1585 1586 If a request reaches us from a source that is allowed by this 1587 directive, then we trust the information it provides regarding 1588 the IP of the client it received from (if any). 1589 1590 For the purpose of ACLs used in this directive the src ACL type always 1591 matches the address we are testing and srcdomain matches its rDNS. 1592 1593 On each HTTP request Squid checks for X-Forwarded-For header fields. 1594 If found the header values are iterated in reverse order and an allow 1595 match is required for Squid to continue on to the next value. 1596 The verification ends when a value receives a deny match, cannot be 1597 tested, or there are no more values to test. 1598 NOTE: Squid does not yet follow the Forwarded HTTP header. 1599 1600 The end result of this process is an IP address that we will 1601 refer to as the indirect client address. This address may 1602 be treated as the client address for access control, ICAP, delay 1603 pools and logging, depending on the acl_uses_indirect_client, 1604 icap_uses_indirect_client, delay_pool_uses_indirect_client, 1605 log_uses_indirect_client and tproxy_uses_indirect_client options. 1606 1607 This clause only supports fast acl types. 1608 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 1609 1610 SECURITY CONSIDERATIONS: 1611 1612 Any host from which we accept client IP details can place 1613 incorrect information in the relevant header, and Squid 1614 will use the incorrect information as if it were the 1615 source address of the request. This may enable remote 1616 hosts to bypass any access control restrictions that are 1617 based on the client's source addresses. 1618 1619 For example: 1620 1621 acl localhost src 127.0.0.1 1622 acl my_other_proxy srcdomain .proxy.example.com 1623 follow_x_forwarded_for allow localhost 1624 follow_x_forwarded_for allow my_other_proxy 1625DOC_END 1626 1627NAME: acl_uses_indirect_client 1628COMMENT: on|off 1629TYPE: onoff 1630IFDEF: FOLLOW_X_FORWARDED_FOR 1631DEFAULT: on 1632LOC: Config.onoff.acl_uses_indirect_client 1633DOC_START 1634 Controls whether the indirect client address 1635 (see follow_x_forwarded_for) is used instead of the 1636 direct client address in acl matching. 1637 1638 NOTE: maxconn ACL considers direct TCP links and indirect 1639 clients will always have zero. So no match. 1640DOC_END 1641 1642NAME: delay_pool_uses_indirect_client 1643COMMENT: on|off 1644TYPE: onoff 1645IFDEF: FOLLOW_X_FORWARDED_FOR&&USE_DELAY_POOLS 1646DEFAULT: on 1647LOC: Config.onoff.delay_pool_uses_indirect_client 1648DOC_START 1649 Controls whether the indirect client address 1650 (see follow_x_forwarded_for) is used instead of the 1651 direct client address in delay pools. 1652DOC_END 1653 1654NAME: log_uses_indirect_client 1655COMMENT: on|off 1656TYPE: onoff 1657IFDEF: FOLLOW_X_FORWARDED_FOR 1658DEFAULT: on 1659LOC: Config.onoff.log_uses_indirect_client 1660DOC_START 1661 Controls whether the indirect client address 1662 (see follow_x_forwarded_for) is used instead of the 1663 direct client address in the access log. 1664DOC_END 1665 1666NAME: tproxy_uses_indirect_client 1667COMMENT: on|off 1668TYPE: onoff 1669IFDEF: FOLLOW_X_FORWARDED_FOR&&LINUX_NETFILTER 1670DEFAULT: off 1671LOC: Config.onoff.tproxy_uses_indirect_client 1672DOC_START 1673 Controls whether the indirect client address 1674 (see follow_x_forwarded_for) is used instead of the 1675 direct client address when spoofing the outgoing client. 1676 1677 This has no effect on requests arriving in non-tproxy 1678 mode ports. 1679 1680 SECURITY WARNING: Usage of this option is dangerous 1681 and should not be used trivially. Correct configuration 1682 of follow_x_forwarded_for with a limited set of trusted 1683 sources is required to prevent abuse of your proxy. 1684DOC_END 1685 1686NAME: spoof_client_ip 1687TYPE: acl_access 1688LOC: Config.accessList.spoof_client_ip 1689DEFAULT: none 1690DEFAULT_DOC: Allow spoofing on all TPROXY traffic. 1691DOC_START 1692 Control client IP address spoofing of TPROXY traffic based on 1693 defined access lists. 1694 1695 spoof_client_ip allow|deny [!]aclname ... 1696 1697 If there are no "spoof_client_ip" lines present, the default 1698 is to "allow" spoofing of any suitable request. 1699 1700 Note that the cache_peer "no-tproxy" option overrides this ACL. 1701 1702 This clause supports fast acl types. 1703 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 1704DOC_END 1705 1706NAME: http_access 1707TYPE: acl_access 1708LOC: Config.accessList.http 1709DEFAULT_IF_NONE: deny all 1710DEFAULT_DOC: Deny, unless rules exist in squid.conf. 1711DOC_START 1712 Allowing or Denying access based on defined access lists 1713 1714 To allow or deny a message received on an HTTP, HTTPS, or FTP port: 1715 http_access allow|deny [!]aclname ... 1716 1717 NOTE on default values: 1718 1719 If there are no "access" lines present, the default is to deny 1720 the request. 1721 1722 If none of the "access" lines cause a match, the default is the 1723 opposite of the last line in the list. If the last line was 1724 deny, the default is allow. Conversely, if the last line 1725 is allow, the default will be deny. For these reasons, it is a 1726 good idea to have an "deny all" entry at the end of your access 1727 lists to avoid potential confusion. 1728 1729 This clause supports both fast and slow acl types. 1730 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 1731 1732NOCOMMENT_START 1733 1734# 1735# Recommended minimum Access Permission configuration: 1736# 1737# Deny requests to certain unsafe ports 1738http_access deny !Safe_ports 1739 1740# Deny CONNECT to other than secure SSL ports 1741http_access deny CONNECT !SSL_ports 1742 1743# Only allow cachemgr access from localhost 1744http_access allow localhost manager 1745http_access deny manager 1746 1747# We strongly recommend the following be uncommented to protect innocent 1748# web applications running on the proxy server who think the only 1749# one who can access services on "localhost" is a local user 1750#http_access deny to_localhost 1751 1752# 1753# INSERT YOUR OWN RULE(S) HERE TO ALLOW ACCESS FROM YOUR CLIENTS 1754# 1755 1756# Example rule allowing access from your local networks. 1757# Adapt localnet in the ACL section to list your (internal) IP networks 1758# from where browsing should be allowed 1759http_access allow localnet 1760http_access allow localhost 1761 1762# And finally deny all other access to this proxy 1763http_access deny all 1764NOCOMMENT_END 1765DOC_END 1766 1767NAME: adapted_http_access http_access2 1768TYPE: acl_access 1769LOC: Config.accessList.adapted_http 1770DEFAULT: none 1771DEFAULT_DOC: Allow, unless rules exist in squid.conf. 1772DOC_START 1773 Allowing or Denying access based on defined access lists 1774 1775 Essentially identical to http_access, but runs after redirectors 1776 and ICAP/eCAP adaptation. Allowing access control based on their 1777 output. 1778 1779 If not set then only http_access is used. 1780DOC_END 1781 1782NAME: http_reply_access 1783TYPE: acl_access 1784LOC: Config.accessList.reply 1785DEFAULT: none 1786DEFAULT_DOC: Allow, unless rules exist in squid.conf. 1787DOC_START 1788 Allow replies to client requests. This is complementary to http_access. 1789 1790 http_reply_access allow|deny [!] aclname ... 1791 1792 NOTE: if there are no access lines present, the default is to allow 1793 all replies. 1794 1795 If none of the access lines cause a match the opposite of the 1796 last line will apply. Thus it is good practice to end the rules 1797 with an "allow all" or "deny all" entry. 1798 1799 This clause supports both fast and slow acl types. 1800 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 1801DOC_END 1802 1803NAME: icp_access 1804TYPE: acl_access 1805LOC: Config.accessList.icp 1806DEFAULT: none 1807DEFAULT_DOC: Deny, unless rules exist in squid.conf. 1808DOC_START 1809 Allowing or Denying access to the ICP port based on defined 1810 access lists 1811 1812 icp_access allow|deny [!]aclname ... 1813 1814 NOTE: The default if no icp_access lines are present is to 1815 deny all traffic. This default may cause problems with peers 1816 using ICP. 1817 1818 This clause only supports fast acl types. 1819 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 1820 1821# Allow ICP queries from local networks only 1822#icp_access allow localnet 1823#icp_access deny all 1824DOC_END 1825 1826NAME: htcp_access 1827IFDEF: USE_HTCP 1828TYPE: acl_access 1829LOC: Config.accessList.htcp 1830DEFAULT: none 1831DEFAULT_DOC: Deny, unless rules exist in squid.conf. 1832DOC_START 1833 Allowing or Denying access to the HTCP port based on defined 1834 access lists 1835 1836 htcp_access allow|deny [!]aclname ... 1837 1838 See also htcp_clr_access for details on access control for 1839 cache purge (CLR) HTCP messages. 1840 1841 NOTE: The default if no htcp_access lines are present is to 1842 deny all traffic. This default may cause problems with peers 1843 using the htcp option. 1844 1845 This clause only supports fast acl types. 1846 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 1847 1848# Allow HTCP queries from local networks only 1849#htcp_access allow localnet 1850#htcp_access deny all 1851DOC_END 1852 1853NAME: htcp_clr_access 1854IFDEF: USE_HTCP 1855TYPE: acl_access 1856LOC: Config.accessList.htcp_clr 1857DEFAULT: none 1858DEFAULT_DOC: Deny, unless rules exist in squid.conf. 1859DOC_START 1860 Allowing or Denying access to purge content using HTCP based 1861 on defined access lists. 1862 See htcp_access for details on general HTCP access control. 1863 1864 htcp_clr_access allow|deny [!]aclname ... 1865 1866 This clause only supports fast acl types. 1867 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 1868 1869# Allow HTCP CLR requests from trusted peers 1870acl htcp_clr_peer src 192.0.2.2 2001:DB8::2 1871htcp_clr_access allow htcp_clr_peer 1872htcp_clr_access deny all 1873DOC_END 1874 1875NAME: miss_access 1876TYPE: acl_access 1877LOC: Config.accessList.miss 1878DEFAULT: none 1879DEFAULT_DOC: Allow, unless rules exist in squid.conf. 1880DOC_START 1881 Determines whether network access is permitted when satisfying a request. 1882 1883 For example; 1884 to force your neighbors to use you as a sibling instead of 1885 a parent. 1886 1887 acl localclients src 192.0.2.0/24 2001:DB8::a:0/64 1888 miss_access deny !localclients 1889 miss_access allow all 1890 1891 This means only your local clients are allowed to fetch relayed/MISS 1892 replies from the network and all other clients can only fetch cached 1893 objects (HITs). 1894 1895 The default for this setting allows all clients who passed the 1896 http_access rules to relay via this proxy. 1897 1898 This clause only supports fast acl types. 1899 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 1900DOC_END 1901 1902NAME: ident_lookup_access 1903TYPE: acl_access 1904IFDEF: USE_IDENT 1905DEFAULT: none 1906DEFAULT_DOC: Unless rules exist in squid.conf, IDENT is not fetched. 1907LOC: Ident::TheConfig.identLookup 1908DOC_START 1909 A list of ACL elements which, if matched, cause an ident 1910 (RFC 931) lookup to be performed for this request. For 1911 example, you might choose to always perform ident lookups 1912 for your main multi-user Unix boxes, but not for your Macs 1913 and PCs. By default, ident lookups are not performed for 1914 any requests. 1915 1916 To enable ident lookups for specific client addresses, you 1917 can follow this example: 1918 1919 acl ident_aware_hosts src 198.168.1.0/24 1920 ident_lookup_access allow ident_aware_hosts 1921 ident_lookup_access deny all 1922 1923 Only src type ACL checks are fully supported. A srcdomain 1924 ACL might work at times, but it will not always provide 1925 the correct result. 1926 1927 This clause only supports fast acl types. 1928 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 1929DOC_END 1930 1931NAME: reply_body_max_size 1932COMMENT: size [acl acl...] 1933TYPE: acl_b_size_t 1934DEFAULT: none 1935DEFAULT_DOC: No limit is applied. 1936LOC: Config.ReplyBodySize 1937DOC_START 1938 This option specifies the maximum size of a reply body. It can be 1939 used to prevent users from downloading very large files, such as 1940 MP3's and movies. When the reply headers are received, the 1941 reply_body_max_size lines are processed, and the first line where 1942 all (if any) listed ACLs are true is used as the maximum body size 1943 for this reply. 1944 1945 This size is checked twice. First when we get the reply headers, 1946 we check the content-length value. If the content length value exists 1947 and is larger than the allowed size, the request is denied and the 1948 user receives an error message that says "the request or reply 1949 is too large." If there is no content-length, and the reply 1950 size exceeds this limit, the client's connection is just closed 1951 and they will receive a partial reply. 1952 1953 WARNING: downstream caches probably can not detect a partial reply 1954 if there is no content-length header, so they will cache 1955 partial responses and give them out as hits. You should NOT 1956 use this option if you have downstream caches. 1957 1958 WARNING: A maximum size smaller than the size of squid's error messages 1959 will cause an infinite loop and crash squid. Ensure that the smallest 1960 non-zero value you use is greater that the maximum header size plus 1961 the size of your largest error page. 1962 1963 If you set this parameter none (the default), there will be 1964 no limit imposed. 1965 1966 Configuration Format is: 1967 reply_body_max_size SIZE UNITS [acl ...] 1968 ie. 1969 reply_body_max_size 10 MB 1970 1971DOC_END 1972 1973NAME: on_unsupported_protocol 1974TYPE: on_unsupported_protocol 1975LOC: Config.accessList.on_unsupported_protocol 1976DEFAULT: none 1977DEFAULT_DOC: Respond with an error message to unidentifiable traffic 1978DOC_START 1979 Determines Squid behavior when encountering strange requests at the 1980 beginning of an accepted TCP connection or the beginning of a bumped 1981 CONNECT tunnel. Controlling Squid reaction to unexpected traffic is 1982 especially useful in interception environments where Squid is likely 1983 to see connections for unsupported protocols that Squid should either 1984 terminate or tunnel at TCP level. 1985 1986 on_unsupported_protocol <action> [!]acl ... 1987 1988 The first matching action wins. Only fast ACLs are supported. 1989 1990 Supported actions are: 1991 1992 tunnel: Establish a TCP connection with the intended server and 1993 blindly shovel TCP packets between the client and server. 1994 1995 respond: Respond with an error message, using the transfer protocol 1996 for the Squid port that received the request (e.g., HTTP 1997 for connections intercepted at the http_port). This is the 1998 default. 1999 2000 Squid expects the following traffic patterns: 2001 2002 http_port: a plain HTTP request 2003 https_port: SSL/TLS handshake followed by an [encrypted] HTTP request 2004 ftp_port: a plain FTP command (no on_unsupported_protocol support yet!) 2005 CONNECT tunnel on http_port: same as https_port 2006 CONNECT tunnel on https_port: same as https_port 2007 2008 Currently, this directive has effect on intercepted connections and 2009 bumped tunnels only. Other cases are not supported because Squid 2010 cannot know the intended destination of other traffic. 2011 2012 For example: 2013 # define what Squid errors indicate receiving non-HTTP traffic: 2014 acl foreignProtocol squid_error ERR_PROTOCOL_UNKNOWN ERR_TOO_BIG 2015 # define what Squid errors indicate receiving nothing: 2016 acl serverTalksFirstProtocol squid_error ERR_REQUEST_START_TIMEOUT 2017 # tunnel everything that does not look like HTTP: 2018 on_unsupported_protocol tunnel foreignProtocol 2019 # tunnel if we think the client waits for the server to talk first: 2020 on_unsupported_protocol tunnel serverTalksFirstProtocol 2021 # in all other error cases, just send an HTTP "error page" response: 2022 on_unsupported_protocol respond all 2023 2024 See also: squid_error ACL 2025DOC_END 2026 2027COMMENT_START 2028 NETWORK OPTIONS 2029 ----------------------------------------------------------------------------- 2030COMMENT_END 2031 2032NAME: http_port ascii_port 2033TYPE: PortCfg 2034DEFAULT: none 2035LOC: HttpPortList 2036DOC_START 2037 Usage: port [mode] [options] 2038 hostname:port [mode] [options] 2039 1.2.3.4:port [mode] [options] 2040 2041 The socket addresses where Squid will listen for HTTP client 2042 requests. You may specify multiple socket addresses. 2043 There are three forms: port alone, hostname with port, and 2044 IP address with port. If you specify a hostname or IP 2045 address, Squid binds the socket to that specific 2046 address. Most likely, you do not need to bind to a specific 2047 address, so you can use the port number alone. 2048 2049 If you are running Squid in accelerator mode, you 2050 probably want to listen on port 80 also, or instead. 2051 2052 The -a command line option may be used to specify additional 2053 port(s) where Squid listens for proxy request. Such ports will 2054 be plain proxy ports with no options. 2055 2056 You may specify multiple socket addresses on multiple lines. 2057 2058 Modes: 2059 2060 intercept Support for IP-Layer NAT interception delivering 2061 traffic to this Squid port. 2062 NP: disables authentication on the port. 2063 2064 tproxy Support Linux TPROXY (or BSD divert-to) with spoofing 2065 of outgoing connections using the client IP address. 2066 NP: disables authentication on the port. 2067 2068 accel Accelerator / reverse proxy mode 2069 2070 ssl-bump For each CONNECT request allowed by ssl_bump ACLs, 2071 establish secure connection with the client and with 2072 the server, decrypt HTTPS messages as they pass through 2073 Squid, and treat them as unencrypted HTTP messages, 2074 becoming the man-in-the-middle. 2075 2076 The ssl_bump option is required to fully enable 2077 bumping of CONNECT requests. 2078 2079 Omitting the mode flag causes default forward proxy mode to be used. 2080 2081 2082 Accelerator Mode Options: 2083 2084 defaultsite=domainname 2085 What to use for the Host: header if it is not present 2086 in a request. Determines what site (not origin server) 2087 accelerators should consider the default. 2088 2089 no-vhost Disable using HTTP/1.1 Host header for virtual domain support. 2090 2091 protocol= Protocol to reconstruct accelerated and intercepted 2092 requests with. Defaults to HTTP/1.1 for http_port and 2093 HTTPS/1.1 for https_port. 2094 When an unsupported value is configured Squid will 2095 produce a FATAL error. 2096 Values: HTTP or HTTP/1.1, HTTPS or HTTPS/1.1 2097 2098 vport Virtual host port support. Using the http_port number 2099 instead of the port passed on Host: headers. 2100 2101 vport=NN Virtual host port support. Using the specified port 2102 number instead of the port passed on Host: headers. 2103 2104 act-as-origin 2105 Act as if this Squid is the origin server. 2106 This currently means generate new Date: and Expires: 2107 headers on HIT instead of adding Age:. 2108 2109 ignore-cc Ignore request Cache-Control headers. 2110 2111 WARNING: This option violates HTTP specifications if 2112 used in non-accelerator setups. 2113 2114 allow-direct Allow direct forwarding in accelerator mode. Normally 2115 accelerated requests are denied direct forwarding as if 2116 never_direct was used. 2117 2118 WARNING: this option opens accelerator mode to security 2119 vulnerabilities usually only affecting in interception 2120 mode. Make sure to protect forwarding with suitable 2121 http_access rules when using this. 2122 2123 2124 SSL Bump Mode Options: 2125 In addition to these options ssl-bump requires TLS/SSL options. 2126 2127 generate-host-certificates[=<on|off>] 2128 Dynamically create SSL server certificates for the 2129 destination hosts of bumped CONNECT requests.When 2130 enabled, the cert and key options are used to sign 2131 generated certificates. Otherwise generated 2132 certificate will be selfsigned. 2133 If there is a CA certificate lifetime of the generated 2134 certificate equals lifetime of the CA certificate. If 2135 generated certificate is selfsigned lifetime is three 2136 years. 2137 This option is enabled by default when ssl-bump is used. 2138 See the ssl-bump option above for more information. 2139 2140 dynamic_cert_mem_cache_size=SIZE 2141 Approximate total RAM size spent on cached generated 2142 certificates. If set to zero, caching is disabled. The 2143 default value is 4MB. 2144 2145 TLS / SSL Options: 2146 2147 tls-cert= Path to file containing an X.509 certificate (PEM format) 2148 to be used in the TLS handshake ServerHello. 2149 2150 If this certificate is constrained by KeyUsage TLS 2151 feature it must allow HTTP server usage, along with 2152 any additional restrictions imposed by your choice 2153 of options= settings. 2154 2155 When OpenSSL is used this file may also contain a 2156 chain of intermediate CA certificates to send in the 2157 TLS handshake. 2158 2159 When GnuTLS is used this option (and any paired 2160 tls-key= option) may be repeated to load multiple 2161 certificates for different domains. 2162 2163 Also, when generate-host-certificates=on is configured 2164 the first tls-cert= option must be a CA certificate 2165 capable of signing the automatically generated 2166 certificates. 2167 2168 tls-key= Path to a file containing private key file (PEM format) 2169 for the previous tls-cert= option. 2170 2171 If tls-key= is not specified tls-cert= is assumed to 2172 reference a PEM file containing both the certificate 2173 and private key. 2174 2175 cipher= Colon separated list of supported ciphers. 2176 NOTE: some ciphers such as EDH ciphers depend on 2177 additional settings. If those settings are 2178 omitted the ciphers may be silently ignored 2179 by the OpenSSL library. 2180 2181 options= Various SSL implementation options. The most important 2182 being: 2183 2184 NO_SSLv3 Disallow the use of SSLv3 2185 2186 NO_TLSv1 Disallow the use of TLSv1.0 2187 2188 NO_TLSv1_1 Disallow the use of TLSv1.1 2189 2190 NO_TLSv1_2 Disallow the use of TLSv1.2 2191 2192 SINGLE_DH_USE 2193 Always create a new key when using 2194 temporary/ephemeral DH key exchanges 2195 2196 SINGLE_ECDH_USE 2197 Enable ephemeral ECDH key exchange. 2198 The adopted curve should be specified 2199 using the tls-dh option. 2200 2201 NO_TICKET 2202 Disable use of RFC5077 session tickets. 2203 Some servers may have problems 2204 understanding the TLS extension due 2205 to ambiguous specification in RFC4507. 2206 2207 ALL Enable various bug workarounds 2208 suggested as "harmless" by OpenSSL 2209 Be warned that this reduces SSL/TLS 2210 strength to some attacks. 2211 2212 See the OpenSSL SSL_CTX_set_options documentation for a 2213 more complete list. 2214 2215 clientca= File containing the list of CAs to use when 2216 requesting a client certificate. 2217 2218 tls-cafile= PEM file containing CA certificates to use when verifying 2219 client certificates. If not configured clientca will be 2220 used. May be repeated to load multiple files. 2221 2222 capath= Directory containing additional CA certificates 2223 and CRL lists to use when verifying client certificates. 2224 Requires OpenSSL or LibreSSL. 2225 2226 crlfile= File of additional CRL lists to use when verifying 2227 the client certificate, in addition to CRLs stored in 2228 the capath. Implies VERIFY_CRL flag below. 2229 2230 tls-dh=[curve:]file 2231 File containing DH parameters for temporary/ephemeral DH key 2232 exchanges, optionally prefixed by a curve for ephemeral ECDH 2233 key exchanges. 2234 See OpenSSL documentation for details on how to create the 2235 DH parameter file. Supported curves for ECDH can be listed 2236 using the "openssl ecparam -list_curves" command. 2237 WARNING: EDH and EECDH ciphers will be silently disabled if 2238 this option is not set. 2239 2240 sslflags= Various flags modifying the use of SSL: 2241 DELAYED_AUTH 2242 Don't request client certificates 2243 immediately, but wait until acl processing 2244 requires a certificate (not yet implemented). 2245 NO_SESSION_REUSE 2246 Don't allow for session reuse. Each connection 2247 will result in a new SSL session. 2248 VERIFY_CRL 2249 Verify CRL lists when accepting client 2250 certificates. 2251 VERIFY_CRL_ALL 2252 Verify CRL lists for all certificates in the 2253 client certificate chain. 2254 2255 tls-default-ca[=off] 2256 Whether to use the system Trusted CAs. Default is OFF. 2257 2258 tls-no-npn Do not use the TLS NPN extension to advertise HTTP/1.1. 2259 2260 sslcontext= SSL session ID context identifier. 2261 2262 Other Options: 2263 2264 connection-auth[=on|off] 2265 use connection-auth=off to tell Squid to prevent 2266 forwarding Microsoft connection oriented authentication 2267 (NTLM, Negotiate and Kerberos) 2268 2269 disable-pmtu-discovery= 2270 Control Path-MTU discovery usage: 2271 off lets OS decide on what to do (default). 2272 transparent disable PMTU discovery when transparent 2273 support is enabled. 2274 always disable always PMTU discovery. 2275 2276 In many setups of transparently intercepting proxies 2277 Path-MTU discovery can not work on traffic towards the 2278 clients. This is the case when the intercepting device 2279 does not fully track connections and fails to forward 2280 ICMP must fragment messages to the cache server. If you 2281 have such setup and experience that certain clients 2282 sporadically hang or never complete requests set 2283 disable-pmtu-discovery option to 'transparent'. 2284 2285 name= Specifies a internal name for the port. Defaults to 2286 the port specification (port or addr:port) 2287 2288 tcpkeepalive[=idle,interval,timeout] 2289 Enable TCP keepalive probes of idle connections. 2290 In seconds; idle is the initial time before TCP starts 2291 probing the connection, interval how often to probe, and 2292 timeout the time before giving up. 2293 2294 require-proxy-header 2295 Require PROXY protocol version 1 or 2 connections. 2296 The proxy_protocol_access is required to whitelist 2297 downstream proxies which can be trusted. 2298 2299 If you run Squid on a dual-homed machine with an internal 2300 and an external interface we recommend you to specify the 2301 internal address:port in http_port. This way Squid will only be 2302 visible on the internal address. 2303 2304NOCOMMENT_START 2305 2306# Squid normally listens to port 3128 2307http_port @DEFAULT_HTTP_PORT@ 2308NOCOMMENT_END 2309DOC_END 2310 2311NAME: https_port 2312IFDEF: USE_GNUTLS||USE_OPENSSL 2313TYPE: PortCfg 2314DEFAULT: none 2315LOC: HttpPortList 2316DOC_START 2317 Usage: [ip:]port [mode] tls-cert=certificate.pem [options] 2318 2319 The socket address where Squid will listen for client requests made 2320 over TLS or SSL connections. Commonly referred to as HTTPS. 2321 2322 This is most useful for situations where you are running squid in 2323 accelerator mode and you want to do the TLS work at the accelerator 2324 level. 2325 2326 You may specify multiple socket addresses on multiple lines, 2327 each with their own certificate and/or options. 2328 2329 The tls-cert= option is mandatory on HTTPS ports. 2330 2331 See http_port for a list of modes and options. 2332DOC_END 2333 2334NAME: ftp_port 2335TYPE: PortCfg 2336DEFAULT: none 2337LOC: FtpPortList 2338DOC_START 2339 Enables Native FTP proxy by specifying the socket address where Squid 2340 listens for FTP client requests. See http_port directive for various 2341 ways to specify the listening address and mode. 2342 2343 Usage: ftp_port address [mode] [options] 2344 2345 WARNING: This is a new, experimental, complex feature that has seen 2346 limited production exposure. Some Squid modules (e.g., caching) do not 2347 currently work with native FTP proxying, and many features have not 2348 even been tested for compatibility. Test well before deploying! 2349 2350 Native FTP proxying differs substantially from proxying HTTP requests 2351 with ftp:// URIs because Squid works as an FTP server and receives 2352 actual FTP commands (rather than HTTP requests with FTP URLs). 2353 2354 Native FTP commands accepted at ftp_port are internally converted or 2355 wrapped into HTTP-like messages. The same happens to Native FTP 2356 responses received from FTP origin servers. Those HTTP-like messages 2357 are shoveled through regular access control and adaptation layers 2358 between the FTP client and the FTP origin server. This allows Squid to 2359 examine, adapt, block, and log FTP exchanges. Squid reuses most HTTP 2360 mechanisms when shoveling wrapped FTP messages. For example, 2361 http_access and adaptation_access directives are used. 2362 2363 Modes: 2364 2365 intercept Same as http_port intercept. The FTP origin address is 2366 determined based on the intended destination of the 2367 intercepted connection. 2368 2369 tproxy Support Linux TPROXY for spoofing outgoing 2370 connections using the client IP address. 2371 NP: disables authentication and maybe IPv6 on the port. 2372 2373 By default (i.e., without an explicit mode option), Squid extracts the 2374 FTP origin address from the login@origin parameter of the FTP USER 2375 command. Many popular FTP clients support such native FTP proxying. 2376 2377 Options: 2378 2379 name=token Specifies an internal name for the port. Defaults to 2380 the port address. Usable with myportname ACL. 2381 2382 ftp-track-dirs 2383 Enables tracking of FTP directories by injecting extra 2384 PWD commands and adjusting Request-URI (in wrapping 2385 HTTP requests) to reflect the current FTP server 2386 directory. Tracking is disabled by default. 2387 2388 protocol=FTP Protocol to reconstruct accelerated and intercepted 2389 requests with. Defaults to FTP. No other accepted 2390 values have been tested with. An unsupported value 2391 results in a FATAL error. Accepted values are FTP, 2392 HTTP (or HTTP/1.1), and HTTPS (or HTTPS/1.1). 2393 2394 Other http_port modes and options that are not specific to HTTP and 2395 HTTPS may also work. 2396DOC_END 2397 2398NAME: tcp_outgoing_tos tcp_outgoing_ds tcp_outgoing_dscp 2399TYPE: acl_tos 2400DEFAULT: none 2401LOC: Ip::Qos::TheConfig.tosToServer 2402DOC_START 2403 Allows you to select a TOS/Diffserv value for packets outgoing 2404 on the server side, based on an ACL. 2405 2406 tcp_outgoing_tos ds-field [!]aclname ... 2407 2408 Example where normal_service_net uses the TOS value 0x00 2409 and good_service_net uses 0x20 2410 2411 acl normal_service_net src 10.0.0.0/24 2412 acl good_service_net src 10.0.1.0/24 2413 tcp_outgoing_tos 0x00 normal_service_net 2414 tcp_outgoing_tos 0x20 good_service_net 2415 2416 TOS/DSCP values really only have local significance - so you should 2417 know what you're specifying. For more information, see RFC2474, 2418 RFC2475, and RFC3260. 2419 2420 The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or 2421 "default" to use whatever default your host has. 2422 Note that only multiples of 4 are usable as the two rightmost bits have 2423 been redefined for use by ECN (RFC 3168 section 23.1). 2424 The squid parser will enforce this by masking away the ECN bits. 2425 2426 Processing proceeds in the order specified, and stops at first fully 2427 matching line. 2428 2429 Only fast ACLs are supported. 2430DOC_END 2431 2432NAME: clientside_tos 2433TYPE: acl_tos 2434DEFAULT: none 2435LOC: Ip::Qos::TheConfig.tosToClient 2436DOC_START 2437 Allows you to select a TOS/DSCP value for packets being transmitted 2438 on the client-side, based on an ACL. 2439 2440 clientside_tos ds-field [!]aclname ... 2441 2442 Example where normal_service_net uses the TOS value 0x00 2443 and good_service_net uses 0x20 2444 2445 acl normal_service_net src 10.0.0.0/24 2446 acl good_service_net src 10.0.1.0/24 2447 clientside_tos 0x00 normal_service_net 2448 clientside_tos 0x20 good_service_net 2449 2450 Note: This feature is incompatible with qos_flows. Any TOS values set here 2451 will be overwritten by TOS values in qos_flows. 2452 2453 The TOS/DSCP byte must be exactly that - a octet value 0 - 255, or 2454 "default" to use whatever default your host has. 2455 Note that only multiples of 4 are usable as the two rightmost bits have 2456 been redefined for use by ECN (RFC 3168 section 23.1). 2457 The squid parser will enforce this by masking away the ECN bits. 2458 2459 This clause only supports fast acl types. 2460 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 2461DOC_END 2462 2463NAME: tcp_outgoing_mark 2464TYPE: acl_nfmark 2465IFDEF: SO_MARK&&USE_LIBCAP 2466DEFAULT: none 2467LOC: Ip::Qos::TheConfig.nfmarkToServer 2468DOC_START 2469 Allows you to apply a Netfilter mark value to outgoing packets 2470 on the server side, based on an ACL. 2471 2472 tcp_outgoing_mark mark-value [!]aclname ... 2473 2474 Example where normal_service_net uses the mark value 0x00 2475 and good_service_net uses 0x20 2476 2477 acl normal_service_net src 10.0.0.0/24 2478 acl good_service_net src 10.0.1.0/24 2479 tcp_outgoing_mark 0x00 normal_service_net 2480 tcp_outgoing_mark 0x20 good_service_net 2481 2482 Only fast ACLs are supported. 2483DOC_END 2484 2485NAME: clientside_mark 2486TYPE: acl_nfmark 2487IFDEF: SO_MARK&&USE_LIBCAP 2488DEFAULT: none 2489LOC: Ip::Qos::TheConfig.nfmarkToClient 2490DOC_START 2491 Allows you to apply a Netfilter mark value to packets being transmitted 2492 on the client-side, based on an ACL. 2493 2494 clientside_mark mark-value [!]aclname ... 2495 2496 Example where normal_service_net uses the mark value 0x00 2497 and good_service_net uses 0x20 2498 2499 acl normal_service_net src 10.0.0.0/24 2500 acl good_service_net src 10.0.1.0/24 2501 clientside_mark 0x00 normal_service_net 2502 clientside_mark 0x20 good_service_net 2503 2504 Note: This feature is incompatible with qos_flows. Any mark values set here 2505 will be overwritten by mark values in qos_flows. 2506 2507 This clause only supports fast acl types. 2508 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 2509DOC_END 2510 2511NAME: qos_flows 2512TYPE: QosConfig 2513IFDEF: USE_QOS_TOS 2514DEFAULT: none 2515LOC: Ip::Qos::TheConfig 2516DOC_START 2517 Allows you to select a TOS/DSCP value to mark outgoing 2518 connections to the client, based on where the reply was sourced. 2519 For platforms using netfilter, allows you to set a netfilter mark 2520 value instead of, or in addition to, a TOS value. 2521 2522 By default this functionality is disabled. To enable it with the default 2523 settings simply use "qos_flows mark" or "qos_flows tos". Default 2524 settings will result in the netfilter mark or TOS value being copied 2525 from the upstream connection to the client. Note that it is the connection 2526 CONNMARK value not the packet MARK value that is copied. 2527 2528 It is not currently possible to copy the mark or TOS value from the 2529 client to the upstream connection request. 2530 2531 TOS values really only have local significance - so you should 2532 know what you're specifying. For more information, see RFC2474, 2533 RFC2475, and RFC3260. 2534 2535 The TOS/DSCP byte must be exactly that - a octet value 0 - 255. 2536 Note that only multiples of 4 are usable as the two rightmost bits have 2537 been redefined for use by ECN (RFC 3168 section 23.1). 2538 The squid parser will enforce this by masking away the ECN bits. 2539 2540 Mark values can be any unsigned 32-bit integer value. 2541 2542 This setting is configured by setting the following values: 2543 2544 tos|mark Whether to set TOS or netfilter mark values 2545 2546 local-hit=0xFF Value to mark local cache hits. 2547 2548 sibling-hit=0xFF Value to mark hits from sibling peers. 2549 2550 parent-hit=0xFF Value to mark hits from parent peers. 2551 2552 miss=0xFF[/mask] Value to mark cache misses. Takes precedence 2553 over the preserve-miss feature (see below), unless 2554 mask is specified, in which case only the bits 2555 specified in the mask are written. 2556 2557 The TOS variant of the following features are only possible on Linux 2558 and require your kernel to be patched with the TOS preserving ZPH 2559 patch, available from http://zph.bratcheda.org 2560 No patch is needed to preserve the netfilter mark, which will work 2561 with all variants of netfilter. 2562 2563 disable-preserve-miss 2564 This option disables the preservation of the TOS or netfilter 2565 mark. By default, the existing TOS or netfilter mark value of 2566 the response coming from the remote server will be retained 2567 and masked with miss-mark. 2568 NOTE: in the case of a netfilter mark, the mark must be set on 2569 the connection (using the CONNMARK target) not on the packet 2570 (MARK target). 2571 2572 miss-mask=0xFF 2573 Allows you to mask certain bits in the TOS or mark value 2574 received from the remote server, before copying the value to 2575 the TOS sent towards clients. 2576 Default for tos: 0xFF (TOS from server is not changed). 2577 Default for mark: 0xFFFFFFFF (mark from server is not changed). 2578 2579 All of these features require the --enable-zph-qos compilation flag 2580 (enabled by default). Netfilter marking also requires the 2581 libnetfilter_conntrack libraries (--with-netfilter-conntrack) and 2582 libcap 2.09+ (--with-libcap). 2583 2584DOC_END 2585 2586NAME: tcp_outgoing_address 2587TYPE: acl_address 2588DEFAULT: none 2589DEFAULT_DOC: Address selection is performed by the operating system. 2590LOC: Config.accessList.outgoing_address 2591DOC_START 2592 Allows you to map requests to different outgoing IP addresses 2593 based on the username or source address of the user making 2594 the request. 2595 2596 tcp_outgoing_address ipaddr [[!]aclname] ... 2597 2598 For example; 2599 Forwarding clients with dedicated IPs for certain subnets. 2600 2601 acl normal_service_net src 10.0.0.0/24 2602 acl good_service_net src 10.0.2.0/24 2603 2604 tcp_outgoing_address 2001:db8::c001 good_service_net 2605 tcp_outgoing_address 10.1.0.2 good_service_net 2606 2607 tcp_outgoing_address 2001:db8::beef normal_service_net 2608 tcp_outgoing_address 10.1.0.1 normal_service_net 2609 2610 tcp_outgoing_address 2001:db8::1 2611 tcp_outgoing_address 10.1.0.3 2612 2613 Processing proceeds in the order specified, and stops at first fully 2614 matching line. 2615 2616 Squid will add an implicit IP version test to each line. 2617 Requests going to IPv4 websites will use the outgoing 10.1.0.* addresses. 2618 Requests going to IPv6 websites will use the outgoing 2001:db8:* addresses. 2619 2620 2621 NOTE: The use of this directive using client dependent ACLs is 2622 incompatible with the use of server side persistent connections. To 2623 ensure correct results it is best to set server_persistent_connections 2624 to off when using this directive in such configurations. 2625 2626 NOTE: The use of this directive to set a local IP on outgoing TCP links 2627 is incompatible with using TPROXY to set client IP out outbound TCP links. 2628 When needing to contact peers use the no-tproxy cache_peer option and the 2629 client_dst_passthru directive re-enable normal forwarding such as this. 2630 2631 This clause only supports fast acl types. 2632 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 2633DOC_END 2634 2635NAME: host_verify_strict 2636TYPE: onoff 2637DEFAULT: off 2638LOC: Config.onoff.hostStrictVerify 2639DOC_START 2640 Regardless of this option setting, when dealing with intercepted 2641 traffic, Squid always verifies that the destination IP address matches 2642 the Host header domain or IP (called 'authority form URL'). 2643 2644 This enforcement is performed to satisfy a MUST-level requirement in 2645 RFC 2616 section 14.23: "The Host field value MUST represent the naming 2646 authority of the origin server or gateway given by the original URL". 2647 2648 When set to ON: 2649 Squid always responds with an HTTP 409 (Conflict) error 2650 page and logs a security warning if there is no match. 2651 2652 Squid verifies that the destination IP address matches 2653 the Host header for forward-proxy and reverse-proxy traffic 2654 as well. For those traffic types, Squid also enables the 2655 following checks, comparing the corresponding Host header 2656 and Request-URI components: 2657 2658 * The host names (domain or IP) must be identical, 2659 but valueless or missing Host header disables all checks. 2660 For the two host names to match, both must be either IP 2661 or FQDN. 2662 2663 * Port numbers must be identical, but if a port is missing 2664 the scheme-default port is assumed. 2665 2666 2667 When set to OFF (the default): 2668 Squid allows suspicious requests to continue but logs a 2669 security warning and blocks caching of the response. 2670 2671 * Forward-proxy traffic is not checked at all. 2672 2673 * Reverse-proxy traffic is not checked at all. 2674 2675 * Intercepted traffic which passes verification is handled 2676 according to client_dst_passthru. 2677 2678 * Intercepted requests which fail verification are sent 2679 to the client original destination instead of DIRECT. 2680 This overrides 'client_dst_passthru off'. 2681 2682 For now suspicious intercepted CONNECT requests are always 2683 responded to with an HTTP 409 (Conflict) error page. 2684 2685 2686 SECURITY NOTE: 2687 2688 As described in CVE-2009-0801 when the Host: header alone is used 2689 to determine the destination of a request it becomes trivial for 2690 malicious scripts on remote websites to bypass browser same-origin 2691 security policy and sandboxing protections. 2692 2693 The cause of this is that such applets are allowed to perform their 2694 own HTTP stack, in which case the same-origin policy of the browser 2695 sandbox only verifies that the applet tries to contact the same IP 2696 as from where it was loaded at the IP level. The Host: header may 2697 be different from the connected IP and approved origin. 2698 2699DOC_END 2700 2701NAME: client_dst_passthru 2702TYPE: onoff 2703DEFAULT: on 2704LOC: Config.onoff.client_dst_passthru 2705DOC_START 2706 With NAT or TPROXY intercepted traffic Squid may pass the request 2707 directly to the original client destination IP or seek a faster 2708 source using the HTTP Host header. 2709 2710 Using Host to locate alternative servers can provide faster 2711 connectivity with a range of failure recovery options. 2712 But can also lead to connectivity trouble when the client and 2713 server are attempting stateful interactions unaware of the proxy. 2714 2715 This option (on by default) prevents alternative DNS entries being 2716 located to send intercepted traffic DIRECT to an origin server. 2717 The clients original destination IP and port will be used instead. 2718 2719 Regardless of this option setting, when dealing with intercepted 2720 traffic Squid will verify the Host: header and any traffic which 2721 fails Host verification will be treated as if this option were ON. 2722 2723 see host_verify_strict for details on the verification process. 2724DOC_END 2725 2726COMMENT_START 2727 TLS OPTIONS 2728 ----------------------------------------------------------------------------- 2729COMMENT_END 2730 2731NAME: tls_outgoing_options 2732IFDEF: USE_GNUTLS||USE_OPENSSL 2733TYPE: securePeerOptions 2734DEFAULT: min-version=1.0 2735LOC: Security::ProxyOutgoingConfig 2736DOC_START 2737 disable Do not support https:// URLs. 2738 2739 cert=/path/to/client/certificate 2740 A client X.509 certificate to use when connecting. 2741 2742 key=/path/to/client/private_key 2743 The private key corresponding to the cert= above. 2744 2745 If key= is not specified cert= is assumed to 2746 reference a PEM file containing both the certificate 2747 and private key. 2748 2749 cipher=... The list of valid TLS ciphers to use. 2750 2751 min-version=1.N 2752 The minimum TLS protocol version to permit. 2753 To control SSLv3 use the options= parameter. 2754 Supported Values: 1.0 (default), 1.1, 1.2, 1.3 2755 2756 options=... Specify various TLS/SSL implementation options. 2757 2758 OpenSSL options most important are: 2759 2760 NO_SSLv3 Disallow the use of SSLv3 2761 2762 SINGLE_DH_USE 2763 Always create a new key when using 2764 temporary/ephemeral DH key exchanges 2765 2766 NO_TICKET 2767 Disable use of RFC5077 session tickets. 2768 Some servers may have problems 2769 understanding the TLS extension due 2770 to ambiguous specification in RFC4507. 2771 2772 ALL Enable various bug workarounds 2773 suggested as "harmless" by OpenSSL 2774 Be warned that this reduces SSL/TLS 2775 strength to some attacks. 2776 2777 See the OpenSSL SSL_CTX_set_options documentation 2778 for a more complete list. 2779 2780 GnuTLS options most important are: 2781 2782 %NO_TICKETS 2783 Disable use of RFC5077 session tickets. 2784 Some servers may have problems 2785 understanding the TLS extension due 2786 to ambiguous specification in RFC4507. 2787 2788 See the GnuTLS Priority Strings documentation 2789 for a more complete list. 2790 http://www.gnutls.org/manual/gnutls.html#Priority-Strings 2791 2792 2793 cafile= PEM file containing CA certificates to use when verifying 2794 the peer certificate. May be repeated to load multiple files. 2795 2796 capath= A directory containing additional CA certificates to 2797 use when verifying the peer certificate. 2798 Requires OpenSSL or LibreSSL. 2799 2800 crlfile=... A certificate revocation list file to use when 2801 verifying the peer certificate. 2802 2803 flags=... Specify various flags modifying the TLS implementation: 2804 2805 DONT_VERIFY_PEER 2806 Accept certificates even if they fail to 2807 verify. 2808 DONT_VERIFY_DOMAIN 2809 Don't verify the peer certificate 2810 matches the server name 2811 2812 default-ca[=off] 2813 Whether to use the system Trusted CAs. Default is ON. 2814 2815 domain= The peer name as advertised in its certificate. 2816 Used for verifying the correctness of the received peer 2817 certificate. If not specified the peer hostname will be 2818 used. 2819DOC_END 2820 2821COMMENT_START 2822 SSL OPTIONS 2823 ----------------------------------------------------------------------------- 2824COMMENT_END 2825 2826NAME: ssl_unclean_shutdown 2827IFDEF: USE_OPENSSL 2828TYPE: onoff 2829DEFAULT: off 2830LOC: Config.SSL.unclean_shutdown 2831DOC_START 2832 Some browsers (especially MSIE) bugs out on SSL shutdown 2833 messages. 2834DOC_END 2835 2836NAME: ssl_engine 2837IFDEF: USE_OPENSSL 2838TYPE: string 2839LOC: Config.SSL.ssl_engine 2840DEFAULT: none 2841DOC_START 2842 The OpenSSL engine to use. You will need to set this if you 2843 would like to use hardware SSL acceleration for example. 2844DOC_END 2845 2846NAME: sslproxy_session_ttl 2847IFDEF: USE_OPENSSL 2848DEFAULT: 300 2849LOC: Config.SSL.session_ttl 2850TYPE: int 2851DOC_START 2852 Sets the timeout value for SSL sessions 2853DOC_END 2854 2855NAME: sslproxy_session_cache_size 2856IFDEF: USE_OPENSSL 2857DEFAULT: 2 MB 2858LOC: Config.SSL.sessionCacheSize 2859TYPE: b_size_t 2860DOC_START 2861 Sets the cache size to use for ssl session 2862DOC_END 2863 2864NAME: sslproxy_foreign_intermediate_certs 2865IFDEF: USE_OPENSSL 2866DEFAULT: none 2867LOC: Config.ssl_client.foreignIntermediateCertsPath 2868TYPE: string 2869DOC_START 2870 Many origin servers fail to send their full server certificate 2871 chain for verification, assuming the client already has or can 2872 easily locate any missing intermediate certificates. 2873 2874 Squid uses the certificates from the specified file to fill in 2875 these missing chains when trying to validate origin server 2876 certificate chains. 2877 2878 The file is expected to contain zero or more PEM-encoded 2879 intermediate certificates. These certificates are not treated 2880 as trusted root certificates, and any self-signed certificate in 2881 this file will be ignored. 2882DOC_END 2883 2884NAME: sslproxy_cert_sign_hash 2885IFDEF: USE_OPENSSL 2886DEFAULT: none 2887LOC: Config.SSL.certSignHash 2888TYPE: string 2889DOC_START 2890 Sets the hashing algorithm to use when signing generated certificates. 2891 Valid algorithm names depend on the OpenSSL library used. The following 2892 names are usually available: sha1, sha256, sha512, and md5. Please see 2893 your OpenSSL library manual for the available hashes. By default, Squids 2894 that support this option use sha256 hashes. 2895 2896 Squid does not forcefully purge cached certificates that were generated 2897 with an algorithm other than the currently configured one. They remain 2898 in the cache, subject to the regular cache eviction policy, and become 2899 useful if the algorithm changes again. 2900DOC_END 2901 2902NAME: ssl_bump 2903IFDEF: USE_OPENSSL 2904TYPE: sslproxy_ssl_bump 2905LOC: Config.accessList.ssl_bump 2906DEFAULT_DOC: Become a TCP tunnel without decrypting proxied traffic. 2907DEFAULT: none 2908DOC_START 2909 This option is consulted when a CONNECT request is received on 2910 an http_port (or a new connection is intercepted at an 2911 https_port), provided that port was configured with an ssl-bump 2912 flag. The subsequent data on the connection is either treated as 2913 HTTPS and decrypted OR tunneled at TCP level without decryption, 2914 depending on the first matching bumping "action". 2915 2916 ssl_bump <action> [!]acl ... 2917 2918 The following bumping actions are currently supported: 2919 2920 splice 2921 Become a TCP tunnel without decrypting proxied traffic. 2922 This is the default action. 2923 2924 bump 2925 When used on step SslBump1, establishes a secure connection 2926 with the client first, then connect to the server. 2927 When used on step SslBump2 or SslBump3, establishes a secure 2928 connection with the server and, using a mimicked server 2929 certificate, with the client. 2930 2931 peek 2932 Receive client (step SslBump1) or server (step SslBump2) 2933 certificate while preserving the possibility of splicing the 2934 connection. Peeking at the server certificate (during step 2) 2935 usually precludes bumping of the connection at step 3. 2936 2937 stare 2938 Receive client (step SslBump1) or server (step SslBump2) 2939 certificate while preserving the possibility of bumping the 2940 connection. Staring at the server certificate (during step 2) 2941 usually precludes splicing of the connection at step 3. 2942 2943 terminate 2944 Close client and server connections. 2945 2946 Backward compatibility actions available at step SslBump1: 2947 2948 client-first 2949 Bump the connection. Establish a secure connection with the 2950 client first, then connect to the server. This old mode does 2951 not allow Squid to mimic server SSL certificate and does not 2952 work with intercepted SSL connections. 2953 2954 server-first 2955 Bump the connection. Establish a secure connection with the 2956 server first, then establish a secure connection with the 2957 client, using a mimicked server certificate. Works with both 2958 CONNECT requests and intercepted SSL connections, but does 2959 not allow to make decisions based on SSL handshake info. 2960 2961 peek-and-splice 2962 Decide whether to bump or splice the connection based on 2963 client-to-squid and server-to-squid SSL hello messages. 2964 XXX: Remove. 2965 2966 none 2967 Same as the "splice" action. 2968 2969 All ssl_bump rules are evaluated at each of the supported bumping 2970 steps. Rules with actions that are impossible at the current step are 2971 ignored. The first matching ssl_bump action wins and is applied at the 2972 end of the current step. If no rules match, the splice action is used. 2973 See the at_step ACL for a list of the supported SslBump steps. 2974 2975 This clause supports both fast and slow acl types. 2976 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 2977 2978 See also: http_port ssl-bump, https_port ssl-bump, and acl at_step. 2979 2980 2981 # Example: Bump all TLS connections except those originating from 2982 # localhost or those going to example.com. 2983 2984 acl broken_sites ssl::server_name .example.com 2985 ssl_bump splice localhost 2986 ssl_bump splice broken_sites 2987 ssl_bump bump all 2988DOC_END 2989 2990NAME: sslproxy_cert_error 2991IFDEF: USE_OPENSSL 2992DEFAULT: none 2993DEFAULT_DOC: Server certificate errors terminate the transaction. 2994LOC: Config.ssl_client.cert_error 2995TYPE: acl_access 2996DOC_START 2997 Use this ACL to bypass server certificate validation errors. 2998 2999 For example, the following lines will bypass all validation errors 3000 when talking to servers for example.com. All other 3001 validation errors will result in ERR_SECURE_CONNECT_FAIL error. 3002 3003 acl BrokenButTrustedServers dstdomain example.com 3004 sslproxy_cert_error allow BrokenButTrustedServers 3005 sslproxy_cert_error deny all 3006 3007 This clause only supports fast acl types. 3008 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 3009 Using slow acl types may result in server crashes 3010 3011 Without this option, all server certificate validation errors 3012 terminate the transaction to protect Squid and the client. 3013 3014 SQUID_X509_V_ERR_INFINITE_VALIDATION error cannot be bypassed 3015 but should not happen unless your OpenSSL library is buggy. 3016 3017 SECURITY WARNING: 3018 Bypassing validation errors is dangerous because an 3019 error usually implies that the server cannot be trusted 3020 and the connection may be insecure. 3021 3022 See also: sslproxy_flags and DONT_VERIFY_PEER. 3023DOC_END 3024 3025NAME: sslproxy_cert_sign 3026IFDEF: USE_OPENSSL 3027DEFAULT: none 3028POSTSCRIPTUM: signUntrusted ssl::certUntrusted 3029POSTSCRIPTUM: signSelf ssl::certSelfSigned 3030POSTSCRIPTUM: signTrusted all 3031TYPE: sslproxy_cert_sign 3032LOC: Config.ssl_client.cert_sign 3033DOC_START 3034 3035 sslproxy_cert_sign <signing algorithm> acl ... 3036 3037 The following certificate signing algorithms are supported: 3038 3039 signTrusted 3040 Sign using the configured CA certificate which is usually 3041 placed in and trusted by end-user browsers. This is the 3042 default for trusted origin server certificates. 3043 3044 signUntrusted 3045 Sign to guarantee an X509_V_ERR_CERT_UNTRUSTED browser error. 3046 This is the default for untrusted origin server certificates 3047 that are not self-signed (see ssl::certUntrusted). 3048 3049 signSelf 3050 Sign using a self-signed certificate with the right CN to 3051 generate a X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT error in the 3052 browser. This is the default for self-signed origin server 3053 certificates (see ssl::certSelfSigned). 3054 3055 This clause only supports fast acl types. 3056 3057 When sslproxy_cert_sign acl(s) match, Squid uses the corresponding 3058 signing algorithm to generate the certificate and ignores all 3059 subsequent sslproxy_cert_sign options (the first match wins). If no 3060 acl(s) match, the default signing algorithm is determined by errors 3061 detected when obtaining and validating the origin server certificate. 3062 3063 WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can 3064 be used with sslproxy_cert_adapt, but if and only if Squid is bumping a 3065 CONNECT request that carries a domain name. In all other cases (CONNECT 3066 to an IP address or an intercepted SSL connection), Squid cannot detect 3067 the domain mismatch at certificate generation time when 3068 bump-server-first is used. 3069DOC_END 3070 3071NAME: sslproxy_cert_adapt 3072IFDEF: USE_OPENSSL 3073DEFAULT: none 3074TYPE: sslproxy_cert_adapt 3075LOC: Config.ssl_client.cert_adapt 3076DOC_START 3077 3078 sslproxy_cert_adapt <adaptation algorithm> acl ... 3079 3080 The following certificate adaptation algorithms are supported: 3081 3082 setValidAfter 3083 Sets the "Not After" property to the "Not After" property of 3084 the CA certificate used to sign generated certificates. 3085 3086 setValidBefore 3087 Sets the "Not Before" property to the "Not Before" property of 3088 the CA certificate used to sign generated certificates. 3089 3090 setCommonName or setCommonName{CN} 3091 Sets Subject.CN property to the host name specified as a 3092 CN parameter or, if no explicit CN parameter was specified, 3093 extracted from the CONNECT request. It is a misconfiguration 3094 to use setCommonName without an explicit parameter for 3095 intercepted or tproxied SSL connections. 3096 3097 This clause only supports fast acl types. 3098 3099 Squid first groups sslproxy_cert_adapt options by adaptation algorithm. 3100 Within a group, when sslproxy_cert_adapt acl(s) match, Squid uses the 3101 corresponding adaptation algorithm to generate the certificate and 3102 ignores all subsequent sslproxy_cert_adapt options in that algorithm's 3103 group (i.e., the first match wins within each algorithm group). If no 3104 acl(s) match, the default mimicking action takes place. 3105 3106 WARNING: SQUID_X509_V_ERR_DOMAIN_MISMATCH and ssl:certDomainMismatch can 3107 be used with sslproxy_cert_adapt, but if and only if Squid is bumping a 3108 CONNECT request that carries a domain name. In all other cases (CONNECT 3109 to an IP address or an intercepted SSL connection), Squid cannot detect 3110 the domain mismatch at certificate generation time when 3111 bump-server-first is used. 3112DOC_END 3113 3114NAME: sslpassword_program 3115IFDEF: USE_OPENSSL 3116DEFAULT: none 3117LOC: Config.Program.ssl_password 3118TYPE: string 3119DOC_START 3120 Specify a program used for entering SSL key passphrases 3121 when using encrypted SSL certificate keys. If not specified 3122 keys must either be unencrypted, or Squid started with the -N 3123 option to allow it to query interactively for the passphrase. 3124 3125 The key file name is given as argument to the program allowing 3126 selection of the right password if you have multiple encrypted 3127 keys. 3128DOC_END 3129 3130COMMENT_START 3131 OPTIONS RELATING TO EXTERNAL SSL_CRTD 3132 ----------------------------------------------------------------------------- 3133COMMENT_END 3134 3135NAME: sslcrtd_program 3136TYPE: eol 3137IFDEF: USE_SSL_CRTD 3138DEFAULT: @DEFAULT_SSL_CRTD@ -s @DEFAULT_SSL_DB_DIR@ -M 4MB 3139LOC: Ssl::TheConfig.ssl_crtd 3140DOC_START 3141 Specify the location and options of the executable for certificate 3142 generator. 3143 3144 @DEFAULT_SSL_CRTD@ program can use a disk cache to improve response 3145 times on repeated requests. To enable caching, specify -s and -M 3146 parameters. If those parameters are not given, the program generates 3147 a new certificate on every request. 3148 3149 For more information use: 3150 @DEFAULT_SSL_CRTD@ -h 3151DOC_END 3152 3153NAME: sslcrtd_children 3154TYPE: HelperChildConfig 3155IFDEF: USE_SSL_CRTD 3156DEFAULT: 32 startup=5 idle=1 3157LOC: Ssl::TheConfig.ssl_crtdChildren 3158DOC_START 3159 Specifies the maximum number of certificate generation processes that 3160 Squid may spawn (numberofchildren) and several related options. Using 3161 too few of these helper processes (a.k.a. "helpers") creates request 3162 queues. Using too many helpers wastes your system resources. Squid 3163 does not support spawning more than 32 helpers. 3164 3165 Usage: numberofchildren [option]... 3166 3167 The startup= and idle= options allow some measure of skew in your 3168 tuning. 3169 3170 startup=N 3171 3172 Sets the minimum number of processes to spawn when Squid 3173 starts or reconfigures. When set to zero the first request will 3174 cause spawning of the first child process to handle it. 3175 3176 Starting too few children temporary slows Squid under load while it 3177 tries to spawn enough additional processes to cope with traffic. 3178 3179 idle=N 3180 3181 Sets a minimum of how many processes Squid is to try and keep available 3182 at all times. When traffic begins to rise above what the existing 3183 processes can handle this many more will be spawned up to the maximum 3184 configured. A minimum setting of 1 is required. 3185 3186 queue-size=N 3187 3188 Sets the maximum number of queued requests. A request is queued when 3189 no existing child is idle and no new child can be started due to 3190 numberofchildren limit. If the queued requests exceed queue size for 3191 more than 3 minutes squid aborts its operation. The default value is 3192 set to 2*numberofchildren. 3193 3194 You must have at least one ssl_crtd process. 3195DOC_END 3196 3197NAME: sslcrtvalidator_program 3198TYPE: eol 3199IFDEF: USE_OPENSSL 3200DEFAULT: none 3201LOC: Ssl::TheConfig.ssl_crt_validator 3202DOC_START 3203 Specify the location and options of the executable for ssl_crt_validator 3204 process. 3205 3206 Usage: sslcrtvalidator_program [ttl=n] [cache=n] path ... 3207 3208 Options: 3209 ttl=n TTL in seconds for cached results. The default is 60 secs 3210 cache=n limit the result cache size. The default value is 2048 3211DOC_END 3212 3213NAME: sslcrtvalidator_children 3214TYPE: HelperChildConfig 3215IFDEF: USE_OPENSSL 3216DEFAULT: 32 startup=5 idle=1 concurrency=1 3217LOC: Ssl::TheConfig.ssl_crt_validator_Children 3218DOC_START 3219 Specifies the maximum number of certificate validation processes that 3220 Squid may spawn (numberofchildren) and several related options. Using 3221 too few of these helper processes (a.k.a. "helpers") creates request 3222 queues. Using too many helpers wastes your system resources. Squid 3223 does not support spawning more than 32 helpers. 3224 3225 Usage: numberofchildren [option]... 3226 3227 The startup= and idle= options allow some measure of skew in your 3228 tuning. 3229 3230 startup=N 3231 3232 Sets the minimum number of processes to spawn when Squid 3233 starts or reconfigures. When set to zero the first request will 3234 cause spawning of the first child process to handle it. 3235 3236 Starting too few children temporary slows Squid under load while it 3237 tries to spawn enough additional processes to cope with traffic. 3238 3239 idle=N 3240 3241 Sets a minimum of how many processes Squid is to try and keep available 3242 at all times. When traffic begins to rise above what the existing 3243 processes can handle this many more will be spawned up to the maximum 3244 configured. A minimum setting of 1 is required. 3245 3246 concurrency= 3247 3248 The number of requests each certificate validator helper can handle in 3249 parallel. A value of 0 indicates the certficate validator does not 3250 support concurrency. Defaults to 1. 3251 3252 When this directive is set to a value >= 1 then the protocol 3253 used to communicate with the helper is modified to include 3254 a request ID in front of the request/response. The request 3255 ID from the request must be echoed back with the response 3256 to that request. 3257 3258 queue-size=N 3259 3260 Sets the maximum number of queued requests. A request is queued when 3261 no existing child can accept it due to concurrency limit and no new 3262 child can be started due to numberofchildren limit. If the queued 3263 requests exceed queue size for more than 3 minutes squid aborts its 3264 operation. The default value is set to 2*numberofchildren. 3265 3266 You must have at least one ssl_crt_validator process. 3267DOC_END 3268 3269COMMENT_START 3270 OPTIONS WHICH AFFECT THE NEIGHBOR SELECTION ALGORITHM 3271 ----------------------------------------------------------------------------- 3272COMMENT_END 3273 3274NAME: cache_peer 3275TYPE: peer 3276DEFAULT: none 3277LOC: Config.peers 3278DOC_START 3279 To specify other caches in a hierarchy, use the format: 3280 3281 cache_peer hostname type http-port icp-port [options] 3282 3283 For example, 3284 3285 # proxy icp 3286 # hostname type port port options 3287 # -------------------- -------- ----- ----- ----------- 3288 cache_peer parent.foo.net parent 3128 3130 default 3289 cache_peer sib1.foo.net sibling 3128 3130 proxy-only 3290 cache_peer sib2.foo.net sibling 3128 3130 proxy-only 3291 cache_peer example.com parent 80 0 default 3292 cache_peer cdn.example.com sibling 3128 0 3293 3294 type: either 'parent', 'sibling', or 'multicast'. 3295 3296 proxy-port: The port number where the peer accept HTTP requests. 3297 For other Squid proxies this is usually 3128 3298 For web servers this is usually 80 3299 3300 icp-port: Used for querying neighbor caches about objects. 3301 Set to 0 if the peer does not support ICP or HTCP. 3302 See ICP and HTCP options below for additional details. 3303 3304 3305 ==== ICP OPTIONS ==== 3306 3307 You MUST also set icp_port and icp_access explicitly when using these options. 3308 The defaults will prevent peer traffic using ICP. 3309 3310 3311 no-query Disable ICP queries to this neighbor. 3312 3313 multicast-responder 3314 Indicates the named peer is a member of a multicast group. 3315 ICP queries will not be sent directly to the peer, but ICP 3316 replies will be accepted from it. 3317 3318 closest-only Indicates that, for ICP_OP_MISS replies, we'll only forward 3319 CLOSEST_PARENT_MISSes and never FIRST_PARENT_MISSes. 3320 3321 background-ping 3322 To only send ICP queries to this neighbor infrequently. 3323 This is used to keep the neighbor round trip time updated 3324 and is usually used in conjunction with weighted-round-robin. 3325 3326 3327 ==== HTCP OPTIONS ==== 3328 3329 You MUST also set htcp_port and htcp_access explicitly when using these options. 3330 The defaults will prevent peer traffic using HTCP. 3331 3332 3333 htcp Send HTCP, instead of ICP, queries to the neighbor. 3334 You probably also want to set the "icp-port" to 4827 3335 instead of 3130. This directive accepts a comma separated 3336 list of options described below. 3337 3338 htcp=oldsquid Send HTCP to old Squid versions (2.5 or earlier). 3339 3340 htcp=no-clr Send HTCP to the neighbor but without 3341 sending any CLR requests. This cannot be used with 3342 only-clr. 3343 3344 htcp=only-clr Send HTCP to the neighbor but ONLY CLR requests. 3345 This cannot be used with no-clr. 3346 3347 htcp=no-purge-clr 3348 Send HTCP to the neighbor including CLRs but only when 3349 they do not result from PURGE requests. 3350 3351 htcp=forward-clr 3352 Forward any HTCP CLR requests this proxy receives to the peer. 3353 3354 3355 ==== PEER SELECTION METHODS ==== 3356 3357 The default peer selection method is ICP, with the first responding peer 3358 being used as source. These options can be used for better load balancing. 3359 3360 3361 default This is a parent cache which can be used as a "last-resort" 3362 if a peer cannot be located by any of the peer-selection methods. 3363 If specified more than once, only the first is used. 3364 3365 round-robin Load-Balance parents which should be used in a round-robin 3366 fashion in the absence of any ICP queries. 3367 weight=N can be used to add bias. 3368 3369 weighted-round-robin 3370 Load-Balance parents which should be used in a round-robin 3371 fashion with the frequency of each parent being based on the 3372 round trip time. Closer parents are used more often. 3373 Usually used for background-ping parents. 3374 weight=N can be used to add bias. 3375 3376 carp Load-Balance parents which should be used as a CARP array. 3377 The requests will be distributed among the parents based on the 3378 CARP load balancing hash function based on their weight. 3379 3380 userhash Load-balance parents based on the client proxy_auth or ident username. 3381 3382 sourcehash Load-balance parents based on the client source IP. 3383 3384 multicast-siblings 3385 To be used only for cache peers of type "multicast". 3386 ALL members of this multicast group have "sibling" 3387 relationship with it, not "parent". This is to a multicast 3388 group when the requested object would be fetched only from 3389 a "parent" cache, anyway. It's useful, e.g., when 3390 configuring a pool of redundant Squid proxies, being 3391 members of the same multicast group. 3392 3393 3394 ==== PEER SELECTION OPTIONS ==== 3395 3396 weight=N use to affect the selection of a peer during any weighted 3397 peer-selection mechanisms. 3398 The weight must be an integer; default is 1, 3399 larger weights are favored more. 3400 This option does not affect parent selection if a peering 3401 protocol is not in use. 3402 3403 basetime=N Specify a base amount to be subtracted from round trip 3404 times of parents. 3405 It is subtracted before division by weight in calculating 3406 which parent to fectch from. If the rtt is less than the 3407 base time the rtt is set to a minimal value. 3408 3409 ttl=N Specify a TTL to use when sending multicast ICP queries 3410 to this address. 3411 Only useful when sending to a multicast group. 3412 Because we don't accept ICP replies from random 3413 hosts, you must configure other group members as 3414 peers with the 'multicast-responder' option. 3415 3416 no-delay To prevent access to this neighbor from influencing the 3417 delay pools. 3418 3419 digest-url=URL Tell Squid to fetch the cache digest (if digests are 3420 enabled) for this host from the specified URL rather 3421 than the Squid default location. 3422 3423 3424 ==== CARP OPTIONS ==== 3425 3426 carp-key=key-specification 3427 use a different key than the full URL to hash against the peer. 3428 the key-specification is a comma-separated list of the keywords 3429 scheme, host, port, path, params 3430 Order is not important. 3431 3432 ==== ACCELERATOR / REVERSE-PROXY OPTIONS ==== 3433 3434 originserver Causes this parent to be contacted as an origin server. 3435 Meant to be used in accelerator setups when the peer 3436 is a web server. 3437 3438 forceddomain=name 3439 Set the Host header of requests forwarded to this peer. 3440 Useful in accelerator setups where the server (peer) 3441 expects a certain domain name but clients may request 3442 others. ie example.com or www.example.com 3443 3444 no-digest Disable request of cache digests. 3445 3446 no-netdb-exchange 3447 Disables requesting ICMP RTT database (NetDB). 3448 3449 3450 ==== AUTHENTICATION OPTIONS ==== 3451 3452 login=user:password 3453 If this is a personal/workgroup proxy and your parent 3454 requires proxy authentication. 3455 3456 Note: The string can include URL escapes (i.e. %20 for 3457 spaces). This also means % must be written as %%. 3458 3459 login=PASSTHRU 3460 Send login details received from client to this peer. 3461 Both Proxy- and WWW-Authorization headers are passed 3462 without alteration to the peer. 3463 Authentication is not required by Squid for this to work. 3464 3465 Note: This will pass any form of authentication but 3466 only Basic auth will work through a proxy unless the 3467 connection-auth options are also used. 3468 3469 login=PASS Send login details received from client to this peer. 3470 Authentication is not required by this option. 3471 3472 If there are no client-provided authentication headers 3473 to pass on, but username and password are available 3474 from an external ACL user= and password= result tags 3475 they may be sent instead. 3476 3477 Note: To combine this with proxy_auth both proxies must 3478 share the same user database as HTTP only allows for 3479 a single login (one for proxy, one for origin server). 3480 Also be warned this will expose your users proxy 3481 password to the peer. USE WITH CAUTION 3482 3483 login=*:password 3484 Send the username to the upstream cache, but with a 3485 fixed password. This is meant to be used when the peer 3486 is in another administrative domain, but it is still 3487 needed to identify each user. 3488 The star can optionally be followed by some extra 3489 information which is added to the username. This can 3490 be used to identify this proxy to the peer, similar to 3491 the login=username:password option above. 3492 3493 login=NEGOTIATE 3494 If this is a personal/workgroup proxy and your parent 3495 requires a secure proxy authentication. 3496 The first principal from the default keytab or defined by 3497 the environment variable KRB5_KTNAME will be used. 3498 3499 WARNING: The connection may transmit requests from multiple 3500 clients. Negotiate often assumes end-to-end authentication 3501 and a single-client. Which is not strictly true here. 3502 3503 login=NEGOTIATE:principal_name 3504 If this is a personal/workgroup proxy and your parent 3505 requires a secure proxy authentication. 3506 The principal principal_name from the default keytab or 3507 defined by the environment variable KRB5_KTNAME will be 3508 used. 3509 3510 WARNING: The connection may transmit requests from multiple 3511 clients. Negotiate often assumes end-to-end authentication 3512 and a single-client. Which is not strictly true here. 3513 3514 connection-auth=on|off 3515 Tell Squid that this peer does or not support Microsoft 3516 connection oriented authentication, and any such 3517 challenges received from there should be ignored. 3518 Default is auto to automatically determine the status 3519 of the peer. 3520 3521 auth-no-keytab 3522 Do not use a keytab to authenticate to a peer when 3523 login=NEGOTIATE is specified. Let the GSSAPI 3524 implementation determine which already existing 3525 credentials cache to use instead. 3526 3527 3528 ==== SSL / HTTPS / TLS OPTIONS ==== 3529 3530 tls Encrypt connections to this peer with TLS. 3531 3532 sslcert=/path/to/ssl/certificate 3533 A client X.509 certificate to use when connecting to 3534 this peer. 3535 3536 sslkey=/path/to/ssl/key 3537 The private key corresponding to sslcert above. 3538 3539 If sslkey= is not specified sslcert= is assumed to 3540 reference a PEM file containing both the certificate 3541 and private key. 3542 3543 sslcipher=... The list of valid SSL ciphers to use when connecting 3544 to this peer. 3545 3546 tls-min-version=1.N 3547 The minimum TLS protocol version to permit. To control 3548 SSLv3 use the tls-options= parameter. 3549 Supported Values: 1.0 (default), 1.1, 1.2 3550 3551 tls-options=... Specify various TLS implementation options. 3552 3553 OpenSSL options most important are: 3554 3555 NO_SSLv3 Disallow the use of SSLv3 3556 3557 SINGLE_DH_USE 3558 Always create a new key when using 3559 temporary/ephemeral DH key exchanges 3560 3561 NO_TICKET 3562 Disable use of RFC5077 session tickets. 3563 Some servers may have problems 3564 understanding the TLS extension due 3565 to ambiguous specification in RFC4507. 3566 3567 ALL Enable various bug workarounds 3568 suggested as "harmless" by OpenSSL 3569 Be warned that this reduces SSL/TLS 3570 strength to some attacks. 3571 3572 See the OpenSSL SSL_CTX_set_options documentation for a 3573 more complete list. 3574 3575 GnuTLS options most important are: 3576 3577 %NO_TICKETS 3578 Disable use of RFC5077 session tickets. 3579 Some servers may have problems 3580 understanding the TLS extension due 3581 to ambiguous specification in RFC4507. 3582 3583 See the GnuTLS Priority Strings documentation 3584 for a more complete list. 3585 http://www.gnutls.org/manual/gnutls.html#Priority-Strings 3586 3587 tls-cafile= PEM file containing CA certificates to use when verifying 3588 the peer certificate. May be repeated to load multiple files. 3589 3590 sslcapath=... A directory containing additional CA certificates to 3591 use when verifying the peer certificate. 3592 Requires OpenSSL or LibreSSL. 3593 3594 sslcrlfile=... A certificate revocation list file to use when 3595 verifying the peer certificate. 3596 3597 sslflags=... Specify various flags modifying the SSL implementation: 3598 3599 DONT_VERIFY_PEER 3600 Accept certificates even if they fail to 3601 verify. 3602 3603 DONT_VERIFY_DOMAIN 3604 Don't verify the peer certificate 3605 matches the server name 3606 3607 ssldomain= The peer name as advertised in it's certificate. 3608 Used for verifying the correctness of the received peer 3609 certificate. If not specified the peer hostname will be 3610 used. 3611 3612 front-end-https[=off|on|auto] 3613 Enable the "Front-End-Https: On" header needed when 3614 using Squid as a SSL frontend in front of Microsoft OWA. 3615 See MS KB document Q307347 for details on this header. 3616 If set to auto the header will only be added if the 3617 request is forwarded as a https:// URL. 3618 3619 tls-default-ca[=off] 3620 Whether to use the system Trusted CAs. Default is ON. 3621 3622 tls-no-npn Do not use the TLS NPN extension to advertise HTTP/1.1. 3623 3624 ==== GENERAL OPTIONS ==== 3625 3626 connect-timeout=N 3627 A peer-specific connect timeout. 3628 Also see the peer_connect_timeout directive. 3629 3630 connect-fail-limit=N 3631 How many times connecting to a peer must fail before 3632 it is marked as down. Standby connection failures 3633 count towards this limit. Default is 10. 3634 3635 allow-miss Disable Squid's use of only-if-cached when forwarding 3636 requests to siblings. This is primarily useful when 3637 icp_hit_stale is used by the sibling. Excessive use 3638 of this option may result in forwarding loops. One way 3639 to prevent peering loops when using this option, is to 3640 deny cache peer usage on requests from a peer: 3641 acl fromPeer ... 3642 cache_peer_access peerName deny fromPeer 3643 3644 max-conn=N Limit the number of concurrent connections the Squid 3645 may open to this peer, including already opened idle 3646 and standby connections. There is no peer-specific 3647 connection limit by default. 3648 3649 A peer exceeding the limit is not used for new 3650 requests unless a standby connection is available. 3651 3652 max-conn currently works poorly with idle persistent 3653 connections: When a peer reaches its max-conn limit, 3654 and there are idle persistent connections to the peer, 3655 the peer may not be selected because the limiting code 3656 does not know whether Squid can reuse those idle 3657 connections. 3658 3659 standby=N Maintain a pool of N "hot standby" connections to an 3660 UP peer, available for requests when no idle 3661 persistent connection is available (or safe) to use. 3662 By default and with zero N, no such pool is maintained. 3663 N must not exceed the max-conn limit (if any). 3664 3665 At start or after reconfiguration, Squid opens new TCP 3666 standby connections until there are N connections 3667 available and then replenishes the standby pool as 3668 opened connections are used up for requests. A used 3669 connection never goes back to the standby pool, but 3670 may go to the regular idle persistent connection pool 3671 shared by all peers and origin servers. 3672 3673 Squid never opens multiple new standby connections 3674 concurrently. This one-at-a-time approach minimizes 3675 flooding-like effect on peers. Furthermore, just a few 3676 standby connections should be sufficient in most cases 3677 to supply most new requests with a ready-to-use 3678 connection. 3679 3680 Standby connections obey server_idle_pconn_timeout. 3681 For the feature to work as intended, the peer must be 3682 configured to accept and keep them open longer than 3683 the idle timeout at the connecting Squid, to minimize 3684 race conditions typical to idle used persistent 3685 connections. Default request_timeout and 3686 server_idle_pconn_timeout values ensure such a 3687 configuration. 3688 3689 name=xxx Unique name for the peer. 3690 Required if you have multiple peers on the same host 3691 but different ports. 3692 This name can be used in cache_peer_access and similar 3693 directives to identify the peer. 3694 Can be used by outgoing access controls through the 3695 peername ACL type. 3696 3697 no-tproxy Do not use the client-spoof TPROXY support when forwarding 3698 requests to this peer. Use normal address selection instead. 3699 This overrides the spoof_client_ip ACL. 3700 3701 proxy-only objects fetched from the peer will not be stored locally. 3702 3703DOC_END 3704 3705NAME: cache_peer_access 3706TYPE: peer_access 3707DEFAULT: none 3708DEFAULT_DOC: No peer usage restrictions. 3709LOC: none 3710DOC_START 3711 Restricts usage of cache_peer proxies. 3712 3713 Usage: 3714 cache_peer_access peer-name allow|deny [!]aclname ... 3715 3716 For the required peer-name parameter, use either the value of the 3717 cache_peer name=value parameter or, if name=value is missing, the 3718 cache_peer hostname parameter. 3719 3720 This directive narrows down the selection of peering candidates, but 3721 does not determine the order in which the selected candidates are 3722 contacted. That order is determined by the peer selection algorithms 3723 (see PEER SELECTION sections in the cache_peer documentation). 3724 3725 If a deny rule matches, the corresponding peer will not be contacted 3726 for the current transaction -- Squid will not send ICP queries and 3727 will not forward HTTP requests to that peer. An allow match leaves 3728 the corresponding peer in the selection. The first match for a given 3729 peer wins for that peer. 3730 3731 The relative order of cache_peer_access directives for the same peer 3732 matters. The relative order of any two cache_peer_access directives 3733 for different peers does not matter. To ease interpretation, it is a 3734 good idea to group cache_peer_access directives for the same peer 3735 together. 3736 3737 A single cache_peer_access directive may be evaluated multiple times 3738 for a given transaction because individual peer selection algorithms 3739 may check it independently from each other. These redundant checks 3740 may be optimized away in future Squid versions. 3741 3742 This clause only supports fast acl types. 3743 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 3744 3745DOC_END 3746 3747NAME: neighbor_type_domain 3748TYPE: hostdomaintype 3749DEFAULT: none 3750DEFAULT_DOC: The peer type from cache_peer directive is used for all requests to that peer. 3751LOC: none 3752DOC_START 3753 Modify the cache_peer neighbor type when passing requests 3754 about specific domains to the peer. 3755 3756 Usage: 3757 neighbor_type_domain neighbor parent|sibling domain domain ... 3758 3759 For example: 3760 cache_peer foo.example.com parent 3128 3130 3761 neighbor_type_domain foo.example.com sibling .au .de 3762 3763 The above configuration treats all requests to foo.example.com as a 3764 parent proxy unless the request is for a .au or .de ccTLD domain name. 3765DOC_END 3766 3767NAME: dead_peer_timeout 3768COMMENT: (seconds) 3769DEFAULT: 10 seconds 3770TYPE: time_t 3771LOC: Config.Timeout.deadPeer 3772DOC_START 3773 This controls how long Squid waits to declare a peer cache 3774 as "dead." If there are no ICP replies received in this 3775 amount of time, Squid will declare the peer dead and not 3776 expect to receive any further ICP replies. However, it 3777 continues to send ICP queries, and will mark the peer as 3778 alive upon receipt of the first subsequent ICP reply. 3779 3780 This timeout also affects when Squid expects to receive ICP 3781 replies from peers. If more than 'dead_peer' seconds have 3782 passed since the last ICP reply was received, Squid will not 3783 expect to receive an ICP reply on the next query. Thus, if 3784 your time between requests is greater than this timeout, you 3785 will see a lot of requests sent DIRECT to origin servers 3786 instead of to your parents. 3787DOC_END 3788 3789NAME: forward_max_tries 3790DEFAULT: 25 3791TYPE: int 3792LOC: Config.forward_max_tries 3793DOC_START 3794 Limits the number of attempts to forward the request. 3795 3796 For the purpose of this limit, Squid counts all high-level request 3797 forwarding attempts, including any same-destination retries after 3798 certain persistent connection failures and any attempts to use a 3799 different peer. However, low-level connection reopening attempts 3800 (enabled using connect_retries) are not counted. 3801 3802 See also: forward_timeout and connect_retries. 3803DOC_END 3804 3805COMMENT_START 3806 MEMORY CACHE OPTIONS 3807 ----------------------------------------------------------------------------- 3808COMMENT_END 3809 3810NAME: cache_mem 3811COMMENT: (bytes) 3812TYPE: b_size_t 3813DEFAULT: 256 MB 3814LOC: Config.memMaxSize 3815DOC_START 3816 NOTE: THIS PARAMETER DOES NOT SPECIFY THE MAXIMUM PROCESS SIZE. 3817 IT ONLY PLACES A LIMIT ON HOW MUCH ADDITIONAL MEMORY SQUID WILL 3818 USE AS A MEMORY CACHE OF OBJECTS. SQUID USES MEMORY FOR OTHER 3819 THINGS AS WELL. SEE THE SQUID FAQ SECTION 8 FOR DETAILS. 3820 3821 'cache_mem' specifies the ideal amount of memory to be used 3822 for: 3823 * In-Transit objects 3824 * Hot Objects 3825 * Negative-Cached objects 3826 3827 Data for these objects are stored in 4 KB blocks. This 3828 parameter specifies the ideal upper limit on the total size of 3829 4 KB blocks allocated. In-Transit objects take the highest 3830 priority. 3831 3832 In-transit objects have priority over the others. When 3833 additional space is needed for incoming data, negative-cached 3834 and hot objects will be released. In other words, the 3835 negative-cached and hot objects will fill up any unused space 3836 not needed for in-transit objects. 3837 3838 If circumstances require, this limit will be exceeded. 3839 Specifically, if your incoming request rate requires more than 3840 'cache_mem' of memory to hold in-transit objects, Squid will 3841 exceed this limit to satisfy the new requests. When the load 3842 decreases, blocks will be freed until the high-water mark is 3843 reached. Thereafter, blocks will be used to store hot 3844 objects. 3845 3846 If shared memory caching is enabled, Squid does not use the shared 3847 cache space for in-transit objects, but they still consume as much 3848 local memory as they need. For more details about the shared memory 3849 cache, see memory_cache_shared. 3850DOC_END 3851 3852NAME: maximum_object_size_in_memory 3853COMMENT: (bytes) 3854TYPE: b_size_t 3855DEFAULT: 512 KB 3856LOC: Config.Store.maxInMemObjSize 3857DOC_START 3858 Objects greater than this size will not be attempted to kept in 3859 the memory cache. This should be set high enough to keep objects 3860 accessed frequently in memory to improve performance whilst low 3861 enough to keep larger objects from hoarding cache_mem. 3862DOC_END 3863 3864NAME: memory_cache_shared 3865COMMENT: on|off 3866TYPE: YesNoNone 3867LOC: Config.memShared 3868DEFAULT: none 3869DEFAULT_DOC: "on" where supported if doing memory caching with multiple SMP workers. 3870DOC_START 3871 Controls whether the memory cache is shared among SMP workers. 3872 3873 The shared memory cache is meant to occupy cache_mem bytes and replace 3874 the non-shared memory cache, although some entities may still be 3875 cached locally by workers for now (e.g., internal and in-transit 3876 objects may be served from a local memory cache even if shared memory 3877 caching is enabled). 3878 3879 By default, the memory cache is shared if and only if all of the 3880 following conditions are satisfied: Squid runs in SMP mode with 3881 multiple workers, cache_mem is positive, and Squid environment 3882 supports required IPC primitives (e.g., POSIX shared memory segments 3883 and GCC-style atomic operations). 3884 3885 To avoid blocking locks, shared memory uses opportunistic algorithms 3886 that do not guarantee that every cachable entity that could have been 3887 shared among SMP workers will actually be shared. 3888DOC_END 3889 3890NAME: memory_cache_mode 3891TYPE: memcachemode 3892LOC: Config 3893DEFAULT: always 3894DEFAULT_DOC: Keep the most recently fetched objects in memory 3895DOC_START 3896 Controls which objects to keep in the memory cache (cache_mem) 3897 3898 always Keep most recently fetched objects in memory (default) 3899 3900 disk Only disk cache hits are kept in memory, which means 3901 an object must first be cached on disk and then hit 3902 a second time before cached in memory. 3903 3904 network Only objects fetched from network is kept in memory 3905DOC_END 3906 3907NAME: memory_replacement_policy 3908TYPE: removalpolicy 3909LOC: Config.memPolicy 3910DEFAULT: lru 3911DOC_START 3912 The memory replacement policy parameter determines which 3913 objects are purged from memory when memory space is needed. 3914 3915 See cache_replacement_policy for details on algorithms. 3916DOC_END 3917 3918COMMENT_START 3919 DISK CACHE OPTIONS 3920 ----------------------------------------------------------------------------- 3921COMMENT_END 3922 3923NAME: cache_replacement_policy 3924TYPE: removalpolicy 3925LOC: Config.replPolicy 3926DEFAULT: lru 3927DOC_START 3928 The cache replacement policy parameter determines which 3929 objects are evicted (replaced) when disk space is needed. 3930 3931 lru : Squid's original list based LRU policy 3932 heap GDSF : Greedy-Dual Size Frequency 3933 heap LFUDA: Least Frequently Used with Dynamic Aging 3934 heap LRU : LRU policy implemented using a heap 3935 3936 Applies to any cache_dir lines listed below this directive. 3937 3938 The LRU policies keeps recently referenced objects. 3939 3940 The heap GDSF policy optimizes object hit rate by keeping smaller 3941 popular objects in cache so it has a better chance of getting a 3942 hit. It achieves a lower byte hit rate than LFUDA though since 3943 it evicts larger (possibly popular) objects. 3944 3945 The heap LFUDA policy keeps popular objects in cache regardless of 3946 their size and thus optimizes byte hit rate at the expense of 3947 hit rate since one large, popular object will prevent many 3948 smaller, slightly less popular objects from being cached. 3949 3950 Both policies utilize a dynamic aging mechanism that prevents 3951 cache pollution that can otherwise occur with frequency-based 3952 replacement policies. 3953 3954 NOTE: if using the LFUDA replacement policy you should increase 3955 the value of maximum_object_size above its default of 4 MB to 3956 to maximize the potential byte hit rate improvement of LFUDA. 3957 3958 For more information about the GDSF and LFUDA cache replacement 3959 policies see http://www.hpl.hp.com/techreports/1999/HPL-1999-69.html 3960 and http://fog.hpl.external.hp.com/techreports/98/HPL-98-173.html. 3961DOC_END 3962 3963NAME: minimum_object_size 3964COMMENT: (bytes) 3965TYPE: b_int64_t 3966DEFAULT: 0 KB 3967DEFAULT_DOC: no limit 3968LOC: Config.Store.minObjectSize 3969DOC_START 3970 Objects smaller than this size will NOT be saved on disk. The 3971 value is specified in bytes, and the default is 0 KB, which 3972 means all responses can be stored. 3973DOC_END 3974 3975NAME: maximum_object_size 3976COMMENT: (bytes) 3977TYPE: b_int64_t 3978DEFAULT: 4 MB 3979LOC: Config.Store.maxObjectSize 3980DOC_START 3981 Set the default value for max-size parameter on any cache_dir. 3982 The value is specified in bytes, and the default is 4 MB. 3983 3984 If you wish to get a high BYTES hit ratio, you should probably 3985 increase this (one 32 MB object hit counts for 3200 10KB 3986 hits). 3987 3988 If you wish to increase hit ratio more than you want to 3989 save bandwidth you should leave this low. 3990 3991 NOTE: if using the LFUDA replacement policy you should increase 3992 this value to maximize the byte hit rate improvement of LFUDA! 3993 See cache_replacement_policy for a discussion of this policy. 3994DOC_END 3995 3996NAME: cache_dir 3997TYPE: cachedir 3998DEFAULT: none 3999DEFAULT_DOC: No disk cache. Store cache ojects only in memory. 4000LOC: Config.cacheSwap 4001DOC_START 4002 Format: 4003 cache_dir Type Directory-Name Fs-specific-data [options] 4004 4005 You can specify multiple cache_dir lines to spread the 4006 cache among different disk partitions. 4007 4008 Type specifies the kind of storage system to use. Only "ufs" 4009 is built by default. To enable any of the other storage systems 4010 see the --enable-storeio configure option. 4011 4012 'Directory' is a top-level directory where cache swap 4013 files will be stored. If you want to use an entire disk 4014 for caching, this can be the mount-point directory. 4015 The directory must exist and be writable by the Squid 4016 process. Squid will NOT create this directory for you. 4017 4018 In SMP configurations, cache_dir must not precede the workers option 4019 and should use configuration macros or conditionals to give each 4020 worker interested in disk caching a dedicated cache directory. 4021 4022 4023 ==== The ufs store type ==== 4024 4025 "ufs" is the old well-known Squid storage format that has always 4026 been there. 4027 4028 Usage: 4029 cache_dir ufs Directory-Name Mbytes L1 L2 [options] 4030 4031 'Mbytes' is the amount of disk space (MB) to use under this 4032 directory. The default is 100 MB. Change this to suit your 4033 configuration. Do NOT put the size of your disk drive here. 4034 Instead, if you want Squid to use the entire disk drive, 4035 subtract 20% and use that value. 4036 4037 'L1' is the number of first-level subdirectories which 4038 will be created under the 'Directory'. The default is 16. 4039 4040 'L2' is the number of second-level subdirectories which 4041 will be created under each first-level directory. The default 4042 is 256. 4043 4044 4045 ==== The aufs store type ==== 4046 4047 "aufs" uses the same storage format as "ufs", utilizing 4048 POSIX-threads to avoid blocking the main Squid process on 4049 disk-I/O. This was formerly known in Squid as async-io. 4050 4051 Usage: 4052 cache_dir aufs Directory-Name Mbytes L1 L2 [options] 4053 4054 see argument descriptions under ufs above 4055 4056 4057 ==== The diskd store type ==== 4058 4059 "diskd" uses the same storage format as "ufs", utilizing a 4060 separate process to avoid blocking the main Squid process on 4061 disk-I/O. 4062 4063 Usage: 4064 cache_dir diskd Directory-Name Mbytes L1 L2 [options] [Q1=n] [Q2=n] 4065 4066 see argument descriptions under ufs above 4067 4068 Q1 specifies the number of unacknowledged I/O requests when Squid 4069 stops opening new files. If this many messages are in the queues, 4070 Squid won't open new files. Default is 64 4071 4072 Q2 specifies the number of unacknowledged messages when Squid 4073 starts blocking. If this many messages are in the queues, 4074 Squid blocks until it receives some replies. Default is 72 4075 4076 When Q1 < Q2 (the default), the cache directory is optimized 4077 for lower response time at the expense of a decrease in hit 4078 ratio. If Q1 > Q2, the cache directory is optimized for 4079 higher hit ratio at the expense of an increase in response 4080 time. 4081 4082 4083 ==== The rock store type ==== 4084 4085 Usage: 4086 cache_dir rock Directory-Name Mbytes [options] 4087 4088 The Rock Store type is a database-style storage. All cached 4089 entries are stored in a "database" file, using fixed-size slots. 4090 A single entry occupies one or more slots. 4091 4092 If possible, Squid using Rock Store creates a dedicated kid 4093 process called "disker" to avoid blocking Squid worker(s) on disk 4094 I/O. One disker kid is created for each rock cache_dir. Diskers 4095 are created only when Squid, running in daemon mode, has support 4096 for the IpcIo disk I/O module. 4097 4098 swap-timeout=msec: Squid will not start writing a miss to or 4099 reading a hit from disk if it estimates that the swap operation 4100 will take more than the specified number of milliseconds. By 4101 default and when set to zero, disables the disk I/O time limit 4102 enforcement. Ignored when using blocking I/O module because 4103 blocking synchronous I/O does not allow Squid to estimate the 4104 expected swap wait time. 4105 4106 max-swap-rate=swaps/sec: Artificially limits disk access using 4107 the specified I/O rate limit. Swap out requests that 4108 would cause the average I/O rate to exceed the limit are 4109 delayed. Individual swap in requests (i.e., hits or reads) are 4110 not delayed, but they do contribute to measured swap rate and 4111 since they are placed in the same FIFO queue as swap out 4112 requests, they may wait longer if max-swap-rate is smaller. 4113 This is necessary on file systems that buffer "too 4114 many" writes and then start blocking Squid and other processes 4115 while committing those writes to disk. Usually used together 4116 with swap-timeout to avoid excessive delays and queue overflows 4117 when disk demand exceeds available disk "bandwidth". By default 4118 and when set to zero, disables the disk I/O rate limit 4119 enforcement. Currently supported by IpcIo module only. 4120 4121 slot-size=bytes: The size of a database "record" used for 4122 storing cached responses. A cached response occupies at least 4123 one slot and all database I/O is done using individual slots so 4124 increasing this parameter leads to more disk space waste while 4125 decreasing it leads to more disk I/O overheads. Should be a 4126 multiple of your operating system I/O page size. Defaults to 4127 16KBytes. A housekeeping header is stored with each slot and 4128 smaller slot-sizes will be rejected. The header is smaller than 4129 100 bytes. 4130 4131 4132 ==== COMMON OPTIONS ==== 4133 4134 no-store no new objects should be stored to this cache_dir. 4135 4136 min-size=n the minimum object size in bytes this cache_dir 4137 will accept. It's used to restrict a cache_dir 4138 to only store large objects (e.g. AUFS) while 4139 other stores are optimized for smaller objects 4140 (e.g. Rock). 4141 Defaults to 0. 4142 4143 max-size=n the maximum object size in bytes this cache_dir 4144 supports. 4145 The value in maximum_object_size directive sets 4146 the default unless more specific details are 4147 available (ie a small store capacity). 4148 4149 Note: To make optimal use of the max-size limits you should order 4150 the cache_dir lines with the smallest max-size value first. 4151 4152NOCOMMENT_START 4153 4154# Uncomment and adjust the following to add a disk cache directory. 4155#cache_dir ufs @DEFAULT_SWAP_DIR@ 100 16 256 4156NOCOMMENT_END 4157DOC_END 4158 4159NAME: store_dir_select_algorithm 4160TYPE: string 4161LOC: Config.store_dir_select_algorithm 4162DEFAULT: least-load 4163DOC_START 4164 How Squid selects which cache_dir to use when the response 4165 object will fit into more than one. 4166 4167 Regardless of which algorithm is used the cache_dir min-size 4168 and max-size parameters are obeyed. As such they can affect 4169 the selection algorithm by limiting the set of considered 4170 cache_dir. 4171 4172 Algorithms: 4173 4174 least-load 4175 4176 This algorithm is suited to caches with similar cache_dir 4177 sizes and disk speeds. 4178 4179 The disk with the least I/O pending is selected. 4180 When there are multiple disks with the same I/O load ranking 4181 the cache_dir with most available capacity is selected. 4182 4183 When a mix of cache_dir sizes are configured the faster disks 4184 have a naturally lower I/O loading and larger disks have more 4185 capacity. So space used to store objects and data throughput 4186 may be very unbalanced towards larger disks. 4187 4188 4189 round-robin 4190 4191 This algorithm is suited to caches with unequal cache_dir 4192 disk sizes. 4193 4194 Each cache_dir is selected in a rotation. The next suitable 4195 cache_dir is used. 4196 4197 Available cache_dir capacity is only considered in relation 4198 to whether the object will fit and meets the min-size and 4199 max-size parameters. 4200 4201 Disk I/O loading is only considered to prevent overload on slow 4202 disks. This algorithm does not spread objects by size, so any 4203 I/O loading per-disk may appear very unbalanced and volatile. 4204 4205 If several cache_dirs use similar min-size, max-size, or other 4206 limits to to reject certain responses, then do not group such 4207 cache_dir lines together, to avoid round-robin selection bias 4208 towards the first cache_dir after the group. Instead, interleave 4209 cache_dir lines from different groups. For example: 4210 4211 store_dir_select_algorithm round-robin 4212 cache_dir rock /hdd1 ... min-size=100000 4213 cache_dir rock /ssd1 ... max-size=99999 4214 cache_dir rock /hdd2 ... min-size=100000 4215 cache_dir rock /ssd2 ... max-size=99999 4216 cache_dir rock /hdd3 ... min-size=100000 4217 cache_dir rock /ssd3 ... max-size=99999 4218DOC_END 4219 4220NAME: max_open_disk_fds 4221TYPE: int 4222LOC: Config.max_open_disk_fds 4223DEFAULT: 0 4224DEFAULT_DOC: no limit 4225DOC_START 4226 To avoid having disk as the I/O bottleneck Squid can optionally 4227 bypass the on-disk cache if more than this amount of disk file 4228 descriptors are open. 4229 4230 A value of 0 indicates no limit. 4231DOC_END 4232 4233NAME: cache_swap_low 4234COMMENT: (percent, 0-100) 4235TYPE: int 4236DEFAULT: 90 4237LOC: Config.Swap.lowWaterMark 4238DOC_START 4239 The low-water mark for AUFS/UFS/diskd cache object eviction by 4240 the cache_replacement_policy algorithm. 4241 4242 Removal begins when the swap (disk) usage of a cache_dir is 4243 above this low-water mark and attempts to maintain utilization 4244 near the low-water mark. 4245 4246 As swap utilization increases towards the high-water mark set 4247 by cache_swap_high object eviction becomes more agressive. 4248 4249 The value difference in percentages between low- and high-water 4250 marks represent an eviction rate of 300 objects per second and 4251 the rate continues to scale in agressiveness by multiples of 4252 this above the high-water mark. 4253 4254 Defaults are 90% and 95%. If you have a large cache, 5% could be 4255 hundreds of MB. If this is the case you may wish to set these 4256 numbers closer together. 4257 4258 See also cache_swap_high and cache_replacement_policy 4259DOC_END 4260 4261NAME: cache_swap_high 4262COMMENT: (percent, 0-100) 4263TYPE: int 4264DEFAULT: 95 4265LOC: Config.Swap.highWaterMark 4266DOC_START 4267 The high-water mark for AUFS/UFS/diskd cache object eviction by 4268 the cache_replacement_policy algorithm. 4269 4270 Removal begins when the swap (disk) usage of a cache_dir is 4271 above the low-water mark set by cache_swap_low and attempts to 4272 maintain utilization near the low-water mark. 4273 4274 As swap utilization increases towards this high-water mark object 4275 eviction becomes more agressive. 4276 4277 The value difference in percentages between low- and high-water 4278 marks represent an eviction rate of 300 objects per second and 4279 the rate continues to scale in agressiveness by multiples of 4280 this above the high-water mark. 4281 4282 Defaults are 90% and 95%. If you have a large cache, 5% could be 4283 hundreds of MB. If this is the case you may wish to set these 4284 numbers closer together. 4285 4286 See also cache_swap_low and cache_replacement_policy 4287DOC_END 4288 4289COMMENT_START 4290 LOGFILE OPTIONS 4291 ----------------------------------------------------------------------------- 4292COMMENT_END 4293 4294NAME: logformat 4295TYPE: logformat 4296LOC: Log::TheConfig 4297DEFAULT: none 4298DEFAULT_DOC: The format definitions squid, common, combined, referrer, useragent are built in. 4299DOC_START 4300 Usage: 4301 4302 logformat <name> <format specification> 4303 4304 Defines an access log format. 4305 4306 The <format specification> is a string with embedded % format codes 4307 4308 % format codes all follow the same basic structure where all 4309 components but the formatcode are optional and usually unnecessary, 4310 especially when dealing with common codes. 4311 4312 % [encoding] [-] [[0]width] [{arg}] formatcode [{arg}] 4313 4314 encoding escapes or otherwise protects "special" characters: 4315 4316 " Quoted string encoding where quote(") and 4317 backslash(\) characters are \-escaped while 4318 CR, LF, and TAB characters are encoded as \r, 4319 \n, and \t two-character sequences. 4320 4321 [ Custom Squid encoding where percent(%), square 4322 brackets([]), backslash(\) and characters with 4323 codes outside of [32,126] range are %-encoded. 4324 SP is not encoded. Used by log_mime_hdrs. 4325 4326 # URL encoding (a.k.a. percent-encoding) where 4327 all URL unsafe and control characters (per RFC 4328 1738) are %-encoded. 4329 4330 / Shell-like encoding where quote(") and 4331 backslash(\) characters are \-escaped while CR 4332 and LF characters are encoded as \r and \n 4333 two-character sequences. Values containing SP 4334 character(s) are surrounded by quotes("). 4335 4336 ' Raw/as-is encoding with no escaping/quoting. 4337 4338 Default encoding: When no explicit encoding is 4339 specified, each %code determines its own encoding. 4340 Most %codes use raw/as-is encoding, but some codes use 4341 a so called "pass-through URL encoding" where all URL 4342 unsafe and control characters (per RFC 1738) are 4343 %-encoded, but the percent character(%) is left as is. 4344 4345 - left aligned 4346 4347 width minimum and/or maximum field width: 4348 [width_min][.width_max] 4349 When minimum starts with 0, the field is zero-padded. 4350 String values exceeding maximum width are truncated. 4351 4352 {arg} argument such as header name etc. This field may be 4353 placed before or after the token, but not both at once. 4354 4355 Format codes: 4356 4357 % a literal % character 4358 sn Unique sequence number per log line entry 4359 err_code The ID of an error response served by Squid or 4360 a similar internal error identifier. 4361 err_detail Additional err_code-dependent error information. 4362 note The annotation specified by the argument. Also 4363 logs the adaptation meta headers set by the 4364 adaptation_meta configuration parameter. 4365 If no argument given all annotations logged. 4366 The argument may include a separator to use with 4367 annotation values: 4368 name[:separator] 4369 By default, multiple note values are separated with "," 4370 and multiple notes are separated with "\r\n". 4371 When logging named notes with %{name}note, the 4372 explicitly configured separator is used between note 4373 values. When logging all notes with %note, the 4374 explicitly configured separator is used between 4375 individual notes. There is currently no way to 4376 specify both value and notes separators when logging 4377 all notes with %note. 4378 4379 Connection related format codes: 4380 4381 >a Client source IP address 4382 >A Client FQDN 4383 >p Client source port 4384 >eui Client source EUI (MAC address, EUI-48 or EUI-64 identifier) 4385 >la Local IP address the client connected to 4386 >lp Local port number the client connected to 4387 >qos Client connection TOS/DSCP value set by Squid 4388 >nfmark Client connection netfilter mark set by Squid 4389 4390 la Local listening IP address the client connection was connected to. 4391 lp Local listening port number the client connection was connected to. 4392 4393 <a Server IP address of the last server or peer connection 4394 <A Server FQDN or peer name 4395 <p Server port number of the last server or peer connection 4396 <la Local IP address of the last server or peer connection 4397 <lp Local port number of the last server or peer connection 4398 <qos Server connection TOS/DSCP value set by Squid 4399 <nfmark Server connection netfilter mark set by Squid 4400 4401 >handshake Raw client handshake 4402 Initial client bytes received by Squid on a newly 4403 accepted TCP connection or inside a just established 4404 CONNECT tunnel. Squid stops accumulating handshake 4405 bytes as soon as the handshake parser succeeds or 4406 fails (determining whether the client is using the 4407 expected protocol). 4408 4409 For HTTP clients, the handshake is the request line. 4410 For TLS clients, the handshake consists of all TLS 4411 records up to and including the TLS record that 4412 contains the last byte of the first ClientHello 4413 message. For clients using an unsupported protocol, 4414 this field contains the bytes received by Squid at the 4415 time of the handshake parsing failure. 4416 4417 See the on_unsupported_protocol directive for more 4418 information on Squid handshake traffic expectations. 4419 4420 Current support is limited to these contexts: 4421 - http_port connections, but only when the 4422 on_unsupported_protocol directive is in use. 4423 - https_port connections (and CONNECT tunnels) that 4424 are subject to the ssl_bump peek or stare action. 4425 4426 To protect binary handshake data, this field is always 4427 base64-encoded (RFC 4648 Section 4). If logformat 4428 field encoding is configured, that encoding is applied 4429 on top of base64. Otherwise, the computed base64 value 4430 is recorded as is. 4431 4432 Time related format codes: 4433 4434 ts Seconds since epoch 4435 tu subsecond time (milliseconds) 4436 tl Local time. Optional strftime format argument 4437 default %d/%b/%Y:%H:%M:%S %z 4438 tg GMT time. Optional strftime format argument 4439 default %d/%b/%Y:%H:%M:%S %z 4440 tr Response time (milliseconds) 4441 dt Total time spent making DNS lookups (milliseconds) 4442 tS Approximate master transaction start time in 4443 <full seconds since epoch>.<fractional seconds> format. 4444 Currently, Squid considers the master transaction 4445 started when a complete HTTP request header initiating 4446 the transaction is received from the client. This is 4447 the same value that Squid uses to calculate transaction 4448 response time when logging %tr to access.log. Currently, 4449 Squid uses millisecond resolution for %tS values, 4450 similar to the default access.log "current time" field 4451 (%ts.%03tu). 4452 4453 Access Control related format codes: 4454 4455 et Tag returned by external acl 4456 ea Log string returned by external acl 4457 un User name (any available) 4458 ul User name from authentication 4459 ue User name from external acl helper 4460 ui User name from ident 4461 un A user name. Expands to the first available name 4462 from the following list of information sources: 4463 - authenticated user name, like %ul 4464 - user name supplied by an external ACL, like %ue 4465 - SSL client name, like %us 4466 - ident user name, like %ui 4467 credentials Client credentials. The exact meaning depends on 4468 the authentication scheme: For Basic authentication, 4469 it is the password; for Digest, the realm sent by the 4470 client; for NTLM and Negotiate, the client challenge 4471 or client credentials prefixed with "YR " or "KK ". 4472 4473 HTTP related format codes: 4474 4475 REQUEST 4476 4477 [http::]rm Request method (GET/POST etc) 4478 [http::]>rm Request method from client 4479 [http::]<rm Request method sent to server or peer 4480 4481 [http::]ru Request URL received (or computed) and sanitized 4482 4483 Logs request URI received from the client, a 4484 request adaptation service, or a request 4485 redirector (whichever was applied last). 4486 4487 Computed URLs are URIs of internally generated 4488 requests and various "error:..." URIs. 4489 4490 Honors strip_query_terms and uri_whitespace. 4491 4492 This field is not encoded by default. Encoding 4493 this field using variants of %-encoding will 4494 clash with uri_whitespace modifications that 4495 also use %-encoding. 4496 4497 [http::]>ru Request URL received from the client (or computed) 4498 4499 Computed URLs are URIs of internally generated 4500 requests and various "error:..." URIs. 4501 4502 Unlike %ru, this request URI is not affected 4503 by request adaptation, URL rewriting services, 4504 and strip_query_terms. 4505 4506 Honors uri_whitespace. 4507 4508 This field is using pass-through URL encoding 4509 by default. Encoding this field using other 4510 variants of %-encoding will clash with 4511 uri_whitespace modifications that also use 4512 %-encoding. 4513 4514 [http::]<ru Request URL sent to server or peer 4515 [http::]>rs Request URL scheme from client 4516 [http::]<rs Request URL scheme sent to server or peer 4517 [http::]>rd Request URL domain from client 4518 [http::]<rd Request URL domain sent to server or peer 4519 [http::]>rP Request URL port from client 4520 [http::]<rP Request URL port sent to server or peer 4521 [http::]rp Request URL path excluding hostname 4522 [http::]>rp Request URL path excluding hostname from client 4523 [http::]<rp Request URL path excluding hostname sent to server or peer 4524 [http::]rv Request protocol version 4525 [http::]>rv Request protocol version from client 4526 [http::]<rv Request protocol version sent to server or peer 4527 4528 [http::]>h Original received request header. 4529 Usually differs from the request header sent by 4530 Squid, although most fields are often preserved. 4531 Accepts optional header field name/value filter 4532 argument using name[:[separator]element] format. 4533 [http::]>ha Received request header after adaptation and 4534 redirection (pre-cache REQMOD vectoring point). 4535 Usually differs from the request header sent by 4536 Squid, although most fields are often preserved. 4537 Optional header name argument as for >h 4538 4539 RESPONSE 4540 4541 [http::]<Hs HTTP status code received from the next hop 4542 [http::]>Hs HTTP status code sent to the client 4543 4544 [http::]<h Reply header. Optional header name argument 4545 as for >h 4546 4547 [http::]mt MIME content type 4548 4549 4550 SIZE COUNTERS 4551 4552 [http::]st Total size of request + reply traffic with client 4553 [http::]>st Total size of request received from client. 4554 Excluding chunked encoding bytes. 4555 [http::]<st Total size of reply sent to client (after adaptation) 4556 4557 [http::]>sh Size of request headers received from client 4558 [http::]<sh Size of reply headers sent to client (after adaptation) 4559 4560 [http::]<sH Reply high offset sent 4561 [http::]<sS Upstream object size 4562 4563 [http::]<bs Number of HTTP-equivalent message body bytes 4564 received from the next hop, excluding chunked 4565 transfer encoding and control messages. 4566 Generated FTP/Gopher listings are treated as 4567 received bodies. 4568 4569 TIMING 4570 4571 [http::]<pt Peer response time in milliseconds. The timer starts 4572 when the last request byte is sent to the next hop 4573 and stops when the last response byte is received. 4574 [http::]<tt Total time in milliseconds. The timer 4575 starts with the first connect request (or write I/O) 4576 sent to the first selected peer. The timer stops 4577 with the last I/O with the last peer. 4578 4579 Squid handling related format codes: 4580 4581 Ss Squid request status (TCP_MISS etc) 4582 Sh Squid hierarchy status (DEFAULT_PARENT etc) 4583 4584 SSL-related format codes: 4585 4586 ssl::bump_mode SslBump decision for the transaction: 4587 4588 For CONNECT requests that initiated bumping of 4589 a connection and for any request received on 4590 an already bumped connection, Squid logs the 4591 corresponding SslBump mode ("splice", "bump", 4592 "peek", "stare", "terminate", "server-first" 4593 or "client-first"). See the ssl_bump option 4594 for more information about these modes. 4595 4596 A "none" token is logged for requests that 4597 triggered "ssl_bump" ACL evaluation matching 4598 a "none" rule. 4599 4600 In all other cases, a single dash ("-") is 4601 logged. 4602 4603 ssl::>sni SSL client SNI sent to Squid. 4604 4605 ssl::>cert_subject 4606 The Subject field of the received client 4607 SSL certificate or a dash ('-') if Squid has 4608 received an invalid/malformed certificate or 4609 no certificate at all. Consider encoding the 4610 logged value because Subject often has spaces. 4611 4612 ssl::>cert_issuer 4613 The Issuer field of the received client 4614 SSL certificate or a dash ('-') if Squid has 4615 received an invalid/malformed certificate or 4616 no certificate at all. Consider encoding the 4617 logged value because Issuer often has spaces. 4618 4619 ssl::<cert_subject 4620 The Subject field of the received server 4621 TLS certificate or a dash ('-') if this is 4622 not available. Consider encoding the logged 4623 value because Subject often has spaces. 4624 4625 ssl::<cert_issuer 4626 The Issuer field of the received server 4627 TLS certificate or a dash ('-') if this is 4628 not available. Consider encoding the logged 4629 value because Issuer often has spaces. 4630 4631 ssl::<cert_errors 4632 The list of certificate validation errors 4633 detected by Squid (including OpenSSL and 4634 certificate validation helper components). The 4635 errors are listed in the discovery order. By 4636 default, the error codes are separated by ':'. 4637 Accepts an optional separator argument. 4638 4639 %ssl::>negotiated_version The negotiated TLS version of the 4640 client connection. 4641 4642 %ssl::<negotiated_version The negotiated TLS version of the 4643 last server or peer connection. 4644 4645 %ssl::>received_hello_version The TLS version of the Hello 4646 message received from TLS client. 4647 4648 %ssl::<received_hello_version The TLS version of the Hello 4649 message received from TLS server. 4650 4651 %ssl::>received_supported_version The maximum TLS version 4652 supported by the TLS client. 4653 4654 %ssl::<received_supported_version The maximum TLS version 4655 supported by the TLS server. 4656 4657 %ssl::>negotiated_cipher The negotiated cipher of the 4658 client connection. 4659 4660 %ssl::<negotiated_cipher The negotiated cipher of the 4661 last server or peer connection. 4662 4663 If ICAP is enabled, the following code becomes available (as 4664 well as ICAP log codes documented with the icap_log option): 4665 4666 icap::tt Total ICAP processing time for the HTTP 4667 transaction. The timer ticks when ICAP 4668 ACLs are checked and when ICAP 4669 transaction is in progress. 4670 4671 If adaptation is enabled the following codes become available: 4672 4673 adapt::<last_h The header of the last ICAP response or 4674 meta-information from the last eCAP 4675 transaction related to the HTTP transaction. 4676 Like <h, accepts an optional header name 4677 argument. 4678 4679 adapt::sum_trs Summed adaptation transaction response 4680 times recorded as a comma-separated list in 4681 the order of transaction start time. Each time 4682 value is recorded as an integer number, 4683 representing response time of one or more 4684 adaptation (ICAP or eCAP) transaction in 4685 milliseconds. When a failed transaction is 4686 being retried or repeated, its time is not 4687 logged individually but added to the 4688 replacement (next) transaction. See also: 4689 adapt::all_trs. 4690 4691 adapt::all_trs All adaptation transaction response times. 4692 Same as adaptation_strs but response times of 4693 individual transactions are never added 4694 together. Instead, all transaction response 4695 times are recorded individually. 4696 4697 You can prefix adapt::*_trs format codes with adaptation 4698 service name in curly braces to record response time(s) specific 4699 to that service. For example: %{my_service}adapt::sum_trs 4700 4701 The default formats available (which do not need re-defining) are: 4702 4703logformat squid %ts.%03tu %6tr %>a %Ss/%03>Hs %<st %rm %ru %[un %Sh/%<a %mt 4704logformat common %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st %Ss:%Sh 4705logformat combined %>a %[ui %[un [%tl] "%rm %ru HTTP/%rv" %>Hs %<st "%{Referer}>h" "%{User-Agent}>h" %Ss:%Sh 4706logformat referrer %ts.%03tu %>a %{Referer}>h %ru 4707logformat useragent %>a [%tl] "%{User-Agent}>h" 4708 4709 NOTE: When the log_mime_hdrs directive is set to ON. 4710 The squid, common and combined formats have a safely encoded copy 4711 of the mime headers appended to each line within a pair of brackets. 4712 4713 NOTE: The common and combined formats are not quite true to the Apache definition. 4714 The logs from Squid contain an extra status and hierarchy code appended. 4715 4716DOC_END 4717 4718NAME: access_log cache_access_log 4719TYPE: access_log 4720LOC: Config.Log.accesslogs 4721DEFAULT_IF_NONE: daemon:@DEFAULT_ACCESS_LOG@ squid 4722DOC_START 4723 Configures whether and how Squid logs HTTP and ICP transactions. 4724 If access logging is enabled, a single line is logged for every 4725 matching HTTP or ICP request. The recommended directive formats are: 4726 4727 access_log <module>:<place> [option ...] [acl acl ...] 4728 access_log none [acl acl ...] 4729 4730 The following directive format is accepted but may be deprecated: 4731 access_log <module>:<place> [<logformat name> [acl acl ...]] 4732 4733 In most cases, the first ACL name must not contain the '=' character 4734 and should not be equal to an existing logformat name. You can always 4735 start with an 'all' ACL to work around those restrictions. 4736 4737 Will log to the specified module:place using the specified format (which 4738 must be defined in a logformat directive) those entries which match 4739 ALL the acl's specified (which must be defined in acl clauses). 4740 If no acl is specified, all requests will be logged to this destination. 4741 4742 ===== Available options for the recommended directive format ===== 4743 4744 logformat=name Names log line format (either built-in or 4745 defined by a logformat directive). Defaults 4746 to 'squid'. 4747 4748 buffer-size=64KB Defines approximate buffering limit for log 4749 records (see buffered_logs). Squid should not 4750 keep more than the specified size and, hence, 4751 should flush records before the buffer becomes 4752 full to avoid overflows under normal 4753 conditions (the exact flushing algorithm is 4754 module-dependent though). The on-error option 4755 controls overflow handling. 4756 4757 on-error=die|drop Defines action on unrecoverable errors. The 4758 'drop' action ignores (i.e., does not log) 4759 affected log records. The default 'die' action 4760 kills the affected worker. The drop action 4761 support has not been tested for modules other 4762 than tcp. 4763 4764 rotate=N Specifies the number of log file rotations to 4765 make when you run 'squid -k rotate'. The default 4766 is to obey the logfile_rotate directive. Setting 4767 rotate=0 will disable the file name rotation, 4768 but the log files are still closed and re-opened. 4769 This will enable you to rename the logfiles 4770 yourself just before sending the rotate signal. 4771 Only supported by the stdio module. 4772 4773 ===== Modules Currently available ===== 4774 4775 none Do not log any requests matching these ACL. 4776 Do not specify Place or logformat name. 4777 4778 stdio Write each log line to disk immediately at the completion of 4779 each request. 4780 Place: the filename and path to be written. 4781 4782 daemon Very similar to stdio. But instead of writing to disk the log 4783 line is passed to a daemon helper for asychronous handling instead. 4784 Place: varies depending on the daemon. 4785 4786 log_file_daemon Place: the file name and path to be written. 4787 4788 syslog To log each request via syslog facility. 4789 Place: The syslog facility and priority level for these entries. 4790 Place Format: facility.priority 4791 4792 where facility could be any of: 4793 authpriv, daemon, local0 ... local7 or user. 4794 4795 And priority could be any of: 4796 err, warning, notice, info, debug. 4797 4798 udp To send each log line as text data to a UDP receiver. 4799 Place: The destination host name or IP and port. 4800 Place Format: //host:port 4801 4802 tcp To send each log line as text data to a TCP receiver. 4803 Lines may be accumulated before sending (see buffered_logs). 4804 Place: The destination host name or IP and port. 4805 Place Format: //host:port 4806 4807 Default: 4808 access_log daemon:@DEFAULT_ACCESS_LOG@ squid 4809DOC_END 4810 4811NAME: icap_log 4812TYPE: access_log 4813IFDEF: ICAP_CLIENT 4814LOC: Config.Log.icaplogs 4815DEFAULT: none 4816DOC_START 4817 ICAP log files record ICAP transaction summaries, one line per 4818 transaction. 4819 4820 The icap_log option format is: 4821 icap_log <filepath> [<logformat name> [acl acl ...]] 4822 icap_log none [acl acl ...]] 4823 4824 Please see access_log option documentation for details. The two 4825 kinds of logs share the overall configuration approach and many 4826 features. 4827 4828 ICAP processing of a single HTTP message or transaction may 4829 require multiple ICAP transactions. In such cases, multiple 4830 ICAP transaction log lines will correspond to a single access 4831 log line. 4832 4833 ICAP log supports many access.log logformat %codes. In ICAP context, 4834 HTTP message-related %codes are applied to the HTTP message embedded 4835 in an ICAP message. Logformat "%http::>..." codes are used for HTTP 4836 messages embedded in ICAP requests while "%http::<..." codes are used 4837 for HTTP messages embedded in ICAP responses. For example: 4838 4839 http::>h To-be-adapted HTTP message headers sent by Squid to 4840 the ICAP service. For REQMOD transactions, these are 4841 HTTP request headers. For RESPMOD, these are HTTP 4842 response headers, but Squid currently cannot log them 4843 (i.e., %http::>h will expand to "-" for RESPMOD). 4844 4845 http::<h Adapted HTTP message headers sent by the ICAP 4846 service to Squid (i.e., HTTP request headers in regular 4847 REQMOD; HTTP response headers in RESPMOD and during 4848 request satisfaction in REQMOD). 4849 4850 ICAP OPTIONS transactions do not embed HTTP messages. 4851 4852 Several logformat codes below deal with ICAP message bodies. An ICAP 4853 message body, if any, typically includes a complete HTTP message 4854 (required HTTP headers plus optional HTTP message body). When 4855 computing HTTP message body size for these logformat codes, Squid 4856 either includes or excludes chunked encoding overheads; see 4857 code-specific documentation for details. 4858 4859 For Secure ICAP services, all size-related information is currently 4860 computed before/after TLS encryption/decryption, as if TLS was not 4861 in use at all. 4862 4863 The following format codes are also available for ICAP logs: 4864 4865 icap::<A ICAP server IP address. Similar to <A. 4866 4867 icap::<service_name ICAP service name from the icap_service 4868 option in Squid configuration file. 4869 4870 icap::ru ICAP Request-URI. Similar to ru. 4871 4872 icap::rm ICAP request method (REQMOD, RESPMOD, or 4873 OPTIONS). Similar to existing rm. 4874 4875 icap::>st The total size of the ICAP request sent to the ICAP 4876 server (ICAP headers + ICAP body), including chunking 4877 metadata (if any). 4878 4879 icap::<st The total size of the ICAP response received from the 4880 ICAP server (ICAP headers + ICAP body), including 4881 chunking metadata (if any). 4882 4883 icap::<bs The size of the ICAP response body received from the 4884 ICAP server, excluding chunking metadata (if any). 4885 4886 icap::tr Transaction response time (in 4887 milliseconds). The timer starts when 4888 the ICAP transaction is created and 4889 stops when the transaction is completed. 4890 Similar to tr. 4891 4892 icap::tio Transaction I/O time (in milliseconds). The 4893 timer starts when the first ICAP request 4894 byte is scheduled for sending. The timers 4895 stops when the last byte of the ICAP response 4896 is received. 4897 4898 icap::to Transaction outcome: ICAP_ERR* for all 4899 transaction errors, ICAP_OPT for OPTION 4900 transactions, ICAP_ECHO for 204 4901 responses, ICAP_MOD for message 4902 modification, and ICAP_SAT for request 4903 satisfaction. Similar to Ss. 4904 4905 icap::Hs ICAP response status code. Similar to Hs. 4906 4907 icap::>h ICAP request header(s). Similar to >h. 4908 4909 icap::<h ICAP response header(s). Similar to <h. 4910 4911 The default ICAP log format, which can be used without an explicit 4912 definition, is called icap_squid: 4913 4914logformat icap_squid %ts.%03tu %6icap::tr %>A %icap::to/%03icap::Hs %icap::<st %icap::rm %icap::ru %un -/%icap::<A - 4915 4916 See also: logformat and %adapt::<last_h 4917DOC_END 4918 4919NAME: logfile_daemon 4920TYPE: string 4921DEFAULT: @DEFAULT_LOGFILED@ 4922LOC: Log::TheConfig.logfile_daemon 4923DOC_START 4924 Specify the path to the logfile-writing daemon. This daemon is 4925 used to write the access and store logs, if configured. 4926 4927 Squid sends a number of commands to the log daemon: 4928 L<data>\n - logfile data 4929 R\n - rotate file 4930 T\n - truncate file 4931 O\n - reopen file 4932 F\n - flush file 4933 r<n>\n - set rotate count to <n> 4934 b<n>\n - 1 = buffer output, 0 = don't buffer output 4935 4936 No responses is expected. 4937DOC_END 4938 4939NAME: stats_collection 4940TYPE: acl_access 4941LOC: Config.accessList.stats_collection 4942DEFAULT: none 4943DEFAULT_DOC: Allow logging for all transactions. 4944COMMENT: allow|deny acl acl... 4945DOC_START 4946 This options allows you to control which requests gets accounted 4947 in performance counters. 4948 4949 This clause only supports fast acl types. 4950 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 4951DOC_END 4952 4953NAME: cache_store_log 4954TYPE: string 4955DEFAULT: none 4956LOC: Config.Log.store 4957DOC_START 4958 Logs the activities of the storage manager. Shows which 4959 objects are ejected from the cache, and which objects are 4960 saved and for how long. 4961 There are not really utilities to analyze this data, so you can safely 4962 disable it (the default). 4963 4964 Store log uses modular logging outputs. See access_log for the list 4965 of modules supported. 4966 4967 Example: 4968 cache_store_log stdio:@DEFAULT_STORE_LOG@ 4969 cache_store_log daemon:@DEFAULT_STORE_LOG@ 4970DOC_END 4971 4972NAME: cache_swap_state cache_swap_log 4973TYPE: string 4974LOC: Config.Log.swap 4975DEFAULT: none 4976DEFAULT_DOC: Store the journal inside its cache_dir 4977DOC_START 4978 Location for the cache "swap.state" file. This index file holds 4979 the metadata of objects saved on disk. It is used to rebuild 4980 the cache during startup. Normally this file resides in each 4981 'cache_dir' directory, but you may specify an alternate 4982 pathname here. Note you must give a full filename, not just 4983 a directory. Since this is the index for the whole object 4984 list you CANNOT periodically rotate it! 4985 4986 If %s can be used in the file name it will be replaced with a 4987 a representation of the cache_dir name where each / is replaced 4988 with '.'. This is needed to allow adding/removing cache_dir 4989 lines when cache_swap_log is being used. 4990 4991 If have more than one 'cache_dir', and %s is not used in the name 4992 these swap logs will have names such as: 4993 4994 cache_swap_log.00 4995 cache_swap_log.01 4996 cache_swap_log.02 4997 4998 The numbered extension (which is added automatically) 4999 corresponds to the order of the 'cache_dir' lines in this 5000 configuration file. If you change the order of the 'cache_dir' 5001 lines in this file, these index files will NOT correspond to 5002 the correct 'cache_dir' entry (unless you manually rename 5003 them). We recommend you do NOT use this option. It is 5004 better to keep these index files in each 'cache_dir' directory. 5005DOC_END 5006 5007NAME: logfile_rotate 5008TYPE: int 5009DEFAULT: 10 5010LOC: Config.Log.rotateNumber 5011DOC_START 5012 Specifies the default number of logfile rotations to make when you 5013 type 'squid -k rotate'. The default is 10, which will rotate 5014 with extensions 0 through 9. Setting logfile_rotate to 0 will 5015 disable the file name rotation, but the logfiles are still closed 5016 and re-opened. This will enable you to rename the logfiles 5017 yourself just before sending the rotate signal. 5018 5019 Note, from Squid-3.1 this option is only a default for cache.log, 5020 that log can be rotated separately by using debug_options. 5021 5022 Note, from Squid-4 this option is only a default for access.log 5023 recorded by stdio: module. Those logs can be rotated separately by 5024 using the rotate=N option on their access_log directive. 5025 5026 Note, the 'squid -k rotate' command normally sends a USR1 5027 signal to the running squid process. In certain situations 5028 (e.g. on Linux with Async I/O), USR1 is used for other 5029 purposes, so -k rotate uses another signal. It is best to get 5030 in the habit of using 'squid -k rotate' instead of 'kill -USR1 5031 <pid>'. 5032 5033DOC_END 5034 5035NAME: mime_table 5036TYPE: string 5037DEFAULT: @DEFAULT_MIME_TABLE@ 5038LOC: Config.mimeTablePathname 5039DOC_START 5040 Path to Squid's icon configuration file. 5041 5042 You shouldn't need to change this, but the default file contains 5043 examples and formatting information if you do. 5044DOC_END 5045 5046NAME: log_mime_hdrs 5047COMMENT: on|off 5048TYPE: onoff 5049LOC: Config.onoff.log_mime_hdrs 5050DEFAULT: off 5051DOC_START 5052 The Cache can record both the request and the response MIME 5053 headers for each HTTP transaction. The headers are encoded 5054 safely and will appear as two bracketed fields at the end of 5055 the access log (for either the native or httpd-emulated log 5056 formats). To enable this logging set log_mime_hdrs to 'on'. 5057DOC_END 5058 5059NAME: pid_filename 5060TYPE: string 5061DEFAULT: @DEFAULT_PID_FILE@ 5062LOC: Config.pidFilename 5063DOC_START 5064 A filename to write the process-id to. To disable, enter "none". 5065 5066 Note: If you change this setting, you need to set squid_pidfile 5067 in /etc/rc.conf to reflect the new value. Please see 5068 /usr/local/etc/rc.d/squid for details. 5069DOC_END 5070 5071NAME: client_netmask 5072TYPE: address 5073LOC: Config.Addrs.client_netmask 5074DEFAULT: no_addr 5075DEFAULT_DOC: Log full client IP address 5076DOC_START 5077 A netmask for client addresses in logfiles and cachemgr output. 5078 Change this to protect the privacy of your cache clients. 5079 A netmask of 255.255.255.0 will log all IP's in that range with 5080 the last digit set to '0'. 5081DOC_END 5082 5083NAME: strip_query_terms 5084TYPE: onoff 5085LOC: Config.onoff.strip_query_terms 5086DEFAULT: on 5087DOC_START 5088 By default, Squid strips query terms from requested URLs before 5089 logging. This protects your user's privacy and reduces log size. 5090 5091 When investigating HIT/MISS or other caching behaviour you 5092 will need to disable this to see the full URL used by Squid. 5093DOC_END 5094 5095NAME: buffered_logs 5096COMMENT: on|off 5097TYPE: onoff 5098DEFAULT: off 5099LOC: Config.onoff.buffered_logs 5100DOC_START 5101 Whether to write/send access_log records ASAP or accumulate them and 5102 then write/send them in larger chunks. Buffering may improve 5103 performance because it decreases the number of I/Os. However, 5104 buffering increases the delay before log records become available to 5105 the final recipient (e.g., a disk file or logging daemon) and, 5106 hence, increases the risk of log records loss. 5107 5108 Note that even when buffered_logs are off, Squid may have to buffer 5109 records if it cannot write/send them immediately due to pending I/Os 5110 (e.g., the I/O writing the previous log record) or connectivity loss. 5111 5112 Currently honored by 'daemon' and 'tcp' access_log modules only. 5113DOC_END 5114 5115NAME: netdb_filename 5116TYPE: string 5117DEFAULT: stdio:@DEFAULT_NETDB_FILE@ 5118LOC: Config.netdbFilename 5119IFDEF: USE_ICMP 5120DOC_START 5121 Where Squid stores it's netdb journal. 5122 When enabled this journal preserves netdb state between restarts. 5123 5124 To disable, enter "none". 5125DOC_END 5126 5127COMMENT_START 5128 OPTIONS FOR TROUBLESHOOTING 5129 ----------------------------------------------------------------------------- 5130COMMENT_END 5131 5132NAME: cache_log 5133TYPE: string 5134DEFAULT_IF_NONE: @DEFAULT_CACHE_LOG@ 5135LOC: Debug::cache_log 5136DOC_START 5137 Squid administrative logging file. 5138 5139 This is where general information about Squid behavior goes. You can 5140 increase the amount of data logged to this file and how often it is 5141 rotated with "debug_options" 5142DOC_END 5143 5144NAME: debug_options 5145TYPE: eol 5146DEFAULT: ALL,1 5147DEFAULT_DOC: Log all critical and important messages. 5148LOC: Debug::debugOptions 5149DOC_START 5150 Logging options are set as section,level where each source file 5151 is assigned a unique section. Lower levels result in less 5152 output, Full debugging (level 9) can result in a very large 5153 log file, so be careful. 5154 5155 The magic word "ALL" sets debugging levels for all sections. 5156 The default is to run with "ALL,1" to record important warnings. 5157 5158 The rotate=N option can be used to keep more or less of these logs 5159 than would otherwise be kept by logfile_rotate. 5160 For most uses a single log should be enough to monitor current 5161 events affecting Squid. 5162DOC_END 5163 5164NAME: coredump_dir 5165TYPE: string 5166LOC: Config.coredump_dir 5167DEFAULT_IF_NONE: none 5168DEFAULT_DOC: Use the directory from where Squid was started. 5169DOC_START 5170 By default Squid leaves core files in the directory from where 5171 it was started. If you set 'coredump_dir' to a directory 5172 that exists, Squid will chdir() to that directory at startup 5173 and coredump files will be left there. 5174 5175NOCOMMENT_START 5176 5177# Leave coredumps in the first cache dir 5178coredump_dir @DEFAULT_SWAP_DIR@ 5179NOCOMMENT_END 5180DOC_END 5181 5182 5183COMMENT_START 5184 OPTIONS FOR FTP GATEWAYING 5185 ----------------------------------------------------------------------------- 5186COMMENT_END 5187 5188NAME: ftp_user 5189TYPE: string 5190DEFAULT: Squid@ 5191LOC: Config.Ftp.anon_user 5192DOC_START 5193 If you want the anonymous login password to be more informative 5194 (and enable the use of picky FTP servers), set this to something 5195 reasonable for your domain, like wwwuser@somewhere.net 5196 5197 The reason why this is domainless by default is the 5198 request can be made on the behalf of a user in any domain, 5199 depending on how the cache is used. 5200 Some FTP server also validate the email address is valid 5201 (for example perl.com). 5202DOC_END 5203 5204NAME: ftp_passive 5205TYPE: onoff 5206DEFAULT: on 5207LOC: Config.Ftp.passive 5208DOC_START 5209 If your firewall does not allow Squid to use passive 5210 connections, turn off this option. 5211 5212 Use of ftp_epsv_all option requires this to be ON. 5213DOC_END 5214 5215NAME: ftp_epsv_all 5216TYPE: onoff 5217DEFAULT: off 5218LOC: Config.Ftp.epsv_all 5219DOC_START 5220 FTP Protocol extensions permit the use of a special "EPSV ALL" command. 5221 5222 NATs may be able to put the connection on a "fast path" through the 5223 translator, as the EPRT command will never be used and therefore, 5224 translation of the data portion of the segments will never be needed. 5225 5226 When a client only expects to do two-way FTP transfers this may be 5227 useful. 5228 If squid finds that it must do a three-way FTP transfer after issuing 5229 an EPSV ALL command, the FTP session will fail. 5230 5231 If you have any doubts about this option do not use it. 5232 Squid will nicely attempt all other connection methods. 5233 5234 Requires ftp_passive to be ON (default) for any effect. 5235DOC_END 5236 5237NAME: ftp_epsv 5238TYPE: ftp_epsv 5239DEFAULT: none 5240LOC: Config.accessList.ftp_epsv 5241DOC_START 5242 FTP Protocol extensions permit the use of a special "EPSV" command. 5243 5244 NATs may be able to put the connection on a "fast path" through the 5245 translator using EPSV, as the EPRT command will never be used 5246 and therefore, translation of the data portion of the segments 5247 will never be needed. 5248 5249 EPSV is often required to interoperate with FTP servers on IPv6 5250 networks. On the other hand, it may break some IPv4 servers. 5251 5252 By default, EPSV may try EPSV with any FTP server. To fine tune 5253 that decision, you may restrict EPSV to certain clients or servers 5254 using ACLs: 5255 5256 ftp_epsv allow|deny al1 acl2 ... 5257 5258 WARNING: Disabling EPSV may cause problems with external NAT and IPv6. 5259 5260 Only fast ACLs are supported. 5261 Requires ftp_passive to be ON (default) for any effect. 5262DOC_END 5263 5264NAME: ftp_eprt 5265TYPE: onoff 5266DEFAULT: on 5267LOC: Config.Ftp.eprt 5268DOC_START 5269 FTP Protocol extensions permit the use of a special "EPRT" command. 5270 5271 This extension provides a protocol neutral alternative to the 5272 IPv4-only PORT command. When supported it enables active FTP data 5273 channels over IPv6 and efficient NAT handling. 5274 5275 Turning this OFF will prevent EPRT being attempted and will skip 5276 straight to using PORT for IPv4 servers. 5277 5278 Some devices are known to not handle this extension correctly and 5279 may result in crashes. Devices which suport EPRT enough to fail 5280 cleanly will result in Squid attempting PORT anyway. This directive 5281 should only be disabled when EPRT results in device failures. 5282 5283 WARNING: Doing so will convert Squid back to the old behavior with all 5284 the related problems with external NAT devices/layers and IPv4-only FTP. 5285DOC_END 5286 5287NAME: ftp_sanitycheck 5288TYPE: onoff 5289DEFAULT: on 5290LOC: Config.Ftp.sanitycheck 5291DOC_START 5292 For security and data integrity reasons Squid by default performs 5293 sanity checks of the addresses of FTP data connections ensure the 5294 data connection is to the requested server. If you need to allow 5295 FTP connections to servers using another IP address for the data 5296 connection turn this off. 5297DOC_END 5298 5299NAME: ftp_telnet_protocol 5300TYPE: onoff 5301DEFAULT: on 5302LOC: Config.Ftp.telnet 5303DOC_START 5304 The FTP protocol is officially defined to use the telnet protocol 5305 as transport channel for the control connection. However, many 5306 implementations are broken and does not respect this aspect of 5307 the FTP protocol. 5308 5309 If you have trouble accessing files with ASCII code 255 in the 5310 path or similar problems involving this ASCII code you can 5311 try setting this directive to off. If that helps, report to the 5312 operator of the FTP server in question that their FTP server 5313 is broken and does not follow the FTP standard. 5314DOC_END 5315 5316COMMENT_START 5317 OPTIONS FOR EXTERNAL SUPPORT PROGRAMS 5318 ----------------------------------------------------------------------------- 5319COMMENT_END 5320 5321NAME: diskd_program 5322TYPE: string 5323DEFAULT: @DEFAULT_DISKD@ 5324LOC: Config.Program.diskd 5325DOC_START 5326 Specify the location of the diskd executable. 5327 Note this is only useful if you have compiled in 5328 diskd as one of the store io modules. 5329DOC_END 5330 5331NAME: unlinkd_program 5332IFDEF: USE_UNLINKD 5333TYPE: string 5334DEFAULT: @DEFAULT_UNLINKD@ 5335LOC: Config.Program.unlinkd 5336DOC_START 5337 Specify the location of the executable for file deletion process. 5338DOC_END 5339 5340NAME: pinger_program 5341IFDEF: USE_ICMP 5342TYPE: icmp 5343DEFAULT: @DEFAULT_PINGER@ 5344LOC: IcmpCfg 5345DOC_START 5346 Specify the location of the executable for the pinger process. 5347DOC_END 5348 5349NAME: pinger_enable 5350TYPE: onoff 5351DEFAULT: on 5352LOC: IcmpCfg.enable 5353IFDEF: USE_ICMP 5354DOC_START 5355 Control whether the pinger is active at run-time. 5356 Enables turning ICMP pinger on and off with a simple 5357 squid -k reconfigure. 5358DOC_END 5359 5360 5361COMMENT_START 5362 OPTIONS FOR URL REWRITING 5363 ----------------------------------------------------------------------------- 5364COMMENT_END 5365 5366NAME: url_rewrite_program redirect_program 5367TYPE: wordlist 5368LOC: Config.Program.redirect 5369DEFAULT: none 5370DOC_START 5371 The name and command line parameters of an admin-provided executable 5372 for redirecting clients or adjusting/replacing client request URLs. 5373 5374 This helper is consulted after the received request is cleared by 5375 http_access and adapted using eICAP/ICAP services (if any). If the 5376 helper does not redirect the client, Squid checks adapted_http_access 5377 and may consult the cache or forward the request to the next hop. 5378 5379 5380 For each request, the helper gets one line in the following format: 5381 5382 [channel-ID <SP>] request-URL [<SP> extras] <NL> 5383 5384 Use url_rewrite_extras to configure what Squid sends as 'extras'. 5385 5386 5387 The helper must reply to each query using a single line: 5388 5389 [channel-ID <SP>] result [<SP> kv-pairs] <NL> 5390 5391 The result section must match exactly one of the following outcomes: 5392 5393 OK [status=30N] url="..." 5394 5395 Redirect the client to a URL supplied in the 'url' parameter. 5396 Optional 'status' specifies the status code to send to the 5397 client in Squid's HTTP redirect response. It must be one of 5398 the standard HTTP redirect status codes: 301, 302, 303, 307, 5399 or 308. When no specific status is requested, Squid uses 302. 5400 5401 OK rewrite-url="..." 5402 5403 Replace the current request URL with the one supplied in the 5404 'rewrite-url' parameter. Squid fetches the resource specified 5405 by the new URL and forwards the received response (or its 5406 cached copy) to the client. 5407 5408 WARNING: Avoid rewriting URLs! When possible, redirect the 5409 client using an "OK url=..." helper response instead. 5410 Rewriting URLs may create inconsistent requests and/or break 5411 synchronization between internal client and origin server 5412 states, especially when URLs or other message parts contain 5413 snippets of that state. For example, Squid does not adjust 5414 Location headers and embedded URLs after the helper rewrites 5415 the request URL. 5416 5417 OK 5418 Keep the client request intact. 5419 5420 ERR 5421 Keep the client request intact. 5422 5423 BH [message="..."] 5424 A helper problem that should be reported to the Squid admin 5425 via a level-1 cache.log message. The 'message' parameter is 5426 reserved for specifying the log message. 5427 5428 In addition to the kv-pairs mentioned above, Squid also understands 5429 the following optional kv-pairs in URL rewriter responses: 5430 5431 clt_conn_tag=TAG 5432 Associates a TAG with the client TCP connection. 5433 5434 The clt_conn_tag=TAG pair is treated as a regular transaction 5435 annotation for the current request and also annotates future 5436 requests on the same client connection. A helper may update 5437 the TAG during subsequent requests by returning a new kv-pair. 5438 5439 5440 Helper messages contain the channel-ID part if and only if the 5441 url_rewrite_children directive specifies positive concurrency. As a 5442 channel-ID value, Squid sends a number between 0 and concurrency-1. 5443 The helper must echo back the received channel-ID in its response. 5444 5445 By default, Squid does not use a URL rewriter. 5446DOC_END 5447 5448NAME: url_rewrite_children redirect_children 5449TYPE: HelperChildConfig 5450DEFAULT: 20 startup=0 idle=1 concurrency=0 5451LOC: Config.redirectChildren 5452DOC_START 5453 Specifies the maximum number of redirector processes that Squid may 5454 spawn (numberofchildren) and several related options. Using too few of 5455 these helper processes (a.k.a. "helpers") creates request queues. 5456 Using too many helpers wastes your system resources. 5457 5458 Usage: numberofchildren [option]... 5459 5460 The startup= and idle= options allow some measure of skew in your 5461 tuning. 5462 5463 startup= 5464 5465 Sets a minimum of how many processes are to be spawned when Squid 5466 starts or reconfigures. When set to zero the first request will 5467 cause spawning of the first child process to handle it. 5468 5469 Starting too few will cause an initial slowdown in traffic as Squid 5470 attempts to simultaneously spawn enough processes to cope. 5471 5472 idle= 5473 5474 Sets a minimum of how many processes Squid is to try and keep available 5475 at all times. When traffic begins to rise above what the existing 5476 processes can handle this many more will be spawned up to the maximum 5477 configured. A minimum setting of 1 is required. 5478 5479 concurrency= 5480 5481 The number of requests each redirector helper can handle in 5482 parallel. Defaults to 0 which indicates the redirector 5483 is a old-style single threaded redirector. 5484 5485 When this directive is set to a value >= 1 then the protocol 5486 used to communicate with the helper is modified to include 5487 an ID in front of the request/response. The ID from the request 5488 must be echoed back with the response to that request. 5489 5490 queue-size=N 5491 5492 Sets the maximum number of queued requests. A request is queued when 5493 no existing child can accept it due to concurrency limit and no new 5494 child can be started due to numberofchildren limit. The default 5495 maximum is zero if url_rewrite_bypass is enabled and 5496 2*numberofchildren otherwise. If the queued requests exceed queue size 5497 and redirector_bypass configuration option is set, then redirector is 5498 bypassed. Otherwise, Squid is allowed to temporarily exceed the 5499 configured maximum, marking the affected helper as "overloaded". If 5500 the helper overload lasts more than 3 minutes, the action prescribed 5501 by the on-persistent-overload option applies. 5502 5503 on-persistent-overload=action 5504 5505 Specifies Squid reaction to a new helper request arriving when the helper 5506 has been overloaded for more that 3 minutes already. The number of queued 5507 requests determines whether the helper is overloaded (see the queue-size 5508 option). 5509 5510 Two actions are supported: 5511 5512 die Squid worker quits. This is the default behavior. 5513 5514 ERR Squid treats the helper request as if it was 5515 immediately submitted, and the helper immediately 5516 replied with an ERR response. This action has no effect 5517 on the already queued and in-progress helper requests. 5518DOC_END 5519 5520NAME: url_rewrite_host_header redirect_rewrites_host_header 5521TYPE: onoff 5522DEFAULT: on 5523LOC: Config.onoff.redir_rewrites_host 5524DOC_START 5525 To preserve same-origin security policies in browsers and 5526 prevent Host: header forgery by redirectors Squid rewrites 5527 any Host: header in redirected requests. 5528 5529 If you are running an accelerator this may not be a wanted 5530 effect of a redirector. This directive enables you disable 5531 Host: alteration in reverse-proxy traffic. 5532 5533 WARNING: Entries are cached on the result of the URL rewriting 5534 process, so be careful if you have domain-virtual hosts. 5535 5536 WARNING: Squid and other software verifies the URL and Host 5537 are matching, so be careful not to relay through other proxies 5538 or inspecting firewalls with this disabled. 5539DOC_END 5540 5541NAME: url_rewrite_access redirector_access 5542TYPE: acl_access 5543DEFAULT: none 5544DEFAULT_DOC: Allow, unless rules exist in squid.conf. 5545LOC: Config.accessList.redirector 5546DOC_START 5547 If defined, this access list specifies which requests are 5548 sent to the redirector processes. 5549 5550 This clause supports both fast and slow acl types. 5551 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 5552DOC_END 5553 5554NAME: url_rewrite_bypass redirector_bypass 5555TYPE: onoff 5556LOC: Config.onoff.redirector_bypass 5557DEFAULT: off 5558DOC_START 5559 When this is 'on', a request will not go through the 5560 redirector if all the helpers are busy. If this is 'off' and the 5561 redirector queue grows too large, the action is prescribed by the 5562 on-persistent-overload option. You should only enable this if the 5563 redirectors are not critical to your caching system. If you use 5564 redirectors for access control, and you enable this option, 5565 users may have access to pages they should not 5566 be allowed to request. 5567 5568 Enabling this option sets the default url_rewrite_children queue-size 5569 option value to 0. 5570DOC_END 5571 5572NAME: url_rewrite_extras 5573TYPE: TokenOrQuotedString 5574LOC: Config.redirector_extras 5575DEFAULT: "%>a/%>A %un %>rm myip=%la myport=%lp" 5576DOC_START 5577 Specifies a string to be append to request line format for the 5578 rewriter helper. "Quoted" format values may contain spaces and 5579 logformat %macros. In theory, any logformat %macro can be used. 5580 In practice, a %macro expands as a dash (-) if the helper request is 5581 sent before the required macro information is available to Squid. 5582DOC_END 5583 5584NAME: url_rewrite_timeout 5585TYPE: UrlHelperTimeout 5586LOC: Config.onUrlRewriteTimeout 5587DEFAULT: none 5588DEFAULT_DOC: Squid waits for the helper response forever 5589DOC_START 5590 Squid times active requests to redirector. The timeout value and Squid 5591 reaction to a timed out request are configurable using the following 5592 format: 5593 5594 url_rewrite_timeout timeout time-units on_timeout=<action> [response=<quoted-response>] 5595 5596 supported timeout actions: 5597 fail Squid return a ERR_GATEWAY_FAILURE error page 5598 5599 bypass Do not re-write the URL 5600 5601 retry Send the lookup to the helper again 5602 5603 use_configured_response 5604 Use the <quoted-response> as helper response 5605DOC_END 5606 5607COMMENT_START 5608 OPTIONS FOR STORE ID 5609 ----------------------------------------------------------------------------- 5610COMMENT_END 5611 5612NAME: store_id_program storeurl_rewrite_program 5613TYPE: wordlist 5614LOC: Config.Program.store_id 5615DEFAULT: none 5616DOC_START 5617 Specify the location of the executable StoreID helper to use. 5618 Since they can perform almost any function there isn't one included. 5619 5620 For each requested URL, the helper will receive one line with the format 5621 5622 [channel-ID <SP>] URL [<SP> extras]<NL> 5623 5624 5625 After processing the request the helper must reply using the following format: 5626 5627 [channel-ID <SP>] result [<SP> kv-pairs] 5628 5629 The result code can be: 5630 5631 OK store-id="..." 5632 Use the StoreID supplied in 'store-id='. 5633 5634 ERR 5635 The default is to use HTTP request URL as the store ID. 5636 5637 BH 5638 An internal error occurred in the helper, preventing 5639 a result being identified. 5640 5641 In addition to the above kv-pairs Squid also understands the following 5642 optional kv-pairs received from URL rewriters: 5643 clt_conn_tag=TAG 5644 Associates a TAG with the client TCP connection. 5645 Please see url_rewrite_program related documentation for this 5646 kv-pair 5647 5648 Helper programs should be prepared to receive and possibly ignore 5649 additional whitespace-separated tokens on each input line. 5650 5651 When using the concurrency= option the protocol is changed by 5652 introducing a query channel tag in front of the request/response. 5653 The query channel tag is a number between 0 and concurrency-1. 5654 This value must be echoed back unchanged to Squid as the first part 5655 of the response relating to its request. 5656 5657 NOTE: when using StoreID refresh_pattern will apply to the StoreID 5658 returned from the helper and not the URL. 5659 5660 WARNING: Wrong StoreID value returned by a careless helper may result 5661 in the wrong cached response returned to the user. 5662 5663 By default, a StoreID helper is not used. 5664DOC_END 5665 5666NAME: store_id_extras 5667TYPE: TokenOrQuotedString 5668LOC: Config.storeId_extras 5669DEFAULT: "%>a/%>A %un %>rm myip=%la myport=%lp" 5670DOC_START 5671 Specifies a string to be append to request line format for the 5672 StoreId helper. "Quoted" format values may contain spaces and 5673 logformat %macros. In theory, any logformat %macro can be used. 5674 In practice, a %macro expands as a dash (-) if the helper request is 5675 sent before the required macro information is available to Squid. 5676DOC_END 5677 5678NAME: store_id_children storeurl_rewrite_children 5679TYPE: HelperChildConfig 5680DEFAULT: 20 startup=0 idle=1 concurrency=0 5681LOC: Config.storeIdChildren 5682DOC_START 5683 Specifies the maximum number of StoreID helper processes that Squid 5684 may spawn (numberofchildren) and several related options. Using 5685 too few of these helper processes (a.k.a. "helpers") creates request 5686 queues. Using too many helpers wastes your system resources. 5687 5688 Usage: numberofchildren [option]... 5689 5690 The startup= and idle= options allow some measure of skew in your 5691 tuning. 5692 5693 startup= 5694 5695 Sets a minimum of how many processes are to be spawned when Squid 5696 starts or reconfigures. When set to zero the first request will 5697 cause spawning of the first child process to handle it. 5698 5699 Starting too few will cause an initial slowdown in traffic as Squid 5700 attempts to simultaneously spawn enough processes to cope. 5701 5702 idle= 5703 5704 Sets a minimum of how many processes Squid is to try and keep available 5705 at all times. When traffic begins to rise above what the existing 5706 processes can handle this many more will be spawned up to the maximum 5707 configured. A minimum setting of 1 is required. 5708 5709 concurrency= 5710 5711 The number of requests each storeID helper can handle in 5712 parallel. Defaults to 0 which indicates the helper 5713 is a old-style single threaded program. 5714 5715 When this directive is set to a value >= 1 then the protocol 5716 used to communicate with the helper is modified to include 5717 an ID in front of the request/response. The ID from the request 5718 must be echoed back with the response to that request. 5719 5720 queue-size=N 5721 5722 Sets the maximum number of queued requests to N. A request is queued 5723 when no existing child can accept it due to concurrency limit and no 5724 new child can be started due to numberofchildren limit. The default 5725 maximum is 2*numberofchildren. If the queued requests exceed queue 5726 size and redirector_bypass configuration option is set, then 5727 redirector is bypassed. Otherwise, Squid is allowed to temporarily 5728 exceed the configured maximum, marking the affected helper as 5729 "overloaded". If the helper overload lasts more than 3 minutes, the 5730 action prescribed by the on-persistent-overload option applies. 5731 5732 on-persistent-overload=action 5733 5734 Specifies Squid reaction to a new helper request arriving when the helper 5735 has been overloaded for more that 3 minutes already. The number of queued 5736 requests determines whether the helper is overloaded (see the queue-size 5737 option). 5738 5739 Two actions are supported: 5740 5741 die Squid worker quits. This is the default behavior. 5742 5743 ERR Squid treats the helper request as if it was 5744 immediately submitted, and the helper immediately 5745 replied with an ERR response. This action has no effect 5746 on the already queued and in-progress helper requests. 5747DOC_END 5748 5749NAME: store_id_access storeurl_rewrite_access 5750TYPE: acl_access 5751DEFAULT: none 5752DEFAULT_DOC: Allow, unless rules exist in squid.conf. 5753LOC: Config.accessList.store_id 5754DOC_START 5755 If defined, this access list specifies which requests are 5756 sent to the StoreID processes. By default all requests 5757 are sent. 5758 5759 This clause supports both fast and slow acl types. 5760 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 5761DOC_END 5762 5763NAME: store_id_bypass storeurl_rewrite_bypass 5764TYPE: onoff 5765LOC: Config.onoff.store_id_bypass 5766DEFAULT: on 5767DOC_START 5768 When this is 'on', a request will not go through the 5769 helper if all helpers are busy. If this is 'off' and the helper 5770 queue grows too large, the action is prescribed by the 5771 on-persistent-overload option. You should only enable this if the 5772 helpers are not critical to your caching system. If you use 5773 helpers for critical caching components, and you enable this 5774 option, users may not get objects from cache. 5775 This options sets default queue-size option of the store_id_children 5776 to 0. 5777DOC_END 5778 5779COMMENT_START 5780 OPTIONS FOR TUNING THE CACHE 5781 ----------------------------------------------------------------------------- 5782COMMENT_END 5783 5784NAME: cache no_cache 5785TYPE: acl_access 5786DEFAULT: none 5787DEFAULT_DOC: By default, this directive is unused and has no effect. 5788LOC: Config.accessList.noCache 5789DOC_START 5790 Requests denied by this directive will not be served from the cache 5791 and their responses will not be stored in the cache. This directive 5792 has no effect on other transactions and on already cached responses. 5793 5794 This clause supports both fast and slow acl types. 5795 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 5796 5797 This and the two other similar caching directives listed below are 5798 checked at different transaction processing stages, have different 5799 access to response information, affect different cache operations, 5800 and differ in slow ACLs support: 5801 5802 * cache: Checked before Squid makes a hit/miss determination. 5803 No access to reply information! 5804 Denies both serving a hit and storing a miss. 5805 Supports both fast and slow ACLs. 5806 * send_hit: Checked after a hit was detected. 5807 Has access to reply (hit) information. 5808 Denies serving a hit only. 5809 Supports fast ACLs only. 5810 * store_miss: Checked before storing a cachable miss. 5811 Has access to reply (miss) information. 5812 Denies storing a miss only. 5813 Supports fast ACLs only. 5814 5815 If you are not sure which of the three directives to use, apply the 5816 following decision logic: 5817 5818 * If your ACL(s) are of slow type _and_ need response info, redesign. 5819 Squid does not support that particular combination at this time. 5820 Otherwise: 5821 * If your directive ACL(s) are of slow type, use "cache"; and/or 5822 * if your directive ACL(s) need no response info, use "cache". 5823 Otherwise: 5824 * If you do not want the response cached, use store_miss; and/or 5825 * if you do not want a hit on a cached response, use send_hit. 5826DOC_END 5827 5828NAME: send_hit 5829TYPE: acl_access 5830DEFAULT: none 5831DEFAULT_DOC: By default, this directive is unused and has no effect. 5832LOC: Config.accessList.sendHit 5833DOC_START 5834 Responses denied by this directive will not be served from the cache 5835 (but may still be cached, see store_miss). This directive has no 5836 effect on the responses it allows and on the cached objects. 5837 5838 Please see the "cache" directive for a summary of differences among 5839 store_miss, send_hit, and cache directives. 5840 5841 Unlike the "cache" directive, send_hit only supports fast acl 5842 types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 5843 5844 For example: 5845 5846 # apply custom Store ID mapping to some URLs 5847 acl MapMe dstdomain .c.example.com 5848 store_id_program ... 5849 store_id_access allow MapMe 5850 5851 # but prevent caching of special responses 5852 # such as 302 redirects that cause StoreID loops 5853 acl Ordinary http_status 200-299 5854 store_miss deny MapMe !Ordinary 5855 5856 # and do not serve any previously stored special responses 5857 # from the cache (in case they were already cached before 5858 # the above store_miss rule was in effect). 5859 send_hit deny MapMe !Ordinary 5860DOC_END 5861 5862NAME: store_miss 5863TYPE: acl_access 5864DEFAULT: none 5865DEFAULT_DOC: By default, this directive is unused and has no effect. 5866LOC: Config.accessList.storeMiss 5867DOC_START 5868 Responses denied by this directive will not be cached (but may still 5869 be served from the cache, see send_hit). This directive has no 5870 effect on the responses it allows and on the already cached responses. 5871 5872 Please see the "cache" directive for a summary of differences among 5873 store_miss, send_hit, and cache directives. See the 5874 send_hit directive for a usage example. 5875 5876 Unlike the "cache" directive, store_miss only supports fast acl 5877 types. See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 5878DOC_END 5879 5880NAME: max_stale 5881COMMENT: time-units 5882TYPE: time_t 5883LOC: Config.maxStale 5884DEFAULT: 1 week 5885DOC_START 5886 This option puts an upper limit on how stale content Squid 5887 will serve from the cache if cache validation fails. 5888 Can be overriden by the refresh_pattern max-stale option. 5889DOC_END 5890 5891NAME: refresh_pattern 5892TYPE: refreshpattern 5893LOC: Config.Refresh 5894DEFAULT: none 5895DOC_START 5896 usage: refresh_pattern [-i] regex min percent max [options] 5897 5898 By default, regular expressions are CASE-SENSITIVE. To make 5899 them case-insensitive, use the -i option. 5900 5901 'Min' is the time (in minutes) an object without an explicit 5902 expiry time should be considered fresh. The recommended 5903 value is 0, any higher values may cause dynamic applications 5904 to be erroneously cached unless the application designer 5905 has taken the appropriate actions. 5906 5907 'Percent' is a percentage of the objects age (time since last 5908 modification age) an object without explicit expiry time 5909 will be considered fresh. 5910 5911 'Max' is an upper limit on how long objects without an explicit 5912 expiry time will be considered fresh. The value is also used 5913 to form Cache-Control: max-age header for a request sent from 5914 Squid to origin/parent. 5915 5916 options: override-expire 5917 override-lastmod 5918 reload-into-ims 5919 ignore-reload 5920 ignore-no-store 5921 ignore-private 5922 max-stale=NN 5923 refresh-ims 5924 store-stale 5925 5926 override-expire enforces min age even if the server 5927 sent an explicit expiry time (e.g., with the 5928 Expires: header or Cache-Control: max-age). Doing this 5929 VIOLATES the HTTP standard. Enabling this feature 5930 could make you liable for problems which it causes. 5931 5932 Note: override-expire does not enforce staleness - it only extends 5933 freshness / min. If the server returns a Expires time which 5934 is longer than your max time, Squid will still consider 5935 the object fresh for that period of time. 5936 5937 override-lastmod enforces min age even on objects 5938 that were modified recently. 5939 5940 reload-into-ims changes a client no-cache or ``reload'' 5941 request for a cached entry into a conditional request using 5942 If-Modified-Since and/or If-None-Match headers, provided the 5943 cached entry has a Last-Modified and/or a strong ETag header. 5944 Doing this VIOLATES the HTTP standard. Enabling this feature 5945 could make you liable for problems which it causes. 5946 5947 ignore-reload ignores a client no-cache or ``reload'' 5948 header. Doing this VIOLATES the HTTP standard. Enabling 5949 this feature could make you liable for problems which 5950 it causes. 5951 5952 ignore-no-store ignores any ``Cache-control: no-store'' 5953 headers received from a server. Doing this VIOLATES 5954 the HTTP standard. Enabling this feature could make you 5955 liable for problems which it causes. 5956 5957 ignore-private ignores any ``Cache-control: private'' 5958 headers received from a server. Doing this VIOLATES 5959 the HTTP standard. Enabling this feature could make you 5960 liable for problems which it causes. 5961 5962 refresh-ims causes squid to contact the origin server 5963 when a client issues an If-Modified-Since request. This 5964 ensures that the client will receive an updated version 5965 if one is available. 5966 5967 store-stale stores responses even if they don't have explicit 5968 freshness or a validator (i.e., Last-Modified or an ETag) 5969 present, or if they're already stale. By default, Squid will 5970 not cache such responses because they usually can't be 5971 reused. Note that such responses will be stale by default. 5972 5973 max-stale=NN provide a maximum staleness factor. Squid won't 5974 serve objects more stale than this even if it failed to 5975 validate the object. Default: use the max_stale global limit. 5976 5977 Basically a cached object is: 5978 5979 FRESH if expire > now, else STALE 5980 STALE if age > max 5981 FRESH if lm-factor < percent, else STALE 5982 FRESH if age < min 5983 else STALE 5984 5985 The refresh_pattern lines are checked in the order listed here. 5986 The first entry which matches is used. If none of the entries 5987 match the default will be used. 5988 5989 Note, you must uncomment all the default lines if you want 5990 to change one. The default setting is only active if none is 5991 used. 5992 5993NOCOMMENT_START 5994 5995# 5996# Add any of your own refresh_pattern entries above these. 5997# 5998refresh_pattern ^ftp: 1440 20% 10080 5999refresh_pattern ^gopher: 1440 0% 1440 6000refresh_pattern -i (/cgi-bin/|\?) 0 0% 0 6001refresh_pattern . 0 20% 4320 6002NOCOMMENT_END 6003DOC_END 6004 6005NAME: quick_abort_min 6006COMMENT: (KB) 6007TYPE: kb_int64_t 6008DEFAULT: 16 KB 6009LOC: Config.quickAbort.min 6010DOC_NONE 6011 6012NAME: quick_abort_max 6013COMMENT: (KB) 6014TYPE: kb_int64_t 6015DEFAULT: 16 KB 6016LOC: Config.quickAbort.max 6017DOC_NONE 6018 6019NAME: quick_abort_pct 6020COMMENT: (percent) 6021TYPE: int 6022DEFAULT: 95 6023LOC: Config.quickAbort.pct 6024DOC_START 6025 The cache by default continues downloading aborted requests 6026 which are almost completed (less than 16 KB remaining). This 6027 may be undesirable on slow (e.g. SLIP) links and/or very busy 6028 caches. Impatient users may tie up file descriptors and 6029 bandwidth by repeatedly requesting and immediately aborting 6030 downloads. 6031 6032 When the user aborts a request, Squid will check the 6033 quick_abort values to the amount of data transferred until 6034 then. 6035 6036 If the transfer has less than 'quick_abort_min' KB remaining, 6037 it will finish the retrieval. 6038 6039 If the transfer has more than 'quick_abort_max' KB remaining, 6040 it will abort the retrieval. 6041 6042 If more than 'quick_abort_pct' of the transfer has completed, 6043 it will finish the retrieval. 6044 6045 If you do not want any retrieval to continue after the client 6046 has aborted, set both 'quick_abort_min' and 'quick_abort_max' 6047 to '0 KB'. 6048 6049 If you want retrievals to always continue if they are being 6050 cached set 'quick_abort_min' to '-1 KB'. 6051DOC_END 6052 6053NAME: read_ahead_gap 6054COMMENT: buffer-size 6055TYPE: b_int64_t 6056LOC: Config.readAheadGap 6057DEFAULT: 16 KB 6058DOC_START 6059 The amount of data the cache will buffer ahead of what has been 6060 sent to the client when retrieving an object from another server. 6061DOC_END 6062 6063NAME: negative_ttl 6064IFDEF: USE_HTTP_VIOLATIONS 6065COMMENT: time-units 6066TYPE: time_t 6067LOC: Config.negativeTtl 6068DEFAULT: 0 seconds 6069DOC_START 6070 Set the Default Time-to-Live (TTL) for failed requests. 6071 Certain types of failures (such as "connection refused" and 6072 "404 Not Found") are able to be negatively-cached for a short time. 6073 Modern web servers should provide Expires: header, however if they 6074 do not this can provide a minimum TTL. 6075 The default is not to cache errors with unknown expiry details. 6076 6077 Note that this is different from negative caching of DNS lookups. 6078 6079 WARNING: Doing this VIOLATES the HTTP standard. Enabling 6080 this feature could make you liable for problems which it 6081 causes. 6082DOC_END 6083 6084NAME: positive_dns_ttl 6085COMMENT: time-units 6086TYPE: time_t 6087LOC: Config.positiveDnsTtl 6088DEFAULT: 6 hours 6089DOC_START 6090 Upper limit on how long Squid will cache positive DNS responses. 6091 Default is 6 hours (360 minutes). This directive must be set 6092 larger than negative_dns_ttl. 6093DOC_END 6094 6095NAME: negative_dns_ttl 6096COMMENT: time-units 6097TYPE: time_t 6098LOC: Config.negativeDnsTtl 6099DEFAULT: 1 minutes 6100DOC_START 6101 Time-to-Live (TTL) for negative caching of failed DNS lookups. 6102 This also sets the lower cache limit on positive lookups. 6103 Minimum value is 1 second, and it is not recommendable to go 6104 much below 10 seconds. 6105DOC_END 6106 6107NAME: range_offset_limit 6108COMMENT: size [acl acl...] 6109TYPE: acl_b_size_t 6110LOC: Config.rangeOffsetLimit 6111DEFAULT: none 6112DOC_START 6113 usage: (size) [units] [[!]aclname] 6114 6115 Sets an upper limit on how far (number of bytes) into the file 6116 a Range request may be to cause Squid to prefetch the whole file. 6117 If beyond this limit, Squid forwards the Range request as it is and 6118 the result is NOT cached. 6119 6120 This is to stop a far ahead range request (lets say start at 17MB) 6121 from making Squid fetch the whole object up to that point before 6122 sending anything to the client. 6123 6124 Multiple range_offset_limit lines may be specified, and they will 6125 be searched from top to bottom on each request until a match is found. 6126 The first match found will be used. If no line matches a request, the 6127 default limit of 0 bytes will be used. 6128 6129 'size' is the limit specified as a number of units. 6130 6131 'units' specifies whether to use bytes, KB, MB, etc. 6132 If no units are specified bytes are assumed. 6133 6134 A size of 0 causes Squid to never fetch more than the 6135 client requested. (default) 6136 6137 A size of 'none' causes Squid to always fetch the object from the 6138 beginning so it may cache the result. (2.0 style) 6139 6140 'aclname' is the name of a defined ACL. 6141 6142 NP: Using 'none' as the byte value here will override any quick_abort settings 6143 that may otherwise apply to the range request. The range request will 6144 be fully fetched from start to finish regardless of the client 6145 actions. This affects bandwidth usage. 6146DOC_END 6147 6148NAME: minimum_expiry_time 6149COMMENT: (seconds) 6150TYPE: time_t 6151LOC: Config.minimum_expiry_time 6152DEFAULT: 60 seconds 6153DOC_START 6154 The minimum caching time according to (Expires - Date) 6155 headers Squid honors if the object can't be revalidated. 6156 The default is 60 seconds. 6157 6158 In reverse proxy environments it might be desirable to honor 6159 shorter object lifetimes. It is most likely better to make 6160 your server return a meaningful Last-Modified header however. 6161 6162 In ESI environments where page fragments often have short 6163 lifetimes, this will often be best set to 0. 6164DOC_END 6165 6166NAME: store_avg_object_size 6167COMMENT: (bytes) 6168TYPE: b_int64_t 6169DEFAULT: 13 KB 6170LOC: Config.Store.avgObjectSize 6171DOC_START 6172 Average object size, used to estimate number of objects your 6173 cache can hold. The default is 13 KB. 6174 6175 This is used to pre-seed the cache index memory allocation to 6176 reduce expensive reallocate operations while handling clients 6177 traffic. Too-large values may result in memory allocation during 6178 peak traffic, too-small values will result in wasted memory. 6179 6180 Check the cache manager 'info' report metrics for the real 6181 object sizes seen by your Squid before tuning this. 6182DOC_END 6183 6184NAME: store_objects_per_bucket 6185TYPE: int 6186DEFAULT: 20 6187LOC: Config.Store.objectsPerBucket 6188DOC_START 6189 Target number of objects per bucket in the store hash table. 6190 Lowering this value increases the total number of buckets and 6191 also the storage maintenance rate. The default is 20. 6192DOC_END 6193 6194COMMENT_START 6195 HTTP OPTIONS 6196 ----------------------------------------------------------------------------- 6197COMMENT_END 6198 6199NAME: request_header_max_size 6200COMMENT: (KB) 6201TYPE: b_size_t 6202DEFAULT: 64 KB 6203LOC: Config.maxRequestHeaderSize 6204DOC_START 6205 This specifies the maximum size for HTTP headers in a request. 6206 Request headers are usually relatively small (about 512 bytes). 6207 Placing a limit on the request header size will catch certain 6208 bugs (for example with persistent connections) and possibly 6209 buffer-overflow or denial-of-service attacks. 6210DOC_END 6211 6212NAME: reply_header_max_size 6213COMMENT: (KB) 6214TYPE: b_size_t 6215DEFAULT: 64 KB 6216LOC: Config.maxReplyHeaderSize 6217DOC_START 6218 This specifies the maximum size for HTTP headers in a reply. 6219 Reply headers are usually relatively small (about 512 bytes). 6220 Placing a limit on the reply header size will catch certain 6221 bugs (for example with persistent connections) and possibly 6222 buffer-overflow or denial-of-service attacks. 6223DOC_END 6224 6225NAME: request_body_max_size 6226COMMENT: (bytes) 6227TYPE: b_int64_t 6228DEFAULT: 0 KB 6229DEFAULT_DOC: No limit. 6230LOC: Config.maxRequestBodySize 6231DOC_START 6232 This specifies the maximum size for an HTTP request body. 6233 In other words, the maximum size of a PUT/POST request. 6234 A user who attempts to send a request with a body larger 6235 than this limit receives an "Invalid Request" error message. 6236 If you set this parameter to a zero (the default), there will 6237 be no limit imposed. 6238 6239 See also client_request_buffer_max_size for an alternative 6240 limitation on client uploads which can be configured. 6241DOC_END 6242 6243NAME: client_request_buffer_max_size 6244COMMENT: (bytes) 6245TYPE: b_size_t 6246DEFAULT: 512 KB 6247LOC: Config.maxRequestBufferSize 6248DOC_START 6249 This specifies the maximum buffer size of a client request. 6250 It prevents squid eating too much memory when somebody uploads 6251 a large file. 6252DOC_END 6253 6254NAME: broken_posts 6255IFDEF: USE_HTTP_VIOLATIONS 6256TYPE: acl_access 6257DEFAULT: none 6258DEFAULT_DOC: Obey RFC 2616. 6259LOC: Config.accessList.brokenPosts 6260DOC_START 6261 A list of ACL elements which, if matched, causes Squid to send 6262 an extra CRLF pair after the body of a PUT/POST request. 6263 6264 Some HTTP servers has broken implementations of PUT/POST, 6265 and rely on an extra CRLF pair sent by some WWW clients. 6266 6267 Quote from RFC2616 section 4.1 on this matter: 6268 6269 Note: certain buggy HTTP/1.0 client implementations generate an 6270 extra CRLF's after a POST request. To restate what is explicitly 6271 forbidden by the BNF, an HTTP/1.1 client must not preface or follow 6272 a request with an extra CRLF. 6273 6274 This clause only supports fast acl types. 6275 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 6276 6277Example: 6278 acl buggy_server url_regex ^http://.... 6279 broken_posts allow buggy_server 6280DOC_END 6281 6282NAME: adaptation_uses_indirect_client icap_uses_indirect_client 6283COMMENT: on|off 6284TYPE: onoff 6285IFDEF: FOLLOW_X_FORWARDED_FOR&&USE_ADAPTATION 6286DEFAULT: on 6287LOC: Adaptation::Config::use_indirect_client 6288DOC_START 6289 Controls whether the indirect client IP address (instead of the direct 6290 client IP address) is passed to adaptation services. 6291 6292 See also: follow_x_forwarded_for adaptation_send_client_ip 6293DOC_END 6294 6295NAME: via 6296IFDEF: USE_HTTP_VIOLATIONS 6297COMMENT: on|off 6298TYPE: onoff 6299DEFAULT: on 6300LOC: Config.onoff.via 6301DOC_START 6302 If set (default), Squid will include a Via header in requests and 6303 replies as required by RFC2616. 6304DOC_END 6305 6306NAME: vary_ignore_expire 6307COMMENT: on|off 6308TYPE: onoff 6309LOC: Config.onoff.vary_ignore_expire 6310DEFAULT: off 6311DOC_START 6312 Many HTTP servers supporting Vary gives such objects 6313 immediate expiry time with no cache-control header 6314 when requested by a HTTP/1.0 client. This option 6315 enables Squid to ignore such expiry times until 6316 HTTP/1.1 is fully implemented. 6317 6318 WARNING: If turned on this may eventually cause some 6319 varying objects not intended for caching to get cached. 6320DOC_END 6321 6322NAME: request_entities 6323TYPE: onoff 6324LOC: Config.onoff.request_entities 6325DEFAULT: off 6326DOC_START 6327 Squid defaults to deny GET and HEAD requests with request entities, 6328 as the meaning of such requests are undefined in the HTTP standard 6329 even if not explicitly forbidden. 6330 6331 Set this directive to on if you have clients which insists 6332 on sending request entities in GET or HEAD requests. But be warned 6333 that there is server software (both proxies and web servers) which 6334 can fail to properly process this kind of request which may make you 6335 vulnerable to cache pollution attacks if enabled. 6336DOC_END 6337 6338NAME: request_header_access 6339IFDEF: USE_HTTP_VIOLATIONS 6340TYPE: http_header_access 6341LOC: Config.request_header_access 6342DEFAULT: none 6343DEFAULT_DOC: No limits. 6344DOC_START 6345 Usage: request_header_access header_name allow|deny [!]aclname ... 6346 6347 WARNING: Doing this VIOLATES the HTTP standard. Enabling 6348 this feature could make you liable for problems which it 6349 causes. 6350 6351 This option replaces the old 'anonymize_headers' and the 6352 older 'http_anonymizer' option with something that is much 6353 more configurable. A list of ACLs for each header name allows 6354 removal of specific header fields under specific conditions. 6355 6356 This option only applies to outgoing HTTP request headers (i.e., 6357 headers sent by Squid to the next HTTP hop such as a cache peer 6358 or an origin server). The option has no effect during cache hit 6359 detection. The equivalent adaptation vectoring point in ICAP 6360 terminology is post-cache REQMOD. 6361 6362 The option is applied to individual outgoing request header 6363 fields. For each request header field F, Squid uses the first 6364 qualifying sets of request_header_access rules: 6365 6366 1. Rules with header_name equal to F's name. 6367 2. Rules with header_name 'Other', provided F's name is not 6368 on the hard-coded list of commonly used HTTP header names. 6369 3. Rules with header_name 'All'. 6370 6371 Within that qualifying rule set, rule ACLs are checked as usual. 6372 If ACLs of an "allow" rule match, the header field is allowed to 6373 go through as is. If ACLs of a "deny" rule match, the header is 6374 removed and request_header_replace is then checked to identify 6375 if the removed header has a replacement. If no rules within the 6376 set have matching ACLs, the header field is left as is. 6377 6378 For example, to achieve the same behavior as the old 6379 'http_anonymizer standard' option, you should use: 6380 6381 request_header_access From deny all 6382 request_header_access Referer deny all 6383 request_header_access User-Agent deny all 6384 6385 Or, to reproduce the old 'http_anonymizer paranoid' feature 6386 you should use: 6387 6388 request_header_access Authorization allow all 6389 request_header_access Proxy-Authorization allow all 6390 request_header_access Cache-Control allow all 6391 request_header_access Content-Length allow all 6392 request_header_access Content-Type allow all 6393 request_header_access Date allow all 6394 request_header_access Host allow all 6395 request_header_access If-Modified-Since allow all 6396 request_header_access Pragma allow all 6397 request_header_access Accept allow all 6398 request_header_access Accept-Charset allow all 6399 request_header_access Accept-Encoding allow all 6400 request_header_access Accept-Language allow all 6401 request_header_access Connection allow all 6402 request_header_access All deny all 6403 6404 HTTP reply headers are controlled with the reply_header_access directive. 6405 6406 By default, all headers are allowed (no anonymizing is performed). 6407DOC_END 6408 6409NAME: reply_header_access 6410IFDEF: USE_HTTP_VIOLATIONS 6411TYPE: http_header_access 6412LOC: Config.reply_header_access 6413DEFAULT: none 6414DEFAULT_DOC: No limits. 6415DOC_START 6416 Usage: reply_header_access header_name allow|deny [!]aclname ... 6417 6418 WARNING: Doing this VIOLATES the HTTP standard. Enabling 6419 this feature could make you liable for problems which it 6420 causes. 6421 6422 This option only applies to reply headers, i.e., from the 6423 server to the client. 6424 6425 This is the same as request_header_access, but in the other 6426 direction. Please see request_header_access for detailed 6427 documentation. 6428 6429 For example, to achieve the same behavior as the old 6430 'http_anonymizer standard' option, you should use: 6431 6432 reply_header_access Server deny all 6433 reply_header_access WWW-Authenticate deny all 6434 reply_header_access Link deny all 6435 6436 Or, to reproduce the old 'http_anonymizer paranoid' feature 6437 you should use: 6438 6439 reply_header_access Allow allow all 6440 reply_header_access WWW-Authenticate allow all 6441 reply_header_access Proxy-Authenticate allow all 6442 reply_header_access Cache-Control allow all 6443 reply_header_access Content-Encoding allow all 6444 reply_header_access Content-Length allow all 6445 reply_header_access Content-Type allow all 6446 reply_header_access Date allow all 6447 reply_header_access Expires allow all 6448 reply_header_access Last-Modified allow all 6449 reply_header_access Location allow all 6450 reply_header_access Pragma allow all 6451 reply_header_access Content-Language allow all 6452 reply_header_access Retry-After allow all 6453 reply_header_access Title allow all 6454 reply_header_access Content-Disposition allow all 6455 reply_header_access Connection allow all 6456 reply_header_access All deny all 6457 6458 HTTP request headers are controlled with the request_header_access directive. 6459 6460 By default, all headers are allowed (no anonymizing is 6461 performed). 6462DOC_END 6463 6464NAME: request_header_replace header_replace 6465IFDEF: USE_HTTP_VIOLATIONS 6466TYPE: http_header_replace 6467LOC: Config.request_header_access 6468DEFAULT: none 6469DOC_START 6470 Usage: request_header_replace header_name message 6471 Example: request_header_replace User-Agent Nutscrape/1.0 (CP/M; 8-bit) 6472 6473 This option allows you to change the contents of headers 6474 denied with request_header_access above, by replacing them 6475 with some fixed string. 6476 6477 This only applies to request headers, not reply headers. 6478 6479 By default, headers are removed if denied. 6480DOC_END 6481 6482NAME: reply_header_replace 6483IFDEF: USE_HTTP_VIOLATIONS 6484TYPE: http_header_replace 6485LOC: Config.reply_header_access 6486DEFAULT: none 6487DOC_START 6488 Usage: reply_header_replace header_name message 6489 Example: reply_header_replace Server Foo/1.0 6490 6491 This option allows you to change the contents of headers 6492 denied with reply_header_access above, by replacing them 6493 with some fixed string. 6494 6495 This only applies to reply headers, not request headers. 6496 6497 By default, headers are removed if denied. 6498DOC_END 6499 6500NAME: request_header_add 6501TYPE: HeaderWithAclList 6502LOC: Config.request_header_add 6503DEFAULT: none 6504DOC_START 6505 Usage: request_header_add field-name field-value [ acl ... ] 6506 Example: request_header_add X-Client-CA "CA=%ssl::>cert_issuer" all 6507 6508 This option adds header fields to outgoing HTTP requests (i.e., 6509 request headers sent by Squid to the next HTTP hop such as a 6510 cache peer or an origin server). The option has no effect during 6511 cache hit detection. The equivalent adaptation vectoring point 6512 in ICAP terminology is post-cache REQMOD. 6513 6514 Field-name is a token specifying an HTTP header name. If a 6515 standard HTTP header name is used, Squid does not check whether 6516 the new header conflicts with any existing headers or violates 6517 HTTP rules. If the request to be modified already contains a 6518 field with the same name, the old field is preserved but the 6519 header field values are not merged. 6520 6521 Field-value is either a token or a quoted string. If quoted 6522 string format is used, then the surrounding quotes are removed 6523 while escape sequences and %macros are processed. 6524 6525 One or more Squid ACLs may be specified to restrict header 6526 injection to matching requests. As always in squid.conf, all 6527 ACLs in the ACL list must be satisfied for the insertion to 6528 happen. The request_header_add supports fast ACLs only. 6529 6530 See also: reply_header_add. 6531DOC_END 6532 6533NAME: reply_header_add 6534TYPE: HeaderWithAclList 6535LOC: Config.reply_header_add 6536DEFAULT: none 6537DOC_START 6538 Usage: reply_header_add field-name field-value [ acl ... ] 6539 Example: reply_header_add X-Client-CA "CA=%ssl::>cert_issuer" all 6540 6541 This option adds header fields to outgoing HTTP responses (i.e., response 6542 headers delivered by Squid to the client). This option has no effect on 6543 cache hit detection. The equivalent adaptation vectoring point in 6544 ICAP terminology is post-cache RESPMOD. This option does not apply to 6545 successful CONNECT replies. 6546 6547 Field-name is a token specifying an HTTP header name. If a 6548 standard HTTP header name is used, Squid does not check whether 6549 the new header conflicts with any existing headers or violates 6550 HTTP rules. If the response to be modified already contains a 6551 field with the same name, the old field is preserved but the 6552 header field values are not merged. 6553 6554 Field-value is either a token or a quoted string. If quoted 6555 string format is used, then the surrounding quotes are removed 6556 while escape sequences and %macros are processed. 6557 6558 One or more Squid ACLs may be specified to restrict header 6559 injection to matching responses. As always in squid.conf, all 6560 ACLs in the ACL list must be satisfied for the insertion to 6561 happen. The reply_header_add option supports fast ACLs only. 6562 6563 See also: request_header_add. 6564DOC_END 6565 6566NAME: note 6567TYPE: note 6568LOC: Config.notes 6569DEFAULT: none 6570DOC_START 6571 This option used to log custom information about the master 6572 transaction. For example, an admin may configure Squid to log 6573 which "user group" the transaction belongs to, where "user group" 6574 will be determined based on a set of ACLs and not [just] 6575 authentication information. 6576 Values of key/value pairs can be logged using %{key}note macros: 6577 6578 note key value acl ... 6579 logformat myFormat ... %{key}note ... 6580 6581 This clause only supports fast acl types. 6582 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 6583DOC_END 6584 6585NAME: relaxed_header_parser 6586COMMENT: on|off|warn 6587TYPE: tristate 6588LOC: Config.onoff.relaxed_header_parser 6589DEFAULT: on 6590DOC_START 6591 In the default "on" setting Squid accepts certain forms 6592 of non-compliant HTTP messages where it is unambiguous 6593 what the sending application intended even if the message 6594 is not correctly formatted. The messages is then normalized 6595 to the correct form when forwarded by Squid. 6596 6597 If set to "warn" then a warning will be emitted in cache.log 6598 each time such HTTP error is encountered. 6599 6600 If set to "off" then such HTTP errors will cause the request 6601 or response to be rejected. 6602DOC_END 6603 6604NAME: collapsed_forwarding 6605COMMENT: (on|off) 6606TYPE: onoff 6607LOC: Config.onoff.collapsed_forwarding 6608DEFAULT: off 6609DOC_START 6610 This option controls whether Squid is allowed to merge multiple 6611 potentially cachable requests for the same URI before Squid knows 6612 whether the response is going to be cachable. 6613 6614 When enabled, instead of forwarding each concurrent request for 6615 the same URL, Squid just sends the first of them. The other, so 6616 called "collapsed" requests, wait for the response to the first 6617 request and, if it happens to be cachable, use that response. 6618 Here, "concurrent requests" means "received after the first 6619 request headers were parsed and before the corresponding response 6620 headers were parsed". 6621 6622 This feature is disabled by default: enabling collapsed 6623 forwarding needlessly delays forwarding requests that look 6624 cachable (when they are collapsed) but then need to be forwarded 6625 individually anyway because they end up being for uncachable 6626 content. However, in some cases, such as acceleration of highly 6627 cachable content with periodic or grouped expiration times, the 6628 gains from collapsing [large volumes of simultaneous refresh 6629 requests] outweigh losses from such delays. 6630 6631 Squid collapses two kinds of requests: regular client requests 6632 received on one of the listening ports and internal "cache 6633 revalidation" requests which are triggered by those regular 6634 requests hitting a stale cached object. Revalidation collapsing 6635 is currently disabled for Squid instances containing SMP-aware 6636 disk or memory caches and for Vary-controlled cached objects. 6637DOC_END 6638 6639NAME: collapsed_forwarding_shared_entries_limit 6640COMMENT: (number of entries) 6641TYPE: int64_t 6642LOC: Config.collapsed_forwarding_shared_entries_limit 6643DEFAULT: 16384 6644DOC_START 6645 This limits the size of a table used for sharing information 6646 about collapsible entries among SMP workers. Limiting sharing 6647 too much results in cache content duplication and missed 6648 collapsing opportunities. Using excessively large values 6649 wastes shared memory. 6650 6651 The limit should be significantly larger then the number of 6652 concurrent collapsible entries one wants to share. For a cache 6653 that handles less than 5000 concurrent requests, the default 6654 setting of 16384 should be plenty. 6655 6656 If the limit is set to zero, it disables sharing of collapsed 6657 forwarding between SMP workers. 6658DOC_END 6659 6660COMMENT_START 6661 TIMEOUTS 6662 ----------------------------------------------------------------------------- 6663COMMENT_END 6664 6665NAME: forward_timeout 6666COMMENT: time-units 6667TYPE: time_t 6668LOC: Config.Timeout.forward 6669DEFAULT: 4 minutes 6670DOC_START 6671 This parameter specifies how long Squid should at most attempt in 6672 finding a forwarding path for the request before giving up. 6673DOC_END 6674 6675NAME: connect_timeout 6676COMMENT: time-units 6677TYPE: time_t 6678LOC: Config.Timeout.connect 6679DEFAULT: 1 minute 6680DOC_START 6681 This parameter specifies how long to wait for the TCP connect to 6682 the requested server or peer to complete before Squid should 6683 attempt to find another path where to forward the request. 6684DOC_END 6685 6686NAME: peer_connect_timeout 6687COMMENT: time-units 6688TYPE: time_t 6689LOC: Config.Timeout.peer_connect 6690DEFAULT: 30 seconds 6691DOC_START 6692 This parameter specifies how long to wait for a pending TCP 6693 connection to a peer cache. The default is 30 seconds. You 6694 may also set different timeout values for individual neighbors 6695 with the 'connect-timeout' option on a 'cache_peer' line. 6696DOC_END 6697 6698NAME: read_timeout 6699COMMENT: time-units 6700TYPE: time_t 6701LOC: Config.Timeout.read 6702DEFAULT: 15 minutes 6703DOC_START 6704 Applied on peer server connections. 6705 6706 After each successful read(), the timeout will be extended by this 6707 amount. If no data is read again after this amount of time, 6708 the request is aborted and logged with ERR_READ_TIMEOUT. 6709 6710 The default is 15 minutes. 6711DOC_END 6712 6713NAME: write_timeout 6714COMMENT: time-units 6715TYPE: time_t 6716LOC: Config.Timeout.write 6717DEFAULT: 15 minutes 6718DOC_START 6719 This timeout is tracked for all connections that have data 6720 available for writing and are waiting for the socket to become 6721 ready. After each successful write, the timeout is extended by 6722 the configured amount. If Squid has data to write but the 6723 connection is not ready for the configured duration, the 6724 transaction associated with the connection is terminated. The 6725 default is 15 minutes. 6726DOC_END 6727 6728NAME: request_timeout 6729TYPE: time_t 6730LOC: Config.Timeout.request 6731DEFAULT: 5 minutes 6732DOC_START 6733 How long to wait for complete HTTP request headers after initial 6734 connection establishment. 6735DOC_END 6736 6737NAME: request_start_timeout 6738TYPE: time_t 6739LOC: Config.Timeout.request_start_timeout 6740DEFAULT: 5 minutes 6741DOC_START 6742 How long to wait for the first request byte after initial 6743 connection establishment. 6744DOC_END 6745 6746NAME: client_idle_pconn_timeout persistent_request_timeout 6747TYPE: time_t 6748LOC: Config.Timeout.clientIdlePconn 6749DEFAULT: 2 minutes 6750DOC_START 6751 How long to wait for the next HTTP request on a persistent 6752 client connection after the previous request completes. 6753DOC_END 6754 6755NAME: ftp_client_idle_timeout 6756TYPE: time_t 6757LOC: Config.Timeout.ftpClientIdle 6758DEFAULT: 30 minutes 6759DOC_START 6760 How long to wait for an FTP request on a connection to Squid ftp_port. 6761 Many FTP clients do not deal with idle connection closures well, 6762 necessitating a longer default timeout than client_idle_pconn_timeout 6763 used for incoming HTTP requests. 6764DOC_END 6765 6766NAME: client_lifetime 6767COMMENT: time-units 6768TYPE: time_t 6769LOC: Config.Timeout.lifetime 6770DEFAULT: 1 day 6771DOC_START 6772 The maximum amount of time a client (browser) is allowed to 6773 remain connected to the cache process. This protects the Cache 6774 from having a lot of sockets (and hence file descriptors) tied up 6775 in a CLOSE_WAIT state from remote clients that go away without 6776 properly shutting down (either because of a network failure or 6777 because of a poor client implementation). The default is one 6778 day, 1440 minutes. 6779 6780 NOTE: The default value is intended to be much larger than any 6781 client would ever need to be connected to your cache. You 6782 should probably change client_lifetime only as a last resort. 6783 If you seem to have many client connections tying up 6784 filedescriptors, we recommend first tuning the read_timeout, 6785 request_timeout, persistent_request_timeout and quick_abort values. 6786DOC_END 6787 6788NAME: pconn_lifetime 6789COMMENT: time-units 6790TYPE: time_t 6791LOC: Config.Timeout.pconnLifetime 6792DEFAULT: 0 seconds 6793DOC_START 6794 Desired maximum lifetime of a persistent connection. 6795 When set, Squid will close a now-idle persistent connection that 6796 exceeded configured lifetime instead of moving the connection into 6797 the idle connection pool (or equivalent). No effect on ongoing/active 6798 transactions. Connection lifetime is the time period from the 6799 connection acceptance or opening time until "now". 6800 6801 This limit is useful in environments with long-lived connections 6802 where Squid configuration or environmental factors change during a 6803 single connection lifetime. If unrestricted, some connections may 6804 last for hours and even days, ignoring those changes that should 6805 have affected their behavior or their existence. 6806 6807 Currently, a new lifetime value supplied via Squid reconfiguration 6808 has no effect on already idle connections unless they become busy. 6809 6810 When set to '0' this limit is not used. 6811DOC_END 6812 6813NAME: half_closed_clients 6814TYPE: onoff 6815LOC: Config.onoff.half_closed_clients 6816DEFAULT: off 6817DOC_START 6818 Some clients may shutdown the sending side of their TCP 6819 connections, while leaving their receiving sides open. Sometimes, 6820 Squid can not tell the difference between a half-closed and a 6821 fully-closed TCP connection. 6822 6823 By default, Squid will immediately close client connections when 6824 read(2) returns "no more data to read." 6825 6826 Change this option to 'on' and Squid will keep open connections 6827 until a read(2) or write(2) on the socket returns an error. 6828 This may show some benefits for reverse proxies. But if not 6829 it is recommended to leave OFF. 6830DOC_END 6831 6832NAME: server_idle_pconn_timeout pconn_timeout 6833TYPE: time_t 6834LOC: Config.Timeout.serverIdlePconn 6835DEFAULT: 1 minute 6836DOC_START 6837 Timeout for idle persistent connections to servers and other 6838 proxies. 6839DOC_END 6840 6841NAME: ident_timeout 6842TYPE: time_t 6843IFDEF: USE_IDENT 6844LOC: Ident::TheConfig.timeout 6845DEFAULT: 10 seconds 6846DOC_START 6847 Maximum time to wait for IDENT lookups to complete. 6848 6849 If this is too high, and you enabled IDENT lookups from untrusted 6850 users, you might be susceptible to denial-of-service by having 6851 many ident requests going at once. 6852DOC_END 6853 6854NAME: shutdown_lifetime 6855COMMENT: time-units 6856TYPE: time_t 6857LOC: Config.shutdownLifetime 6858DEFAULT: 30 seconds 6859DOC_START 6860 When SIGTERM or SIGHUP is received, the cache is put into 6861 "shutdown pending" mode until all active sockets are closed. 6862 This value is the lifetime to set for all open descriptors 6863 during shutdown mode. Any active clients after this many 6864 seconds will receive a 'timeout' message. 6865DOC_END 6866 6867COMMENT_START 6868 ADMINISTRATIVE PARAMETERS 6869 ----------------------------------------------------------------------------- 6870COMMENT_END 6871 6872NAME: cache_mgr 6873TYPE: string 6874DEFAULT: webmaster 6875LOC: Config.adminEmail 6876DOC_START 6877 Email-address of local cache manager who will receive 6878 mail if the cache dies. The default is "webmaster". 6879DOC_END 6880 6881NAME: mail_from 6882TYPE: string 6883DEFAULT: none 6884LOC: Config.EmailFrom 6885DOC_START 6886 From: email-address for mail sent when the cache dies. 6887 The default is to use 'squid@unique_hostname'. 6888 6889 See also: unique_hostname directive. 6890DOC_END 6891 6892NAME: mail_program 6893TYPE: eol 6894DEFAULT: mail 6895LOC: Config.EmailProgram 6896DOC_START 6897 Email program used to send mail if the cache dies. 6898 The default is "mail". The specified program must comply 6899 with the standard Unix mail syntax: 6900 mail-program recipient < mailfile 6901 6902 Optional command line options can be specified. 6903DOC_END 6904 6905NAME: cache_effective_user 6906TYPE: string 6907DEFAULT: @DEFAULT_CACHE_EFFECTIVE_USER@ 6908LOC: Config.effectiveUser 6909DOC_START 6910 If you start Squid as root, it will change its effective/real 6911 UID/GID to the user specified below. The default is to change 6912 to UID of @DEFAULT_CACHE_EFFECTIVE_USER@. 6913 see also; cache_effective_group 6914DOC_END 6915 6916NAME: cache_effective_group 6917TYPE: string 6918DEFAULT: none 6919DEFAULT_DOC: Use system group memberships of the cache_effective_user account 6920LOC: Config.effectiveGroup 6921DOC_START 6922 Squid sets the GID to the effective user's default group ID 6923 (taken from the password file) and supplementary group list 6924 from the groups membership. 6925 6926 If you want Squid to run with a specific GID regardless of 6927 the group memberships of the effective user then set this 6928 to the group (or GID) you want Squid to run as. When set 6929 all other group privileges of the effective user are ignored 6930 and only this GID is effective. If Squid is not started as 6931 root the user starting Squid MUST be member of the specified 6932 group. 6933 6934 This option is not recommended by the Squid Team. 6935 Our preference is for administrators to configure a secure 6936 user account for squid with UID/GID matching system policies. 6937DOC_END 6938 6939NAME: httpd_suppress_version_string 6940COMMENT: on|off 6941TYPE: onoff 6942DEFAULT: off 6943LOC: Config.onoff.httpd_suppress_version_string 6944DOC_START 6945 Suppress Squid version string info in HTTP headers and HTML error pages. 6946DOC_END 6947 6948NAME: visible_hostname 6949TYPE: string 6950LOC: Config.visibleHostname 6951DEFAULT: none 6952DEFAULT_DOC: Automatically detect the system host name 6953DOC_START 6954 If you want to present a special hostname in error messages, etc, 6955 define this. Otherwise, the return value of gethostname() 6956 will be used. If you have multiple caches in a cluster and 6957 get errors about IP-forwarding you must set them to have individual 6958 names with this setting. 6959DOC_END 6960 6961NAME: unique_hostname 6962TYPE: string 6963LOC: Config.uniqueHostname 6964DEFAULT: none 6965DEFAULT_DOC: Copy the value from visible_hostname 6966DOC_START 6967 If you want to have multiple machines with the same 6968 'visible_hostname' you must give each machine a different 6969 'unique_hostname' so forwarding loops can be detected. 6970DOC_END 6971 6972NAME: hostname_aliases 6973TYPE: wordlist 6974LOC: Config.hostnameAliases 6975DEFAULT: none 6976DOC_START 6977 A list of other DNS names your cache has. 6978DOC_END 6979 6980NAME: umask 6981TYPE: int 6982LOC: Config.umask 6983DEFAULT: 027 6984DOC_START 6985 Minimum umask which should be enforced while the proxy 6986 is running, in addition to the umask set at startup. 6987 6988 For a traditional octal representation of umasks, start 6989 your value with 0. 6990DOC_END 6991 6992COMMENT_START 6993 OPTIONS FOR THE CACHE REGISTRATION SERVICE 6994 ----------------------------------------------------------------------------- 6995 6996 This section contains parameters for the (optional) cache 6997 announcement service. This service is provided to help 6998 cache administrators locate one another in order to join or 6999 create cache hierarchies. 7000 7001 An 'announcement' message is sent (via UDP) to the registration 7002 service by Squid. By default, the announcement message is NOT 7003 SENT unless you enable it with 'announce_period' below. 7004 7005 The announcement message includes your hostname, plus the 7006 following information from this configuration file: 7007 7008 http_port 7009 icp_port 7010 cache_mgr 7011 7012 All current information is processed regularly and made 7013 available on the Web at http://www.ircache.net/Cache/Tracker/. 7014COMMENT_END 7015 7016NAME: announce_period 7017TYPE: time_t 7018LOC: Config.Announce.period 7019DEFAULT: 0 7020DEFAULT_DOC: Announcement messages disabled. 7021DOC_START 7022 This is how frequently to send cache announcements. 7023 7024 To enable announcing your cache, just set an announce period. 7025 7026 Example: 7027 announce_period 1 day 7028DOC_END 7029 7030NAME: announce_host 7031TYPE: string 7032DEFAULT: tracker.ircache.net 7033LOC: Config.Announce.host 7034DOC_START 7035 Set the hostname where announce registration messages will be sent. 7036 7037 See also announce_port and announce_file 7038DOC_END 7039 7040NAME: announce_file 7041TYPE: string 7042DEFAULT: none 7043LOC: Config.Announce.file 7044DOC_START 7045 The contents of this file will be included in the announce 7046 registration messages. 7047DOC_END 7048 7049NAME: announce_port 7050TYPE: u_short 7051DEFAULT: 3131 7052LOC: Config.Announce.port 7053DOC_START 7054 Set the port where announce registration messages will be sent. 7055 7056 See also announce_host and announce_file 7057DOC_END 7058 7059COMMENT_START 7060 HTTPD-ACCELERATOR OPTIONS 7061 ----------------------------------------------------------------------------- 7062COMMENT_END 7063 7064NAME: httpd_accel_surrogate_id 7065TYPE: string 7066DEFAULT: none 7067DEFAULT_DOC: visible_hostname is used if no specific ID is set. 7068LOC: Config.Accel.surrogate_id 7069DOC_START 7070 Surrogates (http://www.esi.org/architecture_spec_1.0.html) 7071 need an identification token to allow control targeting. Because 7072 a farm of surrogates may all perform the same tasks, they may share 7073 an identification token. 7074DOC_END 7075 7076NAME: http_accel_surrogate_remote 7077COMMENT: on|off 7078TYPE: onoff 7079DEFAULT: off 7080LOC: Config.onoff.surrogate_is_remote 7081DOC_START 7082 Remote surrogates (such as those in a CDN) honour the header 7083 "Surrogate-Control: no-store-remote". 7084 7085 Set this to on to have squid behave as a remote surrogate. 7086DOC_END 7087 7088NAME: esi_parser 7089IFDEF: USE_SQUID_ESI 7090COMMENT: libxml2|expat 7091TYPE: string 7092LOC: ESIParser::Type 7093DEFAULT: auto 7094DEFAULT_DOC: Selects libxml2 if available at ./configure time or libexpat otherwise. 7095DOC_START 7096 Selects the XML parsing library to use when interpreting responses with 7097 Edge Side Includes. 7098 7099 To disable ESI handling completely, ./configure Squid with --disable-esi. 7100DOC_END 7101 7102COMMENT_START 7103 DELAY POOL PARAMETERS 7104 ----------------------------------------------------------------------------- 7105COMMENT_END 7106 7107NAME: delay_pools 7108TYPE: delay_pool_count 7109DEFAULT: 0 7110IFDEF: USE_DELAY_POOLS 7111LOC: Config.Delay 7112DOC_START 7113 This represents the number of delay pools to be used. For example, 7114 if you have one class 2 delay pool and one class 3 delays pool, you 7115 have a total of 2 delay pools. 7116 7117 See also delay_parameters, delay_class, delay_access for pool 7118 configuration details. 7119DOC_END 7120 7121NAME: delay_class 7122TYPE: delay_pool_class 7123DEFAULT: none 7124IFDEF: USE_DELAY_POOLS 7125LOC: Config.Delay 7126DOC_START 7127 This defines the class of each delay pool. There must be exactly one 7128 delay_class line for each delay pool. For example, to define two 7129 delay pools, one of class 2 and one of class 3, the settings above 7130 and here would be: 7131 7132 Example: 7133 delay_pools 4 # 4 delay pools 7134 delay_class 1 2 # pool 1 is a class 2 pool 7135 delay_class 2 3 # pool 2 is a class 3 pool 7136 delay_class 3 4 # pool 3 is a class 4 pool 7137 delay_class 4 5 # pool 4 is a class 5 pool 7138 7139 The delay pool classes are: 7140 7141 class 1 Everything is limited by a single aggregate 7142 bucket. 7143 7144 class 2 Everything is limited by a single aggregate 7145 bucket as well as an "individual" bucket chosen 7146 from bits 25 through 32 of the IPv4 address. 7147 7148 class 3 Everything is limited by a single aggregate 7149 bucket as well as a "network" bucket chosen 7150 from bits 17 through 24 of the IP address and a 7151 "individual" bucket chosen from bits 17 through 7152 32 of the IPv4 address. 7153 7154 class 4 Everything in a class 3 delay pool, with an 7155 additional limit on a per user basis. This 7156 only takes effect if the username is established 7157 in advance - by forcing authentication in your 7158 http_access rules. 7159 7160 class 5 Requests are grouped according their tag (see 7161 external_acl's tag= reply). 7162 7163 7164 Each pool also requires a delay_parameters directive to configure the pool size 7165 and speed limits used whenever the pool is applied to a request. Along with 7166 a set of delay_access directives to determine when it is used. 7167 7168 NOTE: If an IP address is a.b.c.d 7169 -> bits 25 through 32 are "d" 7170 -> bits 17 through 24 are "c" 7171 -> bits 17 through 32 are "c * 256 + d" 7172 7173 NOTE-2: Due to the use of bitmasks in class 2,3,4 pools they only apply to 7174 IPv4 traffic. Class 1 and 5 pools may be used with IPv6 traffic. 7175 7176 This clause only supports fast acl types. 7177 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 7178 7179 See also delay_parameters and delay_access. 7180DOC_END 7181 7182NAME: delay_access 7183TYPE: delay_pool_access 7184DEFAULT: none 7185DEFAULT_DOC: Deny using the pool, unless allow rules exist in squid.conf for the pool. 7186IFDEF: USE_DELAY_POOLS 7187LOC: Config.Delay 7188DOC_START 7189 This is used to determine which delay pool a request falls into. 7190 7191 delay_access is sorted per pool and the matching starts with pool 1, 7192 then pool 2, ..., and finally pool N. The first delay pool where the 7193 request is allowed is selected for the request. If it does not allow 7194 the request to any pool then the request is not delayed (default). 7195 7196 For example, if you want some_big_clients in delay 7197 pool 1 and lotsa_little_clients in delay pool 2: 7198 7199 delay_access 1 allow some_big_clients 7200 delay_access 1 deny all 7201 delay_access 2 allow lotsa_little_clients 7202 delay_access 2 deny all 7203 delay_access 3 allow authenticated_clients 7204 7205 See also delay_parameters and delay_class. 7206 7207DOC_END 7208 7209NAME: delay_parameters 7210TYPE: delay_pool_rates 7211DEFAULT: none 7212IFDEF: USE_DELAY_POOLS 7213LOC: Config.Delay 7214DOC_START 7215 This defines the parameters for a delay pool. Each delay pool has 7216 a number of "buckets" associated with it, as explained in the 7217 description of delay_class. 7218 7219 For a class 1 delay pool, the syntax is: 7220 delay_class pool 1 7221 delay_parameters pool aggregate 7222 7223 For a class 2 delay pool: 7224 delay_class pool 2 7225 delay_parameters pool aggregate individual 7226 7227 For a class 3 delay pool: 7228 delay_class pool 3 7229 delay_parameters pool aggregate network individual 7230 7231 For a class 4 delay pool: 7232 delay_class pool 4 7233 delay_parameters pool aggregate network individual user 7234 7235 For a class 5 delay pool: 7236 delay_class pool 5 7237 delay_parameters pool tagrate 7238 7239 The option variables are: 7240 7241 pool a pool number - ie, a number between 1 and the 7242 number specified in delay_pools as used in 7243 delay_class lines. 7244 7245 aggregate the speed limit parameters for the aggregate bucket 7246 (class 1, 2, 3). 7247 7248 individual the speed limit parameters for the individual 7249 buckets (class 2, 3). 7250 7251 network the speed limit parameters for the network buckets 7252 (class 3). 7253 7254 user the speed limit parameters for the user buckets 7255 (class 4). 7256 7257 tagrate the speed limit parameters for the tag buckets 7258 (class 5). 7259 7260 A pair of delay parameters is written restore/maximum, where restore is 7261 the number of bytes (not bits - modem and network speeds are usually 7262 quoted in bits) per second placed into the bucket, and maximum is the 7263 maximum number of bytes which can be in the bucket at any time. 7264 7265 There must be one delay_parameters line for each delay pool. 7266 7267 7268 For example, if delay pool number 1 is a class 2 delay pool as in the 7269 above example, and is being used to strictly limit each host to 64Kbit/sec 7270 (plus overheads), with no overall limit, the line is: 7271 7272 delay_parameters 1 none 8000/8000 7273 7274 Note that 8 x 8K Byte/sec -> 64K bit/sec. 7275 7276 Note that the word 'none' is used to represent no limit. 7277 7278 7279 And, if delay pool number 2 is a class 3 delay pool as in the above 7280 example, and you want to limit it to a total of 256Kbit/sec (strict limit) 7281 with each 8-bit network permitted 64Kbit/sec (strict limit) and each 7282 individual host permitted 4800bit/sec with a bucket maximum size of 64Kbits 7283 to permit a decent web page to be downloaded at a decent speed 7284 (if the network is not being limited due to overuse) but slow down 7285 large downloads more significantly: 7286 7287 delay_parameters 2 32000/32000 8000/8000 600/8000 7288 7289 Note that 8 x 32K Byte/sec -> 256K bit/sec. 7290 8 x 8K Byte/sec -> 64K bit/sec. 7291 8 x 600 Byte/sec -> 4800 bit/sec. 7292 7293 7294 Finally, for a class 4 delay pool as in the example - each user will 7295 be limited to 128Kbits/sec no matter how many workstations they are logged into.: 7296 7297 delay_parameters 4 32000/32000 8000/8000 600/64000 16000/16000 7298 7299 7300 See also delay_class and delay_access. 7301 7302DOC_END 7303 7304NAME: delay_initial_bucket_level 7305COMMENT: (percent, 0-100) 7306TYPE: u_short 7307DEFAULT: 50 7308IFDEF: USE_DELAY_POOLS 7309LOC: Config.Delay.initial 7310DOC_START 7311 The initial bucket percentage is used to determine how much is put 7312 in each bucket when squid starts, is reconfigured, or first notices 7313 a host accessing it (in class 2 and class 3, individual hosts and 7314 networks only have buckets associated with them once they have been 7315 "seen" by squid). 7316DOC_END 7317 7318COMMENT_START 7319 CLIENT DELAY POOL PARAMETERS 7320 ----------------------------------------------------------------------------- 7321COMMENT_END 7322 7323NAME: client_delay_pools 7324TYPE: client_delay_pool_count 7325DEFAULT: 0 7326IFDEF: USE_DELAY_POOLS 7327LOC: Config.ClientDelay 7328DOC_START 7329 This option specifies the number of client delay pools used. It must 7330 preceed other client_delay_* options. 7331 7332 Example: 7333 client_delay_pools 2 7334 7335 See also client_delay_parameters and client_delay_access. 7336DOC_END 7337 7338NAME: client_delay_initial_bucket_level 7339COMMENT: (percent, 0-no_limit) 7340TYPE: u_short 7341DEFAULT: 50 7342IFDEF: USE_DELAY_POOLS 7343LOC: Config.ClientDelay.initial 7344DOC_START 7345 This option determines the initial bucket size as a percentage of 7346 max_bucket_size from client_delay_parameters. Buckets are created 7347 at the time of the "first" connection from the matching IP. Idle 7348 buckets are periodically deleted up. 7349 7350 You can specify more than 100 percent but note that such "oversized" 7351 buckets are not refilled until their size goes down to max_bucket_size 7352 from client_delay_parameters. 7353 7354 Example: 7355 client_delay_initial_bucket_level 50 7356DOC_END 7357 7358NAME: client_delay_parameters 7359TYPE: client_delay_pool_rates 7360DEFAULT: none 7361IFDEF: USE_DELAY_POOLS 7362LOC: Config.ClientDelay 7363DOC_START 7364 7365 This option configures client-side bandwidth limits using the 7366 following format: 7367 7368 client_delay_parameters pool speed_limit max_bucket_size 7369 7370 pool is an integer ID used for client_delay_access matching. 7371 7372 speed_limit is bytes added to the bucket per second. 7373 7374 max_bucket_size is the maximum size of a bucket, enforced after any 7375 speed_limit additions. 7376 7377 Please see the delay_parameters option for more information and 7378 examples. 7379 7380 Example: 7381 client_delay_parameters 1 1024 2048 7382 client_delay_parameters 2 51200 16384 7383 7384 See also client_delay_access. 7385 7386DOC_END 7387 7388NAME: client_delay_access 7389TYPE: client_delay_pool_access 7390DEFAULT: none 7391DEFAULT_DOC: Deny use of the pool, unless allow rules exist in squid.conf for the pool. 7392IFDEF: USE_DELAY_POOLS 7393LOC: Config.ClientDelay 7394DOC_START 7395 This option determines the client-side delay pool for the 7396 request: 7397 7398 client_delay_access pool_ID allow|deny acl_name 7399 7400 All client_delay_access options are checked in their pool ID 7401 order, starting with pool 1. The first checked pool with allowed 7402 request is selected for the request. If no ACL matches or there 7403 are no client_delay_access options, the request bandwidth is not 7404 limited. 7405 7406 The ACL-selected pool is then used to find the 7407 client_delay_parameters for the request. Client-side pools are 7408 not used to aggregate clients. Clients are always aggregated 7409 based on their source IP addresses (one bucket per source IP). 7410 7411 This clause only supports fast acl types. 7412 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 7413 Additionally, only the client TCP connection details are available. 7414 ACLs testing HTTP properties will not work. 7415 7416 Please see delay_access for more examples. 7417 7418 Example: 7419 client_delay_access 1 allow low_rate_network 7420 client_delay_access 2 allow vips_network 7421 7422 7423 See also client_delay_parameters and client_delay_pools. 7424DOC_END 7425 7426COMMENT_START 7427 WCCPv1 AND WCCPv2 CONFIGURATION OPTIONS 7428 ----------------------------------------------------------------------------- 7429COMMENT_END 7430 7431NAME: wccp_router 7432TYPE: address 7433LOC: Config.Wccp.router 7434DEFAULT: any_addr 7435DEFAULT_DOC: WCCP disabled. 7436IFDEF: USE_WCCP 7437DOC_START 7438 Use this option to define your WCCP ``home'' router for 7439 Squid. 7440 7441 wccp_router supports a single WCCP(v1) router 7442 7443 wccp2_router supports multiple WCCPv2 routers 7444 7445 only one of the two may be used at the same time and defines 7446 which version of WCCP to use. 7447DOC_END 7448 7449NAME: wccp2_router 7450TYPE: IpAddress_list 7451LOC: Config.Wccp2.router 7452DEFAULT: none 7453DEFAULT_DOC: WCCPv2 disabled. 7454IFDEF: USE_WCCPv2 7455DOC_START 7456 Use this option to define your WCCP ``home'' router for 7457 Squid. 7458 7459 wccp_router supports a single WCCP(v1) router 7460 7461 wccp2_router supports multiple WCCPv2 routers 7462 7463 only one of the two may be used at the same time and defines 7464 which version of WCCP to use. 7465DOC_END 7466 7467NAME: wccp_version 7468TYPE: int 7469LOC: Config.Wccp.version 7470DEFAULT: 4 7471IFDEF: USE_WCCP 7472DOC_START 7473 This directive is only relevant if you need to set up WCCP(v1) 7474 to some very old and end-of-life Cisco routers. In all other 7475 setups it must be left unset or at the default setting. 7476 It defines an internal version in the WCCP(v1) protocol, 7477 with version 4 being the officially documented protocol. 7478 7479 According to some users, Cisco IOS 11.2 and earlier only 7480 support WCCP version 3. If you're using that or an earlier 7481 version of IOS, you may need to change this value to 3, otherwise 7482 do not specify this parameter. 7483DOC_END 7484 7485NAME: wccp2_rebuild_wait 7486TYPE: onoff 7487LOC: Config.Wccp2.rebuildwait 7488DEFAULT: on 7489IFDEF: USE_WCCPv2 7490DOC_START 7491 If this is enabled Squid will wait for the cache dir rebuild to finish 7492 before sending the first wccp2 HereIAm packet 7493DOC_END 7494 7495NAME: wccp2_forwarding_method 7496TYPE: wccp2_method 7497LOC: Config.Wccp2.forwarding_method 7498DEFAULT: gre 7499IFDEF: USE_WCCPv2 7500DOC_START 7501 WCCP2 allows the setting of forwarding methods between the 7502 router/switch and the cache. Valid values are as follows: 7503 7504 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel) 7505 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting) 7506 7507 Currently (as of IOS 12.4) cisco routers only support GRE. 7508 Cisco switches only support the L2 redirect assignment method. 7509DOC_END 7510 7511NAME: wccp2_return_method 7512TYPE: wccp2_method 7513LOC: Config.Wccp2.return_method 7514DEFAULT: gre 7515IFDEF: USE_WCCPv2 7516DOC_START 7517 WCCP2 allows the setting of return methods between the 7518 router/switch and the cache for packets that the cache 7519 decides not to handle. Valid values are as follows: 7520 7521 gre - GRE encapsulation (forward the packet in a GRE/WCCP tunnel) 7522 l2 - L2 redirect (forward the packet using Layer 2/MAC rewriting) 7523 7524 Currently (as of IOS 12.4) cisco routers only support GRE. 7525 Cisco switches only support the L2 redirect assignment. 7526 7527 If the "ip wccp redirect exclude in" command has been 7528 enabled on the cache interface, then it is still safe for 7529 the proxy server to use a l2 redirect method even if this 7530 option is set to GRE. 7531DOC_END 7532 7533NAME: wccp2_assignment_method 7534TYPE: wccp2_amethod 7535LOC: Config.Wccp2.assignment_method 7536DEFAULT: hash 7537IFDEF: USE_WCCPv2 7538DOC_START 7539 WCCP2 allows the setting of methods to assign the WCCP hash 7540 Valid values are as follows: 7541 7542 hash - Hash assignment 7543 mask - Mask assignment 7544 7545 As a general rule, cisco routers support the hash assignment method 7546 and cisco switches support the mask assignment method. 7547DOC_END 7548 7549NAME: wccp2_service 7550TYPE: wccp2_service 7551LOC: Config.Wccp2.info 7552DEFAULT_IF_NONE: standard 0 7553DEFAULT_DOC: Use the 'web-cache' standard service. 7554IFDEF: USE_WCCPv2 7555DOC_START 7556 WCCP2 allows for multiple traffic services. There are two 7557 types: "standard" and "dynamic". The standard type defines 7558 one service id - http (id 0). The dynamic service ids can be from 7559 51 to 255 inclusive. In order to use a dynamic service id 7560 one must define the type of traffic to be redirected; this is done 7561 using the wccp2_service_info option. 7562 7563 The "standard" type does not require a wccp2_service_info option, 7564 just specifying the service id will suffice. 7565 7566 MD5 service authentication can be enabled by adding 7567 "password=<password>" to the end of this service declaration. 7568 7569 Examples: 7570 7571 wccp2_service standard 0 # for the 'web-cache' standard service 7572 wccp2_service dynamic 80 # a dynamic service type which will be 7573 # fleshed out with subsequent options. 7574 wccp2_service standard 0 password=foo 7575DOC_END 7576 7577NAME: wccp2_service_info 7578TYPE: wccp2_service_info 7579LOC: Config.Wccp2.info 7580DEFAULT: none 7581IFDEF: USE_WCCPv2 7582DOC_START 7583 Dynamic WCCPv2 services require further information to define the 7584 traffic you wish to have diverted. 7585 7586 The format is: 7587 7588 wccp2_service_info <id> protocol=<protocol> flags=<flag>,<flag>.. 7589 priority=<priority> ports=<port>,<port>.. 7590 7591 The relevant WCCPv2 flags: 7592 + src_ip_hash, dst_ip_hash 7593 + source_port_hash, dst_port_hash 7594 + src_ip_alt_hash, dst_ip_alt_hash 7595 + src_port_alt_hash, dst_port_alt_hash 7596 + ports_source 7597 7598 The port list can be one to eight entries. 7599 7600 Example: 7601 7602 wccp2_service_info 80 protocol=tcp flags=src_ip_hash,ports_source 7603 priority=240 ports=80 7604 7605 Note: the service id must have been defined by a previous 7606 'wccp2_service dynamic <id>' entry. 7607DOC_END 7608 7609NAME: wccp2_weight 7610TYPE: int 7611LOC: Config.Wccp2.weight 7612DEFAULT: 10000 7613IFDEF: USE_WCCPv2 7614DOC_START 7615 Each cache server gets assigned a set of the destination 7616 hash proportional to their weight. 7617DOC_END 7618 7619NAME: wccp_address 7620TYPE: address 7621LOC: Config.Wccp.address 7622DEFAULT: 0.0.0.0 7623DEFAULT_DOC: Address selected by the operating system. 7624IFDEF: USE_WCCP 7625DOC_START 7626 Use this option if you require WCCP(v1) to use a specific 7627 interface address. 7628 7629 The default behavior is to not bind to any specific address. 7630DOC_END 7631 7632NAME: wccp2_address 7633TYPE: address 7634LOC: Config.Wccp2.address 7635DEFAULT: 0.0.0.0 7636DEFAULT_DOC: Address selected by the operating system. 7637IFDEF: USE_WCCPv2 7638DOC_START 7639 Use this option if you require WCCPv2 to use a specific 7640 interface address. 7641 7642 The default behavior is to not bind to any specific address. 7643DOC_END 7644 7645COMMENT_START 7646 PERSISTENT CONNECTION HANDLING 7647 ----------------------------------------------------------------------------- 7648 7649 Also see "pconn_timeout" in the TIMEOUTS section 7650COMMENT_END 7651 7652NAME: client_persistent_connections 7653TYPE: onoff 7654LOC: Config.onoff.client_pconns 7655DEFAULT: on 7656DOC_START 7657 Persistent connection support for clients. 7658 Squid uses persistent connections (when allowed). You can use 7659 this option to disable persistent connections with clients. 7660DOC_END 7661 7662NAME: server_persistent_connections 7663TYPE: onoff 7664LOC: Config.onoff.server_pconns 7665DEFAULT: on 7666DOC_START 7667 Persistent connection support for servers. 7668 Squid uses persistent connections (when allowed). You can use 7669 this option to disable persistent connections with servers. 7670DOC_END 7671 7672NAME: persistent_connection_after_error 7673TYPE: onoff 7674LOC: Config.onoff.error_pconns 7675DEFAULT: on 7676DOC_START 7677 With this directive the use of persistent connections after 7678 HTTP errors can be disabled. Useful if you have clients 7679 who fail to handle errors on persistent connections proper. 7680DOC_END 7681 7682NAME: detect_broken_pconn 7683TYPE: onoff 7684LOC: Config.onoff.detect_broken_server_pconns 7685DEFAULT: off 7686DOC_START 7687 Some servers have been found to incorrectly signal the use 7688 of HTTP/1.0 persistent connections even on replies not 7689 compatible, causing significant delays. This server problem 7690 has mostly been seen on redirects. 7691 7692 By enabling this directive Squid attempts to detect such 7693 broken replies and automatically assume the reply is finished 7694 after 10 seconds timeout. 7695DOC_END 7696 7697COMMENT_START 7698 CACHE DIGEST OPTIONS 7699 ----------------------------------------------------------------------------- 7700COMMENT_END 7701 7702NAME: digest_generation 7703IFDEF: USE_CACHE_DIGESTS 7704TYPE: onoff 7705LOC: Config.onoff.digest_generation 7706DEFAULT: on 7707DOC_START 7708 This controls whether the server will generate a Cache Digest 7709 of its contents. By default, Cache Digest generation is 7710 enabled if Squid is compiled with --enable-cache-digests defined. 7711DOC_END 7712 7713NAME: digest_bits_per_entry 7714IFDEF: USE_CACHE_DIGESTS 7715TYPE: int 7716LOC: Config.digest.bits_per_entry 7717DEFAULT: 5 7718DOC_START 7719 This is the number of bits of the server's Cache Digest which 7720 will be associated with the Digest entry for a given HTTP 7721 Method and URL (public key) combination. The default is 5. 7722DOC_END 7723 7724NAME: digest_rebuild_period 7725IFDEF: USE_CACHE_DIGESTS 7726COMMENT: (seconds) 7727TYPE: time_t 7728LOC: Config.digest.rebuild_period 7729DEFAULT: 1 hour 7730DOC_START 7731 This is the wait time between Cache Digest rebuilds. 7732DOC_END 7733 7734NAME: digest_rewrite_period 7735COMMENT: (seconds) 7736IFDEF: USE_CACHE_DIGESTS 7737TYPE: time_t 7738LOC: Config.digest.rewrite_period 7739DEFAULT: 1 hour 7740DOC_START 7741 This is the wait time between Cache Digest writes to 7742 disk. 7743DOC_END 7744 7745NAME: digest_swapout_chunk_size 7746COMMENT: (bytes) 7747TYPE: b_size_t 7748IFDEF: USE_CACHE_DIGESTS 7749LOC: Config.digest.swapout_chunk_size 7750DEFAULT: 4096 bytes 7751DOC_START 7752 This is the number of bytes of the Cache Digest to write to 7753 disk at a time. It defaults to 4096 bytes (4KB), the Squid 7754 default swap page. 7755DOC_END 7756 7757NAME: digest_rebuild_chunk_percentage 7758COMMENT: (percent, 0-100) 7759IFDEF: USE_CACHE_DIGESTS 7760TYPE: int 7761LOC: Config.digest.rebuild_chunk_percentage 7762DEFAULT: 10 7763DOC_START 7764 This is the percentage of the Cache Digest to be scanned at a 7765 time. By default it is set to 10% of the Cache Digest. 7766DOC_END 7767 7768COMMENT_START 7769 SNMP OPTIONS 7770 ----------------------------------------------------------------------------- 7771COMMENT_END 7772 7773NAME: snmp_port 7774TYPE: u_short 7775LOC: Config.Port.snmp 7776DEFAULT: 0 7777DEFAULT_DOC: SNMP disabled. 7778IFDEF: SQUID_SNMP 7779DOC_START 7780 The port number where Squid listens for SNMP requests. To enable 7781 SNMP support set this to a suitable port number. Port number 7782 3401 is often used for the Squid SNMP agent. By default it's 7783 set to "0" (disabled) 7784 7785 Example: 7786 snmp_port 3401 7787DOC_END 7788 7789NAME: snmp_access 7790TYPE: acl_access 7791LOC: Config.accessList.snmp 7792DEFAULT: none 7793DEFAULT_DOC: Deny, unless rules exist in squid.conf. 7794IFDEF: SQUID_SNMP 7795DOC_START 7796 Allowing or denying access to the SNMP port. 7797 7798 All access to the agent is denied by default. 7799 usage: 7800 7801 snmp_access allow|deny [!]aclname ... 7802 7803 This clause only supports fast acl types. 7804 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 7805 7806Example: 7807 snmp_access allow snmppublic localhost 7808 snmp_access deny all 7809DOC_END 7810 7811NAME: snmp_incoming_address 7812TYPE: address 7813LOC: Config.Addrs.snmp_incoming 7814DEFAULT: any_addr 7815DEFAULT_DOC: Accept SNMP packets from all machine interfaces. 7816IFDEF: SQUID_SNMP 7817DOC_START 7818 Just like 'udp_incoming_address', but for the SNMP port. 7819 7820 snmp_incoming_address is used for the SNMP socket receiving 7821 messages from SNMP agents. 7822 7823 The default snmp_incoming_address is to listen on all 7824 available network interfaces. 7825DOC_END 7826 7827NAME: snmp_outgoing_address 7828TYPE: address 7829LOC: Config.Addrs.snmp_outgoing 7830DEFAULT: no_addr 7831DEFAULT_DOC: Use snmp_incoming_address or an address selected by the operating system. 7832IFDEF: SQUID_SNMP 7833DOC_START 7834 Just like 'udp_outgoing_address', but for the SNMP port. 7835 7836 snmp_outgoing_address is used for SNMP packets returned to SNMP 7837 agents. 7838 7839 If snmp_outgoing_address is not set it will use the same socket 7840 as snmp_incoming_address. Only change this if you want to have 7841 SNMP replies sent using another address than where this Squid 7842 listens for SNMP queries. 7843 7844 NOTE, snmp_incoming_address and snmp_outgoing_address can not have 7845 the same value since they both use the same port. 7846DOC_END 7847 7848COMMENT_START 7849 ICP OPTIONS 7850 ----------------------------------------------------------------------------- 7851COMMENT_END 7852 7853NAME: icp_port udp_port 7854TYPE: u_short 7855DEFAULT: 0 7856DEFAULT_DOC: ICP disabled. 7857LOC: Config.Port.icp 7858DOC_START 7859 The port number where Squid sends and receives ICP queries to 7860 and from neighbor caches. The standard UDP port for ICP is 3130. 7861 7862 Example: 7863 icp_port @DEFAULT_ICP_PORT@ 7864DOC_END 7865 7866NAME: htcp_port 7867IFDEF: USE_HTCP 7868TYPE: u_short 7869DEFAULT: 0 7870DEFAULT_DOC: HTCP disabled. 7871LOC: Config.Port.htcp 7872DOC_START 7873 The port number where Squid sends and receives HTCP queries to 7874 and from neighbor caches. To turn it on you want to set it to 7875 4827. 7876 7877 Example: 7878 htcp_port 4827 7879DOC_END 7880 7881NAME: log_icp_queries 7882COMMENT: on|off 7883TYPE: onoff 7884DEFAULT: on 7885LOC: Config.onoff.log_udp 7886DOC_START 7887 If set, ICP queries are logged to access.log. You may wish 7888 do disable this if your ICP load is VERY high to speed things 7889 up or to simplify log analysis. 7890DOC_END 7891 7892NAME: udp_incoming_address 7893TYPE: address 7894LOC:Config.Addrs.udp_incoming 7895DEFAULT: any_addr 7896DEFAULT_DOC: Accept packets from all machine interfaces. 7897DOC_START 7898 udp_incoming_address is used for UDP packets received from other 7899 caches. 7900 7901 The default behavior is to not bind to any specific address. 7902 7903 Only change this if you want to have all UDP queries received on 7904 a specific interface/address. 7905 7906 NOTE: udp_incoming_address is used by the ICP, HTCP, and DNS 7907 modules. Altering it will affect all of them in the same manner. 7908 7909 see also; udp_outgoing_address 7910 7911 NOTE, udp_incoming_address and udp_outgoing_address can not 7912 have the same value since they both use the same port. 7913DOC_END 7914 7915NAME: udp_outgoing_address 7916TYPE: address 7917LOC: Config.Addrs.udp_outgoing 7918DEFAULT: no_addr 7919DEFAULT_DOC: Use udp_incoming_address or an address selected by the operating system. 7920DOC_START 7921 udp_outgoing_address is used for UDP packets sent out to other 7922 caches. 7923 7924 The default behavior is to not bind to any specific address. 7925 7926 Instead it will use the same socket as udp_incoming_address. 7927 Only change this if you want to have UDP queries sent using another 7928 address than where this Squid listens for UDP queries from other 7929 caches. 7930 7931 NOTE: udp_outgoing_address is used by the ICP, HTCP, and DNS 7932 modules. Altering it will affect all of them in the same manner. 7933 7934 see also; udp_incoming_address 7935 7936 NOTE, udp_incoming_address and udp_outgoing_address can not 7937 have the same value since they both use the same port. 7938DOC_END 7939 7940NAME: icp_hit_stale 7941COMMENT: on|off 7942TYPE: onoff 7943DEFAULT: off 7944LOC: Config.onoff.icp_hit_stale 7945DOC_START 7946 If you want to return ICP_HIT for stale cache objects, set this 7947 option to 'on'. If you have sibling relationships with caches 7948 in other administrative domains, this should be 'off'. If you only 7949 have sibling relationships with caches under your control, 7950 it is probably okay to set this to 'on'. 7951 If set to 'on', your siblings should use the option "allow-miss" 7952 on their cache_peer lines for connecting to you. 7953DOC_END 7954 7955NAME: minimum_direct_hops 7956TYPE: int 7957DEFAULT: 4 7958LOC: Config.minDirectHops 7959DOC_START 7960 If using the ICMP pinging stuff, do direct fetches for sites 7961 which are no more than this many hops away. 7962DOC_END 7963 7964NAME: minimum_direct_rtt 7965COMMENT: (msec) 7966TYPE: int 7967DEFAULT: 400 7968LOC: Config.minDirectRtt 7969DOC_START 7970 If using the ICMP pinging stuff, do direct fetches for sites 7971 which are no more than this many rtt milliseconds away. 7972DOC_END 7973 7974NAME: netdb_low 7975TYPE: int 7976DEFAULT: 900 7977LOC: Config.Netdb.low 7978DOC_START 7979 The low water mark for the ICMP measurement database. 7980 7981 Note: high watermark controlled by netdb_high directive. 7982 7983 These watermarks are counts, not percents. The defaults are 7984 (low) 900 and (high) 1000. When the high water mark is 7985 reached, database entries will be deleted until the low 7986 mark is reached. 7987DOC_END 7988 7989NAME: netdb_high 7990TYPE: int 7991DEFAULT: 1000 7992LOC: Config.Netdb.high 7993DOC_START 7994 The high water mark for the ICMP measurement database. 7995 7996 Note: low watermark controlled by netdb_low directive. 7997 7998 These watermarks are counts, not percents. The defaults are 7999 (low) 900 and (high) 1000. When the high water mark is 8000 reached, database entries will be deleted until the low 8001 mark is reached. 8002DOC_END 8003 8004NAME: netdb_ping_period 8005TYPE: time_t 8006LOC: Config.Netdb.period 8007DEFAULT: 5 minutes 8008DOC_START 8009 The minimum period for measuring a site. There will be at 8010 least this much delay between successive pings to the same 8011 network. The default is five minutes. 8012DOC_END 8013 8014NAME: query_icmp 8015COMMENT: on|off 8016TYPE: onoff 8017DEFAULT: off 8018LOC: Config.onoff.query_icmp 8019DOC_START 8020 If you want to ask your peers to include ICMP data in their ICP 8021 replies, enable this option. 8022 8023 If your peer has configured Squid (during compilation) with 8024 '--enable-icmp' that peer will send ICMP pings to origin server 8025 sites of the URLs it receives. If you enable this option the 8026 ICP replies from that peer will include the ICMP data (if available). 8027 Then, when choosing a parent cache, Squid will choose the parent with 8028 the minimal RTT to the origin server. When this happens, the 8029 hierarchy field of the access.log will be 8030 "CLOSEST_PARENT_MISS". This option is off by default. 8031DOC_END 8032 8033NAME: test_reachability 8034COMMENT: on|off 8035TYPE: onoff 8036DEFAULT: off 8037LOC: Config.onoff.test_reachability 8038DOC_START 8039 When this is 'on', ICP MISS replies will be ICP_MISS_NOFETCH 8040 instead of ICP_MISS if the target host is NOT in the ICMP 8041 database, or has a zero RTT. 8042DOC_END 8043 8044NAME: icp_query_timeout 8045COMMENT: (msec) 8046DEFAULT: 0 8047DEFAULT_DOC: Dynamic detection. 8048TYPE: int 8049LOC: Config.Timeout.icp_query 8050DOC_START 8051 Normally Squid will automatically determine an optimal ICP 8052 query timeout value based on the round-trip-time of recent ICP 8053 queries. If you want to override the value determined by 8054 Squid, set this 'icp_query_timeout' to a non-zero value. This 8055 value is specified in MILLISECONDS, so, to use a 2-second 8056 timeout (the old default), you would write: 8057 8058 icp_query_timeout 2000 8059DOC_END 8060 8061NAME: maximum_icp_query_timeout 8062COMMENT: (msec) 8063DEFAULT: 2000 8064TYPE: int 8065LOC: Config.Timeout.icp_query_max 8066DOC_START 8067 Normally the ICP query timeout is determined dynamically. But 8068 sometimes it can lead to very large values (say 5 seconds). 8069 Use this option to put an upper limit on the dynamic timeout 8070 value. Do NOT use this option to always use a fixed (instead 8071 of a dynamic) timeout value. To set a fixed timeout see the 8072 'icp_query_timeout' directive. 8073DOC_END 8074 8075NAME: minimum_icp_query_timeout 8076COMMENT: (msec) 8077DEFAULT: 5 8078TYPE: int 8079LOC: Config.Timeout.icp_query_min 8080DOC_START 8081 Normally the ICP query timeout is determined dynamically. But 8082 sometimes it can lead to very small timeouts, even lower than 8083 the normal latency variance on your link due to traffic. 8084 Use this option to put an lower limit on the dynamic timeout 8085 value. Do NOT use this option to always use a fixed (instead 8086 of a dynamic) timeout value. To set a fixed timeout see the 8087 'icp_query_timeout' directive. 8088DOC_END 8089 8090NAME: background_ping_rate 8091COMMENT: time-units 8092TYPE: time_t 8093DEFAULT: 10 seconds 8094LOC: Config.backgroundPingRate 8095DOC_START 8096 Controls how often the ICP pings are sent to siblings that 8097 have background-ping set. 8098DOC_END 8099 8100COMMENT_START 8101 MULTICAST ICP OPTIONS 8102 ----------------------------------------------------------------------------- 8103COMMENT_END 8104 8105NAME: mcast_groups 8106TYPE: wordlist 8107LOC: Config.mcast_group_list 8108DEFAULT: none 8109DOC_START 8110 This tag specifies a list of multicast groups which your server 8111 should join to receive multicasted ICP queries. 8112 8113 NOTE! Be very careful what you put here! Be sure you 8114 understand the difference between an ICP _query_ and an ICP 8115 _reply_. This option is to be set only if you want to RECEIVE 8116 multicast queries. Do NOT set this option to SEND multicast 8117 ICP (use cache_peer for that). ICP replies are always sent via 8118 unicast, so this option does not affect whether or not you will 8119 receive replies from multicast group members. 8120 8121 You must be very careful to NOT use a multicast address which 8122 is already in use by another group of caches. 8123 8124 If you are unsure about multicast, please read the Multicast 8125 chapter in the Squid FAQ (http://www.squid-cache.org/FAQ/). 8126 8127 Usage: mcast_groups 239.128.16.128 224.0.1.20 8128 8129 By default, Squid doesn't listen on any multicast groups. 8130DOC_END 8131 8132NAME: mcast_miss_addr 8133IFDEF: MULTICAST_MISS_STREAM 8134TYPE: address 8135LOC: Config.mcast_miss.addr 8136DEFAULT: no_addr 8137DEFAULT_DOC: disabled. 8138DOC_START 8139 If you enable this option, every "cache miss" URL will 8140 be sent out on the specified multicast address. 8141 8142 Do not enable this option unless you are are absolutely 8143 certain you understand what you are doing. 8144DOC_END 8145 8146NAME: mcast_miss_ttl 8147IFDEF: MULTICAST_MISS_STREAM 8148TYPE: u_short 8149LOC: Config.mcast_miss.ttl 8150DEFAULT: 16 8151DOC_START 8152 This is the time-to-live value for packets multicasted 8153 when multicasting off cache miss URLs is enabled. By 8154 default this is set to 'site scope', i.e. 16. 8155DOC_END 8156 8157NAME: mcast_miss_port 8158IFDEF: MULTICAST_MISS_STREAM 8159TYPE: u_short 8160LOC: Config.mcast_miss.port 8161DEFAULT: 3135 8162DOC_START 8163 This is the port number to be used in conjunction with 8164 'mcast_miss_addr'. 8165DOC_END 8166 8167NAME: mcast_miss_encode_key 8168IFDEF: MULTICAST_MISS_STREAM 8169TYPE: string 8170LOC: Config.mcast_miss.encode_key 8171DEFAULT: XXXXXXXXXXXXXXXX 8172DOC_START 8173 The URLs that are sent in the multicast miss stream are 8174 encrypted. This is the encryption key. 8175DOC_END 8176 8177NAME: mcast_icp_query_timeout 8178COMMENT: (msec) 8179DEFAULT: 2000 8180TYPE: int 8181LOC: Config.Timeout.mcast_icp_query 8182DOC_START 8183 For multicast peers, Squid regularly sends out ICP "probes" to 8184 count how many other peers are listening on the given multicast 8185 address. This value specifies how long Squid should wait to 8186 count all the replies. The default is 2000 msec, or 2 8187 seconds. 8188DOC_END 8189 8190COMMENT_START 8191 INTERNAL ICON OPTIONS 8192 ----------------------------------------------------------------------------- 8193COMMENT_END 8194 8195NAME: icon_directory 8196TYPE: string 8197LOC: Config.icons.directory 8198DEFAULT: @DEFAULT_ICON_DIR@ 8199DOC_START 8200 Where the icons are stored. These are normally kept in 8201 @DEFAULT_ICON_DIR@ 8202DOC_END 8203 8204NAME: global_internal_static 8205TYPE: onoff 8206LOC: Config.onoff.global_internal_static 8207DEFAULT: on 8208DOC_START 8209 This directive controls is Squid should intercept all requests for 8210 /squid-internal-static/ no matter which host the URL is requesting 8211 (default on setting), or if nothing special should be done for 8212 such URLs (off setting). The purpose of this directive is to make 8213 icons etc work better in complex cache hierarchies where it may 8214 not always be possible for all corners in the cache mesh to reach 8215 the server generating a directory listing. 8216DOC_END 8217 8218NAME: short_icon_urls 8219TYPE: onoff 8220LOC: Config.icons.use_short_names 8221DEFAULT: on 8222DOC_START 8223 If this is enabled Squid will use short URLs for icons. 8224 If disabled it will revert to the old behavior of including 8225 it's own name and port in the URL. 8226 8227 If you run a complex cache hierarchy with a mix of Squid and 8228 other proxies you may need to disable this directive. 8229DOC_END 8230 8231COMMENT_START 8232 ERROR PAGE OPTIONS 8233 ----------------------------------------------------------------------------- 8234COMMENT_END 8235 8236NAME: error_directory 8237TYPE: string 8238LOC: Config.errorDirectory 8239DEFAULT: none 8240DEFAULT_DOC: Send error pages in the clients preferred language 8241DOC_START 8242 If you wish to create your own versions of the default 8243 error files to customize them to suit your company copy 8244 the error/template files to another directory and point 8245 this tag at them. 8246 8247 WARNING: This option will disable multi-language support 8248 on error pages if used. 8249 8250 The squid developers are interested in making squid available in 8251 a wide variety of languages. If you are making translations for a 8252 language that Squid does not currently provide please consider 8253 contributing your translation back to the project. 8254 http://wiki.squid-cache.org/Translations 8255 8256 The squid developers working on translations are happy to supply drop-in 8257 translated error files in exchange for any new language contributions. 8258DOC_END 8259 8260NAME: error_default_language 8261IFDEF: USE_ERR_LOCALES 8262TYPE: string 8263LOC: Config.errorDefaultLanguage 8264DEFAULT: none 8265DEFAULT_DOC: Generate English language pages. 8266DOC_START 8267 Set the default language which squid will send error pages in 8268 if no existing translation matches the clients language 8269 preferences. 8270 8271 If unset (default) generic English will be used. 8272 8273 The squid developers are interested in making squid available in 8274 a wide variety of languages. If you are interested in making 8275 translations for any language see the squid wiki for details. 8276 http://wiki.squid-cache.org/Translations 8277DOC_END 8278 8279NAME: error_log_languages 8280IFDEF: USE_ERR_LOCALES 8281TYPE: onoff 8282LOC: Config.errorLogMissingLanguages 8283DEFAULT: on 8284DOC_START 8285 Log to cache.log what languages users are attempting to 8286 auto-negotiate for translations. 8287 8288 Successful negotiations are not logged. Only failures 8289 have meaning to indicate that Squid may need an upgrade 8290 of its error page translations. 8291DOC_END 8292 8293NAME: err_page_stylesheet 8294TYPE: string 8295LOC: Config.errorStylesheet 8296DEFAULT: @DEFAULT_CONFIG_DIR@/errorpage.css 8297DOC_START 8298 CSS Stylesheet to pattern the display of Squid default error pages. 8299 8300 For information on CSS see http://www.w3.org/Style/CSS/ 8301DOC_END 8302 8303NAME: err_html_text 8304TYPE: eol 8305LOC: Config.errHtmlText 8306DEFAULT: none 8307DOC_START 8308 HTML text to include in error messages. Make this a "mailto" 8309 URL to your admin address, or maybe just a link to your 8310 organizations Web page. 8311 8312 To include this in your error messages, you must rewrite 8313 the error template files (found in the "errors" directory). 8314 Wherever you want the 'err_html_text' line to appear, 8315 insert a %L tag in the error template file. 8316DOC_END 8317 8318NAME: email_err_data 8319COMMENT: on|off 8320TYPE: onoff 8321LOC: Config.onoff.emailErrData 8322DEFAULT: on 8323DOC_START 8324 If enabled, information about the occurred error will be 8325 included in the mailto links of the ERR pages (if %W is set) 8326 so that the email body contains the data. 8327 Syntax is <A HREF="mailto:%w%W">%w</A> 8328DOC_END 8329 8330NAME: deny_info 8331TYPE: denyinfo 8332LOC: Config.denyInfoList 8333DEFAULT: none 8334DOC_START 8335 Usage: deny_info err_page_name acl 8336 or deny_info http://... acl 8337 or deny_info TCP_RESET acl 8338 8339 This can be used to return a ERR_ page for requests which 8340 do not pass the 'http_access' rules. Squid remembers the last 8341 acl it evaluated in http_access, and if a 'deny_info' line exists 8342 for that ACL Squid returns a corresponding error page. 8343 8344 The acl is typically the last acl on the http_access deny line which 8345 denied access. The exceptions to this rule are: 8346 - When Squid needs to request authentication credentials. It's then 8347 the first authentication related acl encountered 8348 - When none of the http_access lines matches. It's then the last 8349 acl processed on the last http_access line. 8350 - When the decision to deny access was made by an adaptation service, 8351 the acl name is the corresponding eCAP or ICAP service_name. 8352 8353 NP: If providing your own custom error pages with error_directory 8354 you may also specify them by your custom file name: 8355 Example: deny_info ERR_CUSTOM_ACCESS_DENIED bad_guys 8356 8357 By defaut Squid will send "403 Forbidden". A different 4xx or 5xx 8358 may be specified by prefixing the file name with the code and a colon. 8359 e.g. 404:ERR_CUSTOM_ACCESS_DENIED 8360 8361 Alternatively you can tell Squid to reset the TCP connection 8362 by specifying TCP_RESET. 8363 8364 Or you can specify an error URL or URL pattern. The browsers will 8365 get redirected to the specified URL after formatting tags have 8366 been replaced. Redirect will be done with 302 or 307 according to 8367 HTTP/1.1 specs. A different 3xx code may be specified by prefixing 8368 the URL. e.g. 303:http://example.com/ 8369 8370 URL FORMAT TAGS: 8371 %a - username (if available. Password NOT included) 8372 %B - FTP path URL 8373 %e - Error number 8374 %E - Error description 8375 %h - Squid hostname 8376 %H - Request domain name 8377 %i - Client IP Address 8378 %M - Request Method 8379 %O - Unescaped message result from external ACL helper 8380 %o - Message result from external ACL helper 8381 %p - Request Port number 8382 %P - Request Protocol name 8383 %R - Request URL path 8384 %T - Timestamp in RFC 1123 format 8385 %U - Full canonical URL from client 8386 (HTTPS URLs terminate with *) 8387 %u - Full canonical URL from client 8388 %w - Admin email from squid.conf 8389 %x - Error name 8390 %% - Literal percent (%) code 8391 8392DOC_END 8393 8394COMMENT_START 8395 OPTIONS INFLUENCING REQUEST FORWARDING 8396 ----------------------------------------------------------------------------- 8397COMMENT_END 8398 8399NAME: nonhierarchical_direct 8400TYPE: onoff 8401LOC: Config.onoff.nonhierarchical_direct 8402DEFAULT: on 8403DOC_START 8404 By default, Squid will send any non-hierarchical requests 8405 (not cacheable request type) direct to origin servers. 8406 8407 When this is set to "off", Squid will prefer to send these 8408 requests to parents. 8409 8410 Note that in most configurations, by turning this off you will only 8411 add latency to these request without any improvement in global hit 8412 ratio. 8413 8414 This option only sets a preference. If the parent is unavailable a 8415 direct connection to the origin server may still be attempted. To 8416 completely prevent direct connections use never_direct. 8417DOC_END 8418 8419NAME: prefer_direct 8420TYPE: onoff 8421LOC: Config.onoff.prefer_direct 8422DEFAULT: off 8423DOC_START 8424 Normally Squid tries to use parents for most requests. If you for some 8425 reason like it to first try going direct and only use a parent if 8426 going direct fails set this to on. 8427 8428 By combining nonhierarchical_direct off and prefer_direct on you 8429 can set up Squid to use a parent as a backup path if going direct 8430 fails. 8431 8432 Note: If you want Squid to use parents for all requests see 8433 the never_direct directive. prefer_direct only modifies how Squid 8434 acts on cacheable requests. 8435DOC_END 8436 8437NAME: cache_miss_revalidate 8438COMMENT: on|off 8439TYPE: onoff 8440DEFAULT: on 8441LOC: Config.onoff.cache_miss_revalidate 8442DOC_START 8443 RFC 7232 defines a conditional request mechanism to prevent 8444 response objects being unnecessarily transferred over the network. 8445 If that mechanism is used by the client and a cache MISS occurs 8446 it can prevent new cache entries being created. 8447 8448 This option determines whether Squid on cache MISS will pass the 8449 client revalidation request to the server or tries to fetch new 8450 content for caching. It can be useful while the cache is mostly 8451 empty to more quickly have the cache populated by generating 8452 non-conditional GETs. 8453 8454 When set to 'on' (default), Squid will pass all client If-* headers 8455 to the server. This permits server responses without a cacheable 8456 payload to be delivered and on MISS no new cache entry is created. 8457 8458 When set to 'off' and if the request is cacheable, Squid will 8459 remove the clients If-Modified-Since and If-None-Match headers from 8460 the request sent to the server. This requests a 200 status response 8461 from the server to create a new cache entry with. 8462DOC_END 8463 8464NAME: always_direct 8465TYPE: acl_access 8466LOC: Config.accessList.AlwaysDirect 8467DEFAULT: none 8468DEFAULT_DOC: Prevent any cache_peer being used for this request. 8469DOC_START 8470 Usage: always_direct allow|deny [!]aclname ... 8471 8472 Here you can use ACL elements to specify requests which should 8473 ALWAYS be forwarded by Squid to the origin servers without using 8474 any peers. For example, to always directly forward requests for 8475 local servers ignoring any parents or siblings you may have use 8476 something like: 8477 8478 acl local-servers dstdomain my.domain.net 8479 always_direct allow local-servers 8480 8481 To always forward FTP requests directly, use 8482 8483 acl FTP proto FTP 8484 always_direct allow FTP 8485 8486 NOTE: There is a similar, but opposite option named 8487 'never_direct'. You need to be aware that "always_direct deny 8488 foo" is NOT the same thing as "never_direct allow foo". You 8489 may need to use a deny rule to exclude a more-specific case of 8490 some other rule. Example: 8491 8492 acl local-external dstdomain external.foo.net 8493 acl local-servers dstdomain .foo.net 8494 always_direct deny local-external 8495 always_direct allow local-servers 8496 8497 NOTE: If your goal is to make the client forward the request 8498 directly to the origin server bypassing Squid then this needs 8499 to be done in the client configuration. Squid configuration 8500 can only tell Squid how Squid should fetch the object. 8501 8502 NOTE: This directive is not related to caching. The replies 8503 is cached as usual even if you use always_direct. To not cache 8504 the replies see the 'cache' directive. 8505 8506 This clause supports both fast and slow acl types. 8507 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 8508DOC_END 8509 8510NAME: never_direct 8511TYPE: acl_access 8512LOC: Config.accessList.NeverDirect 8513DEFAULT: none 8514DEFAULT_DOC: Allow DNS results to be used for this request. 8515DOC_START 8516 Usage: never_direct allow|deny [!]aclname ... 8517 8518 never_direct is the opposite of always_direct. Please read 8519 the description for always_direct if you have not already. 8520 8521 With 'never_direct' you can use ACL elements to specify 8522 requests which should NEVER be forwarded directly to origin 8523 servers. For example, to force the use of a proxy for all 8524 requests, except those in your local domain use something like: 8525 8526 acl local-servers dstdomain .foo.net 8527 never_direct deny local-servers 8528 never_direct allow all 8529 8530 or if Squid is inside a firewall and there are local intranet 8531 servers inside the firewall use something like: 8532 8533 acl local-intranet dstdomain .foo.net 8534 acl local-external dstdomain external.foo.net 8535 always_direct deny local-external 8536 always_direct allow local-intranet 8537 never_direct allow all 8538 8539 This clause supports both fast and slow acl types. 8540 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 8541DOC_END 8542 8543COMMENT_START 8544 ADVANCED NETWORKING OPTIONS 8545 ----------------------------------------------------------------------------- 8546COMMENT_END 8547 8548NAME: incoming_udp_average incoming_icp_average 8549TYPE: int 8550DEFAULT: 6 8551LOC: Config.comm_incoming.udp.average 8552DOC_START 8553 Heavy voodoo here. I can't even believe you are reading this. 8554 Are you crazy? Don't even think about adjusting these unless 8555 you understand the algorithms in comm_select.c first! 8556DOC_END 8557 8558NAME: incoming_tcp_average incoming_http_average 8559TYPE: int 8560DEFAULT: 4 8561LOC: Config.comm_incoming.tcp.average 8562DOC_START 8563 Heavy voodoo here. I can't even believe you are reading this. 8564 Are you crazy? Don't even think about adjusting these unless 8565 you understand the algorithms in comm_select.c first! 8566DOC_END 8567 8568NAME: incoming_dns_average 8569TYPE: int 8570DEFAULT: 4 8571LOC: Config.comm_incoming.dns.average 8572DOC_START 8573 Heavy voodoo here. I can't even believe you are reading this. 8574 Are you crazy? Don't even think about adjusting these unless 8575 you understand the algorithms in comm_select.c first! 8576DOC_END 8577 8578NAME: min_udp_poll_cnt min_icp_poll_cnt 8579TYPE: int 8580DEFAULT: 8 8581LOC: Config.comm_incoming.udp.min_poll 8582DOC_START 8583 Heavy voodoo here. I can't even believe you are reading this. 8584 Are you crazy? Don't even think about adjusting these unless 8585 you understand the algorithms in comm_select.c first! 8586DOC_END 8587 8588NAME: min_dns_poll_cnt 8589TYPE: int 8590DEFAULT: 8 8591LOC: Config.comm_incoming.dns.min_poll 8592DOC_START 8593 Heavy voodoo here. I can't even believe you are reading this. 8594 Are you crazy? Don't even think about adjusting these unless 8595 you understand the algorithms in comm_select.c first! 8596DOC_END 8597 8598NAME: min_tcp_poll_cnt min_http_poll_cnt 8599TYPE: int 8600DEFAULT: 8 8601LOC: Config.comm_incoming.tcp.min_poll 8602DOC_START 8603 Heavy voodoo here. I can't even believe you are reading this. 8604 Are you crazy? Don't even think about adjusting these unless 8605 you understand the algorithms in comm_select.c first! 8606DOC_END 8607 8608NAME: accept_filter 8609TYPE: string 8610DEFAULT: none 8611LOC: Config.accept_filter 8612DOC_START 8613 FreeBSD: 8614 8615 The name of an accept(2) filter to install on Squid's 8616 listen socket(s). This feature is perhaps specific to 8617 FreeBSD and requires support in the kernel. 8618 8619 The 'httpready' filter delays delivering new connections 8620 to Squid until a full HTTP request has been received. 8621 See the accf_http(9) man page for details. 8622 8623 The 'dataready' filter delays delivering new connections 8624 to Squid until there is some data to process. 8625 See the accf_dataready(9) man page for details. 8626 8627 Linux: 8628 8629 The 'data' filter delays delivering of new connections 8630 to Squid until there is some data to process by TCP_ACCEPT_DEFER. 8631 You may optionally specify a number of seconds to wait by 8632 'data=N' where N is the number of seconds. Defaults to 30 8633 if not specified. See the tcp(7) man page for details. 8634EXAMPLE: 8635# FreeBSD 8636accept_filter httpready 8637# Linux 8638accept_filter data 8639DOC_END 8640 8641NAME: client_ip_max_connections 8642TYPE: int 8643LOC: Config.client_ip_max_connections 8644DEFAULT: -1 8645DEFAULT_DOC: No limit. 8646DOC_START 8647 Set an absolute limit on the number of connections a single 8648 client IP can use. Any more than this and Squid will begin to drop 8649 new connections from the client until it closes some links. 8650 8651 Note that this is a global limit. It affects all HTTP, HTCP, Gopher and FTP 8652 connections from the client. For finer control use the ACL access controls. 8653 8654 Requires client_db to be enabled (the default). 8655 8656 WARNING: This may noticably slow down traffic received via external proxies 8657 or NAT devices and cause them to rebound error messages back to their clients. 8658DOC_END 8659 8660NAME: tcp_recv_bufsize 8661COMMENT: (bytes) 8662TYPE: b_size_t 8663DEFAULT: 0 bytes 8664DEFAULT_DOC: Use operating system TCP defaults. 8665LOC: Config.tcpRcvBufsz 8666DOC_START 8667 Size of receive buffer to set for TCP sockets. Probably just 8668 as easy to change your kernel's default. 8669 Omit from squid.conf to use the default buffer size. 8670DOC_END 8671 8672COMMENT_START 8673 ICAP OPTIONS 8674 ----------------------------------------------------------------------------- 8675COMMENT_END 8676 8677NAME: icap_enable 8678TYPE: onoff 8679IFDEF: ICAP_CLIENT 8680COMMENT: on|off 8681LOC: Adaptation::Icap::TheConfig.onoff 8682DEFAULT: off 8683DOC_START 8684 If you want to enable the ICAP module support, set this to on. 8685DOC_END 8686 8687NAME: icap_connect_timeout 8688TYPE: time_t 8689DEFAULT: none 8690LOC: Adaptation::Icap::TheConfig.connect_timeout_raw 8691IFDEF: ICAP_CLIENT 8692DOC_START 8693 This parameter specifies how long to wait for the TCP connect to 8694 the requested ICAP server to complete before giving up and either 8695 terminating the HTTP transaction or bypassing the failure. 8696 8697 The default for optional services is peer_connect_timeout. 8698 The default for essential services is connect_timeout. 8699 If this option is explicitly set, its value applies to all services. 8700DOC_END 8701 8702NAME: icap_io_timeout 8703COMMENT: time-units 8704TYPE: time_t 8705DEFAULT: none 8706DEFAULT_DOC: Use read_timeout. 8707LOC: Adaptation::Icap::TheConfig.io_timeout_raw 8708IFDEF: ICAP_CLIENT 8709DOC_START 8710 This parameter specifies how long to wait for an I/O activity on 8711 an established, active ICAP connection before giving up and 8712 either terminating the HTTP transaction or bypassing the 8713 failure. 8714DOC_END 8715 8716NAME: icap_service_failure_limit 8717COMMENT: limit [in memory-depth time-units] 8718TYPE: icap_service_failure_limit 8719IFDEF: ICAP_CLIENT 8720LOC: Adaptation::Icap::TheConfig 8721DEFAULT: 10 8722DOC_START 8723 The limit specifies the number of failures that Squid tolerates 8724 when establishing a new TCP connection with an ICAP service. If 8725 the number of failures exceeds the limit, the ICAP service is 8726 not used for new ICAP requests until it is time to refresh its 8727 OPTIONS. 8728 8729 A negative value disables the limit. Without the limit, an ICAP 8730 service will not be considered down due to connectivity failures 8731 between ICAP OPTIONS requests. 8732 8733 Squid forgets ICAP service failures older than the specified 8734 value of memory-depth. The memory fading algorithm 8735 is approximate because Squid does not remember individual 8736 errors but groups them instead, splitting the option 8737 value into ten time slots of equal length. 8738 8739 When memory-depth is 0 and by default this option has no 8740 effect on service failure expiration. 8741 8742 Squid always forgets failures when updating service settings 8743 using an ICAP OPTIONS transaction, regardless of this option 8744 setting. 8745 8746 For example, 8747 # suspend service usage after 10 failures in 5 seconds: 8748 icap_service_failure_limit 10 in 5 seconds 8749DOC_END 8750 8751NAME: icap_service_revival_delay 8752TYPE: int 8753IFDEF: ICAP_CLIENT 8754LOC: Adaptation::Icap::TheConfig.service_revival_delay 8755DEFAULT: 180 8756DOC_START 8757 The delay specifies the number of seconds to wait after an ICAP 8758 OPTIONS request failure before requesting the options again. The 8759 failed ICAP service is considered "down" until fresh OPTIONS are 8760 fetched. 8761 8762 The actual delay cannot be smaller than the hardcoded minimum 8763 delay of 30 seconds. 8764DOC_END 8765 8766NAME: icap_preview_enable 8767TYPE: onoff 8768IFDEF: ICAP_CLIENT 8769COMMENT: on|off 8770LOC: Adaptation::Icap::TheConfig.preview_enable 8771DEFAULT: on 8772DOC_START 8773 The ICAP Preview feature allows the ICAP server to handle the 8774 HTTP message by looking only at the beginning of the message body 8775 or even without receiving the body at all. In some environments, 8776 previews greatly speedup ICAP processing. 8777 8778 During an ICAP OPTIONS transaction, the server may tell Squid what 8779 HTTP messages should be previewed and how big the preview should be. 8780 Squid will not use Preview if the server did not request one. 8781 8782 To disable ICAP Preview for all ICAP services, regardless of 8783 individual ICAP server OPTIONS responses, set this option to "off". 8784Example: 8785icap_preview_enable off 8786DOC_END 8787 8788NAME: icap_preview_size 8789TYPE: int 8790IFDEF: ICAP_CLIENT 8791LOC: Adaptation::Icap::TheConfig.preview_size 8792DEFAULT: -1 8793DEFAULT_DOC: No preview sent. 8794DOC_START 8795 The default size of preview data to be sent to the ICAP server. 8796 This value might be overwritten on a per server basis by OPTIONS requests. 8797DOC_END 8798 8799NAME: icap_206_enable 8800TYPE: onoff 8801IFDEF: ICAP_CLIENT 8802COMMENT: on|off 8803LOC: Adaptation::Icap::TheConfig.allow206_enable 8804DEFAULT: on 8805DOC_START 8806 206 (Partial Content) responses is an ICAP extension that allows the 8807 ICAP agents to optionally combine adapted and original HTTP message 8808 content. The decision to combine is postponed until the end of the 8809 ICAP response. Squid supports Partial Content extension by default. 8810 8811 Activation of the Partial Content extension is negotiated with each 8812 ICAP service during OPTIONS exchange. Most ICAP servers should handle 8813 negotation correctly even if they do not support the extension, but 8814 some might fail. To disable Partial Content support for all ICAP 8815 services and to avoid any negotiation, set this option to "off". 8816 8817 Example: 8818 icap_206_enable off 8819DOC_END 8820 8821NAME: icap_default_options_ttl 8822TYPE: int 8823IFDEF: ICAP_CLIENT 8824LOC: Adaptation::Icap::TheConfig.default_options_ttl 8825DEFAULT: 60 8826DOC_START 8827 The default TTL value for ICAP OPTIONS responses that don't have 8828 an Options-TTL header. 8829DOC_END 8830 8831NAME: icap_persistent_connections 8832TYPE: onoff 8833IFDEF: ICAP_CLIENT 8834COMMENT: on|off 8835LOC: Adaptation::Icap::TheConfig.reuse_connections 8836DEFAULT: on 8837DOC_START 8838 Whether or not Squid should use persistent connections to 8839 an ICAP server. 8840DOC_END 8841 8842NAME: adaptation_send_client_ip icap_send_client_ip 8843TYPE: onoff 8844IFDEF: USE_ADAPTATION 8845COMMENT: on|off 8846LOC: Adaptation::Config::send_client_ip 8847DEFAULT: off 8848DOC_START 8849 If enabled, Squid shares HTTP client IP information with adaptation 8850 services. For ICAP, Squid adds the X-Client-IP header to ICAP requests. 8851 For eCAP, Squid sets the libecap::metaClientIp transaction option. 8852 8853 See also: adaptation_uses_indirect_client 8854DOC_END 8855 8856NAME: adaptation_send_username icap_send_client_username 8857TYPE: onoff 8858IFDEF: USE_ADAPTATION 8859COMMENT: on|off 8860LOC: Adaptation::Config::send_username 8861DEFAULT: off 8862DOC_START 8863 This sends authenticated HTTP client username (if available) to 8864 the adaptation service. 8865 8866 For ICAP, the username value is encoded based on the 8867 icap_client_username_encode option and is sent using the header 8868 specified by the icap_client_username_header option. 8869DOC_END 8870 8871NAME: icap_client_username_header 8872TYPE: string 8873IFDEF: ICAP_CLIENT 8874LOC: Adaptation::Icap::TheConfig.client_username_header 8875DEFAULT: X-Client-Username 8876DOC_START 8877 ICAP request header name to use for adaptation_send_username. 8878DOC_END 8879 8880NAME: icap_client_username_encode 8881TYPE: onoff 8882IFDEF: ICAP_CLIENT 8883COMMENT: on|off 8884LOC: Adaptation::Icap::TheConfig.client_username_encode 8885DEFAULT: off 8886DOC_START 8887 Whether to base64 encode the authenticated client username. 8888DOC_END 8889 8890NAME: icap_service 8891TYPE: icap_service_type 8892IFDEF: ICAP_CLIENT 8893LOC: Adaptation::Icap::TheConfig 8894DEFAULT: none 8895DOC_START 8896 Defines a single ICAP service using the following format: 8897 8898 icap_service id vectoring_point uri [option ...] 8899 8900 id: ID 8901 an opaque identifier or name which is used to direct traffic to 8902 this specific service. Must be unique among all adaptation 8903 services in squid.conf. 8904 8905 vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache 8906 This specifies at which point of transaction processing the 8907 ICAP service should be activated. *_postcache vectoring points 8908 are not yet supported. 8909 8910 uri: icap://servername:port/servicepath 8911 ICAP server and service location. 8912 icaps://servername:port/servicepath 8913 The "icap:" URI scheme is used for traditional ICAP server and 8914 service location (default port is 1344, connections are not 8915 encrypted). The "icaps:" URI scheme is for Secure ICAP 8916 services that use SSL/TLS-encrypted ICAP connections (by 8917 default, on port 11344). 8918 8919 ICAP does not allow a single service to handle both REQMOD and RESPMOD 8920 transactions. Squid does not enforce that requirement. You can specify 8921 services with the same service_url and different vectoring_points. You 8922 can even specify multiple identical services as long as their 8923 service_names differ. 8924 8925 To activate a service, use the adaptation_access directive. To group 8926 services, use adaptation_service_chain and adaptation_service_set. 8927 8928 Service options are separated by white space. ICAP services support 8929 the following name=value options: 8930 8931 bypass=on|off|1|0 8932 If set to 'on' or '1', the ICAP service is treated as 8933 optional. If the service cannot be reached or malfunctions, 8934 Squid will try to ignore any errors and process the message as 8935 if the service was not enabled. No all ICAP errors can be 8936 bypassed. If set to 0, the ICAP service is treated as 8937 essential and all ICAP errors will result in an error page 8938 returned to the HTTP client. 8939 8940 Bypass is off by default: services are treated as essential. 8941 8942 routing=on|off|1|0 8943 If set to 'on' or '1', the ICAP service is allowed to 8944 dynamically change the current message adaptation plan by 8945 returning a chain of services to be used next. The services 8946 are specified using the X-Next-Services ICAP response header 8947 value, formatted as a comma-separated list of service names. 8948 Each named service should be configured in squid.conf. Other 8949 services are ignored. An empty X-Next-Services value results 8950 in an empty plan which ends the current adaptation. 8951 8952 Dynamic adaptation plan may cross or cover multiple supported 8953 vectoring points in their natural processing order. 8954 8955 Routing is not allowed by default: the ICAP X-Next-Services 8956 response header is ignored. 8957 8958 ipv6=on|off 8959 Only has effect on split-stack systems. The default on those systems 8960 is to use IPv4-only connections. When set to 'on' this option will 8961 make Squid use IPv6-only connections to contact this ICAP service. 8962 8963 on-overload=block|bypass|wait|force 8964 If the service Max-Connections limit has been reached, do 8965 one of the following for each new ICAP transaction: 8966 * block: send an HTTP error response to the client 8967 * bypass: ignore the "over-connected" ICAP service 8968 * wait: wait (in a FIFO queue) for an ICAP connection slot 8969 * force: proceed, ignoring the Max-Connections limit 8970 8971 In SMP mode with N workers, each worker assumes the service 8972 connection limit is Max-Connections/N, even though not all 8973 workers may use a given service. 8974 8975 The default value is "bypass" if service is bypassable, 8976 otherwise it is set to "wait". 8977 8978 8979 max-conn=number 8980 Use the given number as the Max-Connections limit, regardless 8981 of the Max-Connections value given by the service, if any. 8982 8983 connection-encryption=on|off 8984 Determines the ICAP service effect on the connections_encrypted 8985 ACL. 8986 8987 The default is "on" for Secure ICAP services (i.e., those 8988 with the icaps:// service URIs scheme) and "off" for plain ICAP 8989 services. 8990 8991 Does not affect ICAP connections (e.g., does not turn Secure 8992 ICAP on or off). 8993 8994 ==== ICAPS / TLS OPTIONS ==== 8995 8996 These options are used for Secure ICAP (icaps://....) services only. 8997 8998 tls-cert=/path/to/ssl/certificate 8999 A client X.509 certificate to use when connecting to 9000 this ICAP server. 9001 9002 tls-key=/path/to/ssl/key 9003 The private key corresponding to the previous 9004 tls-cert= option. 9005 9006 If tls-key= is not specified tls-cert= is assumed to 9007 reference a PEM file containing both the certificate 9008 and private key. 9009 9010 tls-cipher=... The list of valid TLS/SSL ciphers to use when connecting 9011 to this icap server. 9012 9013 tls-min-version=1.N 9014 The minimum TLS protocol version to permit. To control 9015 SSLv3 use the tls-options= parameter. 9016 Supported Values: 1.0 (default), 1.1, 1.2 9017 9018 tls-options=... Specify various OpenSSL library options: 9019 9020 NO_SSLv3 Disallow the use of SSLv3 9021 9022 SINGLE_DH_USE 9023 Always create a new key when using 9024 temporary/ephemeral DH key exchanges 9025 9026 ALL Enable various bug workarounds 9027 suggested as "harmless" by OpenSSL 9028 Be warned that this reduces SSL/TLS 9029 strength to some attacks. 9030 9031 See the OpenSSL SSL_CTX_set_options documentation for a 9032 more complete list. Options relevant only to SSLv2 are 9033 not supported. 9034 9035 tls-cafile= PEM file containing CA certificates to use when verifying 9036 the icap server certificate. 9037 Use to specify intermediate CA certificate(s) if not sent 9038 by the server. Or the full CA chain for the server when 9039 using the tls-default-ca=off flag. 9040 May be repeated to load multiple files. 9041 9042 tls-capath=... A directory containing additional CA certificates to 9043 use when verifying the icap server certificate. 9044 Requires OpenSSL or LibreSSL. 9045 9046 tls-crlfile=... A certificate revocation list file to use when 9047 verifying the icap server certificate. 9048 9049 tls-flags=... Specify various flags modifying the Squid TLS implementation: 9050 9051 DONT_VERIFY_PEER 9052 Accept certificates even if they fail to 9053 verify. 9054 DONT_VERIFY_DOMAIN 9055 Don't verify the icap server certificate 9056 matches the server name 9057 9058 tls-default-ca[=off] 9059 Whether to use the system Trusted CAs. Default is ON. 9060 9061 tls-domain= The icap server name as advertised in it's certificate. 9062 Used for verifying the correctness of the received icap 9063 server certificate. If not specified the icap server 9064 hostname extracted from ICAP URI will be used. 9065 9066 Older icap_service format without optional named parameters is 9067 deprecated but supported for backward compatibility. 9068 9069Example: 9070icap_service svcBlocker reqmod_precache icap://icap1.mydomain.net:1344/reqmod bypass=0 9071icap_service svcLogger reqmod_precache icaps://icap2.mydomain.net:11344/reqmod routing=on 9072DOC_END 9073 9074NAME: icap_class 9075TYPE: icap_class_type 9076IFDEF: ICAP_CLIENT 9077LOC: none 9078DEFAULT: none 9079DOC_START 9080 This deprecated option was documented to define an ICAP service 9081 chain, even though it actually defined a set of similar, redundant 9082 services, and the chains were not supported. 9083 9084 To define a set of redundant services, please use the 9085 adaptation_service_set directive. For service chains, use 9086 adaptation_service_chain. 9087DOC_END 9088 9089NAME: icap_access 9090TYPE: icap_access_type 9091IFDEF: ICAP_CLIENT 9092LOC: none 9093DEFAULT: none 9094DOC_START 9095 This option is deprecated. Please use adaptation_access, which 9096 has the same ICAP functionality, but comes with better 9097 documentation, and eCAP support. 9098DOC_END 9099 9100COMMENT_START 9101 eCAP OPTIONS 9102 ----------------------------------------------------------------------------- 9103COMMENT_END 9104 9105NAME: ecap_enable 9106TYPE: onoff 9107IFDEF: USE_ECAP 9108COMMENT: on|off 9109LOC: Adaptation::Ecap::TheConfig.onoff 9110DEFAULT: off 9111DOC_START 9112 Controls whether eCAP support is enabled. 9113DOC_END 9114 9115NAME: ecap_service 9116TYPE: ecap_service_type 9117IFDEF: USE_ECAP 9118LOC: Adaptation::Ecap::TheConfig 9119DEFAULT: none 9120DOC_START 9121 Defines a single eCAP service 9122 9123 ecap_service id vectoring_point uri [option ...] 9124 9125 id: ID 9126 an opaque identifier or name which is used to direct traffic to 9127 this specific service. Must be unique among all adaptation 9128 services in squid.conf. 9129 9130 vectoring_point: reqmod_precache|reqmod_postcache|respmod_precache|respmod_postcache 9131 This specifies at which point of transaction processing the 9132 eCAP service should be activated. *_postcache vectoring points 9133 are not yet supported. 9134 9135 uri: ecap://vendor/service_name?custom&cgi=style¶meters=optional 9136 Squid uses the eCAP service URI to match this configuration 9137 line with one of the dynamically loaded services. Each loaded 9138 eCAP service must have a unique URI. Obtain the right URI from 9139 the service provider. 9140 9141 To activate a service, use the adaptation_access directive. To group 9142 services, use adaptation_service_chain and adaptation_service_set. 9143 9144 Service options are separated by white space. eCAP services support 9145 the following name=value options: 9146 9147 bypass=on|off|1|0 9148 If set to 'on' or '1', the eCAP service is treated as optional. 9149 If the service cannot be reached or malfunctions, Squid will try 9150 to ignore any errors and process the message as if the service 9151 was not enabled. No all eCAP errors can be bypassed. 9152 If set to 'off' or '0', the eCAP service is treated as essential 9153 and all eCAP errors will result in an error page returned to the 9154 HTTP client. 9155 9156 Bypass is off by default: services are treated as essential. 9157 9158 routing=on|off|1|0 9159 If set to 'on' or '1', the eCAP service is allowed to 9160 dynamically change the current message adaptation plan by 9161 returning a chain of services to be used next. 9162 9163 Dynamic adaptation plan may cross or cover multiple supported 9164 vectoring points in their natural processing order. 9165 9166 Routing is not allowed by default. 9167 9168 connection-encryption=on|off 9169 Determines the eCAP service effect on the connections_encrypted 9170 ACL. 9171 9172 Defaults to "on", which does not taint the master transaction 9173 w.r.t. that ACL. 9174 9175 Does not affect eCAP API calls. 9176 9177 Older ecap_service format without optional named parameters is 9178 deprecated but supported for backward compatibility. 9179 9180 9181Example: 9182ecap_service s1 reqmod_precache ecap://filters.R.us/leakDetector?on_error=block bypass=off 9183ecap_service s2 respmod_precache ecap://filters.R.us/virusFilter config=/etc/vf.cfg bypass=on 9184DOC_END 9185 9186NAME: loadable_modules 9187TYPE: wordlist 9188IFDEF: USE_LOADABLE_MODULES 9189LOC: Config.loadable_module_names 9190DEFAULT: none 9191DOC_START 9192 Instructs Squid to load the specified dynamic module(s) or activate 9193 preloaded module(s). 9194Example: 9195loadable_modules @DEFAULT_PREFIX@/lib/MinimalAdapter.so 9196DOC_END 9197 9198COMMENT_START 9199 MESSAGE ADAPTATION OPTIONS 9200 ----------------------------------------------------------------------------- 9201COMMENT_END 9202 9203NAME: adaptation_service_set 9204TYPE: adaptation_service_set_type 9205IFDEF: USE_ADAPTATION 9206LOC: none 9207DEFAULT: none 9208DOC_START 9209 9210 Configures an ordered set of similar, redundant services. This is 9211 useful when hot standby or backup adaptation servers are available. 9212 9213 adaptation_service_set set_name service_name1 service_name2 ... 9214 9215 The named services are used in the set declaration order. The first 9216 applicable adaptation service from the set is used first. The next 9217 applicable service is tried if and only if the transaction with the 9218 previous service fails and the message waiting to be adapted is still 9219 intact. 9220 9221 When adaptation starts, broken services are ignored as if they were 9222 not a part of the set. A broken service is a down optional service. 9223 9224 The services in a set must be attached to the same vectoring point 9225 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD). 9226 9227 If all services in a set are optional then adaptation failures are 9228 bypassable. If all services in the set are essential, then a 9229 transaction failure with one service may still be retried using 9230 another service from the set, but when all services fail, the master 9231 transaction fails as well. 9232 9233 A set may contain a mix of optional and essential services, but that 9234 is likely to lead to surprising results because broken services become 9235 ignored (see above), making previously bypassable failures fatal. 9236 Technically, it is the bypassability of the last failed service that 9237 matters. 9238 9239 See also: adaptation_access adaptation_service_chain 9240 9241Example: 9242adaptation_service_set svcBlocker urlFilterPrimary urlFilterBackup 9243adaptation service_set svcLogger loggerLocal loggerRemote 9244DOC_END 9245 9246NAME: adaptation_service_chain 9247TYPE: adaptation_service_chain_type 9248IFDEF: USE_ADAPTATION 9249LOC: none 9250DEFAULT: none 9251DOC_START 9252 9253 Configures a list of complementary services that will be applied 9254 one-by-one, forming an adaptation chain or pipeline. This is useful 9255 when Squid must perform different adaptations on the same message. 9256 9257 adaptation_service_chain chain_name service_name1 svc_name2 ... 9258 9259 The named services are used in the chain declaration order. The first 9260 applicable adaptation service from the chain is used first. The next 9261 applicable service is applied to the successful adaptation results of 9262 the previous service in the chain. 9263 9264 When adaptation starts, broken services are ignored as if they were 9265 not a part of the chain. A broken service is a down optional service. 9266 9267 Request satisfaction terminates the adaptation chain because Squid 9268 does not currently allow declaration of RESPMOD services at the 9269 "reqmod_precache" vectoring point (see icap_service or ecap_service). 9270 9271 The services in a chain must be attached to the same vectoring point 9272 (e.g., pre-cache) and use the same adaptation method (e.g., REQMOD). 9273 9274 A chain may contain a mix of optional and essential services. If an 9275 essential adaptation fails (or the failure cannot be bypassed for 9276 other reasons), the master transaction fails. Otherwise, the failure 9277 is bypassed as if the failed adaptation service was not in the chain. 9278 9279 See also: adaptation_access adaptation_service_set 9280 9281Example: 9282adaptation_service_chain svcRequest requestLogger urlFilter leakDetector 9283DOC_END 9284 9285NAME: adaptation_access 9286TYPE: adaptation_access_type 9287IFDEF: USE_ADAPTATION 9288LOC: none 9289DEFAULT: none 9290DEFAULT_DOC: Allow, unless rules exist in squid.conf. 9291DOC_START 9292 Sends an HTTP transaction to an ICAP or eCAP adaptation service. 9293 9294 adaptation_access service_name allow|deny [!]aclname... 9295 adaptation_access set_name allow|deny [!]aclname... 9296 9297 At each supported vectoring point, the adaptation_access 9298 statements are processed in the order they appear in this 9299 configuration file. Statements pointing to the following services 9300 are ignored (i.e., skipped without checking their ACL): 9301 9302 - services serving different vectoring points 9303 - "broken-but-bypassable" services 9304 - "up" services configured to ignore such transactions 9305 (e.g., based on the ICAP Transfer-Ignore header). 9306 9307 When a set_name is used, all services in the set are checked 9308 using the same rules, to find the first applicable one. See 9309 adaptation_service_set for details. 9310 9311 If an access list is checked and there is a match, the 9312 processing stops: For an "allow" rule, the corresponding 9313 adaptation service is used for the transaction. For a "deny" 9314 rule, no adaptation service is activated. 9315 9316 It is currently not possible to apply more than one adaptation 9317 service at the same vectoring point to the same HTTP transaction. 9318 9319 See also: icap_service and ecap_service 9320 9321Example: 9322adaptation_access service_1 allow all 9323DOC_END 9324 9325NAME: adaptation_service_iteration_limit 9326TYPE: int 9327IFDEF: USE_ADAPTATION 9328LOC: Adaptation::Config::service_iteration_limit 9329DEFAULT: 16 9330DOC_START 9331 Limits the number of iterations allowed when applying adaptation 9332 services to a message. If your longest adaptation set or chain 9333 may have more than 16 services, increase the limit beyond its 9334 default value of 16. If detecting infinite iteration loops sooner 9335 is critical, make the iteration limit match the actual number 9336 of services in your longest adaptation set or chain. 9337 9338 Infinite adaptation loops are most likely with routing services. 9339 9340 See also: icap_service routing=1 9341DOC_END 9342 9343NAME: adaptation_masterx_shared_names 9344TYPE: string 9345IFDEF: USE_ADAPTATION 9346LOC: Adaptation::Config::masterx_shared_name 9347DEFAULT: none 9348DOC_START 9349 For each master transaction (i.e., the HTTP request and response 9350 sequence, including all related ICAP and eCAP exchanges), Squid 9351 maintains a table of metadata. The table entries are (name, value) 9352 pairs shared among eCAP and ICAP exchanges. The table is destroyed 9353 with the master transaction. 9354 9355 This option specifies the table entry names that Squid must accept 9356 from and forward to the adaptation transactions. 9357 9358 An ICAP REQMOD or RESPMOD transaction may set an entry in the 9359 shared table by returning an ICAP header field with a name 9360 specified in adaptation_masterx_shared_names. 9361 9362 An eCAP REQMOD or RESPMOD transaction may set an entry in the 9363 shared table by implementing the libecap::visitEachOption() API 9364 to provide an option with a name specified in 9365 adaptation_masterx_shared_names. 9366 9367 Squid will store and forward the set entry to subsequent adaptation 9368 transactions within the same master transaction scope. 9369 9370 Only one shared entry name is supported at this time. 9371 9372Example: 9373# share authentication information among ICAP services 9374adaptation_masterx_shared_names X-Subscriber-ID 9375DOC_END 9376 9377NAME: adaptation_meta 9378TYPE: note 9379IFDEF: USE_ADAPTATION 9380LOC: Adaptation::Config::metaHeaders 9381DEFAULT: none 9382DOC_START 9383 This option allows Squid administrator to add custom ICAP request 9384 headers or eCAP options to Squid ICAP requests or eCAP transactions. 9385 Use it to pass custom authentication tokens and other 9386 transaction-state related meta information to an ICAP/eCAP service. 9387 9388 The addition of a meta header is ACL-driven: 9389 adaptation_meta name value [!]aclname ... 9390 9391 Processing for a given header name stops after the first ACL list match. 9392 Thus, it is impossible to add two headers with the same name. If no ACL 9393 lists match for a given header name, no such header is added. For 9394 example: 9395 9396 # do not debug transactions except for those that need debugging 9397 adaptation_meta X-Debug 1 needs_debugging 9398 9399 # log all transactions except for those that must remain secret 9400 adaptation_meta X-Log 1 !keep_secret 9401 9402 # mark transactions from users in the "G 1" group 9403 adaptation_meta X-Authenticated-Groups "G 1" authed_as_G1 9404 9405 The "value" parameter may be a regular squid.conf token or a "double 9406 quoted string". Within the quoted string, use backslash (\) to escape 9407 any character, which is currently only useful for escaping backslashes 9408 and double quotes. For example, 9409 "this string has one backslash (\\) and two \"quotes\"" 9410 9411 Used adaptation_meta header values may be logged via %note 9412 logformat code. If multiple adaptation_meta headers with the same name 9413 are used during master transaction lifetime, the header values are 9414 logged in the order they were used and duplicate values are ignored 9415 (only the first repeated value will be logged). 9416DOC_END 9417 9418NAME: icap_retry 9419TYPE: acl_access 9420IFDEF: ICAP_CLIENT 9421LOC: Adaptation::Icap::TheConfig.repeat 9422DEFAULT_IF_NONE: deny all 9423DOC_START 9424 This ACL determines which retriable ICAP transactions are 9425 retried. Transactions that received a complete ICAP response 9426 and did not have to consume or produce HTTP bodies to receive 9427 that response are usually retriable. 9428 9429 icap_retry allow|deny [!]aclname ... 9430 9431 Squid automatically retries some ICAP I/O timeouts and errors 9432 due to persistent connection race conditions. 9433 9434 See also: icap_retry_limit 9435DOC_END 9436 9437NAME: icap_retry_limit 9438TYPE: int 9439IFDEF: ICAP_CLIENT 9440LOC: Adaptation::Icap::TheConfig.repeat_limit 9441DEFAULT: 0 9442DEFAULT_DOC: No retries are allowed. 9443DOC_START 9444 Limits the number of retries allowed. 9445 9446 Communication errors due to persistent connection race 9447 conditions are unavoidable, automatically retried, and do not 9448 count against this limit. 9449 9450 See also: icap_retry 9451DOC_END 9452 9453 9454COMMENT_START 9455 DNS OPTIONS 9456 ----------------------------------------------------------------------------- 9457COMMENT_END 9458 9459NAME: check_hostnames 9460TYPE: onoff 9461DEFAULT: off 9462LOC: Config.onoff.check_hostnames 9463DOC_START 9464 For security and stability reasons Squid can check 9465 hostnames for Internet standard RFC compliance. If you want 9466 Squid to perform these checks turn this directive on. 9467DOC_END 9468 9469NAME: allow_underscore 9470TYPE: onoff 9471DEFAULT: on 9472LOC: Config.onoff.allow_underscore 9473DOC_START 9474 Underscore characters is not strictly allowed in Internet hostnames 9475 but nevertheless used by many sites. Set this to off if you want 9476 Squid to be strict about the standard. 9477 This check is performed only when check_hostnames is set to on. 9478DOC_END 9479 9480NAME: dns_retransmit_interval 9481TYPE: time_msec 9482DEFAULT: 5 seconds 9483LOC: Config.Timeout.idns_retransmit 9484DOC_START 9485 Initial retransmit interval for DNS queries. The interval is 9486 doubled each time all configured DNS servers have been tried. 9487DOC_END 9488 9489NAME: dns_timeout 9490TYPE: time_msec 9491DEFAULT: 30 seconds 9492LOC: Config.Timeout.idns_query 9493DOC_START 9494 DNS Query timeout. If no response is received to a DNS query 9495 within this time all DNS servers for the queried domain 9496 are assumed to be unavailable. 9497DOC_END 9498 9499NAME: dns_packet_max 9500TYPE: b_ssize_t 9501DEFAULT_DOC: EDNS disabled 9502DEFAULT: none 9503LOC: Config.dns.packet_max 9504DOC_START 9505 Maximum number of bytes packet size to advertise via EDNS. 9506 Set to "none" to disable EDNS large packet support. 9507 9508 For legacy reasons DNS UDP replies will default to 512 bytes which 9509 is too small for many responses. EDNS provides a means for Squid to 9510 negotiate receiving larger responses back immediately without having 9511 to failover with repeat requests. Responses larger than this limit 9512 will retain the old behaviour of failover to TCP DNS. 9513 9514 Squid has no real fixed limit internally, but allowing packet sizes 9515 over 1500 bytes requires network jumbogram support and is usually not 9516 necessary. 9517 9518 WARNING: The RFC also indicates that some older resolvers will reply 9519 with failure of the whole request if the extension is added. Some 9520 resolvers have already been identified which will reply with mangled 9521 EDNS response on occasion. Usually in response to many-KB jumbogram 9522 sizes being advertised by Squid. 9523 Squid will currently treat these both as an unable-to-resolve domain 9524 even if it would be resolvable without EDNS. 9525DOC_END 9526 9527NAME: dns_defnames 9528COMMENT: on|off 9529TYPE: onoff 9530DEFAULT: off 9531DEFAULT_DOC: Search for single-label domain names is disabled. 9532LOC: Config.onoff.res_defnames 9533DOC_START 9534 Normally the RES_DEFNAMES resolver option is disabled 9535 (see res_init(3)). This prevents caches in a hierarchy 9536 from interpreting single-component hostnames locally. To allow 9537 Squid to handle single-component names, enable this option. 9538DOC_END 9539 9540NAME: dns_multicast_local 9541COMMENT: on|off 9542TYPE: onoff 9543DEFAULT: off 9544DEFAULT_DOC: Search for .local and .arpa names is disabled. 9545LOC: Config.onoff.dns_mdns 9546DOC_START 9547 When set to on, Squid sends multicast DNS lookups on the local 9548 network for domains ending in .local and .arpa. 9549 This enables local servers and devices to be contacted in an 9550 ad-hoc or zero-configuration network environment. 9551DOC_END 9552 9553NAME: dns_nameservers 9554TYPE: wordlist 9555DEFAULT: none 9556DEFAULT_DOC: Use operating system definitions 9557LOC: Config.dns_nameservers 9558DOC_START 9559 Use this if you want to specify a list of DNS name servers 9560 (IP addresses) to use instead of those given in your 9561 /etc/resolv.conf file. 9562 9563 On Windows platforms, if no value is specified here or in 9564 the /etc/resolv.conf file, the list of DNS name servers are 9565 taken from the Windows registry, both static and dynamic DHCP 9566 configurations are supported. 9567 9568 Example: dns_nameservers 10.0.0.1 192.172.0.4 9569DOC_END 9570 9571NAME: hosts_file 9572TYPE: string 9573DEFAULT: @DEFAULT_HOSTS@ 9574LOC: Config.etcHostsPath 9575DOC_START 9576 Location of the host-local IP name-address associations 9577 database. Most Operating Systems have such a file on different 9578 default locations: 9579 - Un*X & Linux: /etc/hosts 9580 - Windows NT/2000: %SystemRoot%\system32\drivers\etc\hosts 9581 (%SystemRoot% value install default is c:\winnt) 9582 - Windows XP/2003: %SystemRoot%\system32\drivers\etc\hosts 9583 (%SystemRoot% value install default is c:\windows) 9584 - Windows 9x/Me: %windir%\hosts 9585 (%windir% value is usually c:\windows) 9586 - Cygwin: /etc/hosts 9587 9588 The file contains newline-separated definitions, in the 9589 form ip_address_in_dotted_form name [name ...] names are 9590 whitespace-separated. Lines beginning with an hash (#) 9591 character are comments. 9592 9593 The file is checked at startup and upon configuration. 9594 If set to 'none', it won't be checked. 9595 If append_domain is used, that domain will be added to 9596 domain-local (i.e. not containing any dot character) host 9597 definitions. 9598DOC_END 9599 9600NAME: append_domain 9601TYPE: string 9602LOC: Config.appendDomain 9603DEFAULT: none 9604DEFAULT_DOC: Use operating system definitions 9605DOC_START 9606 Appends local domain name to hostnames without any dots in 9607 them. append_domain must begin with a period. 9608 9609 Be warned there are now Internet names with no dots in 9610 them using only top-domain names, so setting this may 9611 cause some Internet sites to become unavailable. 9612 9613Example: 9614 append_domain .yourdomain.com 9615DOC_END 9616 9617NAME: ignore_unknown_nameservers 9618TYPE: onoff 9619LOC: Config.onoff.ignore_unknown_nameservers 9620DEFAULT: on 9621DOC_START 9622 By default Squid checks that DNS responses are received 9623 from the same IP addresses they are sent to. If they 9624 don't match, Squid ignores the response and writes a warning 9625 message to cache.log. You can allow responses from unknown 9626 nameservers by setting this option to 'off'. 9627DOC_END 9628 9629NAME: dns_v4_first 9630TYPE: onoff 9631DEFAULT: off 9632LOC: Config.dns.v4_first 9633DOC_START 9634 With the IPv6 Internet being as fast or faster than IPv4 Internet 9635 for most networks Squid prefers to contact websites over IPv6. 9636 9637 This option reverses the order of preference to make Squid contact 9638 dual-stack websites over IPv4 first. Squid will still perform both 9639 IPv6 and IPv4 DNS lookups before connecting. 9640 9641 WARNING: 9642 This option will restrict the situations under which IPv6 9643 connectivity is used (and tested). Hiding network problems 9644 which would otherwise be detected and warned about. 9645DOC_END 9646 9647NAME: ipcache_size 9648COMMENT: (number of entries) 9649TYPE: int 9650DEFAULT: 1024 9651LOC: Config.ipcache.size 9652DOC_START 9653 Maximum number of DNS IP cache entries. 9654DOC_END 9655 9656NAME: ipcache_low 9657COMMENT: (percent) 9658TYPE: int 9659DEFAULT: 90 9660LOC: Config.ipcache.low 9661DOC_NONE 9662 9663NAME: ipcache_high 9664COMMENT: (percent) 9665TYPE: int 9666DEFAULT: 95 9667LOC: Config.ipcache.high 9668DOC_START 9669 The size, low-, and high-water marks for the IP cache. 9670DOC_END 9671 9672NAME: fqdncache_size 9673COMMENT: (number of entries) 9674TYPE: int 9675DEFAULT: 1024 9676LOC: Config.fqdncache.size 9677DOC_START 9678 Maximum number of FQDN cache entries. 9679DOC_END 9680 9681COMMENT_START 9682 MISCELLANEOUS 9683 ----------------------------------------------------------------------------- 9684COMMENT_END 9685 9686NAME: configuration_includes_quoted_values 9687COMMENT: on|off 9688TYPE: configuration_includes_quoted_values 9689DEFAULT: off 9690LOC: ConfigParser::RecognizeQuotedValues 9691DOC_START 9692 If set, Squid will recognize each "quoted string" after a configuration 9693 directive as a single parameter. The quotes are stripped before the 9694 parameter value is interpreted or used. 9695 See "Values with spaces, quotes, and other special characters" 9696 section for more details. 9697DOC_END 9698 9699NAME: memory_pools 9700COMMENT: on|off 9701TYPE: onoff 9702DEFAULT: on 9703LOC: Config.onoff.mem_pools 9704DOC_START 9705 If set, Squid will keep pools of allocated (but unused) memory 9706 available for future use. If memory is a premium on your 9707 system and you believe your malloc library outperforms Squid 9708 routines, disable this. 9709DOC_END 9710 9711NAME: memory_pools_limit 9712COMMENT: (bytes) 9713TYPE: b_int64_t 9714DEFAULT: 5 MB 9715LOC: Config.MemPools.limit 9716DOC_START 9717 Used only with memory_pools on: 9718 memory_pools_limit 50 MB 9719 9720 If set to a non-zero value, Squid will keep at most the specified 9721 limit of allocated (but unused) memory in memory pools. All free() 9722 requests that exceed this limit will be handled by your malloc 9723 library. Squid does not pre-allocate any memory, just safe-keeps 9724 objects that otherwise would be free()d. Thus, it is safe to set 9725 memory_pools_limit to a reasonably high value even if your 9726 configuration will use less memory. 9727 9728 If set to none, Squid will keep all memory it can. That is, there 9729 will be no limit on the total amount of memory used for safe-keeping. 9730 9731 To disable memory allocation optimization, do not set 9732 memory_pools_limit to 0 or none. Set memory_pools to "off" instead. 9733 9734 An overhead for maintaining memory pools is not taken into account 9735 when the limit is checked. This overhead is close to four bytes per 9736 object kept. However, pools may actually _save_ memory because of 9737 reduced memory thrashing in your malloc library. 9738DOC_END 9739 9740NAME: forwarded_for 9741COMMENT: on|off|transparent|truncate|delete 9742TYPE: string 9743DEFAULT: on 9744LOC: opt_forwarded_for 9745DOC_START 9746 If set to "on", Squid will append your client's IP address 9747 in the HTTP requests it forwards. By default it looks like: 9748 9749 X-Forwarded-For: 192.1.2.3 9750 9751 If set to "off", it will appear as 9752 9753 X-Forwarded-For: unknown 9754 9755 If set to "transparent", Squid will not alter the 9756 X-Forwarded-For header in any way. 9757 9758 If set to "delete", Squid will delete the entire 9759 X-Forwarded-For header. 9760 9761 If set to "truncate", Squid will remove all existing 9762 X-Forwarded-For entries, and place the client IP as the sole entry. 9763DOC_END 9764 9765NAME: cachemgr_passwd 9766TYPE: cachemgrpasswd 9767DEFAULT: none 9768DEFAULT_DOC: No password. Actions which require password are denied. 9769LOC: Config.passwd_list 9770DOC_START 9771 Specify passwords for cachemgr operations. 9772 9773 Usage: cachemgr_passwd password action action ... 9774 9775 Some valid actions are (see cache manager menu for a full list): 9776 5min 9777 60min 9778 asndb 9779 authenticator 9780 cbdata 9781 client_list 9782 comm_incoming 9783 config * 9784 counters 9785 delay 9786 digest_stats 9787 dns 9788 events 9789 filedescriptors 9790 fqdncache 9791 histograms 9792 http_headers 9793 info 9794 io 9795 ipcache 9796 mem 9797 menu 9798 netdb 9799 non_peers 9800 objects 9801 offline_toggle * 9802 pconn 9803 peer_select 9804 reconfigure * 9805 redirector 9806 refresh 9807 server_list 9808 shutdown * 9809 store_digest 9810 storedir 9811 utilization 9812 via_headers 9813 vm_objects 9814 9815 * Indicates actions which will not be performed without a 9816 valid password, others can be performed if not listed here. 9817 9818 To disable an action, set the password to "disable". 9819 To allow performing an action without a password, set the 9820 password to "none". 9821 9822 Use the keyword "all" to set the same password for all actions. 9823 9824Example: 9825 cachemgr_passwd secret shutdown 9826 cachemgr_passwd lesssssssecret info stats/objects 9827 cachemgr_passwd disable all 9828DOC_END 9829 9830NAME: client_db 9831COMMENT: on|off 9832TYPE: onoff 9833DEFAULT: on 9834LOC: Config.onoff.client_db 9835DOC_START 9836 If you want to disable collecting per-client statistics, 9837 turn off client_db here. 9838DOC_END 9839 9840NAME: refresh_all_ims 9841COMMENT: on|off 9842TYPE: onoff 9843DEFAULT: off 9844LOC: Config.onoff.refresh_all_ims 9845DOC_START 9846 When you enable this option, squid will always check 9847 the origin server for an update when a client sends an 9848 If-Modified-Since request. Many browsers use IMS 9849 requests when the user requests a reload, and this 9850 ensures those clients receive the latest version. 9851 9852 By default (off), squid may return a Not Modified response 9853 based on the age of the cached version. 9854DOC_END 9855 9856NAME: reload_into_ims 9857IFDEF: USE_HTTP_VIOLATIONS 9858COMMENT: on|off 9859TYPE: onoff 9860DEFAULT: off 9861LOC: Config.onoff.reload_into_ims 9862DOC_START 9863 When you enable this option, client no-cache or ``reload'' 9864 requests will be changed to If-Modified-Since requests. 9865 Doing this VIOLATES the HTTP standard. Enabling this 9866 feature could make you liable for problems which it 9867 causes. 9868 9869 see also refresh_pattern for a more selective approach. 9870DOC_END 9871 9872NAME: connect_retries 9873TYPE: int 9874LOC: Config.connect_retries 9875DEFAULT: 0 9876DEFAULT_DOC: Do not retry failed connections. 9877DOC_START 9878 Limits the number of reopening attempts when establishing a single 9879 TCP connection. All these attempts must still complete before the 9880 applicable connection opening timeout expires. 9881 9882 By default and when connect_retries is set to zero, Squid does not 9883 retry failed connection opening attempts. 9884 9885 The (not recommended) maximum is 10 tries. An attempt to configure a 9886 higher value results in the value of 10 being used (with a warning). 9887 9888 Squid may open connections to retry various high-level forwarding 9889 failures. For an outside observer, that activity may look like a 9890 low-level connection reopening attempt, but those high-level retries 9891 are governed by forward_max_tries instead. 9892 9893 See also: connect_timeout, forward_timeout, icap_connect_timeout, 9894 ident_timeout, and forward_max_tries. 9895DOC_END 9896 9897NAME: retry_on_error 9898TYPE: onoff 9899LOC: Config.retry.onerror 9900DEFAULT: off 9901DOC_START 9902 If set to ON Squid will automatically retry requests when 9903 receiving an error response with status 403 (Forbidden), 9904 500 (Internal Error), 501 or 503 (Service not available). 9905 Status 502 and 504 (Gateway errors) are always retried. 9906 9907 This is mainly useful if you are in a complex cache hierarchy to 9908 work around access control errors. 9909 9910 NOTE: This retry will attempt to find another working destination. 9911 Which is different from the server which just failed. 9912DOC_END 9913 9914NAME: as_whois_server 9915TYPE: string 9916LOC: Config.as_whois_server 9917DEFAULT: whois.ra.net 9918DOC_START 9919 WHOIS server to query for AS numbers. NOTE: AS numbers are 9920 queried only when Squid starts up, not for every request. 9921DOC_END 9922 9923NAME: offline_mode 9924TYPE: onoff 9925LOC: Config.onoff.offline 9926DEFAULT: off 9927DOC_START 9928 Enable this option and Squid will never try to validate cached 9929 objects. 9930DOC_END 9931 9932NAME: uri_whitespace 9933TYPE: uri_whitespace 9934LOC: Config.uri_whitespace 9935DEFAULT: strip 9936DOC_START 9937 What to do with requests that have whitespace characters in the 9938 URI. Options: 9939 9940 strip: The whitespace characters are stripped out of the URL. 9941 This is the behavior recommended by RFC2396 and RFC3986 9942 for tolerant handling of generic URI. 9943 NOTE: This is one difference between generic URI and HTTP URLs. 9944 9945 deny: The request is denied. The user receives an "Invalid 9946 Request" message. 9947 This is the behaviour recommended by RFC2616 for safe 9948 handling of HTTP request URL. 9949 9950 allow: The request is allowed and the URI is not changed. The 9951 whitespace characters remain in the URI. Note the 9952 whitespace is passed to redirector processes if they 9953 are in use. 9954 Note this may be considered a violation of RFC2616 9955 request parsing where whitespace is prohibited in the 9956 URL field. 9957 9958 encode: The request is allowed and the whitespace characters are 9959 encoded according to RFC1738. 9960 9961 chop: The request is allowed and the URI is chopped at the 9962 first whitespace. 9963 9964 9965 NOTE the current Squid implementation of encode and chop violates 9966 RFC2616 by not using a 301 redirect after altering the URL. 9967DOC_END 9968 9969NAME: chroot 9970TYPE: string 9971LOC: Config.chroot_dir 9972DEFAULT: none 9973DOC_START 9974 Specifies a directory where Squid should do a chroot() while 9975 initializing. This also causes Squid to fully drop root 9976 privileges after initializing. This means, for example, if you 9977 use a HTTP port less than 1024 and try to reconfigure, you may 9978 get an error saying that Squid can not open the port. 9979DOC_END 9980 9981NAME: pipeline_prefetch 9982TYPE: pipelinePrefetch 9983LOC: Config.pipeline_max_prefetch 9984DEFAULT: 0 9985DEFAULT_DOC: Do not pre-parse pipelined requests. 9986DOC_START 9987 HTTP clients may send a pipeline of 1+N requests to Squid using a 9988 single connection, without waiting for Squid to respond to the first 9989 of those requests. This option limits the number of concurrent 9990 requests Squid will try to handle in parallel. If set to N, Squid 9991 will try to receive and process up to 1+N requests on the same 9992 connection concurrently. 9993 9994 Defaults to 0 (off) for bandwidth management and access logging 9995 reasons. 9996 9997 NOTE: pipelining requires persistent connections to clients. 9998 9999 WARNING: pipelining breaks NTLM and Negotiate/Kerberos authentication. 10000DOC_END 10001 10002NAME: high_response_time_warning 10003TYPE: int 10004COMMENT: (msec) 10005LOC: Config.warnings.high_rptm 10006DEFAULT: 0 10007DEFAULT_DOC: disabled. 10008DOC_START 10009 If the one-minute median response time exceeds this value, 10010 Squid prints a WARNING with debug level 0 to get the 10011 administrators attention. The value is in milliseconds. 10012DOC_END 10013 10014NAME: high_page_fault_warning 10015TYPE: int 10016LOC: Config.warnings.high_pf 10017DEFAULT: 0 10018DEFAULT_DOC: disabled. 10019DOC_START 10020 If the one-minute average page fault rate exceeds this 10021 value, Squid prints a WARNING with debug level 0 to get 10022 the administrators attention. The value is in page faults 10023 per second. 10024DOC_END 10025 10026NAME: high_memory_warning 10027TYPE: b_size_t 10028LOC: Config.warnings.high_memory 10029IFDEF: HAVE_MSTATS&&HAVE_GNUMALLOC_H 10030DEFAULT: 0 KB 10031DEFAULT_DOC: disabled. 10032DOC_START 10033 If the memory usage (as determined by gnumalloc, if available and used) 10034 exceeds this amount, Squid prints a WARNING with debug level 0 to get 10035 the administrators attention. 10036DOC_END 10037# TODO: link high_memory_warning to mempools? 10038 10039NAME: sleep_after_fork 10040COMMENT: (microseconds) 10041TYPE: int 10042LOC: Config.sleep_after_fork 10043DEFAULT: 0 10044DOC_START 10045 When this is set to a non-zero value, the main Squid process 10046 sleeps the specified number of microseconds after a fork() 10047 system call. This sleep may help the situation where your 10048 system reports fork() failures due to lack of (virtual) 10049 memory. Note, however, if you have a lot of child 10050 processes, these sleep delays will add up and your 10051 Squid will not service requests for some amount of time 10052 until all the child processes have been started. 10053 On Windows value less then 1000 (1 milliseconds) are 10054 rounded to 1000. 10055DOC_END 10056 10057NAME: windows_ipaddrchangemonitor 10058IFDEF: _SQUID_WINDOWS_ 10059COMMENT: on|off 10060TYPE: onoff 10061DEFAULT: on 10062LOC: Config.onoff.WIN32_IpAddrChangeMonitor 10063DOC_START 10064 On Windows Squid by default will monitor IP address changes and will 10065 reconfigure itself after any detected event. This is very useful for 10066 proxies connected to internet with dial-up interfaces. 10067 In some cases (a Proxy server acting as VPN gateway is one) it could be 10068 desiderable to disable this behaviour setting this to 'off'. 10069 Note: after changing this, Squid service must be restarted. 10070DOC_END 10071 10072NAME: eui_lookup 10073TYPE: onoff 10074IFDEF: USE_SQUID_EUI 10075DEFAULT: on 10076LOC: Eui::TheConfig.euiLookup 10077DOC_START 10078 Whether to lookup the EUI or MAC address of a connected client. 10079DOC_END 10080 10081NAME: max_filedescriptors max_filedesc 10082TYPE: int 10083DEFAULT: 0 10084DEFAULT_DOC: Use operating system soft limit set by ulimit. 10085LOC: Config.max_filedescriptors 10086DOC_START 10087 Set the maximum number of filedescriptors, either below the 10088 operating system default or up to the hard limit. 10089 10090 Remove from squid.conf to inherit the current ulimit soft 10091 limit setting. 10092 10093 Note: Changing this requires a restart of Squid. Also 10094 not all I/O types supports large values (eg on Windows). 10095DOC_END 10096 10097NAME: force_request_body_continuation 10098TYPE: acl_access 10099LOC: Config.accessList.forceRequestBodyContinuation 10100DEFAULT: none 10101DEFAULT_DOC: Deny, unless rules exist in squid.conf. 10102DOC_START 10103 This option controls how Squid handles data upload requests from HTTP 10104 and FTP agents that require a "Please Continue" control message response 10105 to actually send the request body to Squid. It is mostly useful in 10106 adaptation environments. 10107 10108 When Squid receives an HTTP request with an "Expect: 100-continue" 10109 header or an FTP upload command (e.g., STOR), Squid normally sends the 10110 request headers or FTP command information to an adaptation service (or 10111 peer) and waits for a response. Most adaptation services (and some 10112 broken peers) may not respond to Squid at that stage because they may 10113 decide to wait for the HTTP request body or FTP data transfer. However, 10114 that request body or data transfer may never come because Squid has not 10115 responded with the HTTP 100 or FTP 150 (Please Continue) control message 10116 to the request sender yet! 10117 10118 An allow match tells Squid to respond with the HTTP 100 or FTP 150 10119 (Please Continue) control message on its own, before forwarding the 10120 request to an adaptation service or peer. Such a response usually forces 10121 the request sender to proceed with sending the body. A deny match tells 10122 Squid to delay that control response until the origin server confirms 10123 that the request body is needed. Delaying is the default behavior. 10124DOC_END 10125 10126NAME: server_pconn_for_nonretriable 10127TYPE: acl_access 10128DEFAULT: none 10129DEFAULT_DOC: Open new connections for forwarding requests Squid cannot retry safely. 10130LOC: Config.accessList.serverPconnForNonretriable 10131DOC_START 10132 This option provides fine-grained control over persistent connection 10133 reuse when forwarding HTTP requests that Squid cannot retry. It is useful 10134 in environments where opening new connections is very expensive 10135 (e.g., all connections are secured with TLS with complex client and server 10136 certificate validation) and race conditions associated with persistent 10137 connections are very rare and/or only cause minor problems. 10138 10139 HTTP prohibits retrying unsafe and non-idempotent requests (e.g., POST). 10140 Squid limitations also prohibit retrying all requests with bodies (e.g., PUT). 10141 By default, when forwarding such "risky" requests, Squid opens a new 10142 connection to the server or cache_peer, even if there is an idle persistent 10143 connection available. When Squid is configured to risk sending a non-retriable 10144 request on a previously used persistent connection, and the server closes 10145 the connection before seeing that risky request, the user gets an error response 10146 from Squid. In most cases, that error response will be HTTP 502 (Bad Gateway) 10147 with ERR_ZERO_SIZE_OBJECT or ERR_WRITE_ERROR (peer connection reset) error detail. 10148 10149 If an allow rule matches, Squid reuses an available idle persistent connection 10150 (if any) for the request that Squid cannot retry. If a deny rule matches, then 10151 Squid opens a new connection for the request that Squid cannot retry. 10152 10153 This option does not affect requests that Squid can retry. They will reuse idle 10154 persistent connections (if any). 10155 10156 This clause only supports fast acl types. 10157 See http://wiki.squid-cache.org/SquidFaq/SquidAcl for details. 10158 10159 Example: 10160 acl SpeedIsWorthTheRisk method POST 10161 server_pconn_for_nonretriable allow SpeedIsWorthTheRisk 10162DOC_END 10163 10164EOF 10165