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

<html>
<!-- SECTION: Getting Started -->
<head>
	<title>Printer Sharing</title>
</head>
<body>

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