source: pst/printing/cups.xml@ f594857

<?xml version="1.0" encoding="ISO-8859-1"?>
<!DOCTYPE sect1 PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
   "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
  <!ENTITY % general-entities SYSTEM "../../general.ent">
  %general-entities;

  <!ENTITY cups-download-http "http://www.cups.org/software/&cups-version;/cups-&cups-version;-source.tar.bz2">
  <!ENTITY cups-download-ftp  " ">
  <!ENTITY cups-md5sum        "8d98b85edbdab7ab03739c9622f570e8">
  <!ENTITY cups-size          "8.4 MB">
  <!ENTITY cups-buildsize     "99 MB (with tests)">
  <!ENTITY cups-time          "0.8 SBU (with tests)">
]>

<sect1 id="cups" xreflabel="Cups-&cups-version;">
  <?dbhtml filename="cups.html"?>

  <sect1info>
    <othername>$LastChangedBy$</othername>
    <date>$Date$</date>
  </sect1info>

  <title>Cups-&cups-version;</title>

  <indexterm zone="cups">
    <primary sortas="a-Cups">Cups</primary>
  </indexterm>

  <sect2 role="package">
    <title>Introduction to Cups</title>

    <para>
      The Common Unix Printing System (CUPS) is a print spooler and
      associated utilities. It is based on the "Internet Printing
      Protocol" and provides printing services to most PostScript
      and raster printers.
    </para>

    &lfs77_checked; &gcc5_checked;

    <bridgehead renderas="sect3">Package Information</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Download (HTTP): <ulink url="&cups-download-http;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download (FTP): <ulink url="&cups-download-ftp;"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Download MD5 sum: &cups-md5sum;
        </para>
      </listitem>
      <listitem>
        <para>
          Download size: &cups-size;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated disk space required: &cups-buildsize;
        </para>
      </listitem>
      <listitem>
        <para>
          Estimated build time: &cups-time;
        </para>
      </listitem>
    </itemizedlist>

    <bridgehead renderas="sect3">Cups Dependencies</bridgehead>

    <bridgehead renderas="sect4">Required</bridgehead>
    <para role="required">
      <xref linkend="gnutls"/>
    </para>

    <bridgehead renderas="sect4">Recommended</bridgehead>
    <para role="recommended">
      <xref linkend="colord"/>,
      <xref linkend="dbus"/>, and
      <xref linkend="libusb"/>
    </para>

    <bridgehead renderas="sect4">Optional</bridgehead>
    <para role="optional">
      <xref linkend="avahi"/>,
      <xref linkend="libpaper"/>,
      <xref linkend="linux-pam"/>,
      <xref linkend="mitkrb"/>,
      <xref linkend="openjdk"/>,
      <xref linkend="php"/>,
      <xref linkend="python2"/>, and
      <xref linkend="xdg-utils"/>
     
    </para>

    <bridgehead renderas="sect4">Required (Postinstall)</bridgehead>
    <para role="required runtime">
      <xref linkend="cups-filters"/>
    </para>

    <bridgehead renderas="sect4">Optional (Postinstall)</bridgehead>
    <para role="optional runtime">
      <xref linkend="gutenprint"/> and
      <ulink url="http://hplipopensource.com/hplip-web/index.html">hplip</ulink> (HP printers)
    </para>
      
    <para condition="html" role="usernotes">User Notes:
      <ulink url="&blfs-wiki;/cups"/>
    </para>
  </sect2>

  <sect2 role="kernel" id="cups-kernel">
    <title>Kernel Configuration</title>

    <note>
      <para>
        There used to be a conflict between the <application>Cups</application>
        <application>libusb</application> backend and the usblp kernel driver.
        This is no longer the case and cups will work with both of these
        enabled.
      </para>
    </note>

    <para>
      If you want to use the kernel usblp driver (for example, if you wish to
      use <application>escputil</application> from <xref
      linkend="gutenprint"/>) enable the following options in your kernel
      configuration and recompile the kernel:
    </para>

<screen><literal>Device Drivers  ---&gt;
  [*] USB support  ---&gt;                          [CONFIG_USB_SUPPORT]
    &lt;*/M&gt;  OHCI HCD (USB 1.1) support            [CONFIG_USB_OHCI_HCD]
    &lt;*/M&gt;  UHCI HCD (most Intel and VIA) support [CONFIG_USB_UHCI_HCD]
    &lt;*/M&gt;  USB Printer support                   [CONFIG_USB_PRINTER]</literal></screen>

    <para>
      If you have a parallel printer, enable the following options in your
      kernel configuration and recompile the kernel:
    </para>

