docs/115220: Patch to Handbook Printer Section to Add CUPS Configuration
Chess Griffin
chess.griffin at gmail.com
Sun Aug 5 15:20:01 UTC 2007
>Number: 115220
>Category: docs
>Synopsis: Patch to Handbook Printer Section to Add CUPS Configuration
>Confidential: no
>Severity: non-critical
>Priority: low
>Responsible: freebsd-doc
>State: open
>Quarter:
>Keywords:
>Date-Required:
>Class: change-request
>Submitter-Id: current-users
>Arrival-Date: Sun Aug 05 15:20:00 GMT 2007
>Closed-Date:
>Last-Modified:
>Originator: Chess Griffin
>Release: 7.0-CURRENT
>Organization:
>Environment:
FreeBSD bsdbob.localdomain 7.0-CURRENT FreeBSD 7.0-CURRENT #0: Mon Jul 30 06:25:50 EDT 2007 root at bsdbob.localdomain:/usr/obj/usr/src/sys/CNG i386
>Description:
This is a diff to /doc/en_US.ISO8859-1/books/handbook/printing/chapter.sgml to provide some information on CUPS installation and configuration. I hope this diff works okay. Please let me know if I need to resubmit. I also look forward to feedback, changes, edits, etc. Thanks!
--- chapter.sgml.old 2007-08-04 16:08:25.000000000 -0400
+++ chapter.sgml 2007-08-04 16:08:39.000000000 -0400
@@ -4519,14 +4519,214 @@
</sect2>
</sect1>
+ <sect1 id="printing-cups">
+ <sect1info>
+ <authorgroup>
+ <author>
+ <firstname>Chess</firstname>
+ <surname>Griffin</surname>
+ <contrib>Restructured and rewritten by </contrib>
+ </author>
+ </authorgroup>
+ </sect1info>
+ <title>Common UNIX Printing System (CUPS)</title>
+
+ <para><application>CUPS</application>, the Common UNIX Printing
+ System, provides a portable printing layer for &unix;-based
+ operating systems. It has been developed by Easy Software
+ Products to promote a standard printing solution for all &unix;
+ vendors and users.</para>
+
+ <para><application>CUPS</application> uses the Internet Printing
+ Protocol (<acronym>IPP</acronym>) as the basis for managing
+ print jobs and queues. The Line Printer Daemon
+ (<acronym>LPD</acronym>), Server Message Block
+ (<acronym>SMB</acronym>), and AppSocket (a.k.a. JetDirect)
+ protocols are also supported with reduced functionality. CUPS
+ adds network printer browsing and PostScript Printer Description
+ (<acronym>PPD</acronym>) based printing options to support
+ real-world printing under &unix;. As a result, CUPS is ideally-suited for sharing and accessing printers in mixed environments of FreeBSD, Linux, Macintosh OS X, or Windows.</para>
+
+ <para>The main site for <application>CUPS</application> is <ulink
+ url="http://www.cups.org/"></ulink>.</para>
+
+ <sect2 id="printing-cups-install">
+ <title>Installing the CUPS Print Server</title>
+
+ <para><application>CUPS</application> can be installed from ports or by using a precompiled
+ binary package. To install <application>CUPS</application> from ports, issue the
+ following command from a root terminal:</para>
+ <screen>&prompt.root; <userinput>cd /usr/ports/print/cups && make install clean</userinput></screen>
+ <para>To install <application>CUPS</application> using a precompiled binary, issue the following
+command from a root terminal:</para>
+ <screen>&prompt.root; <userinput>pkg_add -r cups</userinput></screen>
+ <para>Other optional, but recommended, ports or packages are <application>print/gutenprint-cups</application> and <application>print/hplip</application>, both of which add drivers and utilities for a variety of printers. Once installed, the <application>CUPS</application> configuration files can be found in the directory <filename>/usr/local/etc/cups</filename>.</para>
+ </sect2>
+
+ <sect2 id="printing-cups-configuring-server">
+ <title>Configuring the CUPS Print Server</title>
+ <para>After installation, a few files must edited in order to configure the <application>CUPS</application> server. First, create or modify, as the case may be, the file <filename>/etc/devfs.rules</filename> and add the following information to set the proper permissions on all potential printer devices and to associate printers with the cups user group:</para>
+
+<programlisting>[system=10]
+add path 'unlpt*' mode 0660 group cups
+add path 'ulpt*' mode 0660 group cups
+add path 'lpt*' mode 0660 group cups</programlisting>
+
+<para>Next, add two lines to <filename>/etc/rc.conf</filename> as follows:</para>
+
+<programlisting>cupsd_enable="YES"
+devfs_system_ruleset="system"</programlisting>
+
+<para>These two entries will start the <application>CUPS</application> print server on boot and invoke the local devfs rule created above, respectively.</para>
+
+<para>In order to enable <application>CUPS</application> printing under certain Microsoft Windows clients, the line <programlisting>application/octet-stream</programlisting> should be uncommented in <filename>/usr/local/etc/cups/mime.types</filename> and <filename>/usr/local/etc/cups/mime.convs</filename>.</para>
+
+<para>Once these changes have been made, the devfs and <application>CUPS</application> systems must both be restarted, either by rebooting the computer or issuing the following two commands in a root terminal:</para>
+
+<screen>&prompt.root; <userinput>/etc/rc.d/devfs restart</userinput>
+&prompt.root; <userinput>/usr/local/etc/rc.d/cupsd restart</userinput></screen>
+</sect2>
+
+<sect2 id="printing-cups-configuring-printers">
+ <title>Configuring Printers on the CUPS Print Server</title>
+ <para>After the <application>CUPS</application> system has been installed and configured, the administrator can begin configuring the local printers attached to the <application>CUPS</application> print server. This part of the process is very similar, if not identical, to configuring <application>CUPS</application> printers on other &unix;-based operating systems, such as a Linux distribution.</para>
+ <para>The primary means for managing and administering the <application>CUPS</application> server is through the web-based interface, which can be found by launching a web browser and entering <filename>http://localhost:631</filename> in the browser's URL bar. If the <application>CUPS</application> server is on another machine on the network, substitute the server's local <acronym>IP</acronym> addresss for "localhost." The <application>CUPS</application> web interface is fairly self-explanatory, as there are sections for managing printers and print jobs, authorizing users, and more. Additionally, on the right-hand side of the Administration screen are several check-boxes allowing easy access to commonly-changed settings, such as whether to share published printers connected to the system, whether to allow remote administration of the <application>CUPS</application> server, and whether to allow users additional access and privileges to the printers and print jobs.</para>
+ <para>Adding a printer is generally as easy as clicking "Add Printer" at the Administration screen of the <application>CUPS</application> web interface, or clicking one of the "New Printers Found" buttons also at the Administration screen. When presented with the "Device" drop-down box, simply select the desired locally-attached printer, and then continue through the process. If one has added the <application>print/gutenprint-cups</application> or <application>print/hplip</application> ports or packages as referenced above, then additional print drivers will be available in the subsequent screens that might provide more stability or features.</para>
+</sect2>
+
+<sect2 id="printing-cups-clients">
+ <title>Configuring CUPS Clients</title>
+ <para>Once the <application>CUPS</application> server has been configured and printers have been added and published to the network, the next step is to configure the clients, or the machines that are going to access the <application>CUPS</application> server. If one has a single desktop machine that is acting as both server and client, then much of this information may not be needed.</para>
+
+<sect3 id="printing-cups-clients-unix">
+ <title>&unix; Clients</title>
+ <para><application>CUPS</application> will also need to be installed on your &unix; clients. Once <application>CUPS</application> is installed on the clients, then <application>CUPS</application> printers that are shared across the network are often automatically discovered by the printer managers for various desktop environments such as <application>GNOME</application> or <application>KDE</application>. Alternatively, one can access the local <application>CUPS</application> interface on the client machine at <filename>http://localhost:631</filename> and click on "Add Printer" in the Administration section. When presented with the "Device" drop-down box, simply select the networked <application>CUPS</application> printer, if it was automatically discovered, or select "ipp" or "http" and enter the ipp or http URI of the networked <application>CUPS</application> printer, usually in one of the two following syntaxes:</para>
+
+<programlisting>ipp://server-name-or-ip/printers/printername</programlisting>
+<programlisting>http://server-name-or-ip:631/printers/printername</programlisting>
+
+<para>If the <application>CUPS</application> clients have difficulty finding other <application>CUPS</application> printers shared across the network, sometimes it is helpful to add or create a file <filename>/usr/local/etc/cups/client.conf</filename> with a single entry as follows:</para>
+
+<programlisting>ServerName (server-ip)</programlisting>
+
+<para>In this case, (server-ip) would be replaced by the local IP address of the <application>CUPS</application> server on the network.</para>
+</sect3>
+
+<sect3 id="printing-cups-clients-windows">
+ <title>Windows Clients</title>
+ <para>Versions of Windows prior to XP did not have the capability to natively network with IPP-based printers. However, Windows XP and later versions do have this capability. Therefore, to add a <application>CUPS</application> printer in these versions of Windows is quite easy. Generally, the Windows administrator will run the Windows "Add Printer" wizard, select "Network Printer" and then enter the <acronym>URI</acronym> in the following syntax:</para>
+
+<programlisting>http://server-name-or-ip:631/printers/printername</programlisting>
+
+<para>If one has an older version of Windows without native IPP printing support, then the general means of connecting to a <application>CUPS</application> printer is to use <application>Samba</application> and <application>CUPS</application> together, which is a topic outside the scope of this chapter.</para>
+</sect3>
+</sect2>
+
+<sect2 id="printing-cups-troubleshooting">
+ <title>CUPS Troubleshooting</title>
+ <para>Difficulties with <application>CUPS</application> often lies in permissions. First, double check the devfs permissions as outlined above. Next, check the actual permissions of the devices created in the filesystem. It is also helpful to make sure your user is a member of the "cups" group. If the permissions check boxes in the "Administration" section of the <application>CUPS</application> web interface do not seem to be working, another fix might be to manually backup the main <application>CUPS</application> configuration file located at <filename>/usr/local/etc/cups/cupsd.conf</filename> and edit the various configuration options and try different combinations of configuration options. One sample <filename>/usr/local/etc/cups/cupsd.conf</filename> to test is listed below. Please note that this sample <filename>cupsd.conf</filename> file sacrifices security for easier configuration; once the administrator successfully connnects to the <application>CUPS</applicat
ion> server and configures the clients, it is advisable to revisit this configuration file and begin locking down access.</para>
+
+<programlisting># Log general information in error_log - change "info" to "debug" for
+# troubleshooting...
+LogLevel info
+
+# Administrator user group...
+SystemGroup wheel
+
+# Listen for connections on Port 631.
+Port 631
+#Listen localhost:631
+Listen /var/run/cups.sock
+
+# Show shared printers on the local network.
+Browsing On
+BrowseOrder allow,deny
+#BrowseAllow @LOCAL
+BrowseAllow 192.168.1.* # change to local LAN settings
+BrowseAddress 192.168.1.* # change to local LAN settings
+
+# Default authentication type, when authentication is required...
+DefaultAuthType Basic
+DefaultEncryption Never # comment this line to allow encryption
+
+# Allow access to the server from any machine on the LAN
+<Location />
+ Order allow,deny
+ #Allow localhost
+ Allow 192.168.1.* # change to local LAN settings
+</Location>
+
+# Allow access to the admin pages from any machine on the LAN
+<Location /admin>
+ #Encryption Required
+ Order allow,deny
+ #Allow localhost
+ Allow 192.168.1.* # change to local LAN settings
+</Location>
+
+# Allow access to configuration files from any machine on the LAN
+<Location /admin/conf>
+ AuthType Basic
+ Require user @SYSTEM
+ Order allow,deny
+ #Allow localhost
+ Allow 192.168.1.* # change to local LAN settings
+</Location>
+
+# Set the default printer/job policies...
+<Policy default>
+ # Job-related operations must be done by the owner or an adminstrator...
+ <Limit Send-Document Send-URI Hold-Job Release-Job Restart-Job Purge-Jobs \
+Set-Job-Attributes Create-Job-Subscription Renew-Subscription Cancel-Subscription \
+Get-Notifications Reprocess-Job Cancel-Current-Job Suspend-Current-Job Resume-Job \
+CUPS-Move-Job>
+ Require user @OWNER @SYSTEM
+ Order deny,allow
+ </Limit>
+
+ # All administration operations require an adminstrator to authenticate...
+ <Limit Pause-Printer Resume-Printer Set-Printer-Attributes Enable-Printer \
+Disable-Printer Pause-Printer-After-Current-Job Hold-New-Jobs Release-Held-New-Jobs \
+Deactivate-Printer Activate-Printer Restart-Printer Shutdown-Printer Startup-Printer \
+Promote-Job Schedule-Job-After CUPS-Add-Printer CUPS-Delete-Printer CUPS-Add-Class \
+CUPS-Delete-Class CUPS-Accept-Jobs CUPS-Reject-Jobs CUPS-Set-Default>
+ AuthType Basic
+ Require user @SYSTEM
+ Order deny,allow
+ </Limit>
+
+ # Only the owner or an administrator can cancel or authenticate a job...
+ <Limit Cancel-Job CUPS-Authenticate-Job>
+ Require user @OWNER @SYSTEM
+ Order deny,allow
+ </Limit>
+
+ <Limit All>
+ Order deny,allow
+ </Limit>
+</Policy></programlisting>
+</sect2>
+
+<sect2 id="printing-cups-ports-knobs">
+ <title>Fine Tuning CUPS-Related Ports</title>
+<para>If <application>CUPS</application> is going to serve as the primary printing system, then one may choose to optionally add certain "knobs" to <filename>/etc/make.conf</filename> that will emphasize <application>CUPS</application> over other printing options. Some of these "knobs" that one may want to add are:</para>
+
+<programlisting>WITH_CUPS=YES
+CUPS_OVERWRITE_BASE=YES
+WITHOUT_LPR=YES</programlisting>
+
+<para>The first knob, WITH_CUPS, adds <application>CUPS</application> support to ports where applicable. The second knob, CUPS_OVERWRITE_BASE, will fix certain symlinks and paths that would otherwise apply to the default FreeBSD printing system, <application>LPR</application>, and will prevent these fixes from being reverted upon the next "buildworld" system upgrade. The third knob, WITHOUT_LPR, will prevent <application>LPR</application> support from being added to ports where applicable.</para>
+</sect2>
+</sect1>
+
<sect1 id="printing-lpd-alternatives">
<title>Alternatives to the Standard Spooler</title>
<para>If you have been reading straight through this manual, by now you
have learned just about everything there is to know about the
<application>LPD</application>
- spooling system that comes with FreeBSD. You can probably appreciate
- many of its shortcomings, which naturally leads to the question:
+ spooling system that comes with FreeBSD, as well as the Common UNIX Printing System known as <application>CUPS</application>. You can probably appreciate
+ many of their shortcomings, which naturally leads to the question:
<quote>What other spooling systems are out there (and work with
FreeBSD)?</quote></para>
@@ -4545,32 +4745,7 @@
url="http://www.lprng.org/"></ulink>.</para>
</listitem>
</varlistentry>
- <varlistentry>
- <term>CUPS</term>
-
- <indexterm><primary>CUPS</primary></indexterm>
- <listitem>
- <para><application>CUPS</application>, the Common UNIX Printing
- System, provides a portable printing layer for &unix;-based
- operating systems. It has been developed by Easy Software
- Products to promote a standard printing solution for all &unix;
- vendors and users.</para>
-
- <para><application>CUPS</application> uses the Internet Printing
- Protocol (<acronym>IPP</acronym>) as the basis for managing
- print jobs and queues. The Line Printer Daemon
- (<acronym>LPD</acronym>), Server Message Block
- (<acronym>SMB</acronym>), and AppSocket (a.k.a. JetDirect)
- protocols are also supported with reduced functionality. CUPS
- adds network printer browsing and PostScript Printer Description
- (<acronym>PPD</acronym>) based printing options to support
- real-world printing under &unix;.</para>
-
- <para>The main site for <application>CUPS</application> is <ulink
- url="http://www.cups.org/"></ulink>.</para>
- </listitem>
- </varlistentry>
- </variablelist>
+ </variablelist>
</sect1>
<sect1 id="printing-troubleshooting">
>How-To-Repeat:
>Fix:
>Release-Note:
>Audit-Trail:
>Unformatted:
More information about the freebsd-doc
mailing list