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

<!DOCTYPE html>
<html>
<!-- SECTION: Getting Started -->
  <head>
    <title>Using Network Printers</title>
    <link rel="stylesheet" type="text/css" href="../cups-printable.css">
  </head>
  <body>
    <h1 class="title">Using Network Printers</h1>

    <p>This help document describes how to discover, configure, and use TCP/IP network printers with CUPS.</p>

    <h2 class="title" id="AUTOMATIC">Automatic Configuration Using Bonjour</h2>

    <p>Most network printers support a protocol known as Bonjour, which is a combination of zero-configuration networking ("ZeroConf"), multicast DNS (mDNS), and DNS service discovery (DNS-SD) standards published by the Internet Engineering Task Force (IETF), the same group that defined TCP/IP and all of the networking we use today.</p>

    <p>A printer that supports Bonjour can be found automatically using the <code>dnssd</code> backend. Run the <code>lpinfo(8)</code> command to find your printer's URI:</p>

    <pre class="command">lpinfo --include-schemes dnssd -v
network dnssd://Acme%20Laser%20Pro._ipp._tcp.local./?uuid=545253fb-1cb7-4d8d-98ed-ab6cd607cea7
network dnssd://Bar99._printer.tcp.local./?uuid=f9efff58-9086-4c95-accb-81dee876a475
network dnssd://Example%20EX-42._ipps._tcp.local./?uuid=4a0c67ad-2824-4ddf-9115-7d4226c5fe65
network dnssd://Foo%20Fighter-1969._pdl-datastream._tcp.local./?uuid=4e216bea-c3de-4f65-a710-c99e11c80d2b</pre>

    <p>You can then <a href="admin.html#PRINTERS">add a printer</a> using the URI reported.</p>


    <h2 class="title" id="MANUAL">Manual Configuration Using IP Addresses</h2>

    <p>You can also manually configure a printer using its Internet Protocol v4 (IPv4) address. This address is either configured manually ("static IP") through the printer's control panel or set using an automatic network protocol such as the Dynamic Host Control Protocol (DHCP) or ZeroConf.</p>

    <blockquote><b>Note:</b> Configuring a printer using an IP address set using DHCP or ZeroConf is not recommended since the address will change every time the printer is turned on or after long periods of inactivity. Thus, every time the address changes you will need to modify the print queue using the <code>lpadmin</code> command.</blockquote>

    <h3>Finding the IP Address</h3>

    <p>You can normally find the IP address of a printer on the printer's control panel or by printing the configuration or status page. The <a href="#SNMP">Simple Network Management Protocol (SNMP)</a> can also be used to get the IP address remotely. To test that the IP address has been successfully assigned and that the printer is properly connected to your LAN or Wi-Fi network, type:</p>

    <pre class="command">ping ip-address</pre>

    <p>where "ip-address" is the address reported by the printer's control panel, configuration page, and/or status page. If the connection is working properly you will see something like:</p>

    <pre class="command">ping 10.0.1.42
PING 10.0.1.42 (10.0.1.42): 56 data bytes
64 bytes from 10.0.1.42: icmp_seq=0 ttl=15 time=1.123 ms
64 bytes from 10.0.1.42: icmp_seq=1 ttl=15 time=2.034 ms
64 bytes from 10.0.1.42: icmp_seq=2 ttl=15 time=1.765 ms
64 bytes from 10.0.1.42: icmp_seq=3 ttl=15 time=1.234 ms
...</pre>

    <p>If the connection is not working properly you will see something like:</p>

    <pre class="command">ping 10.0.1.42
PING 10.0.1.42 (10.0.1.42): 56 data bytes
Request timeout for icmp_seq 0
Request timeout for icmp_seq 1
...</pre>

    <p>Press <kbd>CTRL+C</kbd> to quit the <code>ping</code> command.</p>

    <blockquote><b>Note:</b> If the command does not show responses from the printer, verify that the printer or print server is powered on and connected to the same LAN or Wi-Fi network as your computer. For LAN connections, also verify that your network cabling is good.</blockquote>


    <h3>Choosing a Network Protocol (Backend)</h3>

    <p>CUPS supports most network printers using one of three TCP/IP-based protocols: <a href="#SOCKET">AppSocket</a>, <a href="#IPP">Internet Printing Protocol</a>, and <a href="#LPD">Line Printer Daemon</a>. The following sections describe the options for each of the backends.</p>


    <h4 id="SOCKET">AppSocket Protocol (aka JetDirect)</h4>

    <p>The AppSocket protocol (sometimes also called the JetDirect protocol, owing to its origins with the HP JetDirect network interfaces) is the simplest and fastest network protocol used for printers. AppSocket printing normally happens over port 9100 and uses the <code>socket</code> backend. Device URIs for the <code>socket</code> backend look like this:</p>

    <pre class="example">socket://ip-address
socket://ip-address/?contimeout=30
socket://ip-address/?waiteof=false
socket://ip-address/?contimeout=30&amp;waiteof=false
socket://ip-address:port-number/?...</pre>

    <p>The "contimeout" option controls the number of seconds that the backend will wait to obtain a connection to the printer. The default is 1 week or 604800 seconds.</p>

    <p>The "waiteof" option controls whether the <code>socket</code> backend waits for the printer to complete the printing of the job. The default is to wait (<code>waiteof=true</code>). Add <code>waiteof=false</code> to the URI to tell the backend not to wait.</p>

    <blockquote><b>Note:</b> While the AppSocket protocol is simple and fast, it also offers no security and is often an attack vector with printers. Consider using the <a href="#IPP">Internet Printing Protocol</a> which supports encryption and other security features.</blockquote>


    <h4 id="IPP">Internet Printing Protocol (IPP)</h4>

    <p>IPP is the only protocol that CUPS supports natively and is supported by most network printers and print servers. IPP supports encryption and other security features over port 631 and uses the <code>http</code> (Windows), <code>ipp</code>, and <code>ipps</code> backends. Device URIs for these backends look like this:</p>

    <pre class="example">http://ip-address-or-hostname:port-number/printers/name/.printer</i>