<screen><literal>Device Drivers  ---&gt;
  &lt;*/M&gt; Parallel port support  ---&gt;    [CONFIG_PARPORT]
    &lt;*/M&gt; PC-style hardware            [CONFIG_PARPORT_PC]
  Character devices  ---&gt;
    &lt;*/M&gt; Parallel printer support     [CONFIG_PRINTER]</literal></screen>

    <indexterm zone="cups cups-kernel">
      <primary sortas="d-cups">cups</primary>
    </indexterm>

  </sect2>

  <sect2 role="installation">
    <title>Installation of Cups</title>

    <para>
      You will need to add an <systemitem class="username">lp</systemitem>
      user, as <application>Cups</application> will create some files owned
      by this user. (The <systemitem class="username">lp</systemitem> user
      is the default used by <application>Cups</application>, but may be
      changed to a different user by passing a parameter to the
      <command>configure</command> script.) Use the following command as
      the <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>useradd -c "Print Service User" -d /var/spool/cups -g lp -s /bin/false -u 9 lp</userinput></screen>

    <para>
      You will also need a dedicated group that will contain users allowed to
      do <application>Cups</application> administrative tasks. Add the group
      by running the following command as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>groupadd -g 19 lpadmin</userinput></screen>

    <para>
      If you want to add a user to the <application>Cups</application>
      administrative group, run the following command as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>usermod -a -G lpadmin <replaceable>&lt;username&gt;</replaceable></userinput></screen>

    <para>
      If you didn't install <xref linkend="xdg-utils"/>, use the following
      <command>sed</command> to change the default browser that will be used
      to access the <application>Cups</application> web interface:
    </para>

<screen><userinput>sed -i 's#@CUPS_HTMLVIEW@#firefox#' desktop/cups.desktop.in</userinput></screen>

    <para>
      Replace <command>firefox</command> with the web browser of your
      choice.
    </para>

    <!-- docdir is also document root for cups administration interface, so
    let's just put it in /usr/share/cups/doc-&cups-version; and create symlink
    in /usr/share/doc/cups-&cups-version;

    When not using libdir switch, CUPS will install libraries into /usr/lib64
    on a 64 bit system, and since /usr/lib64 is symlink to /usr/lib it might
    introduce some difficulties with packaging -->

    <para>
      Build <application>Cups</application> by running the following commands:
    </para>

<screen><userinput>sed -i 's:555:755:g;s:444:644:g' Makedefs.in                                  &amp;&amp;
sed -i '/MAN.EXT/s:.gz::g' configure config-scripts/cups-manpages.m4          &amp;&amp;
sed -i '/LIBGCRYPTCONFIG/d' config-scripts/cups-ssl.m4                        &amp;&amp;
sed -i 's@else /\* HAVE_AVAHI \*/@elif defined(HAVE_AVAHI)@' test/ippserver.c &amp;&amp;

aclocal  -I config-scripts &amp;&amp;
autoconf -I config-scripts &amp;&amp;

./configure --libdir=/usr/lib            \
            --disable-systemd            \
            --with-rcdir=/tmp/cupsinit   \
            --with-system-groups=lpadmin \
            --with-docdir=/usr/share/cups/doc-&cups-version; &amp;&amp;
make</userinput></screen>

    <para>
      To test the results, issue: <command>make check</command>. An already
      active graphical session with bus address is necessary to run the tests.
    </para>

    <para>
      Now, as the <systemitem class="username">root</systemitem> user:
    </para>

<!-- dev note: make BUILDROOT=<DESTDIR> install -->

<screen role="root"><userinput>make install &amp;&amp;
rm -rf /tmp/cupsinit &amp;&amp;
ln -svnf ../cups/doc-&cups-version; /usr/share/doc/cups-&cups-version;</userinput></screen>

    <para>
      Create a basic <application>Cups</application> client configuration file
      by running the following command as the <systemitem
      class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>echo "ServerName /var/run/cups/cups.sock" > /etc/cups/client.conf</userinput></screen>

    <para>
      Remove filters that are now part of the <application>Cups
      Filters</application> package by running the following commands as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>rm -rf /usr/share/cups/banners &amp;&amp;
