🔗 功能：用于请求操作的附加帮助程序

目标：支持根据本地需求对请求处理进行简单定制。
状态：已完成。2.5
版本: 2.5
更多:
- NTLM
- (Digest) KnowledgeBase/LdapBackedDigestAuthentication
- (Kerberos) ConfigExamples/Authenticate/Kerberos

🔗 详细信息

每个网络和安装都有其自身的操作标准。Squid 开发人员和社区没有时间或意愿为每种细微情况编写代码。相反，我们提供了通过本地附加脚本或程序（我们称之为帮助程序）轻松扩展各种操作的方法。

🔗 帮助程序应使用什么语言编写？

帮助程序可以用您喜欢的任何语言编写。它们可以是可执行程序或解释型脚本。

Squid 随附的帮助程序目前是用 Bash shell 脚本、awk 脚本、perl 脚本和 C++ 编写的。还有用于用 Python 或 Ruby 编写的帮助程序的框架。

有几种语言会遇到困难

Perl, Python 写入 stdout 的某些输出方法会自动附加换行符。必须注意，响应中只输出一套换行符。
PHP Zend 5.x 引擎的各种版本存在与 I/O 和执行超时相关的错误。其他版本在用于控制这些超时的配置设置中存在错误。通常最好完全避免使用 PHP，除非您想花费大量时间进行测试并寻找解决这些问题的办法。其中一些错误没有解决方案。
Go read() 操作似乎对线程有某种超时，会返回套接字关闭信号。导致多线程并发帮助程序退出，如果其最不常用的线程超时。对此没有已知的解决方法或解决方案。截至 Go 1.12.1 版本，该问题似乎已解决。

🔗 帮助程序如何与 Squid 通信？

与 Squid 的接口非常简单。为了执行预期的任务，帮助程序会通过 stdin 接收少量信息。结果通过 stdout 返回给 Squid。任何错误或调试跟踪都会通过 stderr 返回。

帮助程序应在响应之前等待输入。过早响应或意外的行到达 Squid 的 stdin 将导致帮助程序被关闭并报错。如果这种情况经常发生，Squid 也可能终止。
帮助程序应处理 Squid 的多个查找。不断重新启动帮助程序会严重拖慢 HTTP 速度。如果发生这种情况足够频繁，Squid 也可能终止。

有关帮助程序应在每个接口上接收和发送的行语法的详细信息，请参阅下面的特定接口协议。

🔗 为什么我的帮助程序无法随 Squid 一起启动？

Squid-3.2 及更高版本支持动态帮助程序初始化。这意味着帮助程序仅在需要时才启动。如果 Squid 配置了 startup=N，且值大于 0，您可以预期许多帮助程序将在 Squid 启动时启动。但这不一定是一个理想的情况，因为 Squid 需要快速启动或重启时间。

当配置为 startup=0 时，通过 Squid 的第一个 HTTP 请求预计会启动至少一个大多数帮助程序的实例。但是，例如，如果配置了外部 ACL 并且仅在罕见情况下进行测试，则其帮助程序直到该罕见情况首次发生时才会启动。

🔗 Squid 关闭或重新配置时会发生什么？

在关闭、重新配置或其他 Squid 需要关闭帮助程序时，Squid 会安排关闭帮助程序的 stdin 连接。当所有正在进行的查找完成后，帮助程序在读取 stdin 时应收到此关闭信号。

关闭或重启受 shutdown_timeout 的限制，这可能导致 Squid 提前中止而未收到所有响应。如果发生这种情况，客户端连接也将被同样突然地终止——因此丢失的帮助程序响应不是问题。

🔗 我可以编写一个与 Squid 在多个接口上通信的帮助程序吗？

可以。在某种程度上。

Squid 为每个接口运行配置的帮助程序作为单独的子进程。您的帮助程序可以被编写为检测到自身正在运行的其他实例并进行通信，从而有效地在 Squid 之外共享内存和/或状态，而不管 Squid 使用哪个接口来运行每个实例。

注意：只需记住，每个接口上运行的实例（子进程）数量是可配置的，可以从零到几百个不等。因此，不要对另一个实例正在运行的接口做任何假设。

🔗 提供帮助程序接口的 Squid 操作

Squid-2.6 及更高版本均支持