ipp://ip-address/ipp/print
ipp://ip-address-or-hostname/printers/name
ipps://ip-address/ipp/print
ipps://ip-address:443/ipp/print
ipps://ip-address-or-hostname/printers/name</pre>

    <p>The backends supports many options, which are summarized in <a href="#TABLE2">Table 2</a>. Like all backends, options are added to the end of the URI using the URL form encoding format, for example:</p>

    <pre class="example">ipp://10.0.1.42/ipp/print?version=1.1
ipps://10.0.1.42:443/ipp/print?waitjob=false&amp;waitprinter=false</pre>

    <div class="table"><table summary="IPP URI Options">
      <caption>Table 2: <A NAME="TABLE2">IPP URI Options</a></caption>
      <thead>
	<tr>
	  <th>Option</th>
	  <th>Description</th>
	</tr>
      </thead>
      <tbody>
	<tr>
	  <td><code>contimeout=<I>seconds</I></code></td>
	  <td>Specifies the number of seconds to wait for the connection to the printer to complete (default 1 week or 604800 seconds).</td>
	</tr>
	<tr>
	  <td><code>encryption=always</code></td>
	  <td>Specifies that the connection to the IPP printer should be encrypted using SSL.</td>
	</tr>
	<tr>
	  <td><code>encryption=ifrequested</code></td>
	  <td>Specifies that the connection to the IPP printer should only be encrypted if the printer requests it.</td>
	</tr>
	<tr>
	  <td><code>encryption=never</code></td>
	  <td>Specifies that the connection to the IPP printer should not be encrypted.</td>
	</tr>
	<tr>
	  <td><code>encryption=required</code></td>
	  <td>Specifies that the connection to the IPP printer should be encrypted using TLS.</td>
	</tr>
	<tr>
	  <td><code>version=1.0</code></td>
	  <td>Specifies that version 1.0 of the IPP protocol should be used instead of the default version 2.0.</td>
	</tr>
	<tr>
	  <td><code>version=1.1</code></td>
	  <td>Specifies that version 1.1 of the IPP protocol should be used instead of the default version 2.0.</td>
	</tr>
	<tr>
	  <td><code>version=2.1</code></td>
	  <td>Specifies that version 2.1 of the IPP protocol should be used instead of the default version 2.0.</td>
	</tr>
	<tr>
	  <td><code>waitjob=false</code></td>
	  <td>Specifies that the IPP backend should not wait for the job to complete.</td>
	</tr>
	<tr>
	  <td><code>waitprinter=false</code></td>
	  <td>Specifies that the IPP backend should not wait for the printer to become idle before sending the print job.</td>
	</tr>
      </tbody>
    </table></div>


    <h4 id="LPD">Line Printer Daemon (LPD) Protocol (aka lpr)</h4>

    <p>LPD is the original network printing protocol created for the Berkeley UNIX line printer daemon (spooler) and is supported by many network printers. LPD printing normally happens over port 515 and uses the <code>lpd</code> backend. Device URIsfor the <code>lpd</code> backend look like this:</p>

    <pre class="example">lpd://ip-address/queue
