source: pst/printing/cups.xml@ 852554e1

<?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://ftp.easysw.com/pub/cups/&cups-version;/cups-&cups-version;-source.tar.bz2">
  <!ENTITY cups-download-ftp  "ftp://ftp.easysw.com/pub/cups/&cups-version;/cups-&cups-version;-source.tar.bz2">
  <!ENTITY cups-md5sum        "87ade07e3d1efd03c9c3add949cf9c00">
  <!ENTITY cups-size          "7.9 MB">
  <!ENTITY cups-buildsize     "90 MB">
  <!ENTITY cups-time          "1.2 SBU">
]>

<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>

    &lfs71_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">Additional Downloads</bridgehead>
    <itemizedlist spacing="compact">
      <listitem>
        <para>
          Required patch:
          <ulink url="&patch-root;/cups-&cups-version;-upstream-fixes-1.patch"/>
        </para>
      </listitem>
    </itemizedlist>

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

    <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="acl"/>,
      <xref linkend="avahi"/>,
      <xref linkend="gnutls"/> or <xref linkend="openssl"/>,
      <ulink
      url="http://packages.debian.org/source/sid/libpaper">libpaper</ulink>,
      <xref linkend="linux-pam"/>,
      <xref linkend="mitkrb"/>,
      <xref linkend="openjdk"/>,
      <xref linkend="php"/>,
      <xref linkend="python2"/>,
      <!-- <ulink url="http://valgrind.org/">Valgrind</ulink>
      (optionaly used during the test suites) -->and
      <xref linkend="xdg-utils"/>
    </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 is a conflict between the <application>Cups</application>
        <application>libusb</application> backend and the usblp kernel
        driver. If you want to use <application>Cups</application> with
        <application>libusb</application> <emphasis>do not</emphasis>
        enable USB Printer support in your kernel.
      </para>
    </note>

    <para>
      If you want to use the kernel usblp driver enable the following
      options in your kernel configuration and recompile the kernel:
    </para>

<screen>Device Drivers  ---&gt;
  [*] USB support  ---&gt;
...
Enable support for either UHCI or OHCI, not both:
    [*]   OHCI HCD support
    [*]   UHCI HCD (most Intel and VIA) support
...
    [*]   USB Printer support</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;
  [*] Parallel port support  ---&gt;
    [*]   PC-style hardware
...
  Character devices  ---&gt;
    [*] Parallel printer support</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 the <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 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 an 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>

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

    <!-- docdir is also document root for cups administration interface, so
    let's just put it in /usr/share/cups/doc and create symlink in 
    /usr/share/doc -->
<screen><userinput>sed -e "s|MAN1EXT=1.gz|MAN1EXT=1|g" \
    -e "s|MAN5EXT=5.gz|MAN5EXT=5|g" \
    -e "s|MAN7EXT=7.gz|MAN7EXT=7|g" \
    -e "s|MAN8EXT=8.gz|MAN8EXT=8|g" \
    -i configure &amp;&amp;
patch -Np1 -i ../cups-&cups-version;-upstream-fixes-1.patch &amp;&amp;
./configure --with-rcdir=/tmp/cupsinit \
            --with-docdir=/usr/share/cups/doc \
            --with-system-groups=lpadmin &amp;&amp;
make</userinput></screen>

   <para>
     This package does not have working testsuite.
   </para>

<!-- Testsuite is broken. It fails at colord tests, and before that I get
     lot of "document format not supported".

    <para>
      To test the results, issue: <command>make check</command>. This will
      run a basic test suite without any load testing. If you wish to run
      the tests specifying non-default parameters, issue:
      <command>make test</command>. Note that the <quote>torture load
      testing</quote> test uses more resources than those displayed in the
      prompt.
    </para>
-->

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

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

<!-- Not all raw usb printer device nodes have root:lp owner. -->
    <para>
      If you have built <application>Cups</application> with
      <application>libusb</application> support, fix the
      backend permissions so that it will be executed as the
      <systemitem class="username">root</systemitem> user.
      Run the following command as the
      <systemitem class="username">root</systemitem> user:
    </para>

<screen role="root"><userinput>chmod -v 744 /usr/lib/cups/backend/usb</userinput></screen>

  </sect2>

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

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

<!-- There isn't any class="group" so I had to use class="username" here -->
    <para>
      <parameter>--with-system-groups=lpadmin</parameter>: This switch ensures
      that only <systemitem class="username">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>

    <para>
      <option>--disable-gnutls --enable-openssl</option>: This switch tells build
      process to use <xref linkend="openssl"/> instead of <xref linkend="gnutls"/>.
      Current version of <application>GnuTLS</application> might produce lot of
      warnings during the <application>Cups</application> build.
    </para>

  </sect2>

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

    <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"/>. The Software
      Administrators Manual and Software Users Manual are particularly useful.
    </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 Ghostscript to convert PostScript to a printable form directly,
      but this is considered to be a hack by <application>Cups</application>
      developers.
    </para>

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

      <para>
        The default <application>Cups</application>
        <application>PAM</application> configuration file should
        work by default. However, it does not make use of the
        BLFS specific <application>PAM</application>
        configuration files.
      </para>

      <para>
        If you have built <application>Cups</application> with
        <application>PAM</application> support, create
        BLFS specific <application>PAM</application>
        configuration file by running the following command as
        the <systemitem class="username">root</systemitem> user:
      </para>

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

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

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

    </sect3>

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

      <para>
        If you want the <application>Cups</application> 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, ipptool, lp,
          lpadmin, lpc, lpinfo, lpmove, lpoptions, lppasswd,
          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/cups,
          /usr/lib/cups,
          /usr/share/cups,
          /usr/share/doc/cups-&cups-version;,
          /var/cache/cups,
          /var/log/cups,
          /var/run/cups and
          /var/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">
        <term><command>cups-config</command></term>
        <listitem>
          <para>
            is a <application>Cups</application>
            program configuration utility.
          </para>
          <indexterm zone="cups cups-config">
            <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="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="lppasswd">
        <term><command>lppasswd</command></term>
        <listitem>
          <para>
            adds, changes or deletes passwords in the
            <application>Cups</application> digest password file
            <filename>passwd.md5</filename>.
          </para>
          <indexterm zone="cups lppasswd">
            <primary sortas="b-lppasswd">lppasswd</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>