doc/help/spec-design.html

   1 <HTML>
   2 <!-- SECTION: Specifications -->
   3 <HEAD>
   4         <TITLE>CUPS Design Description</TITLE>
   5 </HEAD>
   6 <BODY>
   7
   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
  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
  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>
 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>
 393 -->
 394
 395 </BODY>
 396 </HTML>