lpd://ip-address/queue?format=l
lpd://ip-address/queue?format=l&amp;reserve=rfc1179</pre>

    <p><a href="#TABLE3">Table 3</a> summarizes the options supported by the <code>lpd</code> backend.</p>

    <blockquote><b>Note:</b> Due to limitations in the LPD protocol, we do not recommend using it if the printer or server supports any of the other protocols. Like AppSocket, LPD offers no security and is a common attack vector. LPD also, by default, requires that the computer save a copy of the entire print job before sending it to the printer - this can result in gigabytes of print data being saved to disk before any printing happens, delaying print jobs and shortening the life of your mass storage device!</blockquote>

    <div class="table"><table summary="LPD URI Options">
      <caption>Table 3: <A NAME="TABLE3">LPD URI Options</a></caption>
      <thead>
	<tr>
	  <th>Option</th>
	  <th>Description</th>
	</tr>
      </thead>
      <tbody>
	<tr>
	  <td><code>banner=on</code></td>
	  <td>Specifies that a banner page should be printed by the printer.</td>
	</tr>
	<tr>
	  <td><code>contimeout=<I>seconds</I></code></td>
	  <td>Specifies the number of seconds to wait for the connection to the printer to complete (default 1 week or 604800 seconds).</td>
	</tr>
	<tr>
	  <td><code>format=f</code></td>
	  <td>Specifies that the print data is a plain text file.</td>
	</tr>
	<tr>
	  <td><code>format=o</code></td>
	  <td>Specifies that the print data is a PostScript file.</td>
	</tr>
	<tr>
	  <td><code>format=p</code></td>
	  <td>Specifies that the print data is a plain text file that should be "pretty" printed with a header and footer.</td>
	</tr>
	<tr>
	  <td><code>mode=stream</code></td>
	  <td>Specifies that the backend should stream print data to the printer and not wait for confirmation that the job has been successfully printed.</td>
	</tr>
	<tr>
	  <td><code>order=data,control</code></td>
	  <td>Specifies that the print data files should be sent before the control file.</td>
	</tr>
	<tr>
	  <td><code>reserve=none</code></td>
	  <td>Specifies that the backend should not reserve a source port.</td>
	</tr>
	<tr>
	  <td><code>reserve=rfc1179</code></td>
	  <td>Specifies that the backend should reserve a source port from 721 to 731 as required by RFC 1179.</td>
	</tr>
	<tr>
	  <td><code>sanitize_title=no</code></td>
	  <td>Specifies that the job title string should not be restricted to ASCII alphanumeric and space characters.</td>
	</tr>
	<tr>
	  <td><code>sanitize_title=yes</code></td>
	  <td>Specifies that the job title string should be restricted to ASCII alphanumeric and space characters.</td>
	</tr>
	<tr>
	  <td><code>timeout=<I>seconds</I></code></td>
	  <td>Specifies the number of seconds to wait for LPD commands to complete (default 5 minutes or 300 seconds).</td>
	</tr>
      </tbody>
    </table></div>


    <h2 class="title" id="SNMP">Finding Printers Using SNMP</h2>

    <p>Whenever you view the administration web page or a list of supported device URIs, the <code>snmp</code> backend can probe the local network(s) using Simple Network Management Protocol (SNMP) v1 broadcasts. Printers that respond to these broadcasts are then interrogated for the make, model, and supported protocols, yielding a device URI that can be used to add the printer.</p>

    <p>The <a href="man-cups-snmp.conf.html"><var>/etc/cups/snmp.conf</var></a> file configures the <code>snmp</code> backend. Add the following line to enable discovery using the <code>snmp</code> backend:</p>

    <pre class="example">Address @LOCAL</pre>

    <p>If you don't use "public" as your community name, change the <code>Community</code> line as well:</p>

    <pre class="example">Community <I>your community name</I></pre>

    <blockquote><b>Note:</b> The <code>snmp</code> backend will not be able to find any printers on your network if SNMP v1 or broadcasting are disabled on your network. Also, broadcasts are typically limited to the local subnet, so printers on different networks cannot be discovered using SNMP.</blockquote>

    <h3>Troubleshooting SNMP Problems</h3>

    <p>The <code>snmp</code> backend sometimes exposes problems in vendor implementations. If you are experiencing long delays in loading the CUPS web interface administration page, or if you don't see your printer listed, the following instructions will help you to diagnose those problems and/or provide important feedback to the CUPS developers so that we can correct problems and improve the <code>snmp</code> backend in future releases.</p>

    <p>The SNMP backend supports a debugging mode that is activated by running it from a shell prompt. Run the following command to get a verbose log of the <code>snmp</code> backend:</p>

    <pre class="command">CUPS_DEBUG_LEVEL=2 /usr/lib/cups/backend/snmp @LOCAL 2>&amp;1 | tee snmp.log</pre>

    <p>On macOS you'll find the backend in /usr/libexec/cups/backend instead:</p>

    <pre class="command">CUPS_DEBUG_LEVEL=2 /usr/libexec/cups/backend/snmp @LOCAL 2>&amp;1 | tee snmp.log</pre>

    <p>The output will look something like this:</p>

    <pre class="example"> 1  INFO: Using default SNMP Address @LOCAL
 2  INFO: Using default SNMP Community public
 3  DEBUG: Scanning for devices in "public" via "@LOCAL"...
 4  DEBUG: 0.000 Sending 46 bytes to 10.0.1.255...
 5  DEBUG: SEQUENCE 44 bytes
 6  DEBUG:     INTEGER 1 bytes 0
 7  DEBUG:     OCTET STRING 6 bytes "public"
 8  DEBUG:     Get-Request-PDU 31 bytes
 9  DEBUG:         INTEGER 4 bytes 1149539174
