                            CUPS on FreeBSD

  Chess Griffin

   <chess@chessgriffin.com>

   $FreeBSD: doc/en_US.ISO8859-1/articles/cups/article.sgml,v 1.7
   2012/03/17 03:12:26 eadler Exp $

   FreeBSD is a registered trademark of the FreeBSD Foundation.

   Many of the designations used by manufacturers and sellers to
   distinguish their products are claimed as trademarks. Where those
   designations appear in this document, and the FreeBSD Project was
   aware of the trademark claim, the designations have been followed
   by the "(TM)" or the "(R)" symbol.

   An article about configuring CUPS on FreeBSD.

     --------------------------------------------------------------

1 An Introduction to the Common Unix Printing System (CUPS)

   CUPS, the Common UNIX Printing System, provides a portable
   printing layer for UNIX(R)-based operating systems. It has been
   developed by Easy Software Products to promote a standard printing
   solution for all UNIX vendors and users.

   CUPS uses the Internet Printing Protocol (IPP) as the basis for
   managing print jobs and queues. The Line Printer Daemon (LPD),
   Server Message Block (SMB), and AppSocket (aka JetDirect)
   protocols are also supported with reduced functionality. CUPS adds
   network printer browsing and PostScript Printer Description (PPD)
   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(R), Mac OS(R) X,
   or Windows(R).

   The main site for CUPS is http://www.cups.org/.

     --------------------------------------------------------------

2 Installing the CUPS Print Server

   CUPS can be installed from ports or by using a precompiled binary
   package. To install CUPS from ports, issue the following command
   from a root terminal:

 # cd /usr/ports/print/cups && make install clean

   To install CUPS using a precompiled binary, issue the following
   command from a root terminal:

 # pkg_add -r cups

   Other optional, but recommended, ports or packages are
   print/gutenprint-cups and print/hplip, both of which add drivers
   and utilities for a variety of printers. Once installed, the CUPS
   configuration files can be found in the directory
   /usr/local/etc/cups.

     --------------------------------------------------------------

3 Configuring the CUPS Print Server

   After installation, a few files must edited in order to configure
   the CUPS server. First, create or modify, as the case may be, the
   file /etc/devfs.rules and add the following information to set the
   proper permissions on all potential printer devices and to
   associate printers with the cups user group:

 [system=10]
 add path 'unlpt*' mode 0660 group cups
 add path 'ulpt*' mode 0660 group cups
 add path 'lpt*' mode 0660 group cups
 add path 'usb/X.Y.Z' mode 0660 group cups

     Note: Note that X, Y, and Z should be replaced with the target
     USB device listed in the /dev/usb directory that corresponds to
     the printer. To find the correct device, examine the output of
     dmesg(8), where ugenX.Y lists the printer device, which is a
     symbolic link to a USB device in /dev/usb.

   Next, add two lines to /etc/rc.conf as follows:

 cupsd_enable="YES"
 devfs_system_ruleset="system"

   These two entries will start the CUPS print server on boot and
   invoke the local devfs rule created above, respectively.

   In order to enable CUPS printing under certain
   Microsoft(R) Windows clients, the line below should be uncommented
   in /usr/local/etc/cups/mime.types and
   /usr/local/etc/cups/mime.convs:

 application/octet-stream

   Once these changes have been made, the devfs(8) and CUPS systems
   must both be restarted, either by rebooting the computer or
   issuing the following two commands in a root terminal:

 # /etc/rc.d/devfs restart
 # /usr/local/etc/rc.d/cupsd restart

     --------------------------------------------------------------

4 Configuring Printers on the CUPS Print Server

   After the CUPS system has been installed and configured, the
   administrator can begin configuring the local printers attached to
   the CUPS print server. This part of the process is very similar,
   if not identical, to configuring CUPS printers on other UNIX-based
   operating systems, such as a Linux distribution.

   The primary means for managing and administering the CUPS server
   is through the web-based interface, which can be found by
   launching a web browser and entering http://localhost:631 in the
   browser's URL bar. If the CUPS server is on another machine on the
   network, substitute the server's local IP address for localhost.
   The CUPS 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 CUPS server, and whether to allow users
   additional access and privileges to the printers and print jobs.

   Adding a printer is generally as easy as clicking "Add Printer" at
   the Administration screen of the CUPS 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 print/gutenprint-cups or
   print/hplip ports or packages as referenced above, then additional
   print drivers will be available in the subsequent screens that
   might provide more stability or features.

     --------------------------------------------------------------

5 Configuring CUPS Clients

   Once the CUPS 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 CUPS
   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.

     --------------------------------------------------------------

  5.1 UNIX(R) Clients

   CUPS will also need to be installed on your UNIX clients. Once
   CUPS is installed on the clients, then CUPS printers that are
   shared across the network are often automatically discovered by
   the printer managers for various desktop environments such as
   GNOME or KDE. Alternatively, one can access the local CUPS
   interface on the client machine at http://localhost:631 and click
   on "Add Printer" in the Administration section. When presented
   with the "Device" drop-down box, simply select the networked CUPS
   printer, if it was automatically discovered, or select ipp or http
   and enter the IPP or HTTP URI of the networked CUPS printer,
   usually in one of the two following syntaxes:

 ipp://server-name-or-ip/printers/printername

 http://server-name-or-ip:631/printers/printername

   If the CUPS clients have difficulty finding other CUPS printers
   shared across the network, sometimes it is helpful to add or
   create a file /usr/local/etc/cups/client.conf with a single entry
   as follows:

 ServerName server-ip

   In this case, server-ip would be replaced by the local IP address
   of the CUPS server on the network.

     --------------------------------------------------------------

  5.2 Windows(R) Clients

   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 CUPS
   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 URI in the following
   syntax:

 http://server-name-or-ip:631/printers/printername

   If one has an older version of Windows without native IPP printing
   support, then the general means of connecting to a CUPS printer is
   to use net/samba3 and CUPS together, which is a topic outside the
   scope of this chapter.

     --------------------------------------------------------------

6 CUPS Troubleshooting

   Difficulties with CUPS often lies in permissions. First, double
   check the devfs(8) permissions as outlined above. Next, check the
   actual permissions of the devices created in the file system. 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 CUPS web interface do not seem to be working,
   another fix might be to manually backup the main CUPS
   configuration file located at /usr/local/etc/cups/cupsd.conf and
   edit the various configuration options and try different
   combinations of configuration options. One sample
   /usr/local/etc/cups/cupsd.conf to test is listed below. Please
   note that this sample cupsd.conf file sacrifices security for
   easier configuration; once the administrator successfully connects
   to the CUPS server and configures the clients, it is advisable to
   revisit this configuration file and begin locking down access.

 # 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 administrator...
   <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 administrator 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>

     --------------------------------------------------------------

7 Fine Tuning CUPS-Related Ports

   If CUPS is going to serve as the primary printing system, then one
   may choose to optionally add certain knobs to /etc/make.conf that
   will emphasize CUPS over other printing options. Some of these
   "knobs" that one may want to add are:

 WITH_CUPS=YES
 CUPS_OVERWRITE_BASE=YES
 WITHOUT_LPR=YES

   The first knob, WITH_CUPS, adds CUPS 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, LPR, and will prevent these fixes from
   being reverted upon the next buildworld system upgrade. The third
   knob, WITHOUT_LPR, will prevent LPR support from being added to
   ports where applicable.

     --------------------------------------------------------------
