]>
Commit | Line | Data |
---|---|---|
4744bd90 | 1 | <HTML> |
2 | <!-- SECTION: Specifications --> | |
3 | <HEAD> | |
4 | <TITLE>CUPS Design Description</TITLE> | |
5 | </HEAD> | |
6 | <BODY> | |
7 | ||
e1d6a774 | 8 | <P><EM>This document is still being updated for CUPS |
9 | 1.2...</EM></P> | |
10 | ||
11 | <P>This design description documents the overall organization of | |
12 | the Common UNIX Printing System. The purpose is not to provide a | |
13 | line-by-line description of the CUPS source code, but rather to | |
14 | describe the overall architecture and location of key pieces so | |
15 | that developers can more easily understand the underlying | |
16 | operation of CUPS.</P> | |
17 | ||
18 | <H2 CLASS="title"><A NAME="INTRO">Introduction</A></H2> | |
19 | ||
4744bd90 | 20 | <P>Like most printing systems, CUPS is designed around a central |
21 | print scheduling process that dispatches print jobs, processes | |
22 | administrative commands, provides printer status information to | |
e1d6a774 | 23 | local and remote programs, and informs users as needed. <A |
24 | HREF="#FIGURE1">Figure 1</A> shows the basic organization of | |
25 | CUPS.</P> | |
26 | ||
27 | <H3>Scheduler</H3> | |
28 | ||
29 | <P>The scheduler is a HTTP/1.1 and IPP/1.1 server application | |
30 | manages HTTP and IPP requests, printers, classes, jobs, | |
31 | subscriptions, and notifications on the system. HTTP is used for | |
32 | normal web browser services as well as IPP operation messages | |
33 | passed via HTTP POST requests with the | |
34 | <CODE>application/ipp</CODE> content type. The scheduler uses a | |
35 | series of helper Common Gateway Interface ("CGI") applications to | |
36 | provide dynamic web interfaces, and can be configured to run | |
37 | additional, site-specific programs or scripts for the web | |
38 | interface.</P> | |
39 | ||
40 | <P>The scheduler is designed as a traditional monolithic, | |
41 | single-threaded server process which runs external processes to | |
42 | do longer-term operations such as printing, notification, | |
43 | device/driver enumeration, and remote printer monitoring. While | |
44 | this design does limit the maximum number of simultaneous clients | |
45 | that can be supported on a typical system, it also keep resource | |
46 | utilization to a minimum and greatly simplifies the scheduler's | |
47 | logic.</P> | |
48 | ||
49 | <DIV CLASS="figure"><TABLE SUMMARY="CUPS Block Diagram"> | |
50 | <CAPTION>Figure 1: <A NAME="FIGURE1">CUPS Block Diagram</A></CAPTION> | |
51 | <TR><TD ALIGN="CENTER"><IMG SRC="../images/cups-block-diagram.gif" | |
52 | WIDTH="768" HEIGHT="768" ALT="CUPS Block Diagram"/></TD></TR> | |
53 | </TABLE></DIV> | |
54 | ||
55 | <H4>Job Files</H4> | |
56 | ||
57 | <P>The scheduler stores job files in a <EM>spool directory</EM>, | |
58 | typically <VAR>/var/spool/cups</VAR>. Two types of files will be | |
59 | found in the spool directory: <EM>control files</EM> starting | |
60 | with the letter "c" ("c00001", "c99999", "c100000", etc.) and | |
61 | <EM>data files</EM> starting with the letter "d" ("d00001-001", | |
62 | "d99999-001", "d100000-001", etc.) Control files are IPP messages | |
63 | based on the original IPP Print-Job or Create-Job messages, while | |
64 | data files are the original print files that were submitted for | |
65 | printing. There is one control file for every job known to the | |
66 | system and 0 or more data files for each job. Data files are | |
67 | normally removed after a job has successfully printed, however | |
68 | this behavior can be configured.</P> | |
69 | ||
70 | <H4>Log Files</H4> | |
71 | ||
72 | <P>The scheduler keeps three kinds of log files which are | |
73 | normally stored in the <VAR>/var/log/cups</VAR> directory. The <A | |
74 | HREF="ref-access_log.html">access_log</A> file lists every HTTP | |
75 | and IPP request that is processed by the scheduler. The <A | |
76 | HREF="ref-error_log.html">error_log</A> file contains messages | |
77 | from the scheduler and its helper applications that can be used | |
78 | to track down problems. The <A | |
79 | HREF="ref-page_log.html">page_log</A> file lists every page that | |
80 | is printed, allowing for simple print accounting.</P> | |
81 | ||
82 | <P>Log files are rotated automatically by the scheduler when they | |
83 | reach the configured size limit, by default 1MB. If the limit is | |
84 | set to 0 then no rotation is performed in the scheduler - this | |
85 | mode is often used by Linux distributions so they can use the | |
86 | <B>logrotated(8)</B> program to rotate them instead.</P> | |
87 | ||
88 | <H4>Config Files</H4> | |
89 | ||
90 | <P>The scheduler uses several configuration files to store the | |
91 | server settings (<A HREF="ref-cupsd-conf.html">cupsd.conf</A>), | |
92 | available classes (<A | |
93 | HREF="ref-classes-conf.html">classes.conf</A>), available | |
94 | printers (<A HREF="ref-printers-conf.html">printers.conf</A>), | |
95 | current notification subscriptions (<A | |
96 | HREF="ref-subscriptions-conf.html">subscriptions.conf</A>), and | |
97 | supported file types and filters (<A | |
98 | HREF="man-mime.types.html">mime.types</A>, <A | |
99 | HREF="man-mime.convs.html">mime.convs</A>). In addition, | |
100 | PostScript Printer Description ("PPD") files or interface scripts | |
101 | are associated with each printer, and the scheduler has cache | |
102 | files for remote printers, PPD files, and current jobs to | |
103 | optimize the scheduler's startup speed and availability.</P> | |
104 | ||
105 | <H3>Berkeley Commands</H3> | |
106 | ||
107 | <P>CUPS provides the Berkeley <A HREF="man-lpc.html">lpc(8)</A>, | |
108 | <A HREF="man-lpq.html">lpq(1)</A>, <A | |
109 | HREF="man-lpr.html">lpr(1)</A>, and <A | |
110 | HREF="man-lprm.html">lprm(1)</A> commands. In general, they | |
111 | function identically to the original Berkeley commands with the | |
112 | following exceptions:</P> | |
113 | ||
114 | <OL> | |
115 | ||
116 | <LI>The <B>lpc</B> command currently only supports the | |
117 | "status" sub-command.</LI> | |
118 | ||
119 | <LI>The <B>lpr</B> command does not support the format | |
120 | modifier options "1" (TROFF font set 1), "2" (TROFF font | |
121 | set 2), "3" (TROFF font set 3), "4" (TROFF font set 4), | |
122 | "c" (CIFPLOT), "d" (DVI), "f" (FORTRAN), "g" (GNU plot), | |
123 | "i" (indentation), "n" (Ditroff), "r" (Sun raster), "t" | |
124 | (Troff), or "w" (width), as they do not map to the IPP | |
125 | MIME media type based document formats.</LI> | |
126 | ||
127 | </OL> | |
128 | ||
129 | <H3>System V Commands</H3> | |
130 | ||
131 | <P>CUPS provides the System V <A | |
132 | HREF="man-accept.html">accept(8)</A>, <A | |
133 | HREF="man-cancel.html">cancel(1)</A>, <A | |
134 | HREF="man-lp.html">lp(1)</A>, <A | |
135 | HREF="man-lpadmin.html">lpadmin(8)</A>, <A | |
136 | HREF="man-lpmove.html">lpmove(8)</A>, <A | |
137 | HREF="man-lpstat.html">lpstat(1)</A>, and <A | |
138 | HREF="man-accept.html">reject(8)</A> commands. In general, they | |
139 | function identically to the original System V commands with the | |
140 | following exceptions:</P> | |
141 | ||
142 | <OL> | |
143 | ||
144 | <LI>All commands may ask for a password; the System V | |
145 | print spooler requires root access to perform | |
146 | administration tasks, while CUPS allows for more flexible | |
147 | configurations.</LI> | |
148 | ||
149 | <LI>The <B>lpadmin</B> command does not implement the | |
150 | Solaris "-A" (alert), "-F" (fault recovery), "-M" (mount | |
151 | form/wheel), "-P" (paper list), "-S" (print wheels), "-T" | |
152 | (type list), "-U" (dialer info), "-W" (wait), "-f" (form | |
153 | name), "-l" (content-type list), "-s" (remote printer), | |
154 | or "-t" (number of trays) options.</LI> | |
155 | ||
156 | </OL> | |
157 | ||
158 | <H3>CUPS Commands</H3> | |
159 | ||
160 | <P>CUPS provides the <A | |
161 | HREF="man-cupsaddsmb.html">cupsaddsmb(8)</A>, <A | |
162 | HREF="man-cupsenable.html">cupsdisable(8)</A>, <A | |
163 | HREF="man-cupsenable.html">cupsenable(8)</A>, <A | |
164 | HREF="man-cupstestppd.html">cupstestppd(1)</A>, <A | |
165 | HREF="man-lpinfo.html">lpinfo(8)</A>, and <A | |
166 | HREF="man-lppasswd.html">lppasswd(1)</A> commands. The | |
167 | <B>cupsdisable</B> and <B>cupsenable</B> commands correspond to | |
168 | the System V <B>disable</B> and <B>enable</B> commands but have | |
169 | been renamed to avoid conflicts with the <B>bash(1)</B> internal | |
170 | commands of the same name.</P> | |
171 | ||
172 | <H3>LPD Support</H3> | |
173 | ||
174 | <P>LPD client support is provided via the <A | |
175 | HREF="man-cups-lpd.html">cups-lpd(8)</A> program. Incoming LPD | |
176 | requests are accepted on TCP port 515 by the local | |
177 | <B>inetd(8)</B>, <B>launchd(8)</B>, or <B>xinetd(8)</B> process | |
178 | and forwarded to the <B>cups-lpd</B> program for conversion to | |
179 | the corresponding IPP request(s).</P> | |
180 | ||
181 | <P>The <B>cups-lpd</B> program conforms, for the most part, to | |
182 | RFC 1179: Line Printer Daemon Protocol, but does not enforce the | |
183 | privileged source port restriction specified in that document. In | |
184 | addition, the banner page and output format options are usually | |
185 | overridden via command-line options to the <B>cups-lpd</B> | |
186 | program when it is invoked by the corresponding super-daemon | |
187 | program.</P> | |
188 | ||
189 | <H3>Web Interface</H3> | |
190 | ||
191 | <P>The web interface is supported by five CGI programs. Table 1 | |
192 | describes the purpose of each of the programs.</P> | |
193 | ||
194 | <DIV CLASS="table"><TABLE SUMMARY="CGI Programs"> | |
195 | <CAPTION>Table 1: <A NAME="TABLE1">CGI Programs</A></CAPTION> | |
196 | <THEAD> | |
197 | <TR> | |
198 | <TH>Program</TH> | |
199 | <TH>Location</TH> | |
200 | <TH>Description</TH> | |
201 | </TR> | |
202 | </THEAD> | |
203 | <TBODY> | |
204 | <TR> | |
205 | <TD>admin.cgi</TD> | |
206 | <TD>/admin</TD> | |
207 | <TD>Provides all of the administrative functions</TD> | |
208 | </TR> | |
209 | <TR> | |
210 | <TD>classes.cgi</TD> | |
211 | <TD>/classes</TD> | |
212 | <TD>Lists classes and provides class management functions</TD> | |
213 | </TR> | |
214 | <TR> | |
215 | <TD>help.cgi</TD> | |
216 | <TD>/help</TD> | |
217 | <TD>Provides access to on-line help documents</TD> | |
218 | </TR> | |
219 | <TR> | |
220 | <TD>jobs.cgi</TD> | |
221 | <TD>/jobs</TD> | |
222 | <TD>Lists jobs and provides job management functions</TD> | |
223 | </TR> | |
224 | <TR> | |
225 | <TD>printers.cgi</TD> | |
226 | <TD>/printers</TD> | |
227 | <TD>Lists printers and provides printer management functions</TD> | |
228 | </TR> | |
229 | </TBODY> | |
230 | </TABLE></DIV> | |
231 | ||
232 | <H3>Notifiers</H3> | |
233 | ||
234 | <P>Notifiers provide the means for sending event notifications | |
235 | from the scheduler. Notifiers are executed with the recipient | |
236 | information on the command-line and the event data on the | |
237 | standard input.</P> | |
238 | ||
239 | <P>The <B>mailto</B> notifier is the only notifier included with | |
240 | CUPS 1.2 and handles email notifications for the scheduler. | |
241 | Additional notifiers can be added as needed without additional | |
242 | configuration.</P> | |
243 | ||
244 | <H3>Filters</H3> | |
245 | ||
246 | <P>Filters convert job files into a printable format. Multiple | |
247 | filters are run, as needed, to convert from the job file format | |
248 | to the printable format. A filter program reads from the standard | |
249 | input or from a file if a filename is supplied. All filters must | |
250 | support a common set of options including printer name, job ID, | |
251 | username, job title, number of copies, and job options. All | |
252 | output is sent to the standard output.</P> | |
253 | ||
254 | <P>CUPS provides filters for printing text, PostScript, PDF, | |
255 | HP-GL/2, and many types of image files. CUPS also provides | |
256 | printer driver filters for HP-PCL, ESC/P, and several types of | |
257 | label printers. Additional filters can be added through the use | |
258 | of mime.convs and PPD files.</P> | |
259 | ||
260 | <H3>Port Monitors</H3> | |
261 | ||
262 | <P>Port monitors handle the device- and channel-specific data | |
263 | formatting for a printer. Port monitors use the same interface as | |
264 | filters.</P> | |
265 | ||
266 | <P>CUPS includes two port monitors: the <B>bcp</B> port monitor | |
267 | which supports the PostScript Binary Communications Protocol | |
268 | ("BCP") and the <b>tbcp</b> port monitor which supports the | |
269 | PostScript Tagged Binary Communications Protocol ("TBCP"). | |
270 | Additional port monitors can be added through PPD files.</P> | |
271 | ||
272 | <H3>Backends</H3> | |
273 | ||
274 | <P>Backends send print data to the printer and enumerate | |
275 | available printers/devices as needed. Backends use the same | |
276 | interface as filters.</P> | |
277 | ||
278 | <P>CUPS includes backends for parallel, serial, SCSI, USB, LPD, | |
279 | IPP, and AppSocket (JetDirect) connections. Additional backends | |
280 | can be added as needed without additional configuration.</P> | |
281 | ||
282 | <H2 CLASS="title"><A NAME="PROGRAMMING">Programming Interfaces</A></H2> | |
283 | ||
284 | <P>CUPS makes use of two general-purpose libraries to provide its | |
285 | printing services. The CUPS library provides the general | |
286 | communications and management infrastructure while the CUPS | |
287 | imaging library provides the image file and raster data | |
288 | support.</P> | |
289 | ||
290 | <H3>CUPS Libary</H3> | |
291 | ||
292 | <P>The CUPS library contains CUPS-specific convenience functions | |
293 | for queuing print jobs, getting printer information, accessing | |
294 | resources via HTTP and IPP, and manipulating PPD files. Unlike | |
295 | the rest of CUPS, the CUPS API is provided under the terms of the | |
296 | GNU LGPL so it may be used by non-GPL applications.</P> | |
297 | ||
298 | <H3>CUPS Imaging Library</H3> | |
299 | ||
300 | <P>The CUPS imaging library provides functions for managing large | |
301 | images, doing colorspace conversion and color management, scaling | |
302 | images for printing, and managing raster page streams. It is used | |
303 | by the CUPS image file filters, the PostScript RIP, and all | |
304 | raster printers drivers.</P> | |
305 | ||
306 | <!--<H2 CLASS="title">Network Printing</H2> | |
307 | ||
308 | <P>Traditionally, network printing has been one of the hardest | |
309 | things to get working under UNIX. One reason is because each | |
310 | vendor added their own extensions to the LPD protocol (the | |
311 | previous standard for network printing), making cross-platform | |
312 | printing difficult if not impossible.</P> | |
313 | ||
314 | <P>Another reason is that you have to administer every network | |
315 | printer on every client machine. In some cases you can "clone' | |
316 | the printer configuration from a "master' client to each of the | |
317 | others, but even that can be time-consuming and error-prone. | |
318 | Something better is needed.</P> | |
319 | ||
320 | <P>CUPS provides "printer browsing", which allows clients to | |
321 | automatically see and use printers from any server on a LAN. | |
322 | This means that you only need to configure the server and the | |
323 | clients will automatically see the printers and classes on | |
324 | it.</P> | |
325 | ||
326 | <P>In addition, CUPS can automatically merge multiple identical | |
327 | network printers into "implicit classes". This allows clients to | |
328 | send jobs to the implicit class and have them print on the first | |
329 | available printer or server. In addition, failsafe and | |
330 | load-balancing functions are enabled simply by defining the same | |
331 | printer on multiple servers!</P> | |
4744bd90 | 332 | |
333 | <H3>Scheduler</H3> | |
334 | ||
335 | <P>The scheduler is a HTTP/1.1 server application that handles | |
336 | HTTP requests. Besides handling printer requests via IPP POST | |
337 | requests, the scheduler also acts as a full-featured web server | |
338 | for documentation, status monitoring, and administration.</P> | |
339 | ||
340 | <P>The scheduler also manages a list of available printers on | |
341 | the LAN and dispatches print jobs as needed using the | |
342 | appropriate filters and backends.</P> | |
343 | ||
344 | <H3>Configuration Files</H3> | |
345 | ||
346 | <P>The configuration files consist of:</P> | |
347 | ||
348 | <ul> | |
349 | ||
350 | <LI>The HTTP server configuration file.</LI> | |
351 | ||
352 | <LI>Printer and class definition files.</LI> | |
353 | ||
354 | <LI>MIME type and conversion rule files.</LI> | |
355 | ||
356 | <LI>PostScript Printer Description (PPD) files.</LI> | |
357 | ||
358 | </ul> | |
359 | ||
360 | <P>The HTTP server configuration file is purposely similar to | |
361 | the Apache server configuration file and defines all of the | |
362 | access control properties for the server.</P> | |
363 | ||
364 | <P>The printer and class definition files list the available | |
365 | printer queues and classes. Printer classes are collections of | |
366 | printers. Jobs sent to a class are forwarded to the first | |
367 | available printer in the class, round-robin fashion.</P> | |
368 | ||
369 | <P>The MIME type files list the supported MIME types | |
370 | (text/plain, application/postscript, etc.) and "magic' rules for | |
371 | automatically detecting the format of a file. These are used by | |
372 | the HTTP server to determine the <tt>Content-Type</tt> field for | |
373 | <tt>GET</tt> and <tt>HEAD</tt> requests and by the IPP request | |
374 | handler to determine the file type when a <tt>Print-Job</tt> or | |
375 | <tt>Send-File</tt> request is received with a | |
376 | <tt>document-format</tt> of | |
377 | <tt>application/octet-stream</tt>.</P> | |
378 | ||
379 | <P>The MIME conversion rule files list the available filters. | |
380 | The filters are used when a job is dispatched so that an | |
381 | application can send a convenient file format to the printing | |
382 | system which then converts the document into a printable format | |
383 | as needed. Each filter has a relative cost associated with it, | |
384 | and the filtering algorithm chooses the set of filters that will | |
385 | convert the file to the needed format with the lowest total | |
386 | "cost".</P> | |
387 | ||
388 | <P>The PPD files describe the capabilities of all printers, not | |
389 | just PostScript printers. There is one PPD file for each | |
390 | printer. PPD files for non-PostScript printers define additional | |
391 | filters through <tt>cupsFilter</tt> attributes to support | |
392 | printer drivers.</P> | |
e1d6a774 | 393 | --> |
4744bd90 | 394 | |
395 | </BODY> | |
396 | </HTML> |