10  DEBUG:         INTEGER 1 bytes 0
11  DEBUG:         INTEGER 1 bytes 0
12  DEBUG:         SEQUENCE 17 bytes
13  DEBUG:             SEQUENCE 15 bytes
14  DEBUG:                 OID 11 bytes .1.3.6.1.2.1.25.3.2.1.2.1
15  DEBUG:                 NULL VALUE 0 bytes
16  DEBUG: 0.001 Received 55 bytes from 10.0.1.42...
17  DEBUG: community="public"
18  DEBUG: request-id=1149539174
19  DEBUG: error-status=0
20  DEBUG: SEQUENCE 53 bytes
21  DEBUG:     INTEGER 1 bytes 0
22  DEBUG:     OCTET STRING 6 bytes "public"
23  DEBUG:     Get-Response-PDU 40 bytes
24  DEBUG:         INTEGER 4 bytes 1149539174
25  DEBUG:         INTEGER 1 bytes 0
26  DEBUG:         INTEGER 1 bytes 0
27  DEBUG:         SEQUENCE 26 bytes
28  DEBUG:             SEQUENCE 24 bytes
29  DEBUG:                 OID 11 bytes .1.3.6.1.2.1.25.3.2.1.2.1
30  DEBUG:                 OID 9 bytes .1.3.6.1.2.1.25.3.1.5
31  DEBUG: add_cache(addr=0xbfffe170, addrname="10.0.1.42", uri="(null)", id="(null)", make_and_model="(null)")
32  DEBUG: 0.002 Sending 46 bytes to 10.0.1.42...
33  DEBUG: SEQUENCE 44 bytes
34  DEBUG:     INTEGER 1 bytes 0
35  DEBUG:     OCTET STRING 6 bytes "public"
36  DEBUG:     Get-Request-PDU 31 bytes
37  DEBUG:         INTEGER 4 bytes 1149539175
38  DEBUG:         INTEGER 1 bytes 0
39  DEBUG:         INTEGER 1 bytes 0
40  DEBUG:         SEQUENCE 17 bytes
41  DEBUG:             SEQUENCE 15 bytes
42  DEBUG:                 OID 11 bytes .1.3.6.1.2.1.25.3.2.1.3.1
43  DEBUG:                 NULL VALUE 0 bytes
44  DEBUG: 0.003 Received 69 bytes from 10.0.1.42...
45  DEBUG: community="public"
46  DEBUG: request-id=1149539175
47  DEBUG: error-status=0
48  DEBUG: SEQUENCE 67 bytes
49  DEBUG:     INTEGER 1 bytes 0
50  DEBUG:     OCTET STRING 6 bytes "public"
51  DEBUG:     Get-Response-PDU 54 bytes
52  DEBUG:         INTEGER 4 bytes 1149539175
53  DEBUG:         INTEGER 1 bytes 0
54  DEBUG:         INTEGER 1 bytes 0
55  DEBUG:         SEQUENCE 40 bytes
56  DEBUG:             SEQUENCE 38 bytes
57  DEBUG:                 OID 11 bytes .1.3.6.1.2.1.25.3.2.1.3.1
58  DEBUG:                 OCTET STRING 23 bytes "HP LaserJet 4000 Series"
59  DEBUG: 1.001 Probing 10.0.1.42...
60  DEBUG: 1.001 Trying socket://10.0.1.42:9100...
61  DEBUG: 10.0.1.42 supports AppSocket!
62  DEBUG: 1.002 Scan complete!
63  network socket://10.0.1.42 "HP LaserJet 4000 Series" "HP LaserJet 4000 Series 10.0.1.42" ""</pre>

    <p>The first two lines are just informational and let you know that the default community name and address are being used. Lines 3-15 contain the initial SNMP query for the device type OID (.1.3.6.1.2.1.25.3.2.1.2.1) from the Host MIB.</p>

    <p>Lines 16-31 show the response we got from an HP LaserJet 4000 network printer. At this point we discover that it is a printer device and then send another SNMP query (lines 32-43) for the device description OID (.1.3.6.1.2.1.25.3.2.1.3.1) from the Host MIB as well.</p>

    <p>Lines 44-58 show the response to the device description query, which tells us that this is an HP LaserJet 4000 Series printer.</p>

    <p>On line 59 we start our active connection probe and discover that this print server supports the AppSocket (JetDirect) protocol on port 9100.</p>

    <p>Finally, line 63 shows the device information line for the print server that is sent to CUPS.</p>

    <p>If you don't see your printer listed, or the wrong information is listed, then you need to gather more information on the printer. The easiest way to do this is to run the snmpwalk command:</p>

    <pre class="command">snmpwalk -Cc -v 1 -c public ip-address | tee snmpwalk.log</pre>

    <p>where "ip-address" is the IP address of the printer or print server. You should see a <em>lot</em> of values stream by - the ones you want to see are:</p>

    <pre class="example">HOST-RESOURCES-MIB::hrDeviceType.1 = OID: HOST-RESOURCES-TYPES::hrDevicePrinter
HOST-RESOURCES-MIB::hrDeviceDescr.1 = STRING: HP LaserJet 4000 Series</pre>

    <p>The hrDeviceType line should show hrDevicePrinter; if not, then your printer or print server doesn't identify itself as a printer. The hrDeviceDescr line should provide a human-readable string for the make and model of the printer, although in some cases you'll just see something less useful like "Axis OfficeBASIC Parallel Print Server".</p>

    <p>Once you have collected the snmpwalk output, you should go to the  <a href="https://github.com/apple/cups/issues">CUPS Issue Tracker</a> page to submit a feature request to support your printer or print server. Be sure to attach those two log files you created - they will help us to identify the SNMP values we need to look for.</p>
  </body>
</html>
Commit	Line	Data
1576d09b MS	1	<!DOCTYPE html>
1576d09b MS	2	<html>
ef416fc2	3	<!-- SECTION: Getting Started -->
1576d09b MS	4	<head>
	5	<title>Using Network Printers</title>
	6	<link rel="stylesheet" type="text/css" href="../cups-printable.css">
	7	</head>
	8	<body>
	9	<h1 class="title">Using Network Printers</h1>
ef416fc2	10
1576d09b	11	<p>This help document describes how to discover, configure, and use TCP/IP network printers with CUPS.</p>
178cb736	12
1576d09b	13	<h2 class="title" id="AUTOMATIC">Automatic Configuration Using Bonjour</h2>
ef416fc2	14
1576d09b	15	<p>Most network printers support a protocol known as Bonjour, which is a combination of zero-configuration networking ("ZeroConf"), multicast DNS (mDNS), and DNS service discovery (DNS-SD) standards published by the Internet Engineering Task Force (IETF), the same group that defined TCP/IP and all of the networking we use today.</p>
b86bc4cf	16
1576d09b	17	<p>A printer that supports Bonjour can be found automatically using the <code>dnssd</code> backend. Run the <code>lpinfo(8)</code> command to find your printer's URI:</p>
b86bc4cf	18
1576d09b MS	19	<pre class="command">lpinfo --include-schemes dnssd -v
	20	network dnssd://Acme%20Laser%20Pro._ipp._tcp.local./?uuid=545253fb-1cb7-4d8d-98ed-ab6cd607cea7
	21	network dnssd://Bar99._printer.tcp.local./?uuid=f9efff58-9086-4c95-accb-81dee876a475
	22	network dnssd://Example%20EX-42._ipps._tcp.local./?uuid=4a0c67ad-2824-4ddf-9115-7d4226c5fe65
	23	network dnssd://Foo%20Fighter-1969._pdl-datastream._tcp.local./?uuid=4e216bea-c3de-4f65-a710-c99e11c80d2b</pre>
