[thirdparty/cups.git] / doc / help / cgi.html

<!DOCTYPE html>
<html>
<!-- SECTION: Getting Started -->
  <head>
    <title>Using CGI Programs</title>
    <link rel="stylesheet" type="text/css" href="../cups-printable.css">
  </head>
  <body>
    <h1 class="title">Using CGI Programs</h1>

    <p>CUPS provides a dynamic web interface through dedicated CGI programs that are executed when users open special directories on the CUPS server. Each CGI performs administration, class, help, job, and printer functions as directed by the user, but the actual programs that are run and functions that are available are limited to those that were originally designed into the scheduler.</p>

    <p>CUPS also supports CGI scripts/programs for pages you want to provide, although this functionality is disabled by default. The "application/x-httpd-cgi" MIME media type is used to identify CGI content and can be associated with any filename extension. The scheduler requires CGI content to have the execute bit set, not have world or group write permissions, and any CGI scripts need to include a <tt>#!</tt> line as the first line of a script to identify the script interpreter. For example, a PHP script would look like:</p>

    <pre class="example">
#!/usr/bin/php -fn
&lt;?php
...
?&gt;
</pre>


    <h2><a name="CONFIG">Configuring the Server</a></h2>

    <p>In order to enable the corresponding type, you must create a new <var>/etc/cups/cgi.types</var> file which maps the filename extensions you use to the appropriate MIME types. For example, the following will support CGI programs/scripts with the "cgi" extension:</p>

    <pre class="command">
application/x-httpd-cgi cgi
</pre>


    <h2><a name="LIMITS">Limitations</a></h2>

    <p>CUPS implements most of the CGI/1.1 specification, with the following exceptions:</p>

    <ul>
      <li>No PATH_INFO or PATH_TRANSLATED support</li>
      <li>Limited HTTP field support; only the Content-Length (<tt>CONTENT_LENGTH</tt>), Content-Type (<tt>CONTENT_TYPE</tt>), Cookie (<tt>HTTP_COOKIE</tt>), Referrer (<tt>HTTP_REFERRER</tt>), and User-Agent (<tt>HTTP_USER_AGENT</tt>) fields are placed in environment variables at this time</li>
    </ul>
  </body>
</html>
Commit	Line	Data
d03753f3 MS	1	<!DOCTYPE html>
d03753f3 MS	2	<html>
757d2cad	3	<!-- SECTION: Getting Started -->
d03753f3 MS	4	<head>
	5	<title>Using CGI Programs</title>
	6	<link rel="stylesheet" type="text/css" href="../cups-printable.css">
	7	</head>
	8	<body>
	9	<h1 class="title">Using CGI Programs</h1>
757d2cad	10
d03753f3	11	<p>CUPS provides a dynamic web interface through dedicated CGI programs that are executed when users open special directories on the CUPS server. Each CGI performs administration, class, help, job, and printer functions as directed by the user, but the actual programs that are run and functions that are available are limited to those that were originally designed into the scheduler.</p>
178cb736	12
d03753f3	13	<p>CUPS also supports CGI scripts/programs for pages you want to provide, although this functionality is disabled by default. The "application/x-httpd-cgi" MIME media type is used to identify CGI content and can be associated with any filename extension. The scheduler requires CGI content to have the execute bit set, not have world or group write permissions, and any CGI scripts need to include a <tt>#!</tt> line as the first line of a script to identify the script interpreter. For example, a PHP script would look like:</p>
757d2cad	14
d03753f3 MS	15	<pre class="example">
	16	#!/usr/bin/php -fn
	17	<?php
	18	...
	19	?>
	20	</pre>
757d2cad	21
757d2cad	22
d03753f3	23	<h2><a name="CONFIG">Configuring the Server</a></h2>
757d2cad	24
d03753f3	25	<p>In order to enable the corresponding type, you must create a new <var>/etc/cups/cgi.types</var> file which maps the filename extensions you use to the appropriate MIME types. For example, the following will support CGI programs/scripts with the "cgi" extension:</p>
757d2cad	26
d03753f3	27	<pre class="command">
757d2cad	28	application/x-httpd-cgi cgi
d03753f3	29	</pre>
757d2cad	30
757d2cad	31
d03753f3	32	<h2><a name="LIMITS">Limitations</a></h2>
757d2cad	33
d03753f3	34	<p>CUPS implements most of the CGI/1.1 specification, with the following exceptions:</p>
757d2cad	35
d03753f3 MS	36	<ul>
	37	<li>No PATH_INFO or PATH_TRANSLATED support</li>
	38	<li>Limited HTTP field support; only the Content-Length (<tt>CONTENT_LENGTH</tt>), Content-Type (<tt>CONTENT_TYPE</tt>), Cookie (<tt>HTTP_COOKIE</tt>), Referrer (<tt>HTTP_REFERRER</tt>), and User-Agent (<tt>HTTP_USER_AGENT</tt>) fields are placed in environment variables at this time</li>
	39	</ul>
	40	</body>
	41	</html>