Details | Last modification | View Log | RSS feed
| Rev | Author | Line No. | Line |
|---|---|---|---|
| 771 | blopes | 1 | <!DOCTYPE html SYSTEM "about:legacy-compat"> |
| 2 | <html lang="en"><head><META http-equiv="Content-Type" content="text/html; charset=UTF-8"><link href="./images/docs-stylesheet.css" rel="stylesheet" type="text/css"><title>Apache Tomcat 9 (9.0.112) - CGI How To</title></head><body><div id="wrapper"><header><div id="header"><div><div><div class="logo noPrint"><a href="https://tomcat.apache.org/"><img alt="Tomcat Home" src="./images/tomcat.png"></a></div><div style="height: 1px;"></div><div class="asfLogo noPrint"><a href="https://www.apache.org/" target="_blank"><img src="./images/asf-logo.svg" alt="The Apache Software Foundation" style="width: 266px; height: 83px;"></a></div><h1>Apache Tomcat 9</h1><div class="versionInfo"> |
||
| 3 | Version 9.0.112, |
||
| 4 | <time datetime="2025-11-06">Nov 6 2025</time></div><div style="height: 1px;"></div><div style="clear: left;"></div></div></div></div></header><div id="middle"><div><div id="mainLeft" class="noprint"><div><nav><div><h2>Links</h2><ul><li><a href="index.html">Docs Home</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/FAQ">FAQ</a></li></ul></div><div><h2>User Guide</h2><ul><li><a href="introduction.html">1) Introduction</a></li><li><a href="setup.html">2) Setup</a></li><li><a href="appdev/index.html">3) First webapp</a></li><li><a href="deployer-howto.html">4) Deployer</a></li><li><a href="manager-howto.html">5) Manager</a></li><li><a href="host-manager-howto.html">6) Host Manager</a></li><li><a href="realm-howto.html">7) Realms and AAA</a></li><li><a href="security-manager-howto.html">8) Security Manager</a></li><li><a href="jndi-resources-howto.html">9) JNDI Resources</a></li><li><a href="jndi-datasource-examples-howto.html">10) JDBC DataSources</a></li><li><a href="class-loader-howto.html">11) Classloading</a></li><li><a href="jasper-howto.html">12) JSPs</a></li><li><a href="ssl-howto.html">13) SSL/TLS</a></li><li><a href="ssi-howto.html">14) SSI</a></li><li><a href="cgi-howto.html">15) CGI</a></li><li><a href="proxy-howto.html">16) Proxy Support</a></li><li><a href="mbeans-descriptors-howto.html">17) MBeans Descriptors</a></li><li><a href="default-servlet.html">18) Default Servlet</a></li><li><a href="cluster-howto.html">19) Clustering</a></li><li><a href="balancer-howto.html">20) Load Balancer</a></li><li><a href="connectors.html">21) Connectors</a></li><li><a href="monitoring.html">22) Monitoring and Management</a></li><li><a href="logging.html">23) Logging</a></li><li><a href="apr.html">24) APR/Native</a></li><li><a href="virtual-hosting-howto.html">25) Virtual Hosting</a></li><li><a href="aio.html">26) Advanced IO</a></li><li><a href="maven-jars.html">27) Mavenized</a></li><li><a href="security-howto.html">28) Security Considerations</a></li><li><a href="windows-service-howto.html">29) Windows Service</a></li><li><a href="windows-auth-howto.html">30) Windows Authentication</a></li><li><a href="jdbc-pool.html">31) Tomcat's JDBC Pool</a></li><li><a href="web-socket-howto.html">32) WebSocket</a></li><li><a href="rewrite.html">33) Rewrite</a></li><li><a href="cdi.html">34) CDI 2 and JAX-RS</a></li><li><a href="graal.html">35) AOT/GraalVM Support</a></li></ul></div><div><h2>Reference</h2><ul><li><a href="RELEASE-NOTES.txt">Release Notes</a></li><li><a href="config/index.html">Configuration</a></li><li><a href="api/index.html">Tomcat Javadocs</a></li><li><a href="servletapi/index.html">Servlet 4.0 Javadocs</a></li><li><a href="jspapi/index.html">JSP 2.3 Javadocs</a></li><li><a href="elapi/index.html">EL 3.0 Javadocs</a></li><li><a href="websocketapi/index.html">WebSocket 1.1 Javadocs</a></li><li><a href="jaspicapi/index.html">JASPIC 1.1 Javadocs</a></li><li><a href="annotationapi/index.html">Common Annotations 1.3 Javadocs</a></li><li><a href="https://tomcat.apache.org/connectors-doc/">JK 1.2 Documentation</a></li></ul></div><div><h2>Apache Tomcat Development</h2><ul><li><a href="building.html">Building</a></li><li><a href="changelog.html">Changelog</a></li><li><a href="https://cwiki.apache.org/confluence/display/TOMCAT/Tomcat+Versions">Status</a></li><li><a href="developers.html">Developers</a></li><li><a href="architecture/index.html">Architecture</a></li><li><a href="tribes/introduction.html">Tribes</a></li></ul></div></nav></div></div><div id="mainRight"><div id="content"><h2>CGI How To</h2><h3 id="Table_of_Contents">Table of Contents</h3><div class="text"> |
||
| 5 | <ul><li><a href="#Introduction">Introduction</a></li><li><a href="#Installation">Installation</a></li><li><a href="#Configuration">Configuration</a></li></ul> |
||
| 6 | </div><h3 id="Introduction">Introduction</h3><div class="text"> |
||
| 7 | |||
| 8 | <p>The CGI (Common Gateway Interface) defines a way for a web server to |
||
| 9 | interact with external content-generating programs, which are often |
||
| 10 | referred to as CGI programs or CGI scripts. |
||
| 11 | </p> |
||
| 12 | |||
| 13 | <p>Within Tomcat, CGI support can be added when you are using Tomcat as your |
||
| 14 | HTTP server and require CGI support. Typically this is done |
||
| 15 | during development when you don't want to run a web server like |
||
| 16 | Apache httpd. |
||
| 17 | Tomcat's CGI support is largely compatible with Apache httpd's, |
||
| 18 | but there are some limitations (e.g., only one cgi-bin directory). |
||
| 19 | </p> |
||
| 20 | |||
| 21 | <p>CGI support is implemented using the servlet class |
||
| 22 | <code>org.apache.catalina.servlets.CGIServlet</code>. Traditionally, |
||
| 23 | this servlet is mapped to the URL pattern "/cgi-bin/*".</p> |
||
| 24 | |||
| 25 | <p>By default CGI support is disabled in Tomcat.</p> |
||
| 26 | </div><h3 id="Installation">Installation</h3><div class="text"> |
||
| 27 | |||
| 28 | <p><strong>CAUTION</strong> - CGI scripts are used to execute programs |
||
| 29 | external to the Tomcat JVM. If you are using the Java SecurityManager this |
||
| 30 | will bypass your security policy configuration in <code>catalina.policy.</code></p> |
||
| 31 | |||
| 32 | <p>To enable CGI support:</p> |
||
| 33 | |||
| 34 | <ol> |
||
| 35 | <li><p>There are commented-out sample servlet and servlet-mapping elements for |
||
| 36 | CGI servlet in the default <code>$CATALINA_BASE/conf/web.xml</code> file. |
||
| 37 | To enable CGI support in your web application, copy that servlet and |
||
| 38 | servlet-mapping declarations into <code>WEB-INF/web.xml</code> file of your |
||
| 39 | web application.</p> |
||
| 40 | |||
| 41 | <p>Uncommenting the servlet and servlet-mapping in |
||
| 42 | <code>$CATALINA_BASE/conf/web.xml</code> file enables CGI for all installed |
||
| 43 | web applications at once.</p> |
||
| 44 | </li> |
||
| 45 | |||
| 46 | <li><p>Set <code>privileged="true"</code> on the Context element for your |
||
| 47 | web application.</p> |
||
| 48 | |||
| 49 | <p>Only Contexts which are marked as privileged are allowed to use the |
||
| 50 | CGI servlet. Note that modifying the global <code>$CATALINA_BASE/conf/context.xml</code> |
||
| 51 | file affects all web applications. See |
||
| 52 | <a href="config/context.html">Context documentation</a> for details.</p> |
||
| 53 | </li> |
||
| 54 | </ol> |
||
| 55 | |||
| 56 | </div><h3 id="Configuration">Configuration</h3><div class="text"> |
||
| 57 | |||
| 58 | <p>There are several servlet init parameters which can be used to |
||
| 59 | configure the behaviour of the CGI servlet.</p> |
||
| 60 | <ul> |
||
| 61 | <li><strong>cgiMethods</strong> - Comma separated list of HTTP methods. Requests |
||
| 62 | using one of these methods will be passed to the CGI script for the script to |
||
| 63 | generate the response. The default value is <code>GET,POST</code>. Use |
||
| 64 | <code>*</code> for the script to handle all requests regardless of method. |
||
| 65 | Unless over-ridden by the configuration of this parameter, requests using HEAD, |
||
| 66 | OPTIONS or TRACE will have handled by the superclass.</li> |
||
| 67 | <li><strong>cgiPathPrefix</strong> - The CGI search path will start at |
||
| 68 | the web application root directory + File.separator + this prefix. |
||
| 69 | By default there is no value, which results in the web application root |
||
| 70 | directory being used as the search path. The recommended value is |
||
| 71 | <code>WEB-INF/cgi</code></li> |
||
| 72 | <li><strong>cmdLineArgumentsDecoded</strong> - If command line arguments |
||
| 73 | are enabled (via <strong>enableCmdLineArguments</strong>) and Tomcat is running |
||
| 74 | on Windows then each individual decoded command line argument must match this |
||
| 75 | pattern else the request will be rejected. This is to protect against known |
||
| 76 | issues passing command line arguments from Java to Windows. These issues can |
||
| 77 | lead to remote code execution. For more information on these issues see |
||
| 78 | <a href="https://codewhitesec.blogspot.com/2016/02/java-and-command-line-injections-in-windows.html">Markus |
||
| 79 | Wulftange's blog</a> and this archived |
||
| 80 | <a href="https://web.archive.org/web/20161228144344/https://blogs.msdn.microsoft.com/twistylittlepassagesallalike/2011/04/23/everyone-quotes-command-line-arguments-the-wrong-way/">blog |
||
| 81 | by Daniel Colascione</a>.</li> |
||
| 82 | <li><strong>cmdLineArgumentsEncoded</strong> - If command line arguments |
||
| 83 | are enabled (via <strong>enableCmdLineArguments</strong>) individual encoded |
||
| 84 | command line argument must match this pattern else the request will be rejected. |
||
| 85 | The default matches the allowed values defined by RFC3875 and is |
||
| 86 | <code>[\w\Q%;/?:@&,$-.!~*'()\E]+</code></li> |
||
| 87 | <li><strong>enableCmdLineArguments</strong> - Are command line arguments |
||
| 88 | generated from the query string as per section 4.4 of 3875 RFC? The default is |
||
| 89 | <code>false</code>.</li> |
||
| 90 | <li><strong>environment-variable-</strong> - An environment to be set for the |
||
| 91 | execution environment of the CGI script. The name of variable is taken from the |
||
| 92 | parameter name. To configure an environment variable named FOO, configure a |
||
| 93 | parameter named environment-variable-FOO. The parameter value is used as the |
||
| 94 | environment variable value. The default is no environment variables.</li> |
||
| 95 | <li><strong>executable</strong> - The name of the executable to be used to |
||
| 96 | run the script. You may explicitly set this parameter to be an empty string |
||
| 97 | if your script is itself executable (e.g. an exe file). Default is |
||
| 98 | <code>perl</code>.</li> |
||
| 99 | <li><strong>executable-arg-1</strong>, <strong>executable-arg-2</strong>, |
||
| 100 | and so on - additional arguments for the executable. These precede the |
||
| 101 | CGI script name. By default there are no additional arguments.</li> |
||
| 102 | <li><strong>envHttpHeaders</strong> - A regular expression used to select the |
||
| 103 | HTTP headers passed to the CGI process as environment variables. Note that |
||
| 104 | headers are converted to upper case before matching and that the entire header |
||
| 105 | name must match the pattern. Default is |
||
| 106 | <code>ACCEPT[-0-9A-Z]*|CACHE-CONTROL|COOKIE|HOST|IF-[-0-9A-Z]*|REFERER|USER-AGENT</code> |
||
| 107 | </li> |
||
| 108 | <li><strong>parameterEncoding</strong> - Name of the parameter encoding |
||
| 109 | to be used with the CGI servlet. Default is |
||
| 110 | <code>System.getProperty("file.encoding","UTF-8")</code>. That is the system |
||
| 111 | default encoding, or UTF-8 if that system property is not available.</li> |
||
| 112 | <li><strong>passShellEnvironment</strong> - Should the shell environment |
||
| 113 | variables from Tomcat process (if any) be passed to the CGI script? Default is |
||
| 114 | <code>false</code>.</li> |
||
| 115 | <li><strong>stderrTimeout</strong> - The time (in milliseconds) to wait for |
||
| 116 | the reading of stderr to complete before terminating the CGI process. Default |
||
| 117 | is <code>2000</code>.</li> |
||
| 118 | </ul> |
||
| 119 | |||
| 120 | <p>The CGI script executed depends on the configuration of the CGI Servlet and |
||
| 121 | how the request is mapped to the CGI Servlet. The CGI search path starts at the |
||
| 122 | web application root directory + File.separator + cgiPathPrefix. The |
||
| 123 | <strong>pathInfo</strong> is then searched unless it is <code>null</code> - in |
||
| 124 | which case the <strong>servletPath</strong> is searched.</p> |
||
| 125 | |||
| 126 | <p>The search starts with the first path segment and expands one path segment |
||
| 127 | at a time until no path segments are left (resulting in a 404) or a script is |
||
| 128 | found. Any remaining path segments are passed to the script in the |
||
| 129 | <strong>PATH_INFO</strong> environment variable.</p> |
||
| 130 | |||
| 131 | </div></div></div></div></div><footer><div id="footer"> |
||
| 132 | Copyright © 1999-2025, The Apache Software Foundation |
||
| 133 | <br> |
||
| 134 | Apache Tomcat, Tomcat, Apache, the Apache Tomcat logo and the Apache logo |
||
| 135 | are either registered trademarks or trademarks of the Apache Software |
||
| 136 | Foundation. |
||
| 137 | </div></footer></div></body></html> |