b86bc4cf	24
1576d09b	25	<p>You can then <a href="admin.html#PRINTERS">add a printer</a> using the URI reported.</p>
b86bc4cf	26
b86bc4cf	27
1576d09b	28	<h2 class="title" id="MANUAL">Manual Configuration Using IP Addresses</h2>
b86bc4cf	29
1576d09b	30	<p>You can also manually configure a printer using its Internet Protocol v4 (IPv4) address. This address is either configured manually ("static IP") through the printer's control panel or set using an automatic network protocol such as the Dynamic Host Control Protocol (DHCP) or ZeroConf.</p>
b86bc4cf	31
1576d09b	32	<blockquote><b>Note:</b> Configuring a printer using an IP address set using DHCP or ZeroConf is not recommended since the address will change every time the printer is turned on or after long periods of inactivity. Thus, every time the address changes you will need to modify the print queue using the <code>lpadmin</code> command.</blockquote>
b86bc4cf	33
1576d09b	34	<h3>Finding the IP Address</h3>
b86bc4cf	35
1576d09b	36	<p>You can normally find the IP address of a printer on the printer's control panel or by printing the configuration or status page. The <a href="#SNMP">Simple Network Management Protocol (SNMP)</a> can also be used to get the IP address remotely. To test that the IP address has been successfully assigned and that the printer is properly connected to your LAN or Wi-Fi network, type:</p>
b86bc4cf	37
1576d09b	38	<pre class="command">ping ip-address</pre>
b86bc4cf	39
1576d09b	40	<p>where "ip-address" is the address reported by the printer's control panel, configuration page, and/or status page. If the connection is working properly you will see something like:</p>
b86bc4cf	41
1576d09b MS	42	<pre class="command">ping 10.0.1.42
	43	PING 10.0.1.42 (10.0.1.42): 56 data bytes
	44	64 bytes from 10.0.1.42: icmp_seq=0 ttl=15 time=1.123 ms
	45	64 bytes from 10.0.1.42: icmp_seq=1 ttl=15 time=2.034 ms
	46	64 bytes from 10.0.1.42: icmp_seq=2 ttl=15 time=1.765 ms
	47	64 bytes from 10.0.1.42: icmp_seq=3 ttl=15 time=1.234 ms
	48	...</pre>
b86bc4cf	49
1576d09b MS	50	<p>If the connection is not working properly you will see something like:</p>
	51
	52	<pre class="command">ping 10.0.1.42
	53	PING 10.0.1.42 (10.0.1.42): 56 data bytes
	54	Request timeout for icmp_seq 0
	55	Request timeout for icmp_seq 1
	56	...</pre>
