path: root/en_US.ISO8859-1/articles/cups/article.xml

<?xml version="1.0" encoding="iso-8859-1"?>
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook XML V5.0-Based Extension//EN"
	"http://www.FreeBSD.org/XML/share/xml/freebsd50.dtd">
<article xmlns="http://docbook.org/ns/docbook"
  xmlns:xlink="http://www.w3.org/1999/xlink" version="5.0"
  xml:lang="en">
  <info>
    <title>CUPS on FreeBSD</title>

    <authorgroup>
      <author>
	<personname>
	  <firstname>Chess</firstname>
	  <surname>Griffin</surname>
	</personname>
	<affiliation>
	  <address>
	    <email>chess@chessgriffin.com</email>
	  </address>
	</affiliation></author>
    </authorgroup>

    <legalnotice xml:id="trademarks" role="trademarks">
      &tm-attrib.freebsd;
      &tm-attrib.general;
    </legalnotice>

    <pubdate>$FreeBSD$</pubdate>

    <releaseinfo>$FreeBSD$</releaseinfo>

    <abstract>
      <para>An article about configuring CUPS on &os;.</para>
    </abstract>
  </info>

  <sect1 xml:id="printing-cups">
    <title>An Introduction to the Common Unix Printing System
      (CUPS)</title>

    <indexterm><primary>printing</primary></indexterm>
    <indexterm><primary>CUPS</primary></indexterm>

    <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 (aka JetDirect)
      protocols are also supported with reduced functionality.
      <application>CUPS</application> adds network printer browsing
      and PostScript Printer Description (<acronym>PPD</acronym>)
      based printing options to support real-world printing under
      &unix;.  As a result, <application>CUPS</application> is
      ideally-suited for sharing and accessing printers in mixed
      environments of &os;, &linux;, &macos;&nbsp;X, or
      &windows;.</para>

    <para>The main site for <application>CUPS</application> is <uri
	xlink:href="http://www.cups.org/">http://www.cups.org/</uri>.</para>
  </sect1>

  <sect1 xml:id="printing-cups-install">
    <title>Installing the CUPS Print Server</title>

    <para>To install <application>CUPS</application> using a
      precompiled binary, issue the following command from a root
      terminal:</para>

    <screen>&prompt.root; <userinput>pkg install cups</userinput></screen>

    <para>Other optional, but recommended, packages are
      <package>print/gutenprint</package> and
      <package>print/hplip</package>, 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>
  </sect1>

  <sect1 xml:id="printing-cups-configuring-server">
    <title>Configuring the CUPS Print Server</title>

    <para>After installation, a few files must be 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 <systemitem
	class="groupname">cups</systemitem> 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
