[thirdparty/cups.git] / doc / help / sharing.html

<html>
<!-- SECTION: Getting Started -->
<head>
	<title>Printer Sharing</title>
	<LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
</HEAD>
<BODY>

<H1 CLASS="title">Printer Sharing</H1>

<p>This document discusses several ways to configure printer sharing.</p>

<h2><a name="BASICS">The Basics</h2>

<p>A "server" is any machine that communicates directly to a printer. A "client"
is any machine that sends print jobs to a server for final printing. Clients can
also be servers if they communicate directly with any printers of their own.</p>

<p>By default, CUPS uses the Internet Printing Protocol (IPP) to send jobs from
a client to a server. When printing to legacy print servers you may also use the
Line Printer Daemon (LPD) when printing to older UNIX-based servers or Server
Message Block (SMB) when printing to Windows<sup>&reg;</sup> servers.</p>

<p>Clients can automatically discover and access shared printers via CUPS
browsing, IPP, Service Location Protocol (SLP), and Lightweight Directory Access
Protocol (LDAP). DNS Service Discovery (DNS-SD a.k.a. Bonjour<sup>&reg;</sup>)
and SMB browsing can also be used to manually discover and access shared
printers.</p>


<h2><a name="SERVER_CONFIG">Configuring the Server</a></h2>

<p>You must enable printer sharing on the server before clients can print
through it. The simplest way to do this is to use the
<a href="man-cupsctl.html">cupsctl(8)</a> command on the server:</p>

<pre class="command">
cupsctl --share-printers
</pre>

<p>By default, the above command will allow printing from other clients on the
same subnet as your server. To allow printing from any subnet, use the following
command instead:</p>

<pre class="command">
cupsctl --share-printers --remote-any
</pre>

<p>Next, you need to choose which protocols to use for printer sharing. The
default is CUPS browsing and DNS-SD on Mac OS X and CUPS browsing alone on
other platforms. To set the sharing protocols, run the <b>cupsctl</b> command
to set the
<a href="ref-cupsd-conf.html#BrowseLocalProtocols">BrowseLocalProtocols</a>
value. For example, run the following command to allow shared printing via
CUPS, DNS-SD, LPD, and SMB:</p>

<pre class="command">
cupsctl 'BrowseLocalProtocols="cups dnssd lpd smb"'
</pre>


<h2><a name="AUTO_CUPS">Automatic Configuration using CUPS Browsing</a></h2>

<p>CUPS browsing works by periodically broadcasting information about printers
that are being shared to client systems on the same subnet. Each client
maintains its own list of shared printers, and when more than one server shares
the same printer (or the same kind of printer) the client uses all of the
servers and printers to provide high-availability and failsafe printing.</p>

<p>To configure printers on the same subnet, <em>do nothing</em>. Each client
should see the available printers within 30 seconds automatically. The printer
and class lists are updated automatically as printers and servers are added or
removed.</p>

<blockquote><b>Note:</b>

<p>Due to user interface changes in Mac OS X 10.5, CUPS shared printers will not
automatically appear in the print dialog. Instead, you must first run the
following command to enable CUPS browsing on your system:</p>

<pre class="command">
cupsctl BrowseRemoteProtocols=cups
</pre>

<p>Then choose each of the CUPS shared printers you want to see in the print
dialog by adding them, either from the <var>Add Printer...</var> item in the
print dialog or from the <var>Print &amp; Fax</var> preference pane in the
<var>System Preferences</var> window.</p>

</blockquote>

<h3><a name="BROWSE_POLL">Seeing Printers on Other Subnets</a></h3>

<p>You can automatically access printers on other subnets by adding
<a href="ref-cupsd-conf.html#BrowsePoll"><code>BrowsePoll</code></a> lines
to the <var>cupsd.conf</var> file on your local system. For a single
server you can use the <b>cupsctl</b> command:</p>

<pre class="command">
cupsctl BrowsePoll=server:port
</pre>