b86bc4cf	57
1576d09b	58	<p>Press <kbd>CTRL+C</kbd> to quit the <code>ping</code> command.</p>
b86bc4cf	59
1576d09b	60	<blockquote><b>Note:</b> If the command does not show responses from the printer, verify that the printer or print server is powered on and connected to the same LAN or Wi-Fi network as your computer. For LAN connections, also verify that your network cabling is good.</blockquote>
b86bc4cf	61
b86bc4cf	62
1576d09b	63	<h3>Choosing a Network Protocol (Backend)</h3>
b86bc4cf	64
1576d09b	65	<p>CUPS supports most network printers using one of three TCP/IP-based protocols: <a href="#SOCKET">AppSocket</a>, <a href="#IPP">Internet Printing Protocol</a>, and <a href="#LPD">Line Printer Daemon</a>. The following sections describe the options for each of the backends.</p>
b86bc4cf	66
b86bc4cf	67
1576d09b MS	68	<h4 id="SOCKET">AppSocket Protocol (aka JetDirect)</h4>
	69
	70	<p>The AppSocket protocol (sometimes also called the JetDirect protocol, owing to its origins with the HP JetDirect network interfaces) is the simplest and fastest network protocol used for printers. AppSocket printing normally happens over port 9100 and uses the <code>socket</code> backend. Device URIs for the <code>socket</code> backend look like this:</p>
	71
	72	<pre class="example">socket://ip-address
	73	socket://ip-address/?contimeout=30
	74	socket://ip-address/?waiteof=false
	75	socket://ip-address/?contimeout=30&waiteof=false
	76	socket://ip-address:port-number/?...</pre>
	77
	78	<p>The "contimeout" option controls the number of seconds that the backend will wait to obtain a connection to the printer. The default is 1 week or 604800 seconds.</p>
	79
	80	<p>The "waiteof" option controls whether the <code>socket</code> backend waits for the printer to complete the printing of the job. The default is to wait (<code>waiteof=true</code>). Add <code>waiteof=false</code> to the URI to tell the backend not to wait.</p>
	81
	82	<blockquote><b>Note:</b> While the AppSocket protocol is simple and fast, it also offers no security and is often an attack vector with printers. Consider using the <a href="#IPP">Internet Printing Protocol</a> which supports encryption and other security features.</blockquote>
	83
	84
	85	<h4 id="IPP">Internet Printing Protocol (IPP)</h4>
	86
	87	<p>IPP is the only protocol that CUPS supports natively and is supported by most network printers and print servers. IPP supports encryption and other security features over port 631 and uses the <code>http</code> (Windows), <code>ipp</code>, and <code>ipps</code> backends. Device URIs for these backends look like this:</p>
	88
	89	<pre class="example">http://ip-address-or-hostname:port-number/printers/name/.printer</i>
	90	ipp://ip-address/ipp/print
	91	ipp://ip-address-or-hostname/printers/name
	92	ipps://ip-address/ipp/print
	93	ipps://ip-address:443/ipp/print
	94	ipps://ip-address-or-hostname/printers/name</pre>
	95
	96	<p>The backends supports many options, which are summarized in <a href="#TABLE2">Table 2</a>. Like all backends, options are added to the end of the URI using the URL form encoding format, for example:</p>
	97
	98	<pre class="example">ipp://10.0.1.42/ipp/print?version=1.1
	99	ipps://10.0.1.42:443/ipp/print?waitjob=false&waitprinter=false</pre>
	100
	101	<div class="table"><table summary="IPP URI Options">
	102	<caption>Table 2: <A NAME="TABLE2">IPP URI Options</a></caption>
	103	<thead>
	104	<tr>
	105	<th>Option</th>
	106	<th>Description</th>
	107	</tr>
	108	</thead>
	109	<tbody>
	110	<tr>
	111	<td><code>contimeout=<I>seconds</I></code></td>
	112	<td>Specifies the number of seconds to wait for the connection to the printer to complete (default 1 week or 604800 seconds).</td>
	113	</tr>
	114	<tr>
	115	<td><code>encryption=always</code></td>
	116	<td>Specifies that the connection to the IPP printer should be encrypted using SSL.</td>
	117	</tr>
	118	<tr>
	119	<td><code>encryption=ifrequested</code></td>
	120	<td>Specifies that the connection to the IPP printer should only be encrypted if the printer requests it.</td>
	121	</tr>
	122	<tr>
	123	<td><code>encryption=never</code></td>
	124	<td>Specifies that the connection to the IPP printer should not be encrypted.</td>
	125	</tr>
	126	<tr>
	127	<td><code>encryption=required</code></td>
	128	<td>Specifies that the connection to the IPP printer should be encrypted using TLS.</td>
	129	</tr>
	130	<tr>
	131	<td><code>version=1.0</code></td>
