Load cups into easysw/current.
[thirdparty/cups.git] / CGI.txt
1 CGI - CUPS v1.1.21 - 06/29/2004
2 -------------------------------
3
4 This file describes the experimental scripting/CGI support
5 provided by CUPS starting with CUPS 1.1.19.
6
7 WARNING: CGI support is not complete; you may run into problems
8 and limitations in the implementation of CGI in CUPS that are
9 not present in full-featured web servers like Apache.
10
11
12 OVERVIEW OF CGI SUPPORT IN CUPS
13
14 CUPS has traditionally provided a dynamic web interface through
15 four CGI programs that are executed when users open special
16 directories on the CUPS server.  Each CGI performs
17 administration, class, job, and printer functions as directed by
18 the user, but the actual programs that are run and functions
19 that are available are limited to those that were originally
20 designed into the scheduler.
21
22 Starting with CUPS 1.1.19, support is now available for CGI
23 programs and specific scripting languages, currently Java, Perl,
24 PHP, and Python.  The interpreters for these languages are
25 currently configured at compile time.  Future versions may
26 expand the interface to allow for generic support of scripting
27 languages similar to the Apache "AddHandler" directive, but with
28 external programs instead of modules.
29
30 The following MIME types are reserved for the CGI support in
31 CUPS (the names have been chosen to mirror those used by
32 Apache):
33
34     application/x-httpd-cgi      CGI script/program
35     application/x-httpd-java     Java program
36     application/x-httpd-perl     Perl script
37     application/x-httpd-php      PHP script
38     application/x-httpd-python   Python script
39
40 In order to enable the corresponding type, you must create a new
41 /etc/cups/cgi.types file which maps the filename extensions to
42 the appropriate MIME type, for example:
43
44     application/x-httpd-cgi cgi
45     application/x-httpd-php php
46
47 CGI scripts/programs (application/x-httpd-cgi) also must have
48 execution permissions to be treated as a CGI script or program.
49
50
51 LIMITATIONS
52
53 CUPS implements most of the CGI/1.1 specification, with the
54 following limitations:
55
56     - No Location: redirection support.
57     - No PATH_INFO or PATH_TRANSLATED support.
58     - Limited HTTP field support; only the Content-Length
59       (CONTENT_LENGTH), Cookie (HTTP_COOKIE), and User-Agent
60       (HTTP_USER_AGENT) fields are placed in environment
61       variables at this time.
62
63
64 REPORTING PROBLEMS
65
66 If you have problems, READ THE DOCUMENTATION FIRST!  If the
67 documentation does not solve your problems please send an email
68 to "cups-support@cups.org".  Include your operating system and
69 version, compiler and version, and any errors or problems you've
70 run into. The "/var/log/cups/error_log" file should also be sent,
71 as it often helps to determine the cause of your problem.
72
73 If you are running a version of Linux, be sure to provide the
74 Linux distribution you have, too.
75
76 Please note that the "cups-support@cups.org" email address goes
77 to the CUPS developers; they are busy people, so your email may
78 go unanswered for days or weeks.  In general, only general build
79 or distribution problems will actually get answered - for
80 end-user support see the "README.txt" for a summary of the
81 resources available.