rm -rf /usr/share/cups/data/testprint</userinput></screen>

    <note>
      <para>
        If you reinstall or update <application>Cups</application>, commands
        above break <xref linkend="cups-filters"/>, which needs, therefore,
        to be reinstalled.</para>
    </note>

    <xi:include xmlns:xi="http://www.w3.org/2001/XInclude"
      href="../../xincludes/gtk-update-icon-cache.xml"/>

  </sect2>

  <sect2 role="commands">
    <title>Command Explanations</title>

    <para>
      <command>sed ... Makedefs.in</command>: Fix files and directories
      permissions.
    </para>

    <para>
      <command>sed ... cups-manpages.m4</command>: This sed prevents
      compression of the man pages by default.
    </para>

    <para>
      <command>sed ... cups-ssl.m4</command>: Prevent
      <command>configure</command> script from searching
      <command>libgcrypt-config</command>, because
      <application>libgcrypt</application> is not used anywere else in the
      package.
    </para>

    <para>
      <command>sed ... test/ippserver.c</command>: This sed fixes a bug,
      which shows up when <application>avahi</application> is not present.
    </para>

    <para>
      <parameter>--disable-systemd</parameter>: Systemd is not supported by
      BLFS.
    </para>

    <para>
      <parameter>--with-rcdir=/tmp/cupsinit</parameter>: This switch tells the
      build process to install the shipped bootscript into <filename
      class="directory">/tmp</filename> instead of <filename
      class="directory">/etc/rc.d</filename>.
    </para>

    <para>
      <parameter>--with-system-groups=lpadmin</parameter>: This switch ensures
      that only <systemitem class="groupname">lpadmin</systemitem> will be used
      as the <application>Cups</application> administrative group.
    </para>

    <para>
      <option>--disable-libusb</option>: Use this switch if you have installed
      <xref linkend="libusb"/>, but wish to use the kernel usblp driver.
    </para>

    <para>
      <option>--enable-libpaper</option>: Use this switch if you have installed
      <application>libpaper</application> and wish to use it with
      <application>Cups</application>.
    </para>

  </sect2>

  <sect2 role="configuration">
    <title>Configuring Cups</title>

    <sect3 id="cups-config">
      <title>Config Files</title>

      <para><filename>/etc/cups/*</filename></para>

      <indexterm zone="cups cups-config">
        <primary sortas="e-etc-cups">/etc/cups/*</primary>
      </indexterm>

    </sect3>

    <sect3>
      <title>Configuration Information</title>

      <para>
        Normally, printers are set up via a web browser.  The
        <application>Cups</application> server will normally connect via
        the url http://localhost:631.  From there printers, print
        jobs, and the server configuration can be set up and managed.
        Remote system administration can also be set up.  Configuration
        can also be done from the command line via the 
        <command>lpadmin</command>, <command>lpoptions</command>, 
        and <command>lpstat</command> commands.
      </para>

      <para>
        Configuration of <application>Cups</application> is dependent on
        the type of printer and can be complex. Generally, PostScript printers
        are easier. For detailed instructions on configuration and use of
        <application>Cups</application>, see <ulink
        url="http://www.cups.org/documentation.php"/>. 
      </para>

      <para>
        For non-PostScript printers to print with
        <application>Cups</application>, you need to install <xref
        linkend="gs"/> to convert PostScript to raster images and a driver
        (e.g. from <xref linkend="gutenprint"/>) to convert the resulting
        raster images to a form that the printer understands.  <ulink
        url="http://www.linuxprinting.org/foomatic.html">Foomatic</ulink>
        drivers use <xref linkend="gs"/> to convert PostScript to a printable
        form directly, but this is considered suboptimal by
        <application>Cups</application> developers.
      </para>

    </sect3>

    <sect3>
      <title>Linux PAM Configuration</title>

      <para>
        If <application>CUPS</application> has been built with
        <application>Linux PAM</application> support, you need to create a
        <application>PAM</application> configuration file to get it working
        correctly with BLFS.
      </para>

      <para>
        Issue the following command as the <systemitem
        class="username">root</systemitem> user to create the configuration
        file for <application>Linux PAM</application>:
      </para>

<screen role="root"><userinput>cat &gt; /etc/pam.d/cups &lt;&lt; "EOF"
<literal># Begin /etc/pam.d/cups

auth    include system-auth
account include system-account
session include system-session

# End /etc/pam.d/cups</literal>
EOF</userinput></screen>

    </sect3>

    <sect3 id="cups-init">
      <title>Boot Script</title>

      <para>
        If you want the <application>Cups</application> print service to start
        automatically when the system is booted, install the init
        script included in the <xref linkend="bootscripts"/>
        package:
      </para>

      <indexterm zone="cups cups-init">
        <primary sortas="f-cups">cups</primary>
      </indexterm>

<screen role="root"><userinput>make install-cups</userinput></screen>

    </sect3>

  </sect2>

  <sect2 role="content">
    <title>Contents</title>

    <segmentedlist>
      <segtitle>Installed Programs</segtitle>
      <segtitle>Installed Libraries</segtitle>
      <segtitle>Installed Directories</segtitle>

      <seglistitem>
        <seg>
          accept, cancel, cupsaccept, cupsaddsmb, cups-config, cupsctl, cupsd,
          cupsdisable, cupsenable, cupsfilter, cupsreject, cupstestdsc,
          cupstestppd, ippfind, ipptool, lp, lpadmin, lpc, lpinfo, lpmove,
          lpoptions, lpq, lpr, lprm, lpstat, ppdc, ppdhtml, ppdi, ppdmerge,
          ppdpo, and reject
        </seg>
        <seg>
          libcupscgi.so, libcupsimage.so, libcupsmime.so,
          libcupsppdc.so, and libcups.so
        </seg>
        <seg>
          /etc/cups,
          /usr/{include,lib,share}/cups,
          /usr/share/doc/cups-&cups-version;, and
          /var/{cache,log,run,spool}/cups
        </seg>
      </seglistitem>
    </segmentedlist>

    <variablelist>
      <bridgehead renderas="sect3">Short Descriptions</bridgehead>
      <?dbfo list-presentation="list"?>
      <?dbhtml list-presentation="table"?>

      <varlistentry id="accept">
        <term><command>accept</command></term>
        <listitem>
          <para>
            instructs the printing system to accept print jobs to the
            specified destinations.
          </para>
          <indexterm zone="cups accept">
            <primary sortas="b-accept">accept</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="cancel-cups">
        <term><command>cancel</command></term>
        <listitem>
          <para>
            cancels existing print jobs from the print queues.
          </para>
          <indexterm zone="cups cancel-cups">
            <primary sortas="b-cancel">cancel</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="cupsaddsmb">
        <term><command>cupsaddsmb</command></term>
        <listitem>
          <para>
            exports printers to the <application>Samba</application>
            software for use with Windows clients.
          </para>
          <indexterm zone="cups cupsaddsmb">
            <primary sortas="b-cupsaddsmb">cupsaddsmb</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="cups-config-prog">
        <term><command>cups-config</command></term>
        <listitem>
          <para>
            is a <application>Cups</application>
            program configuration utility.
          </para>
          <indexterm zone="cups cups-config-prog">
            <primary sortas="b-cups-config">cups-config</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="cupsctl">
        <term><command>cupsctl</command></term>
        <listitem>
          <para>
            updates or queries the cupsd.conf file for a server.
          </para>
          <indexterm zone="cups cupsctl">
            <primary sortas="b-cupsctl">cupsctl</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="cupsd">
        <term><command>cupsd</command></term>
        <listitem>
          <para>
            is the scheduler for the Common Unix Printing System.
          </para>
          <indexterm zone="cups cupsd">
            <primary sortas="b-cupsd">cupsd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="cupsfilter">
        <term><command>cupsfilter</command></term>
        <listitem>
          <para>
            is a front-end to the <application>Cups</application>
            filter subsystem which allows you to convert a file
            to a specific format.
          </para>
          <indexterm zone="cups cupsfilter">
            <primary sortas="b-cupsfilter">cupsfilter</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="cupstestdsc">
        <term><command>cupstestdsc</command></term>
        <listitem>
          <para>
            tests the conformance of PostScript files.
          </para>
          <indexterm zone="cups cupstestdsc">
            <primary sortas="b-cupstestdsc">cupstestdsc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="cupstestppd">
        <term><command>cupstestppd</command></term>
        <listitem>
          <para>
            tests the conformance of PPD files.
          </para>
          <indexterm zone="cups cupstestppd">
            <primary sortas="b-cupstestppd">cupstestppd</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ippfind">
        <term><command>ippfind</command></term>
        <listitem>
          <para>
            finds internet printing protocol printers.
          </para>
          <indexterm zone="cups ippfind">
            <primary sortas="b-ippfind">ippfind</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ipptool">
        <term><command>ipptool</command></term>
        <listitem>
          <para>
            sends IPP requests to the specified URI and tests
            and/or displays the results.
          </para>
          <indexterm zone="cups ipptool">
            <primary sortas="b-ipptool">ipptool</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lp-cups">
        <term><command>lp</command></term>
        <listitem>
          <para>
            submits files for printing or alters a pending job.
          </para>
          <indexterm zone="cups lp-cups">
            <primary sortas="b-lp">lp</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lpadmin">
        <term><command>lpadmin</command></term>
        <listitem>
          <para>
            configures printer and class queues provided by
            <application>Cups</application>.
          </para>
          <indexterm zone="cups lpadmin">
            <primary sortas="b-lpadmin">lpadmin</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lpc-cups">
        <term><command>lpc</command></term>
        <listitem>
          <para>
            provides limited control over printer and class queues
            provided by <application>Cups</application>.
          </para>
          <indexterm zone="cups lpc-cups">
            <primary sortas="b-lpc">lpc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lpinfo">
        <term><command>lpinfo</command></term>
        <listitem>
          <para>
            lists the available devices or drivers known to the
            <application>Cups</application> server.
          </para>
          <indexterm zone="cups lpinfo">
            <primary sortas="b-lpinfo">lpinfo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lpmove">
        <term><command>lpmove</command></term>
        <listitem>
          <para>
            moves the specified job to a new destination.
          </para>
          <indexterm zone="cups lpmove">
            <primary sortas="b-lpmove">lpmove</primary>
          </indexterm>
      </listitem>
      </varlistentry>

      <varlistentry id="lpoptions">
        <term><command>lpoptions</command></term>
        <listitem>
          <para>
            displays or sets printer options and defaults.
          </para>
          <indexterm zone="cups lpoptions">
            <primary sortas="b-lpoptions">lpoptions</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lpq-cups">
        <term><command>lpq</command></term>
        <listitem>
          <para>
            shows the current print queue status on the named printer.
          </para>
          <indexterm zone="cups lpq-cups">
            <primary sortas="b-lpq">lpq</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lpr-cups">
        <term><command>lpr</command></term>
        <listitem>
          <para>
            submits files for printing.
          </para>
          <indexterm zone="cups lpr-cups">
            <primary sortas="b-lpr">lpr</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lprm-cups">
        <term><command>lprm</command></term>
        <listitem>
          <para>
            cancels print jobs that have been queued for printing.
          </para>
          <indexterm zone="cups lprm-cups">
            <primary sortas="b-lprm">lprm</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="lpstat-cups">
        <term><command>lpstat</command></term>
        <listitem>
          <para>
            displays status information about the current classes, jobs,
            and printers.
          </para>
          <indexterm zone="cups lpstat-cups">
            <primary sortas="b-lpstat">lpstat</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ppdc">
        <term><command>ppdc</command></term>
        <listitem>
          <para>
            compiles PPDC source files into one or more PPD files.
          </para>
          <indexterm zone="cups ppdc">
            <primary sortas="b-ppdc">ppdc</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ppdhtml">
        <term><command>ppdhtml</command></term>
        <listitem>
          <para>
            reads a driver information file and produces a HTML summary
            page that lists all of the drivers in a file and the
            supported options.
          </para>
          <indexterm zone="cups ppdhtml">
            <primary sortas="b-ppdhtml">ppdhtml</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ppdi">
        <term><command>ppdi</command></term>
        <listitem>
          <para>
            imports one or more PPD files into a PPD compiler source file.
          </para>
          <indexterm zone="cups ppdi">
            <primary sortas="b-ppdi">ppdi</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ppdmerge">
        <term><command>ppdmerge</command></term>
        <listitem>
          <para>
            merges two or more PPD files into a single, multi-language
            PPD file.
          </para>
          <indexterm zone="cups ppdmerge">
            <primary sortas="b-ppdmerge">ppdmerge</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="ppdpo">
        <term><command>ppdpo</command></term>
        <listitem>
          <para>
            extracts UI strings from PPDC source files and
            updates either a GNU gettext or Mac OS X strings
            format message catalog source file for translation.
          </para>
          <indexterm zone="cups ppdpo">
            <primary sortas="b-ppdpo">ppdpo</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="reject">
        <term><command>reject</command></term>
        <listitem>
          <para>
            instructs the printing system to reject print jobs to the
            specified destinations.
          </para>
          <indexterm zone="cups reject">
            <primary sortas="b-reject">reject</primary>
          </indexterm>
        </listitem>
      </varlistentry>

      <varlistentry id="libcups">
        <term><filename class="libraryfile">libcups.so</filename></term>
        <listitem>
          <para>
            contains the <application>Cups</application> API functions.
          </para>
          <indexterm zone="cups libcups">
            <primary sortas="c-libcups">libcups.so</primary>
          </indexterm>
        </listitem>
      </varlistentry>

    </variablelist>

  </sect2>

</sect1>