URL 操作：重写和重定向
- [url_rewrite_program](https://squid.org.cn/Doc/config/url_rewrite_program#), url_rewrite_access
- 在 Features/Redirectors 上的具体功能详情
ACL 逻辑测试
- external_acl_type
身份验证
- auth_param
- 在 Features/Authentication Features/NegotiateAuthentication 上的具体功能详情
缓存文件擦除器
- unlinkd_program

Squid-2.7 和 Squid-3.1+ 支持

日志记录
- logfile_daemon
- 在 Features/LogModules 上的具体功能详情

Squid-3.1+ 支持

SSL 证书生成 (3.1.12.1 及更高版本)。

Squid-3.4+ 支持

缓存对象去重
- store_id_program, store_id_access, store_id_children, store_id_bypass
- 在 Features/StoreID 上的具体功能详情
SSL 证书验证
- sslcrtvalidator_program, sslcrtvalidator_children
- 在 Features/SslServerCertValidator 上的具体功能详情

squid-3.5+ 支持

对帮助程序查找请求行进行灵活的 key-extras 扩展

Squid-3.1 及更高版本还支持 eCAP 插件和 ICAP 服务，它们在许多方面与帮助程序脚本不同。

🔗 帮助程序状态

单个帮助程序进程可能处于以下一种或多种状态：

键	名称	含义
B	忙碌	Squid 正在等待帮助程序进程的响应
W	正在写入	Squid 正在向无状态帮助程序进程发送一个或多个请求。Squid 尚未收到所有已发送数据已写入的通知。正在写入的帮助程序是忙碌的帮助程序。请注意，当前不支持对有状态帮助程序报告此状态。
R	已保留	Squid 正在向有状态帮助程序进程发送请求。Squid 尚未收到所有已发送数据已写入的通知。
P	占位符	至少有一个主事务正在等待此有状态帮助程序（但不一定是这个特定的有状态帮助程序进程）变得可用（即非忙碌）。
C	正在关闭	Squid 关闭了帮助程序进程的写入套接字，但帮助程序尚未退出（或者更精确地说，尚未关闭其 stdout）。
S	待关机	Squid 已将此帮助程序进程标记为最终关闭，但尚未启动关闭（通常是因为帮助程序仍处于忙碌状态）。

上述表格未反映一些晦涩的特殊情况，尤其是在帮助程序状态的结束条件方面。例如，有状态帮助程序进程可能因写入整个请求数据到帮助程序进程之外的原因而停止保留。

Squid 的Cache Manager会在特定于帮助程序的页面上报告单个帮助程序的状态，例如 mgr:store_io。

🔗 帮助程序协议

Squid-2.6 及更高版本均支持并发，但捆绑的帮助程序和许多第三方商业帮助程序不支持。这种情况正在改变，鼓励使用并发来提高性能。相关的 squid.conf 并发设置必须与帮助程序并发支持相匹配。可以使用helper multiplexer包装器为大多数非并发帮助程序添加并发优势。

:alert: 对于 Squid 发送的每一行，都期望收到一行响应。某些脚本语言（如 perl 和 python）需要注意其输出中的换行符数量。
:alert: 请注意，除了日志记录之外，帮助程序不能使用缓冲 I/O。

🔗 键值对 (kv-pairs) 格式

所有帮助程序的接口都已扩展，以支持任意的键=值对列表，语法为 ` key=value 。一些键对 Squid 有特殊含义，如下文所述。所有来自 squid 的消息都经过 URL 转义（可以使用 ` rfc1738_unescape ` 来自 rfc1738.h 进行解码）。对于响应，安全的方法是进行 URL 转义，或将值括在双引号（“）中；值中的任何双引号或反斜杠（\）都需要用反斜杠进行前缀，\r 和 \n 分别被替换为 CR 和 LF。



一些键值示例

                user=John%20Smith
                user="John Smith"
                user="J. \"Bob\" Smith"


  
  
    🔗 URL 操作
    

从 Squid 接收的输入行

[channel-ID] URL [key-extras]



  
    channel-ID

    
      当启用并发时，这是行的 ID。当禁用并发（设置为1）时，此字段以及后面的空格将完全缺失。
    
  
  
    URL

    
      从客户端接收的 URL。在支持 ICAP 的 Squid 中，这是 ICAP REQMOD 发生后的 URL。
    
  
  
    key-extras

    
      从Squid-3.5开始，传递给帮助程序的附加参数可以通过 url_rewrite_extras 配置。为了向后兼容，URL 帮助程序的默认 key-extras 匹配Squid-3.4及更早版本在此字段位置发送的格式字段。
    

    

    
      
        
 ip/fqdn ident method [urlgroup] kv-pair
        
      
    
  
  
    ip

    
      这是客户端的 IP 地址。后面跟着一个斜杠（/），如上所示。
    
  
  
    fqdn

    
      客户端的 FQDN rDNS（如果已知）。Squid 通常不会执行查找，除非日志记录或 ACL 需要。Squid 不会等待任何结果，除非配置了等待的 ACL。如果不可用，将发送-给帮助程序。
    
  
  
    ident

    
      客户端机器的 IDENT 协议用户名（如果已知）。Squid 不会等待 IDENT 用户名可知，除非有 ACL 依赖它。因此，在重写器运行时，IDENT 用户名可能尚未可知。如果不可用，将发送-给帮助程序。
    
  
  
    method

    
      HTTP 请求方法。URL 更改，尤其是重定向，仅在某些方法上可能，并且像 POST 和 CONNECT 这样的方法需要特别小心。
    
  
  
    urlgroup

    
      Squid-2 将发送此字段以及可在 http_port 上配置的 URL 分组标签。Squid-3.x 不会发送此字段。
    
  
  
    kv-pair

    
      
        一个或多个键=值对。仅记录了下面文档中的“myip”和“myport”对，并且由Squid-3.4及更早版本无条件发送。

        
          
            
              myip=…
              Squid 接收地址
            
            
              myport=…
              Squid 接收端口
            
          
        
      
    
  


  
  
    🔗 HTTP 重定向
    

重定向可以由url_rewrite_program接口上的帮助程序执行。执行重定向或重写行的帮助程序可以为每个请求生成。重定向是首选的，因为重写 URL 会给客户端 HTTP 体验带来大量问题。

从 Squid 接收的输入行由上述部分详细说明。

重定向器以稍有不同的格式将行发送回 Squid。

返回给 Squid 的结果行

[channel-ID] [result] [kv-pairs] [status:URL]



  
    channel-ID

    
      当收到并发channel-ID时，它必须作为行上的第一个条目不变地发送回 Squid。
    
  
  
    result

    
      
        其中一个结果代码

        
          
            
               
               
            
          
          
            
              OK
              成功。出现新的 URL。
            
            
              ERR
              成功。此 URL 无操作。
            
            
              BH
              失败。帮助程序遇到问题。
            
          
        
      
      
         result 字段仅被Squid-3.4及更新版本接受。
      
    
  
  
    kv-pair

    
      
        一个或多个键=值对。在此接口上为 HTTP 重定向保留的键名称

        
          
            
               
               
            
          
          
            
              clt_conn_tag=…
              标记客户端 TCP 连接（Squid-3.5）
            
            
              message=…
              reserved
            
            
              status=…
              用于重定向的 HTTP 状态码。必须是以下之一：301、302、303、307、308
            
            
              tag=…
              reserved
            
            
              ttl=…
              reserved
            
            
              url=…
              将客户端重定向到给定的 URL
            
            
              *_=…
              以 (_) 结尾的键名保留给本地管理员使用。
            
          
        
      
      
         kv-pair 字段仅被Squid-3.4及更新版本接受。
      
      
         此帮助程序返回的 kv-pair 可以通过 %note logformat 代码进行日志记录。
      
    
  
  
    status

    
      HTTP 301、302 或 307 状态码。有关 HTTP 重定向代码的解释以及它们可能发送的请求方法，请参阅 RFC 2616 的第 10.3 节。
    
  
  
    URL

    
      将用于替换客户端发送的 URL 的 URL。这必须是一个绝对 URL。例如，以  或  等开头。
    

     如果不需要操作，请将 status:URL 区域留空。

     status 和 URL 之间用冒号（:）分隔，如上所示，而不是用空格。
  


  
  
    🔗 URL 重写（篡改）
    

URL 重写可以由url_rewrite_program、storeurl_rewrite_program 和location_rewrite_program 接口上的帮助程序执行。

警告：在 url_rewrite_program 接口上使用时，重写 URL 会给客户端 HTTP 体验带来大量问题。其中一些问题可以通过在location_rewrite_program接口上运行的配对帮助程序来缓解，以进行服务器重定向 URL 的反篡改。

返回给 Squid 的结果行

[channel-ID] [result] [kv-pair] [URL]



  
    channel-ID

    
      当收到并发channel-ID时，它必须作为行上的第一个条目不变地发送回 Squid。
    
  
  
    result

    
      
        其中一个结果代码

        
          
            
               
               
            
          
          
            
              OK
              成功。出现新的 URL
            
            
              ERR
              成功。此 URL 无更改。
            
            
              BH
              失败。帮助程序遇到问题。
            
          
        
      
      
         result 字段仅被Squid-3.4及更新版本接受。
      
    
  
  
    kv-pair

    
      
        一个或多个键=值对。在此接口上为 URL 重写保留的键名称

        
          
            
               
               
            
          
          
            
              clt_conn_tag=…
              标记客户端 TCP 连接（Squid-3.5）
            
            
              message=…
              reserved
            
            
              rewrite-url=…
              将事务重写为给定的 URL。
            
            
              tag=…
              reserved
            
            
              ttl=…
              reserved
            
            
              *_=…
              以 (_) 结尾的键名保留给本地管理员使用。
            
          
        
      
      
         kv-pair 字段仅被Squid-3.4及更新版本接受。
      
      
         此帮助程序返回的 kv-pair 可以通过 %note logformat 代码进行日志记录。
      
    
  





  
    URL

    
      将用于替换客户端发送的 URL 的 URL。如果没有操作需要，请将 URL 字段留空。发送的 URL 必须是绝对 URL。例如，以  或  等开头。
    
  


  
  
    🔗 Store ID 去重
    

URL 与 Store-ID 的映射可以由storeid_rewrite_program接口上的帮助程序执行。

警告：必须谨慎确保映射到同一个共享 ID 的 URL 实际上是重复的。需要重新验证的客户端将导致缓存对象从任一重复位置获取。如果它们不是真正的重复项，这可能会随机地导致客户端体验出现严重问题。

返回给 Squid 的结果行

[channel-ID] result kv-pair



  
    channel-ID

    
      当收到并发channel-ID时，它必须作为行上的第一个条目不变地发送回 Squid。
    
  
  
    result

    
      
        其中一个结果代码

        
          
            
               
               
            
          
          
            
              OK
              成功。为该 URL 出现新的存储 ID。
            
            
              ERR
              成功。此 URL 无更改。
            
            
              BH
              失败。帮助程序遇到问题。
            
          
        
      
    
  
  
    kv-pair

    
      
        一个或多个键=值对。在此接口上为 URL 重写保留的键名称

        
          
            
               
               
            
          
          
            
              clt_conn_tag=…
              标记客户端 TCP 连接（Squid-3.5）
            
            
              message=…
              reserved
            
            
              store-id=…
              设置该 URL 的缓存存储 ID。
            
            
              tag=…
              reserved
            
            
              ttl=…
              reserved
            
            
              *_=…
              以 (_) 结尾的键名保留给本地管理员使用。
            
          
        
      
      
         此帮助程序返回的 kv-pair 可以通过 %note logformat 代码进行日志记录。
      
    

     此接口还将接受Store URL-rewrite功能帮助程序为Squid-2.7编写的语法响应。但是，该语法已弃用，应尽快将此类帮助程序升级到使用此 Store-ID 语法。
  


  
  
    🔗 身份验证器
    

  
  
    🔗 Basic 方案
    

从 Squid 接收的输入行

[channel-ID] username password [key-extras]



  
    channel-ID

    
      当启用并发时，这是行的 ID。当禁用并发（设置为1）时，此字段以及后面的空格将完全缺失。
    
  
  
    username

    
      客户端在 HTTP 头中发送的用户名字段。可能为空或缺失。
    
  
  
    password

    
      客户端在 HTTP 头中发送的密码值。可能为空或缺失。
    
  
  
    key-extras

    
      传递给帮助程序的附加参数，这些参数可以通过 auth_param 的key_extras参数进行配置。仅在Squid-3.5及更高版本中可用。
    
  


返回给 Squid 的结果行

[channel-ID] result [kv-pair]



  
    channel-ID

    
      当收到并发channel-ID时，它必须作为行上的第一个条目不变地发送回 Squid。
    
  
  
    result

    
      
        其中一个结果代码

        
          
            
               
               
            
          
          
            
              OK
              成功。凭据有效。
            
            
              ERR
              成功。凭据无效。
            
            
              BH
              失败。帮助程序遇到问题。
            
          
        
      
      
         BH 结果代码仅被Squid-3.4及更新版本接受。
      
    
  
  
    kv-pair

    
      
        一个或多个键=值对。在此接口上保留的键名称

        
          
            
               
               
            
          
          
            
              clt_conn_tag=…
              标记客户端 TCP 连接（Squid-3.5）
            
            
              group=…
              reserved
            
            
              message=…
              Squid 可以在错误页面上显示的字符串消息。
            
            
              tag=…
              reserved
            
            
              ttl=…
              reserved
            
            
              *_=…
              以 (_) 结尾的键名保留给本地管理员使用。
            
          
        
      
      
         kv-pair 字段仅被Squid-3.4及更新版本接受。
      
      
         此帮助程序返回的 kv-pair 可以通过 %note logformat 代码进行日志记录。
      
    
  


  
  
    🔗 Bearer 方案
    


  
 Bearer 身份验证方案已提议支持Squid-3.4及更新版本。但尚未被接受到主干。


从 Squid 接收的输入行

channel-ID b64token [key-extras]



  
    channel-ID

    
      这是用于支持并发查找的行的 ID。
    
  
  
    b64token

    
      客户端在 HTTP 头中发送的不透明凭据令牌字段。
    
  
  
    key-extras

    
      传递给帮助程序的附加参数，这些参数可以通过 auth_param 的key_extras参数进行配置。仅在Squid-3.5及更高版本中可用。
    
  


返回给 Squid 的结果行

channel-ID result [kv-pair]



  
    channel-ID

    
      接收到的并发channel-ID。它必须作为行上的第一个条目不变地发送回 Squid。
    
  
  
    result

    
      
        其中一个结果代码

        
          
            
               
               
            
          
          
            
              OK
              成功。凭据有效。
            
            
              ERR
              成功。凭据无效。
            
            
              BH
              失败。帮助程序遇到问题。
            
          
        
      
    
  
  
    kv-pair

    
      
        一个或多个键=值对。在此接口上保留的键名称

        


clt_conn_tag=...
标记客户端 TCP 连接（Squid-3.5）


group=...
reserved


message=...
Squid 可以在错误页面上显示的字符串消息。


tag=...
reserved


ttl=...

此结果可使用的时间长度。
如果未提供，则令牌被视为已过时（随机数）。



user=...
Squid 用于此客户端请求的标签，作为“用户名”。


*_=...
以 (_) 结尾的键名保留给本地管理员使用。



      
    
  


  
  
    🔗 Digest 方案
    

从 Squid 接收的输入行

[channel-ID] "username":"realm" [key-extras]



  
    channel-ID

    
      当启用并发时，这是行的 ID。当禁用并发（设置为1）时，此字段以及后面的空格将完全缺失。
    
  
  
    username

    
      客户端在 HTTP 头中发送的用户名字段。作为“双引号”字符串发送。可能为空。可以配置为使用 UTF-8 字节而不是接收到的 ISO-8859-1。
    
  
  
    realm

    
      在 squid.conf 中配置的 digest auth realm 字符串。作为“双引号”字符串发送。
    
  


 username 和 realm 字符串都用双引号（“）括起来，并用冒号（:）分隔，如上所示。


  
    key-extras

    
      传递给帮助程序的附加参数，这些参数可以通过 auth_param 的key_extras参数进行配置。仅在Squid-3.5及更高版本中可用。
    
  


返回给 Squid 的结果行

[channel-ID] [result] [kv-pair] [hash]



  
    channel-ID

    
      当收到并发channel-ID时，它必须作为行上的第一个条目不变地发送回 Squid。
    
  
  
    result

    
      
        其中一个结果代码

        
          
            
               
               
            
          
          
            
              OK
              成功。凭据有效。Digest HA1 值已显示。
            
            
              ERR
              成功。凭据无效。
            
            
              BH
              失败。帮助程序遇到问题。
            
          
        
      
      
         OK 和 BH 结果代码仅被Squid-3.4及更新版本接受。
      
      
         对于Squid-3.3及更早版本，OK 结果不发送，但会发送 hash 字段。
      
    
  
  
    kv-pair

    
      
        一个或多个键=值对。在此接口上保留的键名称

        
          
            
               
               
            
          
          
            
              clt_conn_tag=…
              标记客户端 TCP 连接（Squid-3.5）
            
            
              group=…
              reserved
            
            
              ha1=…
              要使用的 digest HA1 值。此字段仅在OK响应中使用。
            
            
              message=…
              Squid 可以在错误页面上显示的字符串消息。
            
            
              tag=…
              reserved
            
            
              ttl=…
              reserved
            
            
              *_=…
              以 (_) 结尾的键名保留给本地管理员使用。
            
          
        
      
      
         kv-pair 字段仅被Squid-3.4及更新版本接受。
      
      
         此帮助程序返回的 kv-pair 可以通过 %note logformat 代码进行日志记录。
      
    
  
  
    hash

    
      
        要使用的 digest HA1 值。此字段仅在OK响应中接受。

         该字段在 Squid-3.4 及更新版本中已弃用，请使用 ha1 kv-pair。
      
    
  


  
  
    🔗 Negotiate 和 NTLM 方案
    


  
 由于 NTLM 的状态性，这些身份验证器方案不支持并发。


从 Squid 接收的输入行

 request [credentials] [key-extras]



  
    request

    
      
        其中一个请求代码

        
          
            
               
               
            
          
          
            
              YR
              需要新的挑战令牌。这是两个进程之间的第一次通信。当 Squid 需要新的挑战时，它也可能随时发生，这是由于 auth_param 的 max_challenge_lifetime 和 max_challenge_uses 参数。帮助程序应响应 TT 消息。
            
            
              KK
              验证用户凭据。帮助程序响应 OK、ERR、AF、NA 或 BH。
            
          
        
      
    
  
  
    credentials

    
      在 HTTP 头中收到的编码 blob。此字段仅在 KK 请求中发送。
    
  
  
    key-extras

    
      传递给帮助程序的附加参数，这些参数可以通过 auth_param 的key_extras参数进行配置。仅在Squid-3.5及更高版本中可用。
    
  


返回给 Squid 的结果行

 result [token label] [kv-pair] [message]



  
    result

    
      
        其中一个结果代码

        
          
            
               
               
            
          
          
            
              TT
              成功。出现新的挑战token值。
            
            
              AF
              成功。凭据有效。自 Squid-3.4 起被 OK 结果弃用。
            
            
              NA
              成功。凭据无效。自 Squid-3.4 起被 ERR 结果弃用。
            
            
              OK
              成功。凭据有效。
            
            
              ERR
              成功。凭据无效。
            
            
              BH
              失败。帮助程序遇到问题。
            
          
        
      
      
         OK 和 ERR 结果代码仅被Squid-3.4及更新版本接受。
      
    
  
  
    token

    
      
        出现新的挑战token值。令牌是 base64 编码的，如 RFC 2045 定义。

         注意：Squid-3.3 及更早版本的 NTLM 身份验证器接口不支持 token 字段。Negotiate 身份验证器接口在 TT、AF 和 NA 响应中需要它。

         此字段不得在 OK、ERR 和 BH 响应中发送。
      
    
  
  
    label

    
      这里提供的标签是 Squid 用于此客户端请求的“用户名”。此字段仅在 AF 响应中接受。不得在任何其他结果代码响应中发送。
    
  
  
    kv-pair

    
      
        一个或多个键=值对。在此接口上保留的键名称

        
          
            
               
               
            
          
          
            
              clt_conn_tag=…
              标记客户端 TCP 连接（Squid-3.5）
            
            
              group=…
              reserved
            
            
              message=…
              Squid 可以在错误页面上显示的字符串消息。
            
            
              tag=…
              reserved
            
            
              token=…
              要使用的 base64 编码（如 RFC 2045 定义）的令牌。此字段仅在 OK 响应中使用。
            
            
              ttl=…
              reserved
            
            
              user=…
              Squid 用于此客户端请求的标签，作为“用户名”。对于 Negotiate 和 NTLM 协议，它通常分别具有 NAME@DOMAIN 或 NAME\\DOMAIN 的格式。
            
            
              *_=…
              以 (_) 结尾的键名保留给本地管理员使用。
            
          
        
      
      
         kv-pair 字段仅被Squid-3.4及更新版本接受。
      
      
         此帮助程序返回的 kv-pair 可以通过 %note logformat 代码进行日志记录。
      
      
         此字段仅在 OK、ERR 和 BH 响应中接受，不得在其他响应中发送。
      
    
  
  
    message

    
      Squid 可以在错误页面上显示的字符串消息。此字段仅在 NA 和 BH 响应中接受。从Squid-3.4起，此字段已被 BH 响应上的 message= kv-pair 弃用。
    
  


  
  
    🔗 访问控制 (ACL)
    

此接口具有非常灵活的字段布局。管理员可以配置任意数量的来自相关 HTTP 请求或回复的详细信息发送给帮助程序。

从 Squid 接收的输入行

[channel-ID] format-options [acl-value [acl-value ...]]



  
    channel-ID

    
      当启用并发时，这是行的 ID。当在 external_acl_type 中将并发设置为（concurrency=1）关闭时，此字段以及后面的空格将完全缺失。
    
  
  
    format-options

    
      这是在 external_acl_type 的 FORMAT 区域配置的灵活的令牌系列。令牌以空格分隔，并与配置的 FORMAT 中的 % 令牌顺序完全匹配。在当前版本中，默认情况下，这些令牌也根据 RFC 1738 进行 URL 编码，以防止出现空格和二进制数据问题。
    
  
  
    acl-value

    
      
        某些 ACL 测试（如组名比较）将测试值传递给外部帮助程序，遵循管理员配置的 FORMAT。根据 ACL，这些可能一次发送一个值，作为一个值列表发送，或者不发送任何内容。在当前版本中，默认情况下，这些令牌也根据 RFC 1738 进行 URL 编码，以防止出现空格和二进制数据问题。

        
          
 在 Squid-4 中，如果 format-options 中没有使用 %DATA 宏，这些 acl-value 将扩展为一个连字符（'-'）。在旧版本的 Squid 中，这会扩展为空格。
        
      
    
  


返回给 Squid 的结果行

[channel-ID] result [kv-pair]



  
    channel-ID

    
      当收到并发channel-ID时，它必须作为行上的第一个条目不变地发送回 Squid。
    
  
  
    result

    
      
        其中一个结果代码

        
          
            
               
               
            
          
          
            
              OK
              成功。ACL 测试匹配。
            
            
              ERR
              成功。ACL 测试不匹配。
            
            
              BH
              失败。帮助程序遇到问题。
            
          
        
      
      
        在 squid.conf 中对外部 ACL 的配置使用决定了这个结果的含义。
      
      
         BH 结果代码仅被Squid-3.4及更新版本接受。
      
    
  
  
    kv-pair

    
      
        一个或多个键=值对。请参阅 external_acl_type 以获取您的 Squid 支持的完整列表。在此接口上保留的键名称

        
          
            
               
               
            
          
          
            
              clt_conn_tag=…
              标记客户端 TCP 连接（Squid-3.5）
            
            
              group=…
              reserved
            
            
              log=…
              要在 access.log 中记录的字符串。在 logformat 规范中作为 %ea 可用。
            
            
              message=…
              描述原因的消息。在错误页面中作为 %o 可用。
            
            
              password=…
              用户的密码（用于 login= cache_peer 选项）
            
            
              tag=…
              为请求应用一个标签（用于 ERR 和 OK 结果）。仅设置标签，不改变现有标签。
            
            
              ttl=…
              reserved
            
            
              user=…
              用户的名称（登录名）
            
            
              *_=…
              以 (_) 结尾的键名保留给本地管理员使用。
            
          
        
      
    
  


  
  
    🔗 日志记录
    

Squid 向日志守护进程发送多个命令。这些命令在每行输入的第一个字节中发送。


  

    
      
        
           
           
        
      
      
        
          L<data>\n
          日志文件数据
        
        
          R\n
          轮换文件
        
        
          T\n
          截断文件
        
        
          O\n
          重新打开文件
        
        
          F\n
          刷新文件
        
        
          r<n>\n
          将轮换计数设置为 <n>
        
        
          b<n>\n
          1 = 缓冲输出，0 = 不缓冲输出
        
      
    
  


不需要响应。任何想要的响应都应该在 stderr 上发生，以便通过 cache.log 查看。

  
  
    🔗 SSL 证书生成
    

此接口具有固定的字段布局。

从 Squid 接收的行输入

request size kv-pairs [body]


 line 指的是逻辑输入。body 可能包含 \n 字符，因此此格式中的每一行都用 0x01 字节分隔，而不是标准的 \n 字节。


  
    request

    
      正在请求的操作类型。目前，new_certificate 代码是唯一进行的请求。
    
  
  
    size

    
      由kv-pair参数和body占用的以下请求字节的总大小。
    
  
  
    kv-pair

    
      
        一个或多个键=值对，用换行符分隔。此接口上保留的键名称

        
          
            
               
               
            
          
          
            
              host=
              需要证书的域的 FQDN 主机名。
            
          
        
      
    
  
  
    body

    
      
        可选的 CA 证书和私有 RSA 密钥用于签名。如果省略此 body 字段，则生成的证书将是自签名的。此字段的内容是 ASCII armored PEM 格式。

        
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----
        
      
    
  


返回给 Squid 的结果行

result size [kv-pairs] body



  
    result

    
      
        其中一个结果代码

        
          
            
               
               
            
          
          
            
              OK
              成功。证书已准备好
            
            
              BH
              失败。帮助程序遇到问题。
            
          
        
      
      
         OK 和 BH 结果代码仅被Squid-3.3及更新版本接受。
      
      
         如果检测到任何错误或意外事件，帮助程序将显示错误消息并中止。
      
    
  
  
    size

    
      由body占用的以下请求字节的总大小。
    
  
  
    kv-pairs

    
      
        可选的键=值参数列表，用换行符分隔。支持的一些键=值对是

        
          
            
               
               
            
          
          
            
              host=
              此证书是关于的域的 FQDN 主机名。
            
          
        
      
    
  
  
    body

    
      
        生成的 CA 证书。此字段的内容是 ASCII armored PEM 格式。

        
-----BEGIN CERTIFICATE-----
...
-----END CERTIFICATE-----
        
      
    
  


  
  
    🔗 SSL 服务器证书验证器
    

此接口与 SSL 证书生成接口类似。

从 Squid 接收的行输入

request size [kv-pairs]


 line 指的是逻辑输入。body 可能包含 \n 字符，因此此格式中的每一行都用 0x01 字节分隔，而不是标准的 \n 字节。


  
    request

    
      正在请求的操作类型。目前，cert_validate 代码是唯一进行的请求。
    
  
  
    size

    
      由key=pair参数占用的以下请求字节的总大小。
    
  
  
    kv-pairs

    
      
        可选的键=值参数列表，用换行符分隔。支持的参数是

        
          
            
               
               
            
          
          
            
              host
              FQDN 主机名或域
            
            
              proto_version
              SSL/TLS 版本
            
            
              cipher
              正在使用的 SSL/TLS 密码
            
            
              cert_ID
              服务器证书。ID 是此证书的索引号。此参数的数量等于服务器证书的数量。
            
            
              error_name_ID
              openSSL 证书验证错误。ID 是此错误的索引号。
            
            
              error_cert_ID
              导致 error_name_ID 的证书的 ID。
            
          
        
      
    
  


示例请求

0 cert_validate 1519 host=dmz.example-domain.com
cert_0=-----BEGIN CERTIFICATE-----
MIID+DCCA2GgAwIBAgIJAIDcHRUxB2O4MA0GCSqGSIb3DQEBBAUAMIGvMQswCQYD
...
YpVJGt5CJuNfCcB/
-----END CERTIFICATE-----
error_name_0=X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT
error_cert_0=cert0


返回给 Squid 的结果行

result size kv-pairs



  
    result

    
      
        其中一个结果代码

        
          
            
               
               
            
          
          
            
              OK
              成功。证书已验证。
            
            
              ERR
              成功。证书未验证。
            
            
              BH
              失败。帮助程序遇到问题。
            
          
        
      
    
  
  
    size

    
      由key=pair参数占用的以下响应字节的总大小。
    
  
  
    kv-pairs

    
      
        键=值参数列表，用换行符分隔。支持的参数是

        
          
            
               
               
            
          
          
            
              cert_ID
              从帮助程序发送到 Squid 的证书。ID 是此证书的索引号。
            
            
              error_name_ID
              错误ID的 openSSL 错误名称。
            
            
              error_reason_ID
              错误ID的原因。
            
            
              error_cert_ID
              损坏的证书。它可以是帮助程序发送给 Squid 的证书之一，也可以是 Squid 发送给帮助程序的证书之一。
            
          
        
      
    
  


示例响应消息

ERR 1444 cert_10=-----BEGIN CERTIFICATE-----
MIIDojCCAoqgAwIBAgIQE4Y1TR0/BvLB+WUF1ZAcYjANBgkqhkiG9w0BAQUFADBr
...
398znM/jra6O1I7mT1GvFpLgXPYHDw==
-----END CERTIFICATE-----
error_name_0=X509_V_ERR_DEPTH_ZERO_SELF_SIGNED_CERT
error_reason_0=Checked by Cert Validator
error_cert_0=cert_10


  
  
    🔗 缓存文件擦除器
    

用于擦除文件的 unlink() 函数是一个阻塞调用，可能会减慢 Squid 的速度。此接口用于将文件擦除指令传递给由 unlinkd_program 指定的帮助程序。

此接口具有固定的字段布局。截至 Squid-3.3，此接口不支持并发。它要求 Squid 使用 –enable-unlinkd 构建，并且只有使用磁盘文件（UFS、AUFS、diskd）的缓存存储类型才使用此接口。

从 Squid 接收的输入行

path



  
    path

    
      要擦除的文件。
    
  


返回给 Squid 的结果行

result [kv-pair]



  
    result

    
      
        其中一个结果代码

        
          
            
               
               
            
          
          
            
              OK
              成功。文件已从缓存中移除。
            
            
              BH
              失败。帮助程序遇到问题。
            
          
        
      
    
  
  
    kv-pair

    
      
        一个或多个键=值对。在此接口上保留的键名称

        
          
            
               
               
            
          
          
            
              clt_conn_tag=…
              reserved
            
            
              message=…
              reserved
            
            
              tag=…
              reserved
            
            
              *_=…
              以 (_) 结尾的键名保留给本地管理员使用。
            
          
        
      
    
  


CategoryFeature
类别：功能
导航：站点搜索，站点页面，类别，🔼 向上

Squid Web Cache Wiki

Squid Web Cache 文档

🔗 功能：用于请求操作的附加帮助程序

🔗 详细信息

🔗 帮助程序应使用什么语言编写？

🔗 帮助程序如何与 Squid 通信？

🔗 为什么我的帮助程序无法随 Squid 一起启动？

🔗 Squid 关闭或重新配置时会发生什么？

🔗 我可以编写一个与 Squid 在多个接口上通信的帮助程序吗？

🔗 提供帮助程序接口的 Squid 操作

🔗 帮助程序状态

🔗 帮助程序协议

🔗 键值对 (kv-pairs) 格式

🔗 URL 操作

🔗 HTTP 重定向

🔗 URL 重写（篡改）

🔗 Store ID 去重

🔗 身份验证器

🔗 Basic 方案

🔗 Bearer 方案

🔗 Digest 方案

🔗 Negotiate 和 NTLM 方案

🔗 访问控制 (ACL)

🔗 日志记录

🔗 SSL 证书生成

🔗 SSL 服务器证书验证器

🔗 缓存文件擦除器


OK	成功。出现新的 URL。
ERR	成功。此 URL 无操作。
BH	失败。帮助程序遇到问题。


clt_conn_tag=…	标记客户端 TCP 连接（Squid-3.5）
message=…	reserved
status=…	用于重定向的 HTTP 状态码。必须是以下之一：301、302、303、307、308
tag=…	reserved
ttl=…	reserved
url=…	将客户端重定向到给定的 URL
*_=…	以 (_) 结尾的键名保留给本地管理员使用。


OK	成功。出现新的 URL
ERR	成功。此 URL 无更改。
BH	失败。帮助程序遇到问题。


OK	成功。为该 URL 出现新的存储 ID。
ERR	成功。此 URL 无更改。
BH	失败。帮助程序遇到问题。


OK	成功。凭据有效。
ERR	成功。凭据无效。
BH	失败。帮助程序遇到问题。


clt_conn_tag=…	标记客户端 TCP 连接（Squid-3.5）
group=…	reserved
message=…	Squid 可以在错误页面上显示的字符串消息。
tag=…	reserved
ttl=…	reserved
*_=…	以 (_) 结尾的键名保留给本地管理员使用。

clt_conn_tag=...	标记客户端 TCP 连接（Squid-3.5）
group=...	reserved
message=...	Squid 可以在错误页面上显示的字符串消息。
tag=...	reserved
ttl=...	此结果可使用的时间长度。如果未提供，则令牌被视为已过时（随机数）。
user=...	Squid 用于此客户端请求的标签，作为“用户名”。
*_=...	以 (_) 结尾的键名保留给本地管理员使用。


OK	成功。凭据有效。Digest HA1 值已显示。
ERR	成功。凭据无效。
BH	失败。帮助程序遇到问题。


YR	需要新的挑战令牌。这是两个进程之间的第一次通信。当 Squid 需要新的挑战时，它也可能随时发生，这是由于 auth_param 的 max_challenge_lifetime 和 max_challenge_uses 参数。帮助程序应响应 TT 消息。
KK	验证用户凭据。帮助程序响应 OK、ERR、AF、NA 或 BH。


TT	成功。出现新的挑战token值。
AF	成功。凭据有效。自 Squid-3.4 起被 OK 结果弃用。
NA	成功。凭据无效。自 Squid-3.4 起被 ERR 结果弃用。
OK	成功。凭据有效。
ERR	成功。凭据无效。
BH	失败。帮助程序遇到问题。


OK	成功。ACL 测试匹配。
ERR	成功。ACL 测试不匹配。
BH	失败。帮助程序遇到问题。


L<data>\n	日志文件数据
R\n	轮换文件
T\n	截断文件
O\n	重新打开文件
F\n	刷新文件
r<n>\n	将轮换计数设置为 <n>
b<n>\n	1 = 缓冲输出，0 = 不缓冲输出


OK	成功。证书已准备好
BH	失败。帮助程序遇到问题。


host	FQDN 主机名或域
proto_version	SSL/TLS 版本
cipher	正在使用的 SSL/TLS 密码
cert_ID	服务器证书。ID 是此证书的索引号。此参数的数量等于服务器证书的数量。
error_name_ID	openSSL 证书验证错误。ID 是此错误的索引号。
error_cert_ID	导致 error_name_ID 的证书的 ID。


OK	成功。证书已验证。
ERR	成功。证书未验证。
BH	失败。帮助程序遇到问题。


cert_ID	从帮助程序发送到 Squid 的证书。ID 是此证书的索引号。
error_name_ID	错误ID的 openSSL 错误名称。
error_reason_ID	错误ID的原因。
error_cert_ID	损坏的证书。它可以是帮助程序发送给 Squid 的证书之一，也可以是 Squid 发送给帮助程序的证书之一。


OK	成功。文件已从缓存中移除。
BH	失败。帮助程序遇到问题。