add path 'usb/<replaceable>X</replaceable>.<replaceable>Y</replaceable>.<replaceable>Z</replaceable>' mode 0660 group cups</programlisting>

    <note>
      <para>Note that <replaceable>X</replaceable>,
	<replaceable>Y</replaceable>, and <replaceable>Z</replaceable>
	should be replaced with the target USB device listed in the
	<filename>/dev/usb</filename> directory that
	corresponds to the printer.  To find the correct device,
	examine the output of &man.dmesg.8;, where
	<filename>ugen<replaceable>X</replaceable>.<replaceable>Y</replaceable></filename>
	lists the printer device, which is a symbolic link to a USB
	device in <filename>/dev/usb</filename>.</para>
    </note>

    <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 below should
      be uncommented in
      <filename>/usr/local/etc/cups/mime.types</filename> and
      <filename>/usr/local/etc/cups/mime.convs</filename>:</para>

    <programlisting>application/octet-stream</programlisting>

    <para>Once these changes have been made, the &man.devfs.8; 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>
  </sect1>

  <sect1 xml: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 <uri
	xlink:href="http://localhost:631">http://localhost:631</uri>
      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>
      address for <systemitem>localhost</systemitem>.  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 <quote>Add
	Printer</quote> at the Administration screen of the
      <application>CUPS</application> web interface, or clicking one
      of the <quote>New Printers Found</quote> buttons also at the
      Administration screen.  When presented with the
      <quote>Device</quote> drop-down box, simply select the desired
      locally-attached printer, and then continue through the process.
      If one has added the <package>print/gutenprint-cups</package> or
      <package>print/hplip</package> 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>
  </sect1>

  <sect1 xml: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>

    <sect2 xml: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 <uri
	  xlink:href="http://localhost:631">http://localhost:631</uri>
	and click on <quote>Add Printer</quote> in the Administration
	section.  When presented with the <quote>Device</quote>
	drop-down box, simply select the networked
	<application>CUPS</application> printer, if it was
	automatically discovered, or select <literal>ipp</literal> or
	<literal>http</literal> and enter the <acronym>IPP</acronym>
	or <acronym>HTTP</acronym> <acronym>URI</acronym> of the
	networked <application>CUPS</application> printer, usually in
	one of the two following syntaxes:</para>

	<programlisting>ipp://<replaceable>server-name-or-ip</replaceable>/printers/<replaceable>printername</replaceable></programlisting>

	<programlisting>http://<replaceable>server-name-or-ip</replaceable>:631/printers/<replaceable>printername</replaceable></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 <replaceable>server-ip</replaceable></programlisting>

      <para>In this case, <replaceable>server-ip</replaceable> would
	be replaced by the local <acronym>IP</acronym> address of the
	<application>CUPS</application> server on the network.</para>
    </sect2>

    <sect2 xml: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
	<acronym>IPP</acronym>-based printers.  However, &windowsxp;
	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; <literal>Add
	  Printer</literal> wizard, select <literal>Network
	  Printer</literal> and then enter the <acronym>URI</acronym>
	in the following syntax:</para>

      <programlisting>http://<replaceable>server-name-or-ip</replaceable>:631/printers/<replaceable>printername</replaceable></programlisting>

      <para>If one has an older version of &windows; without native
	<acronym>IPP</acronym> printing support, then the general
	means of connecting to a <application>CUPS</application>
	printer is to use <package>net/samba410</package> and
	<application>CUPS</application> together, which is a topic
	outside the scope of this chapter.</para>
    </sect2>
  </sect1>

  <sect1 xml:id="printing-cups-troubleshooting">
    <title>CUPS Troubleshooting</title>

    <para>Difficulties with <application>CUPS</application> often lies
      in permissions.  First, double check the &man.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
      <systemitem class="groupname">cups</systemitem> 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> sacrifices security for
      easier configuration; once the administrator successfully
      connects to the <application>CUPS</application> 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
&lt;Location /&gt;
  Order allow,deny
  #Allow localhost
  Allow 192.168.1.* # change to local LAN settings
&lt;/Location&gt;

# Allow access to the admin pages from any machine on the LAN
&lt;Location /admin&gt;
  #Encryption Required
  Order allow,deny
  #Allow localhost
  Allow 192.168.1.* # change to local LAN settings
&lt;/Location&gt;

# Allow access to configuration files from any machine on the LAN
&lt;Location /admin/conf&gt;
  AuthType Basic
  Require user @SYSTEM
  Order allow,deny
  #Allow localhost
  Allow 192.168.1.* # change to local LAN settings
&lt;/Location&gt;

# Set the default printer/job policies...
&lt;Policy default&gt;
  # Job-related operations must be done by the owner or an administrator...
  &lt;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&gt;
    Require user @OWNER @SYSTEM
    Order deny,allow
  &lt;/Limit&gt;

  # All administration operations require an administrator to authenticate...
  &lt;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&gt;
    AuthType Basic
    Require user @SYSTEM
    Order deny,allow
  &lt;/Limit&gt;

  # Only the owner or an administrator can cancel or authenticate a job...
  &lt;Limit Cancel-Job CUPS-Authenticate-Job&gt;
    Require user @OWNER @SYSTEM
    Order deny,allow
  &lt;/Limit&gt;

  &lt;Limit All&gt;
    Order deny,allow
  &lt;/Limit&gt;
&lt;/Policy&gt;</programlisting>
  </sect1>
  <index/>
</article>