os/doc
3
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Add a new article regarding CUPS installation and configuration.

Browse source 
PR:		docs/115220
Submitted by:	Chess Griffin <chess at chessgriffin dot com>
This commit is contained in:
Remko Lodder 2008-05-31 13:30:22 +00:00
parent c78ca1caeb
commit f7057ffa20
Notes: svn2git 2020-12-08 03:00:23 +00:00 
svn path=/head/; revision=32107
2 changed files with 404 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

17
en_US.ISO8859-1/articles/cups/Makefile Normal file
View file

@ -0,0 +1,17 @@
#
# $FreeBSD$
#
# Article: CUPS on FreeBSD
DOC?= article
FORMATS?= html
WITH_ARTICLE_TOC?= YES
INSTALL_COMPRESSED?=gz
INSTALL_ONLY_COMPRESSED?=
SRCS= article.sgml
DOC_PREFIX?= ${.CURDIR}/../../..
.include "${DOC_PREFIX}/share/mk/doc.project.mk"

387
en_US.ISO8859-1/articles/cups/article.sgml Normal file
View file

@ -0,0 +1,387 @@
<!DOCTYPE article PUBLIC "-//FreeBSD//DTD DocBook V4.1-Based Extension//EN" [
<!ENTITY % articles.ent PUBLIC "-//FreeBSD//ENTITIES DocBook FreeBSD Articles Entity Set//EN">
%articles.ent;
<!ENTITY % not.published "IGNORE">
]>
<article>
<articleinfo>
<title>CUPS on FreeBSD</title>
<pubdate>$FreeBSD$</pubdate>
<authorgroup>
<author>
<firstname>Chess</firstname>
<surname>Grifin</surname>
<affiliation>
<address><email>chess@chessgriffin.com</email></address>
</affiliation>
</author>
</authorgroup>
<legalnotice id="trademarks" role="trademarks">
&tm-attrib.freebsd;
&tm-attrib.general;
</legalnotice>
<abstract>
<para>An article about configuring CUPS on &os;.</para>
</abstract>
</articleinfo>
<sect1 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 (a.k.a. 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 <ulink
url="http://www.cups.org/"></ulink>.</para>
<sect2 id="printing-cups-install">
<title>Installing the CUPS Print Server</title>
<para><application>CUPS</application> can be installed from ports
or by using a precompiled binary package. To install
<application>CUPS</application> from ports, issue the following
command from a root terminal:</para>
<screen>&prompt.root; <userinput>cd /usr/ports/print/cups && make install clean</userinput></screen>
<para>To install <application>CUPS</application> using a
precompiled binary, issue the following command from a root
terminal:</para>
<screen>&prompt.root; <userinput>pkg_add -r cups</userinput></screen>
<para>Other optional, but recommended, ports or packages are
<application>print/gutenprint-cups</application> and
<application>print/hplip</application>, 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>
</sect2>
<sect2 id="printing-cups-configuring-server">
<title>Configuring the CUPS Print Server</title>
<para>After installation, a few files must 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 cups 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</programlisting>
<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
<programlisting>application/octet-stream</programlisting> should be
uncommented in <filename>/usr/local/etc/cups/mime.types</filename>
and <filename>/usr/local/etc/cups/mime.convs</filename>.</para>
<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>
</sect2>
<sect2 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 <filename>http://localhost:631</filename> 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> addresss for
<literal>localhost</literal>. 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
<literal>Add Printer</literal> at the Administration screen of
the <application>CUPS</application> web interface, or clicking
one of the <literal>New Printers Found</literal> buttons also
at the Administration screen. When presented with the
<literal>Device</literal> drop-down box, simply select the
desired locally-attached printer, and then continue through the
process. If one has added the
<application>print/gutenprint-cups</application> or
<application>print/hplip</application> 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>
</sect2>
<sect2 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>
<sect3 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 <filename>http://localhost:631</filename> and
click on <literal>Add Printer</literal> in the Administration
section. When presented with the <literal>Device</literal>
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://server-name-or-ip/printers/printername</programlisting>
<programlisting>http://server-name-or-ip:631/printers/printername</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 (server-ip)</programlisting>
<para>In this case, (server-ip) would be replaced by the local
<acronym>IP</acronym> address of the
<application>CUPS</application> server on the network.</para>
</sect3>
<sect3 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://server-name-or-ip:631/printers/printername</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
<filename role="package">net/samba3</filename> and
<application>CUPS</application> together, which is a topic
outside the scope of this chapter.</para>
</sect3>
</sect2>
<sect2 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 filesystem. It is
also helpful to make sure your user is a member of the
<literal>cups</literal> group. If the permissions check boxes
in the <literal>Administration</literal> 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> file sacrifices security for
easier configuration; once the administrator successfully
connnects 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 adminstrator...
&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 adminstrator 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>
</sect2>
<sect2 id="printing-cups-ports-knobs">
<title>Fine Tuning CUPS-Related Ports</title>
<para>If <application>CUPS</application> is going to serve as the
primary printing system, then one may choose to optionally add
certain knobs to <filename>/etc/make.conf</filename> that will
emphasize <application>CUPS</application> over other printing
options. Some of these "knobs" that one may want to add
are:</para>
<programlisting>WITH_CUPS=YES
CUPS_OVERWRITE_BASE=YES
WITHOUT_LPR=YES</programlisting>
<para>The first knob, WITH_CUPS, adds
<application>CUPS</application> support to ports where
applicable. The second knob, CUPS_OVERWRITE_BASE, will fix
certain symlinks and paths that would otherwise apply to the
default &os; printing system, <application>LPR</application>,
and will prevent these fixes from being reverted upon the next
"buildworld" system upgrade. The third knob, WITHOUT_LPR, will
prevent <application>LPR</application> support from being added
to ports where applicable.</para>
</sect2>
</sect1>
</article>
<!--
Local Variables:
mode: sgml
sgml-indent-data: t
sgml-omittag: nil
sgml-always-quote-attributes: t
End:
-->