132	<td>Specifies that version 1.0 of the IPP protocol should be used instead of the default version 2.0.</td>
133	</tr>
134	<tr>
135	<td><code>version=1.1</code></td>
136	<td>Specifies that version 1.1 of the IPP protocol should be used instead of the default version 2.0.</td>
137	</tr>
138	<tr>
139	<td><code>version=2.1</code></td>
140	<td>Specifies that version 2.1 of the IPP protocol should be used instead of the default version 2.0.</td>
141	</tr>
142	<tr>
143	<td><code>waitjob=false</code></td>
144	<td>Specifies that the IPP backend should not wait for the job to complete.</td>
145	</tr>
146	<tr>
147	<td><code>waitprinter=false</code></td>
148	<td>Specifies that the IPP backend should not wait for the printer to become idle before sending the print job.</td>
149	</tr>
150	</tbody>
151	</table></div>
152
153
154	<h4 id="LPD">Line Printer Daemon (LPD) Protocol (aka lpr)</h4>
155
156	<p>LPD is the original network printing protocol created for the Berkeley UNIX line printer daemon (spooler) and is supported by many network printers. LPD printing normally happens over port 515 and uses the <code>lpd</code> backend. Device URIsfor the <code>lpd</code> backend look like this:</p>
157
158	<pre class="example">lpd://ip-address/queue
159	lpd://ip-address/queue?format=l
160	lpd://ip-address/queue?format=l&reserve=rfc1179</pre>
161
162	<p><a href="#TABLE3">Table 3</a> summarizes the options supported by the <code>lpd</code> backend.</p>
163
164	<blockquote><b>Note:</b> Due to limitations in the LPD protocol, we do not recommend using it if the printer or server supports any of the other protocols. Like AppSocket, LPD offers no security and is a common attack vector. LPD also, by default, requires that the computer save a copy of the entire print job before sending it to the printer - this can result in gigabytes of print data being saved to disk before any printing happens, delaying print jobs and shortening the life of your mass storage device!</blockquote>
165
166	<div class="table"><table summary="LPD URI Options">
167	<caption>Table 3: <A NAME="TABLE3">LPD URI Options</a></caption>
168	<thead>
169	<tr>
170	<th>Option</th>
171	<th>Description</th>
172	</tr>
173	</thead>
174	<tbody>
175	<tr>
176	<td><code>banner=on</code></td>
177	<td>Specifies that a banner page should be printed by the printer.</td>
178	</tr>
179	<tr>
180	<td><code>contimeout=<I>seconds</I></code></td>
181	<td>Specifies the number of seconds to wait for the connection to the printer to complete (default 1 week or 604800 seconds).</td>
182	</tr>
183	<tr>
184	<td><code>format=f</code></td>
185	<td>Specifies that the print data is a plain text file.</td>
186	</tr>
187	<tr>
188	<td><code>format=o</code></td>
189	<td>Specifies that the print data is a PostScript file.</td>
190	</tr>
191	<tr>
192	<td><code>format=p</code></td>
193	<td>Specifies that the print data is a plain text file that should be "pretty" printed with a header and footer.</td>
194	</tr>
195	<tr>
196	<td><code>mode=stream</code></td>
197	<td>Specifies that the backend should stream print data to the printer and not wait for confirmation that the job has been successfully printed.</td>
198	</tr>
199	<tr>
200	<td><code>order=data,control</code></td>
201	<td>Specifies that the print data files should be sent before the control file.</td>
202	</tr>
203	<tr>
204	<td><code>reserve=none</code></td>
205	<td>Specifies that the backend should not reserve a source port.</td>
206	</tr>
207	<tr>
208	<td><code>reserve=rfc1179</code></td>
209	<td>Specifies that the backend should reserve a source port from 721 to 731 as required by RFC 1179.</td>
210	</tr>
211	<tr>
212	<td><code>sanitize_title=no</code></td>
213	<td>Specifies that the job title string should not be restricted to ASCII alphanumeric and space characters.</td>
214	</tr>
215	<tr>
216	<td><code>sanitize_title=yes</code></td>
217	<td>Specifies that the job title string should be restricted to ASCII alphanumeric and space characters.</td>
218	</tr>
219	<tr>
220	<td><code>timeout=<I>seconds</I></code></td>
221	<td>Specifies the number of seconds to wait for LPD commands to complete (default 5 minutes or 300 seconds).</td>
222	</tr>
223	</tbody>
224	</table></div>
225
226
227	<h2 class="title" id="SNMP">Finding Printers Using SNMP</h2>
228
229	<p>Whenever you view the administration web page or a list of supported device URIs, the <code>snmp</code> backend can probe the local network(s) using Simple Network Management Protocol (SNMP) v1 broadcasts. Printers that respond to these broadcasts are then interrogated for the make, model, and supported protocols, yielding a device URI that can be used to add the printer.</p>
230
231	<p>The <a href="man-cups-snmp.conf.html"><var>/etc/cups/snmp.conf</var></a> file configures the <code>snmp</code> backend. Add the following line to enable discovery using the <code>snmp</code> backend:</p>
232
233	<pre class="example">Address @LOCAL</pre>
234
235	<p>If you don't use "public" as your community name, change the <code>Community</code> line as well:</p>
236
237	<pre class="example">Community <I>your community name</I></pre>
238
239	<blockquote><b>Note:</b> The <code>snmp</code> backend will not be able to find any printers on your network if SNMP v1 or broadcasting are disabled on your network. Also, broadcasts are typically limited to the local subnet, so printers on different networks cannot be discovered using SNMP.</blockquote>
240
241	<h3>Troubleshooting SNMP Problems</h3>
242
243	<p>The <code>snmp</code> backend sometimes exposes problems in vendor implementations. If you are experiencing long delays in loading the CUPS web interface administration page, or if you don't see your printer listed, the following instructions will help you to diagnose those problems and/or provide important feedback to the CUPS developers so that we can correct problems and improve the <code>snmp</code> backend in future releases.</p>
244
245	<p>The SNMP backend supports a debugging mode that is activated by running it from a shell prompt. Run the following command to get a verbose log of the <code>snmp</code> backend:</p>
246
247	<pre class="command">CUPS_DEBUG_LEVEL=2 /usr/lib/cups/backend/snmp @LOCAL 2>&1 \| tee snmp.log</pre>
248
249	<p>On macOS you'll find the backend in /usr/libexec/cups/backend instead:</p>
250
251	<pre class="command">CUPS_DEBUG_LEVEL=2 /usr/libexec/cups/backend/snmp @LOCAL 2>&1 \| tee snmp.log</pre>
252
253	<p>The output will look something like this:</p>
254
255	<pre class="example"> 1 INFO: Using default SNMP Address @LOCAL
b86bc4cf	256	2 INFO: Using default SNMP Community public
b86bc4cf	257	3 DEBUG: Scanning for devices in "public" via "@LOCAL"...
1576d09b	258	4 DEBUG: 0.000 Sending 46 bytes to 10.0.1.255...
b86bc4cf	259	5 DEBUG: SEQUENCE 44 bytes
	260	6 DEBUG: INTEGER 1 bytes 0
	261	7 DEBUG: OCTET STRING 6 bytes "public"
	262	8 DEBUG: Get-Request-PDU 31 bytes
	263	9 DEBUG: INTEGER 4 bytes 1149539174
	264	10 DEBUG: INTEGER 1 bytes 0
	265	11 DEBUG: INTEGER 1 bytes 0
	266	12 DEBUG: SEQUENCE 17 bytes
	267	13 DEBUG: SEQUENCE 15 bytes
	268	14 DEBUG: OID 11 bytes .1.3.6.1.2.1.25.3.2.1.2.1
	269	15 DEBUG: NULL VALUE 0 bytes
1576d09b	270	16 DEBUG: 0.001 Received 55 bytes from 10.0.1.42...
b86bc4cf	271	17 DEBUG: community="public"
	272	18 DEBUG: request-id=1149539174
	273	19 DEBUG: error-status=0
	274	20 DEBUG: SEQUENCE 53 bytes
	275	21 DEBUG: INTEGER 1 bytes 0
	276	22 DEBUG: OCTET STRING 6 bytes "public"
	277	23 DEBUG: Get-Response-PDU 40 bytes
	278	24 DEBUG: INTEGER 4 bytes 1149539174
	279	25 DEBUG: INTEGER 1 bytes 0
	280	26 DEBUG: INTEGER 1 bytes 0
	281	27 DEBUG: SEQUENCE 26 bytes
	282	28 DEBUG: SEQUENCE 24 bytes
	283	29 DEBUG: OID 11 bytes .1.3.6.1.2.1.25.3.2.1.2.1
	284	30 DEBUG: OID 9 bytes .1.3.6.1.2.1.25.3.1.5