<p>For multiple servers, use the CUPS web interface (http://localhost:631/admin)
to edit the configuration file instead. Enter one <code>BrowsePoll</code> line
per server at the bottom of the file, as follows:</p>

<pre class="example">
BrowsePoll server1:port
BrowsePoll server2:port
BrowsePoll server3:port
</pre>

<p>If you have more than one client on your subnet that wants to see the
printers on those servers, add a
<a href="ref-cupsd-conf.html#BrowseRelay"><code>BrowseRely</code></a> line
to the <var>cupsd.conf</var> file on your local system using the <b>cupsctl</b>
command:</p>

<pre class="command">
cupsctl 'BrowseRelay="127.0.0.1 @LOCAL"'
</pre>

<p>or CUPS web interface (again, at the bottom of the file):</p>

<pre class="example">
BrowseRelay 127.0.0.1 @LOCAL
</pre>


<h2><a name="AUTO_IPP">Automatic Configuration using IPP</a></h2>

<p>CUPS can be configured to run without a local spooler and send all jobs to a
single server. However, if that server goes down then all printing will be
disabled. Use this configuration only as absolutely necessary.</p>

<p>The default server is normally the local system ("localhost"). To override
the default server create a file named <var>/etc/cups/client.conf</var> with a
line as follows:</p>

<pre class='example'>
ServerName <em>server</em>
</pre>

<p>The <var>server</var> name can be the hostname or IP address of the default
server. If the server is not using the default IPP port (631), you can add the
port number at the end like this:</p>

<pre class='example'>
ServerName <em>server:port</em>
</pre>

<p>The default server can also be customized on a per-user basis. To set a
user-specific server create a file named <var>~/.cups/client.conf</var> instead.
The user <var>client.conf</var> file takes precedence over the system one.</p>

<p>Finally, you can set the <code>CUPS_SERVER</code> environment variable to
override the default server for a single process, for example:</p>

<pre class='command'>
CUPS_SERVER=server:port firefox http://www.cups.org
</pre>

<p>will run the Firefox web browser pointed to the specified server and
port. The environment variable overrides both the user and system
<var>client.conf</var> files, if any.</p>


<h2><a name="MANUAL">Manual Configuration of Print Queues</a></h2>

<p>The most tedious method of configuring client machines is to configure
each remote queue by hand using the <a href="man-lpadmin.html">lpadmin(8)</a>
command:</p>

<pre class='command'>
lpadmin -p <em>printer</em> -E -v ipp://<em>server</em>/printers/<em>printer</em>
</pre>

<p>The <var>printer</var> name is the name of the printer on the server machine.
The <var>server</var> name is the hostname or IP address of the server machine.
Repeat the <b>lpadmin</b> command for each remote printer you wish to use.</p>


</body>
</html>
Commit	Line	Data
d2354e63 MS	1	<html>
	2	<!-- SECTION: Getting Started -->
	3	<head>
	4	<title>Printer Sharing</title>
178cb736 MS	5	<LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
	6	</HEAD>
	7	<BODY>
	8
	9	<H1 CLASS="title">Printer Sharing</H1>
d2354e63 MS	10
	11	<p>This document discusses several ways to configure printer sharing.</p>
	12
	13	<h2><a name="BASICS">The Basics</h2>
	14
	15	<p>A "server" is any machine that communicates directly to a printer. A "client"
	16	is any machine that sends print jobs to a server for final printing. Clients can
	17	also be servers if they communicate directly with any printers of their own.</p>
	18
	19	<p>By default, CUPS uses the Internet Printing Protocol (IPP) to send jobs from
	20	a client to a server. When printing to legacy print servers you may also use the
	21	Line Printer Daemon (LPD) when printing to older UNIX-based servers or Server
	22	Message Block (SMB) when printing to Windows<sup>®</sup> servers.</p>
	23
	24	<p>Clients can automatically discover and access shared printers via CUPS
	25	browsing, IPP, Service Location Protocol (SLP), and Lightweight Directory Access
	26	Protocol (LDAP). DNS Service Discovery (DNS-SD a.k.a. Bonjour<sup>®</sup>)
	27	and SMB browsing can also be used to manually discover and access shared
	28	printers.</p>
	29
	30
	31	<h2><a name="SERVER_CONFIG">Configuring the Server</a></h2>
	32
	33	<p>You must enable printer sharing on the server before clients can print
	34	through it. The simplest way to do this is to use the
	35	<a href="man-cupsctl.html">cupsctl(8)</a> command on the server:</p>
	36
	37	<pre class="command">
	38	cupsctl --share-printers
	39	</pre>
	40
	41	<p>By default, the above command will allow printing from other clients on the
	42	same subnet as your server. To allow printing from any subnet, use the following
	43	command instead:</p>
	44
	45	<pre class="command">
	46	cupsctl --share-printers --remote-any
	47	</pre>
	48
	49	<p>Next, you need to choose which protocols to use for printer sharing. The
	50	default is CUPS browsing and DNS-SD on Mac OS X and CUPS browsing alone on
	51	other platforms. To set the sharing protocols, run the <b>cupsctl</b> command
	52	to set the
	53	<a href="ref-cupsd-conf.html#BrowseLocalProtocols">BrowseLocalProtocols</a>
	54	value. For example, run the following command to allow shared printing via
	55	CUPS, DNS-SD, LPD, and SMB:</p>
	56
	57	<pre class="command">
	58	cupsctl 'BrowseLocalProtocols="cups dnssd lpd smb"'
	59	</pre>
	60
	61
	62	<h2><a name="AUTO_CUPS">Automatic Configuration using CUPS Browsing</a></h2>
	63
	64	<p>CUPS browsing works by periodically broadcasting information about printers
	65	that are being shared to client systems on the same subnet. Each client
	66	maintains its own list of shared printers, and when more than one server shares
	67	the same printer (or the same kind of printer) the client uses all of the
	68	servers and printers to provide high-availability and failsafe printing.</p>
	69
	70	<p>To configure printers on the same subnet, <em>do nothing</em>. Each client
	71	should see the available printers within 30 seconds automatically. The printer
	72	and class lists are updated automatically as printers and servers are added or
	73	removed.</p>
74
75	<blockquote><b>Note:</b>
76
77	<p>Due to user interface changes in Mac OS X 10.5, CUPS shared printers will not
78	automatically appear in the print dialog. Instead, you must first run the
79	following command to enable CUPS browsing on your system:</p>
80
81	<pre class="command">
82	cupsctl BrowseRemoteProtocols=cups
83	</pre>
84
85	<p>Then choose each of the CUPS shared printers you want to see in the print
86	dialog by adding them, either from the <var>Add Printer...</var> item in the
87	print dialog or from the <var>Print & Fax</var> preference pane in the
88	<var>System Preferences</var> window.</p>
89
90	</blockquote>
91
92	<h3><a name="BROWSE_POLL">Seeing Printers on Other Subnets</a></h3>
93
94	<p>You can automatically access printers on other subnets by adding
95	<a href="ref-cupsd-conf.html#BrowsePoll"><code>BrowsePoll</code></a> lines
96	to the <var>cupsd.conf</var> file on your local system. For a single
97	server you can use the <b>cupsctl</b> command:</p>
98
99	<pre class="command">
100	cupsctl BrowsePoll=server:port
101	</pre>
102
103	<p>For multiple servers, use the CUPS web interface (http://localhost:631/admin)
104	to edit the configuration file instead. Enter one <code>BrowsePoll</code> line
105	per server at the bottom of the file, as follows:</p>
106
107	<pre class="example">
108	BrowsePoll server1:port
109	BrowsePoll server2:port
110	BrowsePoll server3:port
111	</pre>
112
113	<p>If you have more than one client on your subnet that wants to see the
114	printers on those servers, add a
115	<a href="ref-cupsd-conf.html#BrowseRelay"><code>BrowseRely</code></a> line
116	to the <var>cupsd.conf</var> file on your local system using the <b>cupsctl</b>
117	command:</p>
118
119	<pre class="command">
120	cupsctl 'BrowseRelay="127.0.0.1 @LOCAL"'
121	</pre>
122
123	<p>or CUPS web interface (again, at the bottom of the file):</p>
124
125	<pre class="example">
126	BrowseRelay 127.0.0.1 @LOCAL
127	</pre>
128
129
130	<h2><a name="AUTO_IPP">Automatic Configuration using IPP</a></h2>
131
132	<p>CUPS can be configured to run without a local spooler and send all jobs to a
133	single server. However, if that server goes down then all printing will be
134	disabled. Use this configuration only as absolutely necessary.</p>
135
136	<p>The default server is normally the local system ("localhost"). To override
137	the default server create a file named <var>/etc/cups/client.conf</var> with a
138	line as follows:</p>
139
140	<pre class='example'>
141	ServerName <em>server</em>
142	</pre>
143
144	<p>The <var>server</var> name can be the hostname or IP address of the default
145	server. If the server is not using the default IPP port (631), you can add the
146	port number at the end like this:</p>
147
148	<pre class='example'>
149	ServerName <em>server:port</em>
150	</pre>
151
152	<p>The default server can also be customized on a per-user basis. To set a
153	user-specific server create a file named <var>~/.cups/client.conf</var> instead.
154	The user <var>client.conf</var> file takes precedence over the system one.</p>
155
156	<p>Finally, you can set the <code>CUPS_SERVER</code> environment variable to
157	override the default server for a single process, for example:</p>
158
159	<pre class='command'>
160	CUPS_SERVER=server:port firefox http://www.cups.org
161	</pre>
162
163	<p>will run the Firefox web browser pointed to the specified server and
164	port. The environment variable overrides both the user and system
165	<var>client.conf</var> files, if any.</p>
166
167
168	<h2><a name="MANUAL">Manual Configuration of Print Queues</a></h2>
169
170	<p>The most tedious method of configuring client machines is to configure
171	each remote queue by hand using the <a href="man-lpadmin.html">lpadmin(8)</a>
172	command:</p>
173
174	<pre class='command'>
175	lpadmin -p <em>printer</em> -E -v ipp://<em>server</em>/printers/<em>printer</em>
176	</pre>
177
178	<p>The <var>printer</var> name is the name of the printer on the server machine.
179	The <var>server</var> name is the hostname or IP address of the server machine.
180	Repeat the <b>lpadmin</b> command for each remote printer you wish to use.</p>
181
182
183	</body>
184	</html>