|
Table of ContentsPreface 1 - Printing System Overview 2 - Building and Installing CUPS 3 - Printer Queue Management
|
||||||||||||||||||||||||||||||||||||
|
PrefaceThis software administrators manual provides printer administration information for the Common UNIX Printing System ("CUPS") Version 1.0.4. |
||||||||||||||||||||||||||||||||||||
Contents Next |
System OverviewThe Common UNIX Printing System provides a portable printing layer for UNIX® operating systems. It has been developed by Easy Software Products to promote a standard printing solution for all UNIX vendors and users. CUPS provides the System V and Berkeley command-line interfaces.CUPS uses the Internet Printing Protocol (IETF-IPP) as the basis for managing print jobs and queues. The Line Printer Daemon (LPD, RFC1179), Server Message Block (SMB), and AppSocket protocols are also supported with reduced functionality. CUPS adds network printer browsing and PostScript Printer Description ("PPD")-based printing options to support real world applications under UNIX. CUPS also includes a customized version of GNU GhostScript (currently based off GNU GhostScript 4.03) and an image file RIP that can be used to support non-PostScript printers. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Document OverviewThis software administrators manual is organized into the following sections:
|
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
1 - Printing System OverviewThis chapter provides an overview of how the Common UNIX Printing System works. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
The Printing ProblemFor years the printing problem has plagued UNIX®. Unlike Microsoft® Windows® or MacOS, UNIX has no standard interface or system in place for supporting printers. Among the solutions previously available, the Berkeley and System V printing systems are the most prevalent. These printing systems support line printers (text only) or PostScript printers (text and graphics), and with some coaxing they can be made to support a full range of printers and file formats. However, because each varient of the UNIX operating system uses a different printing system than the next, developing printer drivers for a wide range of printers is extremely difficult. That combined with the limited volume of customers for each UNIX varient has forced most printer vendors to give up supporting UNIX entirely. The Common UNIX Printing System, or CUPS, is designed to eliminate the printing problem. One common printing system can be used by all UNIX varients to support the printing needs of users. Printer vendors can use its modular filter interface to develop a single driver program that supports a wide range of file formats with little or no effort. Since CUPS provides both the System V and Berkeley printing commands, users (and applications) can reap the benefits of this new technology with no changes. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
The TechnologyCUPS is based upon an emerging Internet standard called the Internet Printing Protocol, or IPP. IPP has been embraced by dozens of printer and printer server manufacturers, and will be supported by the next Microsoft Windows operating system. IPP defines a standard protocol for printing as well as managing print jobs and printer options like media size, resolution, and so forth. Like all IP-based protocols, IPP can be used locally or over the Internet to printers hundreds or thousands of miles away. Unlike other protocols, however, IPP also supports access control, authentication, and encryption, making it a much more secure printing solution than older ones. IPP is layered on top of the Hyper-Text Transport Protocol, or HTTP, which is the basis of web servers on the Internet. This allows the user to view documentation and status information on a printer or server using their web browser. CUPS provides a complete IPP/1.0-based printing system that provides Basic authentication and domain or IP-based access control. Digest authentication and TLS encryption will be available in future versions of CUPS. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
JobsEach file that is submitted for printing is called a job. Jobs are identified by a unique number starting at 1 and are assigned to a particular destination (usually a printer). Jobs can also have options associated with them such as media size, number of copies, and priority. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
ClassesCUPS supports collections of printers known as classes. Jobs sent to a class are forwarded to the first available printer in the class. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
FiltersFilters allow a user or application to print many types of files without extra effort. Print jobs sent to a CUPS server are filtered before sending them to a printer. Some filters convert job files to different formats that the printer can understand. Others perform page selection and ordering tasks. Backend filters perform the most important task of all - they send the filtered print data to the printer. CUPS provides filters for printing many types of image files, HP-GL/2 files, PDF files, and text files. CUPS also supplies PostScript and image file Raster Image Processors, or RIPs, that convert PostScript or image files into bitmaps that can be sent to a raster printer. CUPS provides backends for printing over parallel and serial ports, and over the network via the JetDirect (AppSocket), Server Message Block, and Line Printer Daemon protocols. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Printer DriversPrinter drivers in CUPS consist of one of more filters specific to a printer. CUPS includes a sample printer driver for Hewlett-Packard LaserJet and DeskJet printers. While this driver does not generate optimal output for different printer models, it does demonstrate how you can write your own printer drivers and incorporate them into CUPS. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
NetworkingPrinters and classes on the local system are automatically shared with other systems on the network. This allows you to setup one system to print to a printer and use this system as a printer server or spool host for all of the others. If there is only one occurrence of a printer on a network, then that printer can be accessed using its name alone. If more than one printer exists with the same name, users must select the printer by specifying which server to use (e.g. "printer@host1" or "printer@host2".) CUPS also provides implicit classes, which are collections of printers and/or classes with the same name. This allows you to setup multiple servers pointing to the same physical network printer, for example, so that you aren't relying on a single system for printing. Because this also works with printer classes, you can setup multiple servers and printers and never worry about a "single point of failure" unless all of the printers and servers goes down! |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
2 - Building and Installing CUPSThis chapter shows how to build and install the Common UNIX Printing System. If you are installing a binary distribution from the CUPS web site, proceed to the section titled, Installing a Binary Distribution. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Installing a Source DistributionRequirementsYou'll need an ANSI C compiler to build CUPS on your system. As its name implies, CUPS is designed to run on the UNIX operating system, however the CUPS interface library and most of the filters and backends supplied with CUPS should also run under Microsoft® Windows®. For the image file filters and PostScript RIP, you'll need the JPEG, PNG, TIFF, and ZLIB libraries. CUPS will build without these, but with reduced functionality. Easy Software Products maintains a mirror of the current versions of these libraries at: ftp://ftp.easysw.com/pub/libraries If you make changes to the man pages you'll need GNU groff or another nroff-like package. GNU groff is available from: ftp://ftp.gnu.org/pub/groff The documentation is formatted using the HTMLDOC software. If you need to make changes you can get the HTMLDOC software from: http://www.easysw.com/htmldoc Compiling CUPSCUPS uses GNU autoconf to configure the makefiles and source code for your system. To configure CUPS for your system type: % ./configure ENTER The default installation will put the CUPS software in the % ./configure --prefix=/usr/local ENTER If the PNG, JPEG, TIFF, and ZLIB libraries are not installed in a
system default location (typically % setenv CFLAGS "-I/some/directory" % setenv LDFLAGS "-L/some/directory" % ./configure ... ENTER Once you have configured things, just type: % make ENTER to build the software. Installing the SoftwareTo install the software type: % make install ENTER Running the SoftwareOnce you have installed the software you can start the CUPS daemon by typing:% /usr/sbin/cupsd & ENTER |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Installing a Binary DistributionWe are currently distributing CUPS binary distributions in TAR format with installation and removal scripts.
Installing CUPS will overwrite your existing printing system. If you experience difficulties with the CUPS software and need to go back to your old printing system, you will need to remove the CUPS software with the provided script and reinstall the printing system from your operating system CDs. To install the CUPS software you will need to be logged in as root (doing an "su" is good enough). Once you are the root user, run the installation script with: ./cups.install ENTER After asking you a few yes/no questions the CUPS software will be installed and the scheduler will be started automatically. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
3 - Printer Queue ManagementThis chapter discusses how to add, modify, and delete print queues on your system. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
The lpadmin CommandThe |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Adding and Modifying PrintersTo add a printer to CUPS you simply run the % /usr/lib/lpadmin -pprinter -E -vdevice -Pppd ENTER Spaces between the option letter and value are optional. The printer name can be up to 127 letters, digits, hyphens, and underscores.
Unlike other printing systems, the printer name in CUPS is not case-sensitive, so you can't add two printers named The device argument specifies the device URI or filename for the printer. The following devices are supported in a basic installation of CUPS:
The ppd argument specifies the PostScript Printer Description file to use
for this printer. Many options (such as media size, etc.) will not be
available if you omit this part of the Using Standard Printer Drivers |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
The % /usr/lib/lpadmin -pprinter -E -vdevice -mmodel ENTER The model argument specifies the name of the PPD file or interface script. For example, to add a printer using the sample HP DeskJet series driver connected to parallel port 1 under Linux you would use: % /usr/lib/lpadmin -pDeskJet -E -vparallel:/dev/par1 -mdeskjet.ppd ENTER |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Removing PrintersTo remove a printer to CUPS you simply run the % /usr/lib/lpadmin -xprinter ENTER |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Printer ClassesCUPS allows you to group similar printers in a printer class. When a user sends a print job to a class, the job will be processed by the first available printer in that class. To add a printer to a class you simply run the % /usr/lib/lpadmin -pprinter -cclass ENTER The class is created automatically if it doesn't exist. To remove a class just use the "-x" option: % /usr/lib/lpadmin -xclass ENTER |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Setting the Default PrinterTo set the default printer or class simply run the % /usr/lib/lpadmin -ddestination ENTER The destination argument is the name of the printer or class. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Starting and Stopping PrintersThe % /usr/bin/enable printer ENTER % /usr/bin/disable printer ENTER Printers that are disabled may still accept jobs for printing, but won't actually print any files until they are restarted. This is useful if the printer malfunctions and you need time to correct the problem. Any queues jobs are printed after the printer is enabled (started). |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Accepting and Rejecting Print JobsThe % /usr/lib/accept printer ENTER % /usr/lib/reject printer ENTER As noted above, a printer can be stopped but accepting new print jobs. A printer can also be rejecting new print jobs while it finishes those that have been queued. This is useful for when you must perform maintenance on the printer and will not have it available to users for a long period of time. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
4 - Printing System ManagementThis chapter shows how you can configure the CUPS server. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Changing the Configuration FilesAll of the server configuration files are located in the % ./cups.sh restart ENTER The binary distribution installs the script in the |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Temporary FilesNormally CUPS puts all of its temporary files in Start by creating the new temporary directory and setting the appropriate permissions: % mkdir /foo/bar/tmp ENTER % chmod a+rwxt /foo/bar/tmp ENTER Then change the line containing the TempDir /foo/bar/tmp Finally, restart the server as outlined in the first section of this chapter. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Network ConfigurationThe default configuration of the CUPS server listens for connections from all network interfaces on port 631 (the standard IPP port). Administration functions are limited to local connections with the appropriate username and password. If you'd like to limit access to your system you'll need to edit the PortThe ListenThe Listen 127.0.0.1:631 instead of the If you want to limit access to a specific network/subnet, make sure you specify only the network address and not your system's network address! BrowsePortThe
You must set the BrowseAddressThe
If you are using HP-UX 10.20 and a subnet that is not 24, 16, or 8 bits, printer browsing (and in fact all broadcast reception) will not work. This problem appears to be fixed in HP-UX 11.0. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Printer SecurityCUPS provides IP and domain-name based access control and Basic authentication for authentication. LocationThe
All other directories are taken from the The
OrderThe
The AllowThe Allow from All Allow from None Allow from *.domain.com Allow from .domain.com Allow from host.domain.com Allow from nnn.* Allow from nnn.nnn.* Allow from nnn.nnn.nnn.* Allow from nnn.nnn.nnn.nnn Allow from nnn.nnn.nnn.nnn/mm Allow from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
The DenyThe Deny from All Deny from None Deny from *.domain.com Deny from .domain.com Deny from host.domain.com Deny from nnn.* Deny from nnn.nnn.* Deny from nnn.nnn.nnn.* Deny from nnn.nnn.nnn.nnn Deny from nnn.nnn.nnn.nnn/mm Deny from nnn.nnn.nnn.nnn/mmm.mmm.mmm.mmm
The AuthTypeThe
The AuthClassThe
The AuthGroupNameThe The SystemGroupThe |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
File FormatsCUPS provides a MIME-based file typing and filtering mechanism to
convert files to a printable format for each printer. The mime.typesThe text/html html htm \ printable(0,1024) + (string(0,"") string(0,"
mime.convsThe source destination cost program text/plain application/postscript 50 texttops application/vnd.cups-postscript application/vnd.cups-raster 50 pstoraster image/* application/vnd.cups-postscript 50 imagetops image/* application/vnd.cups-raster 50 imagetoraster The source field is a MIME type, optionally using a wildcard for the super-type or sub-type (e.g. "text/plain", "image/*", "*/postscript"). The destination field is a MIME type defined in the The cost field defines a relative cost for the filtering operation from 1
to 100. The cost is used to choose between two different sets of
filters when converting a file. For example, to convert from The program field defines the filter program to run; the special program "-" can be used to make two file types equivalent. The program must accept the standard filter arguments and environment variables described in the CUPS Interface Design Document: program job user title options [filename] If specified, the filename argument defines a file to read when filtering, otherwise the filter must read from the standard input. All filtered output must go to the standard output. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
5 - Printer AccountingThis chapter describes the CUPS log files. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
Where to Find the Log FilesThe log files are normally stored in the |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
The access_log FileThe host group user date-time \"method resource version\" status bytes 127.0.0.1 - - [20/May/1999:19:20:29 +0000] "POST /admin/ HTTP/1.1" 401 0 127.0.0.1 - mike [20/May/1999:19:20:31 +0000] "POST /admin/ HTTP/1.1" 200 0 The host field will normally only be an IP address unless you have changed
the The group field always contains "-". The user field is the authenticated username of the requesting user. If no username and password is supplied for the request then this field contains "-". The date-time field is the date and time of the request in Greenwich Mean Time (a.k.a. ZULU) and is in the format: [DD/MON/YYYY:HH:MM:SS +0000] The method field is the HTTP method used ("GET", "PUT", "POST", etc.) The resource field is the filename of the requested resource. The version field is the HTTP specification version used by the client. For CUPS clients this will always be "HTTP/1.1". The status field contains the HTTP result status of the request. Usually it is "200", but other HTTP status codes are possible. For example, 401 is the "unauthorized access" status in the example above. The bytes field contains the number of bytes in the request. For POST requests the bytes field contains the number of bytes of non-IPP data that is received from the client. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
The error_log FileThe level date-time message I [20/May/1999:19:18:28 +0000] Job 1 queued on 'DeskJet' by 'mike'. I [20/May/1999:19:21:02 +0000] Job 2 queued on 'DeskJet' by 'mike'. I [20/May/1999:19:22:24 +0000] Job 2 was cancelled by 'mike'. The level field contains the type of message:
The date-time field contains the date and time of when the page started
printing. The format of this field is identical to the data-time field in the The message fields contains a free-form textual message. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
The page_log FileThe printer user job-id date-time page-number num-copies DeskJet root 2 [20/May/1999:19:21:05 +0000] 1 0 The printer field contains the name of the printer that printed the page. If you send a job to a printer class, this field will contain the name of the printer that was assigned the job. The user field contains the name of the user (the IPP The job-id field contains the job number of the page being printed. Job numbers are reset to 1 whenever the CUPS server is started, so don't depend on this number being unique! The date-time field contains the date and time of when the page started
printing. The format of this field is identical to the data-time field in the The page-number and num-pages fields contain the page number and number of copies being printed of that page. For printer that can not produce copies on their own, the num-pages field will always be 1. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
A - Using CUPS with SAMBAThis appendix describes how to use CUPS with SAMBA. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
What is SAMBA?In case you haven't heard of SAMBA, it is basically a software package that allows you to configure your UNIX system as a Windows file and printer server. It also allows you to access files and printers on a Windows system. Like CUPS, SAMBA is free software. SAMBA version 2.0.6 is the first release of SAMBA that supports CUPS. You can download SAMBA from: |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
How Do I Configure SAMBA for CUPS?To configure SAMBA for CUPS, edit the printing = cups That's all there is to it! Remote users will now be able to browse and print to printers on your system. |
||||||||||||||||||||||||||||||||||||
Contents Previous Next |
How Do I Configure CUPS for SAMBA?To configure CUPS for SAMBA, run the following command: % ln -s `which smbspool` /var/cups/backend/smb ENTER The % lpadmin -p printer -v smb://hostname/printer ... ENTER % lpadmin -p printer -v smb://workgroup/hostname/printer ... ENTER The second form only needs to be used if the Windows system is in a different workgroup. |