1576d09b MS	285	31 DEBUG: add_cache(addr=0xbfffe170, addrname="10.0.1.42", uri="(null)", id="(null)", make_and_model="(null)")
1576d09b MS	286	32 DEBUG: 0.002 Sending 46 bytes to 10.0.1.42...
b86bc4cf	287	33 DEBUG: SEQUENCE 44 bytes
	288	34 DEBUG: INTEGER 1 bytes 0
	289	35 DEBUG: OCTET STRING 6 bytes "public"
	290	36 DEBUG: Get-Request-PDU 31 bytes
	291	37 DEBUG: INTEGER 4 bytes 1149539175
	292	38 DEBUG: INTEGER 1 bytes 0
	293	39 DEBUG: INTEGER 1 bytes 0
	294	40 DEBUG: SEQUENCE 17 bytes
	295	41 DEBUG: SEQUENCE 15 bytes
	296	42 DEBUG: OID 11 bytes .1.3.6.1.2.1.25.3.2.1.3.1
	297	43 DEBUG: NULL VALUE 0 bytes
1576d09b	298	44 DEBUG: 0.003 Received 69 bytes from 10.0.1.42...
b86bc4cf	299	45 DEBUG: community="public"
	300	46 DEBUG: request-id=1149539175
	301	47 DEBUG: error-status=0
	302	48 DEBUG: SEQUENCE 67 bytes
	303	49 DEBUG: INTEGER 1 bytes 0
	304	50 DEBUG: OCTET STRING 6 bytes "public"
	305	51 DEBUG: Get-Response-PDU 54 bytes
	306	52 DEBUG: INTEGER 4 bytes 1149539175
	307	53 DEBUG: INTEGER 1 bytes 0
	308	54 DEBUG: INTEGER 1 bytes 0
	309	55 DEBUG: SEQUENCE 40 bytes
	310	56 DEBUG: SEQUENCE 38 bytes
	311	57 DEBUG: OID 11 bytes .1.3.6.1.2.1.25.3.2.1.3.1
1576d09b MS	312	58 DEBUG: OCTET STRING 23 bytes "HP LaserJet 4000 Series"
	313	59 DEBUG: 1.001 Probing 10.0.1.42...
	314	60 DEBUG: 1.001 Trying socket://10.0.1.42:9100...
	315	61 DEBUG: 10.0.1.42 supports AppSocket!
b86bc4cf	316	62 DEBUG: 1.002 Scan complete!
1576d09b MS	317	63 network socket://10.0.1.42 "HP LaserJet 4000 Series" "HP LaserJet 4000 Series 10.0.1.42" ""</pre>
	318
	319	<p>The first two lines are just informational and let you know that the default community name and address are being used. Lines 3-15 contain the initial SNMP query for the device type OID (.1.3.6.1.2.1.25.3.2.1.2.1) from the Host MIB.</p>
	320
	321	<p>Lines 16-31 show the response we got from an HP LaserJet 4000 network printer. At this point we discover that it is a printer device and then send another SNMP query (lines 32-43) for the device description OID (.1.3.6.1.2.1.25.3.2.1.3.1) from the Host MIB as well.</p>
	322
	323	<p>Lines 44-58 show the response to the device description query, which tells us that this is an HP LaserJet 4000 Series printer.</p>
	324
	325	<p>On line 59 we start our active connection probe and discover that this print server supports the AppSocket (JetDirect) protocol on port 9100.</p>
	326
	327	<p>Finally, line 63 shows the device information line for the print server that is sent to CUPS.</p>
ef416fc2	328
1576d09b	329	<p>If you don't see your printer listed, or the wrong information is listed, then you need to gather more information on the printer. The easiest way to do this is to run the snmpwalk command:</p>
ef416fc2	330
1576d09b	331	<pre class="command">snmpwalk -Cc -v 1 -c public ip-address \| tee snmpwalk.log</pre>
ef416fc2	332
1576d09b	333	<p>where "ip-address" is the IP address of the printer or print server. You should see a <em>lot</em> of values stream by - the ones you want to see are:</p>
ef416fc2	334
1576d09b MS	335	<pre class="example">HOST-RESOURCES-MIB::hrDeviceType.1 = OID: HOST-RESOURCES-TYPES::hrDevicePrinter
1576d09b MS	336	HOST-RESOURCES-MIB::hrDeviceDescr.1 = STRING: HP LaserJet 4000 Series</pre>
ef416fc2	337
1576d09b	338	<p>The hrDeviceType line should show hrDevicePrinter; if not, then your printer or print server doesn't identify itself as a printer. The hrDeviceDescr line should provide a human-readable string for the make and model of the printer, although in some cases you'll just see something less useful like "Axis OfficeBASIC Parallel Print Server".</p>
ef416fc2	339
1576d09b MS	340	<p>Once you have collected the snmpwalk output, you should go to the <a href="https://github.com/apple/cups/issues">CUPS Issue Tracker</a> page to submit a feature request to support your printer or print server. Be sure to attach those two log files you created - they will help us to identify the SNMP values we need to look for.</p>
	341	</body>
	342	</html>