source: pst/printing/cups.xml@ f0cd0274

<?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        "f06a997d4b71b81b23324e27174f93e7">
  <!ENTITY cups-size          "8.4 MB">
  <!ENTITY cups-buildsize     "63 MB (additional 16 MB for the tests)">
  <!ENTITY cups-time          "0.6 SBU (additional 4.1 SBU for the 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>

    &lfs75_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;-blfs-1.patch"/>
        </para>
      </listitem>
      <listitem>
        <para>
          Optional patch:
          <ulink url="&patch-root;/cups-&cups-version;-content_type-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"/> (if you have it installed, then
      <xref linkend="libgcrypt"/> is required) 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"/>, and
      <xref linkend="xdg-utils"/>
    </para>

    <bridgehead renderas="sect4">Required (Runtime)</bridgehead>
    <para role="optional"><!-- Yes, optional -->
      <xref linkend="cups-filters"/>
    </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>Device Drivers  ---&gt;
  USB support  ---&gt;
    OHCI HCD (USB 1.1) support: Y or M
    UHCI HCD (most Intel and VIA) support: Y or M
    USB Printer support: Y or M</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: Y or M
  Character devices  ---&gt;
    Parallel printer support: Y or M</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>

    <para>
       If you need to access a remote <application>Cups</application> print
       server, use the following patch:
    </para>

<screen><userinput>patch -Np1 -i ../cups-&cups-version;-content_type-1.patch</userinput></screen>

    <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
    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 -->
<screen><userinput>patch -Np1 -i ../cups-&cups-version;-blfs-1.patch &amp;&amp;
aclocal -I config-scripts &amp;&amp;
autoconf -I config-scripts &amp;&amp;

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

   <para>
     To test the results, issue: <command>make -k check</command>. An already
     active graphical session with bus address is necessary to run the tests.
     A small number of tests fail for unknown reasons.
   </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 -svfn ../cups/doc /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>
      <envar>CC=gcc</envar>: This environment variable ensures that gcc
      is used if clang is installed.  The build fails with the clang compiler.
    </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>

    <para>
      <option>--disable-gnutls --enable-openssl</option>: This switch tells the build
      process to use <xref linkend="openssl"/> instead of <xref linkend="gnutls"/>.
      The 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>

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

    <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, 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-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="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>