CGI 使用指南

目录

简介

CGI（通用网关接口）定义了 Web 服务器与外部内容生成程序交互的方式，这些程序通常被称为 CGI 程序或 CGI 脚本。

在 Tomcat 中，当您使用 Tomcat 作为 HTTP 服务器并需要 CGI 支持时，可以添加 CGI 支持。这通常在开发期间进行，当您不想运行像 Apache httpd 这样的 Web 服务器时。Tomcat 的 CGI 支持与 Apache httpd 的大致兼容，但存在一些限制（例如，只能有一个 cgi-bin 目录）。

CGI 支持是使用 servlet 类 org.apache.catalina.servlets.CGIServlet 实现的。传统上，这个 servlet 被映射到 URL 模式 "/cgi-bin/*"。

默认情况下，Tomcat 中禁用了 CGI 支持。

安装

注意 - CGI 脚本用于执行 Tomcat JVM 外部的程序。

启用 CGI 支持

  1. 默认的 $CATALINA_BASE/conf/web.xml 文件中包含 CGI servlet 的被注释掉的 servlet 和 servlet-mapping 示例元素。要在您的 Web 应用程序中启用 CGI 支持，请将这些 servlet 和 servlet-mapping 声明复制到您的 Web 应用程序的 WEB-INF/web.xml 文件中。

    取消 $CATALINA_BASE/conf/web.xml 文件中 servlet 和 servlet-mapping 的注释会立即为所有已安装的 Web 应用程序启用 CGI。

  2. 将您的 Web 应用程序的 Context 元素上的 privileged="true" 设置为 true。

    只有被标记为 privileged 的 Context 才允许使用 CGI servlet。请注意，修改全局 $CATALINA_BASE/conf/context.xml 文件会影响所有 Web 应用程序。有关详细信息，请参阅 Context 文档。

配置

有几个 servlet 初始化参数可用于配置 CGI servlet 的行为。

  • cgiMethods - 用逗号分隔的 HTTP 方法列表。使用这些方法之一的请求将被传递给 CGI 脚本，由脚本生成响应。默认值为 GET,POST。使用 * 表示脚本处理所有请求，无论方法如何。除非被此参数的配置覆盖，否则使用 HEAD、OPTIONS 或 TRACE 的请求将由超类处理。
  • cgiPathPrefix - CGI 搜索路径将从 Web 应用程序根目录 + File.separator + 此前缀开始。默认情况下没有值，这意味着 Web 应用程序根目录用作搜索路径。推荐值为 WEB-INF/cgi。
  • cmdLineArgumentsDecoded - 如果启用了命令行参数（通过 enableCmdLineArguments），并且 Tomcat 在 Windows 上运行，那么每个单独解码的命令行参数都必须匹配此模式，否则请求将被拒绝。这是为了防止从 Java 向 Windows 传递命令行参数时出现的已知问题。这些问题可能导致远程代码执行。有关这些问题的更多信息，请参阅 Markus Wulftange 的博客 和这篇存档的 Daniel Colascione 的博客。
  • cmdLineArgumentsEncoded - 如果启用了命令行参数（通过 enableCmdLineArguments），则每个单独编码的命令行参数必须匹配此模式，否则请求将被拒绝。默认值与 RFC3875 定义的允许值匹配，为 [\w\Q%;/?:@&,$-.!~*'()\E]+。
  • enableCmdLineArguments - 命令行参数是否根据 RFC 3875 的 4.4 节从查询字符串生成？默认值为 false。
  • environment-variable- - 为 CGI 脚本的执行环境设置的环境变量。变量名称取自参数名称。要配置名为 FOO 的环境变量，请配置名为 environment-variable-FOO 的参数。参数值用作环境变量值。默认情况下没有环境变量。
  • executable - 用于运行脚本的可执行文件的名称。如果您的脚本本身是可执行的（例如 exe 文件），您可以显式地将此参数设置为空字符串。默认值为 perl。
  • executable-arg-1、executable-arg-2 等 - 可执行文件的附加参数。这些参数位于 CGI 脚本名称之前。默认情况下没有附加参数。
  • envHttpHeaders - 用于选择作为环境变量传递给 CGI 进程的 HTTP 头部的正则表达式。请注意，头部在匹配前会转换为大写，并且整个头部名称必须匹配该模式。默认值为 ACCEPT[-0-9A-Z]*|CACHE-CONTROL|COOKIE|HOST|IF-[-0-9A-Z]*|REFERER|USER-AGENT。
  • parameterEncoding - CGI servlet 使用的参数编码名称。默认值为 System.getProperty("file.encoding","UTF-8")。即系统默认编码，如果该系统属性不可用，则为 UTF-8。
  • passShellEnvironment - 是否将 Tomcat 进程的 shell 环境变量（如果有）传递给 CGI 脚本？默认值为 false。
  • stderrTimeout - 在终止 CGI 进程之前，等待 stderr 读取完成的时间（毫秒）。默认值为 2000。

执行的 CGI 脚本取决于 CGI Servlet 的配置以及请求如何映射到 CGI Servlet。CGI 搜索路径从 Web 应用程序根目录 + File.separator + cgiPathPrefix 开始。然后搜索 pathInfo，除非它是 null - 在这种情况下，搜索 servletPath。

搜索从第一个路径段开始，每次扩展一个路径段，直到没有路径段剩余（导致 404 错误）或找到脚本。任何剩余的路径段都将作为 PATH_INFO 环境变量传递给脚本。