1*5e7646d2SAndroid Build Coastguard Worker<!DOCTYPE html> 2*5e7646d2SAndroid Build Coastguard Worker<html> 3*5e7646d2SAndroid Build Coastguard Worker <!-- SECTION: Getting Started --> 4*5e7646d2SAndroid Build Coastguard Worker <head> 5*5e7646d2SAndroid Build Coastguard Worker <title>Command-Line Printer Administration</title> 6*5e7646d2SAndroid Build Coastguard Worker <link rel="stylesheet" type="text/css" href="../cups-printable.css"> 7*5e7646d2SAndroid Build Coastguard Worker </head> 8*5e7646d2SAndroid Build Coastguard Worker <body> 9*5e7646d2SAndroid Build Coastguard Worker <h1 class="title">Command-Line Printer Administration</h1> 10*5e7646d2SAndroid Build Coastguard Worker 11*5e7646d2SAndroid Build Coastguard Worker <p>This help document describes how to configure and manage destinations with CUPS.</p> 12*5e7646d2SAndroid Build Coastguard Worker 13*5e7646d2SAndroid Build Coastguard Worker 14*5e7646d2SAndroid Build Coastguard Worker <h2 class="title" id="INTRO">Introduction</h2> 15*5e7646d2SAndroid Build Coastguard Worker 16*5e7646d2SAndroid Build Coastguard Worker <p>Destinations are individual printers and classes (pools) of printers. <a href="#PRINTERS">Printers</a> use a description file with one or more driver ("filter") programs that communicate with the printer through a "backend" program. CUPS currently uses PPD (PostScript Printer Description) files to describe the printer and driver programs needed, some of which come with CUPS while others come with your operating system or Linux distribution. Backends are specified using a URI (Universal Resource Identifier) where the URI scheme is the backend name, e.g., "ipp://11.22.33.44/ipp/print" specifies the "ipp" backend - like PPD files, some backends come with CUPS while others come with your operating system.</p> 17*5e7646d2SAndroid Build Coastguard Worker 18*5e7646d2SAndroid Build Coastguard Worker <p><a href="#CLASSES">Classes</a> are associated with one or more printers and are typically used to distribute print jobs amongst a group of printers or provide redundancy or high availability when printing. Print jobs sent to a class are forwarded to the next available printer in the class.</p> 19*5e7646d2SAndroid Build Coastguard Worker 20*5e7646d2SAndroid Build Coastguard Worker <p>The <a href="man-lpadmin.html"><code>lpadmin(8)</code></a> program is used to add, modify, or delete destinations, while the <a href="man-lpinfo.html"><code>lpinfo(8)</code></a> command is used to list the available printer drivers and backends. The <a href="man-cupsctl.html"><code>cupsctl(8)</code></a> program is used to manage the printing system as a whole, including things like <a href="#DEBUG">debug logging</a> and <a href="#SHARING">printer sharing</a>. The CUPS web interface ("http://localhost:631" or "https://servername:631") can also be used, and most operating systems provide their own GUI administration tools.</p> 21*5e7646d2SAndroid Build Coastguard Worker 22*5e7646d2SAndroid Build Coastguard Worker 23*5e7646d2SAndroid Build Coastguard Worker <h2 class="title" id="PRINTERS">Managing Printers</h2> 24*5e7646d2SAndroid Build Coastguard Worker 25*5e7646d2SAndroid Build Coastguard Worker <p>The <code>lpadmin</code> command is used to create, modify, or delete a printer. The <code>-p</code> option specifies a printer to create or modify:</p> 26*5e7646d2SAndroid Build Coastguard Worker 27*5e7646d2SAndroid Build Coastguard Worker <pre class="command">lpadmin -p printername ...</pre> 28*5e7646d2SAndroid Build Coastguard Worker 29*5e7646d2SAndroid Build Coastguard Worker <p>The <code>lpadmin</code> accepts several additional options after <code>-p printername</code> when adding or modifying a printer:</p> 30*5e7646d2SAndroid Build Coastguard Worker 31*5e7646d2SAndroid Build Coastguard Worker <dl> 32*5e7646d2SAndroid Build Coastguard Worker <dt><code>-D "description"</code></dt> 33*5e7646d2SAndroid Build Coastguard Worker <dd>Sets the description of the printer which is often shown instead of the printer name, for example "HP LaserJet".</dd> 34*5e7646d2SAndroid Build Coastguard Worker 35*5e7646d2SAndroid Build Coastguard Worker <dt><code>-E</code></dt> 36*5e7646d2SAndroid Build Coastguard Worker <dd>Enables the printer and accepts new print jobs.</dd> 37*5e7646d2SAndroid Build Coastguard Worker 38*5e7646d2SAndroid Build Coastguard Worker <dt><code>-L "location"</code></dt> 39*5e7646d2SAndroid Build Coastguard Worker <dd>Sets the location of the printer, for example "Conference Room".</dd> 40*5e7646d2SAndroid Build Coastguard Worker 41*5e7646d2SAndroid Build Coastguard Worker <dt><code>-m model</code></dt> 42*5e7646d2SAndroid Build Coastguard Worker <dd>Sets the printer driver using the <a href="#MODELS">model name</a>.</dd> 43*5e7646d2SAndroid Build Coastguard Worker 44*5e7646d2SAndroid Build Coastguard Worker <dt><code>-o option=value</code></dt> 45*5e7646d2SAndroid Build Coastguard Worker <dd>Sets the <a href="#OPTIONS">named option</a>.</dd> 46*5e7646d2SAndroid Build Coastguard Worker 47*5e7646d2SAndroid Build Coastguard Worker <dt><code>-v device-uri</code></dt> 48*5e7646d2SAndroid Build Coastguard Worker <dd>Sets the <a href="#DEVICES">URI for the printer</a>.</dd> 49*5e7646d2SAndroid Build Coastguard Worker 50*5e7646d2SAndroid Build Coastguard Worker </dl> 51*5e7646d2SAndroid Build Coastguard Worker 52*5e7646d2SAndroid Build Coastguard Worker <p>The <code>-x</code> option deletes the named printer:</p> 53*5e7646d2SAndroid Build Coastguard Worker 54*5e7646d2SAndroid Build Coastguard Worker <pre class="command">lpadmin -x printername</pre> 55*5e7646d2SAndroid Build Coastguard Worker 56*5e7646d2SAndroid Build Coastguard Worker 57*5e7646d2SAndroid Build Coastguard Worker <h3 id="MODELS">Printer Drivers and PPDs</h3> 58*5e7646d2SAndroid Build Coastguard Worker 59*5e7646d2SAndroid Build Coastguard Worker <p>The <code>-m</code> option to <code>lpadmin</code> specifies the driver ("model") to use for the printer. You can run the <code>lpinfo -m</code> command to list all of the available drivers ("models") on your system:</p> 60*5e7646d2SAndroid Build Coastguard Worker 61*5e7646d2SAndroid Build Coastguard Worker <pre class="command">lpinfo -m</pre> 62*5e7646d2SAndroid Build Coastguard Worker 63*5e7646d2SAndroid Build Coastguard Worker <p>Each line contains the driver name followed by its description, for example:</p> 64*5e7646d2SAndroid Build Coastguard Worker 65*5e7646d2SAndroid Build Coastguard Worker <pre class="example">drv:///sample.drv/dymo.ppd Dymo Label Printer 66*5e7646d2SAndroid Build Coastguard Workerdrv:///sample.drv/epson9.ppd Epson 9-Pin Series 67*5e7646d2SAndroid Build Coastguard Workerdrv:///sample.drv/epson24.ppd Epson 24-Pin Series 68*5e7646d2SAndroid Build Coastguard Workerdrv:///sample.drv/generpcl.ppd Generic PCL Laser Printer 69*5e7646d2SAndroid Build Coastguard Workerdrv:///sample.drv/generic.ppd Generic PostScript Printer 70*5e7646d2SAndroid Build Coastguard Workerdrv:///sample.drv/deskjet.ppd HP DeskJet Series 71*5e7646d2SAndroid Build Coastguard Workerdrv:///sample.drv/laserjet.ppd HP LaserJet Series PCL 4/5 72*5e7646d2SAndroid Build Coastguard Workerdrv:///sample.drv/intelbar.ppd Intellitech IntelliBar Label Printer, 2.1 73*5e7646d2SAndroid Build Coastguard Workerdrv:///sample.drv/okidata9.ppd Oki 9-Pin Series 74*5e7646d2SAndroid Build Coastguard Workerdrv:///sample.drv/okidat24.ppd Oki 24-Pin Series 75*5e7646d2SAndroid Build Coastguard Workerdrv:///sample.drv/zebracpl.ppd Zebra CPCL Label Printer 76*5e7646d2SAndroid Build Coastguard Workerdrv:///sample.drv/zebraep1.ppd Zebra EPL1 Label Printer 77*5e7646d2SAndroid Build Coastguard Workerdrv:///sample.drv/zebraep2.ppd Zebra EPL2 Label Printer 78*5e7646d2SAndroid Build Coastguard Workerdrv:///sample.drv/zebra.ppd Zebra ZPL Label Printer 79*5e7646d2SAndroid Build Coastguard Workereverywhere IPP Everywhere</pre> 80*5e7646d2SAndroid Build Coastguard Worker 81*5e7646d2SAndroid Build Coastguard Worker <p>The <code>everywhere</code> driver is used for nearly all modern networks printers sold since about 2009. For example, the following command creates a destination for a printer at IP address 11.22.33.44:</p> 82*5e7646d2SAndroid Build Coastguard Worker 83*5e7646d2SAndroid Build Coastguard Worker <pre class="command">lpadmin -p printername -E -v ipp://11.22.33.44/ipp/print -m everywhere</pre> 84*5e7646d2SAndroid Build Coastguard Worker 85*5e7646d2SAndroid Build Coastguard Worker <p>The CUPS sample drivers (the "drv:///sample.drv/..." lines above) can be used for "legacy" printers. For example, the following command creates a destination for a HP LaserJet printer at IP address 11.22.33.44:</p> 86*5e7646d2SAndroid Build Coastguard Worker 87*5e7646d2SAndroid Build Coastguard Worker <pre class="command">lpadmin -p printername -E -v socket://11.22.33.44 -m drv:///sample.drv/laserjet.ppd</pre> 88*5e7646d2SAndroid Build Coastguard Worker 89*5e7646d2SAndroid Build Coastguard Worker <blockquote>Note: The CUPS sample drivers are designed to provide basic printing capabilities for the broadest range of printers possible, but generally do not exercise the full potential of the printers or CUPS. Other drivers (including the <code>everywhere</code> driver) provide greater printing capabilities and better print quality.</blockquote> 90*5e7646d2SAndroid Build Coastguard Worker 91*5e7646d2SAndroid Build Coastguard Worker 92*5e7646d2SAndroid Build Coastguard Worker <h3 id="DEVICES">Device URIs (Backends)</h3> 93*5e7646d2SAndroid Build Coastguard Worker 94*5e7646d2SAndroid Build Coastguard Worker <p>CUPS comes with several standard backends that communicate with printers:</p> 95*5e7646d2SAndroid Build Coastguard Worker 96*5e7646d2SAndroid Build Coastguard Worker <ol> 97*5e7646d2SAndroid Build Coastguard Worker <li><code>dnssd</code>: The Bonjour (DNS-SD) protocol.</li> 98*5e7646d2SAndroid Build Coastguard Worker <li><code>ipp</code>: The Internet Printing Protocol (IPP) with optional encryption.</li> 99*5e7646d2SAndroid Build Coastguard Worker <li><code>ipps</code>: The Internet Printing Protocol with mandatory encryption.</li> 100*5e7646d2SAndroid Build Coastguard Worker <li><code>lpd</code>: The Line Printer Daemon protocol.</li> 101*5e7646d2SAndroid Build Coastguard Worker <li><code>socket</code>: The AppSocket (JetDirect) protocol.</li> 102*5e7646d2SAndroid Build Coastguard Worker <li><code>usb</code>: The Universal Serial Bus (USB) printer class.</li> 103*5e7646d2SAndroid Build Coastguard Worker </ol> 104*5e7646d2SAndroid Build Coastguard Worker 105*5e7646d2SAndroid Build Coastguard Worker <p>Run the <code>lpinfo -v</code> command to list the available backends and printers:</p> 106*5e7646d2SAndroid Build Coastguard Worker 107*5e7646d2SAndroid Build Coastguard Worker <pre class="command">lpinfo -v</pre> 108*5e7646d2SAndroid Build Coastguard Worker 109*5e7646d2SAndroid Build Coastguard Worker <p>Each line contains the backend "class" followed by the backend name or a full printer device URI, for example:</p> 110*5e7646d2SAndroid Build Coastguard Worker 111*5e7646d2SAndroid Build Coastguard Worker <pre class="example">network lpd 112*5e7646d2SAndroid Build Coastguard Workernetwork ipps 113*5e7646d2SAndroid Build Coastguard Workernetwork ipp 114*5e7646d2SAndroid Build Coastguard Workernetwork socket 115*5e7646d2SAndroid Build Coastguard Workernetwork dnssd://Acme%20Laser%20Pro._ipp._tcp.local./?uuid=545253fb-1cb7-4d8d-98ed-ab6cd607cea7 116*5e7646d2SAndroid Build Coastguard Workernetwork dnssd://Bar99._printer.tcp.local./?uuid=f9efff58-9086-4c95-accb-81dee876a475 117*5e7646d2SAndroid Build Coastguard Workernetwork dnssd://Example%20EX-42._ipps._tcp.local./?uuid=4a0c67ad-2824-4ddf-9115-7d4226c5fe65 118*5e7646d2SAndroid Build Coastguard Workernetwork dnssd://Foo%20Fighter-1969._pdl-datastream._tcp.local./?uuid=4e216bea-c3de-4f65-a710-c99e11c80d2b 119*5e7646d2SAndroid Build Coastguard Workerdirect usb://ZP/LazerJet%20MFP?serial=42</pre> 120*5e7646d2SAndroid Build Coastguard Worker 121*5e7646d2SAndroid Build Coastguard Worker <p>The <code>network</code> class of backends is used for all network protocols. The <a href="network.html">Using Network Printers</a> help document describes how to use the standard CUPS network backends. The <code>direct</code> class of backends is used for directly-connected printers such as USB and Bluetooth. Because these backends use a system-specific identifier, you should only use the reported device URIs.</p> 122*5e7646d2SAndroid Build Coastguard Worker 123*5e7646d2SAndroid Build Coastguard Worker <p>Once you know the correct URI for the printer, set it using the <code>lpadmin</code> command's <code>-v</code> option:</p> 124*5e7646d2SAndroid Build Coastguard Worker 125*5e7646d2SAndroid Build Coastguard Worker <pre class="command">lpadmin -p printername -v device-uri</pre> 126*5e7646d2SAndroid Build Coastguard Worker 127*5e7646d2SAndroid Build Coastguard Worker 128*5e7646d2SAndroid Build Coastguard Worker <h3 id="OPTIONS">Printer Options</h3> 129*5e7646d2SAndroid Build Coastguard Worker 130*5e7646d2SAndroid Build Coastguard Worker <p>The <code>lpadmin</code> command allows you to set various options for a printer:</p> 131*5e7646d2SAndroid Build Coastguard Worker 132*5e7646d2SAndroid Build Coastguard Worker <dl> 133*5e7646d2SAndroid Build Coastguard Worker <dt><code>-o cupsIPPSupplies=false</code></dt> 134*5e7646d2SAndroid Build Coastguard Worker <dd>Turns off IPP supply level reporting for a printer.</dd> 135*5e7646d2SAndroid Build Coastguard Worker 136*5e7646d2SAndroid Build Coastguard Worker <dt><code>-o cupsSNMPSupplies=false</code></dt> 137*5e7646d2SAndroid Build Coastguard Worker <dd>Turns off SNMP supply level reporting for a printer.</dd> 138*5e7646d2SAndroid Build Coastguard Worker 139*5e7646d2SAndroid Build Coastguard Worker <dt><code>-o name=value</code></dt> 140*5e7646d2SAndroid Build Coastguard Worker <dd>Sets the default value for the named PPD option. For example, <code>-o PageSize=Legal</code> sets the default page size to US Legal.</dd> 141*5e7646d2SAndroid Build Coastguard Worker 142*5e7646d2SAndroid Build Coastguard Worker <dt><code>-o printer-error-policy=name</code></dt> 143*5e7646d2SAndroid Build Coastguard Worker <dd>Sets the policy for errors such as printers that cannot be found or accessed, don't support the format being printed, fail during submission of the print data, or cause one or more filters to crash:<dl> 144*5e7646d2SAndroid Build Coastguard Worker <dt><code>abort-job</code></dt> 145*5e7646d2SAndroid Build Coastguard Worker <dd>Aborts the job on error.</dd> 146*5e7646d2SAndroid Build Coastguard Worker <dt><code>retry-job</code></dt> 147*5e7646d2SAndroid Build Coastguard Worker <dd>Retries the job at a future time.</dd> 148*5e7646d2SAndroid Build Coastguard Worker <dt><code>retry-current-job</code></dt> 149*5e7646d2SAndroid Build Coastguard Worker <dd>Retries the current job immediately.</dd> 150*5e7646d2SAndroid Build Coastguard Worker <dt><code>stop-printer</code></dt> 151*5e7646d2SAndroid Build Coastguard Worker <dd>Stops the printer on error.</dd> 152*5e7646d2SAndroid Build Coastguard Worker </dl></dd> 153*5e7646d2SAndroid Build Coastguard Worker 154*5e7646d2SAndroid Build Coastguard Worker <dt><code>-o printer-is-shared=true/false</code></dt> 155*5e7646d2SAndroid Build Coastguard Worker <dd>Enables/disables per-printer sharing. See the section on <a href="#SHARING">Printer Sharing</a> for more information.</dd> 156*5e7646d2SAndroid Build Coastguard Worker 157*5e7646d2SAndroid Build Coastguard Worker <dt><code>-o printer-op-policy=name</code></dt> 158*5e7646d2SAndroid Build Coastguard Worker <dd>Sets the operation policy associated with the printer. See the <a href="policies.html">Managing Operation Policies</a> help document for more information.</dd> 159*5e7646d2SAndroid Build Coastguard Worker 160*5e7646d2SAndroid Build Coastguard Worker <dt><code>-u allow:{user|@group}{,user|,@group}*</code></dt> 161*5e7646d2SAndroid Build Coastguard Worker <dt><code>-u allow:all</code></dt> 162*5e7646d2SAndroid Build Coastguard Worker <dt><code>-u deny:{user|@group}{,user|,@group}*</code></dt> 163*5e7646d2SAndroid Build Coastguard Worker <dt><code>-u deny:none</code></dt> 164*5e7646d2SAndroid Build Coastguard Worker <dd>Sets user-level access control for the printer. The <code>allow:</code> list defines a whitelist of users and groups while the <code>deny:</code> list defines a blacklist of users and groups.</dd> 165*5e7646d2SAndroid Build Coastguard Worker </dl> 166*5e7646d2SAndroid Build Coastguard Worker 167*5e7646d2SAndroid Build Coastguard Worker 168*5e7646d2SAndroid Build Coastguard Worker <h2 class="title" id="SHARING">Printer Sharing</h2> 169*5e7646d2SAndroid Build Coastguard Worker 170*5e7646d2SAndroid Build Coastguard Worker <p>CUPS supports sharing of printers with other computers and mobile devices. Two <code>cupsctl</code> options control the general printer sharing features:</p> 171*5e7646d2SAndroid Build Coastguard Worker 172*5e7646d2SAndroid Build Coastguard Worker <dl> 173*5e7646d2SAndroid Build Coastguard Worker <dt><code>--share-printers</code></dt> 174*5e7646d2SAndroid Build Coastguard Worker <dd>Enables sharing of printers with other computers and mobile devices on your local network.</dd> 175*5e7646d2SAndroid Build Coastguard Worker 176*5e7646d2SAndroid Build Coastguard Worker <dt><code>--remote-any</code></dt> 177*5e7646d2SAndroid Build Coastguard Worker <dd>Expands printer sharing to any network that can reach your server.</dd> 178*5e7646d2SAndroid Build Coastguard Worker </dl> 179*5e7646d2SAndroid Build Coastguard Worker 180*5e7646d2SAndroid Build Coastguard Worker <p>Once you have enabled printer sharing, you then must select which printers will be shared using the <code>lpadmin</code> command and the <code>-o printer-is-shared=true</code> option.</p> 181*5e7646d2SAndroid Build Coastguard Worker 182*5e7646d2SAndroid Build Coastguard Worker <p>For example, to share two printers ("foo" and "bar") on the local network, run the following commands:</p> 183*5e7646d2SAndroid Build Coastguard Worker 184*5e7646d2SAndroid Build Coastguard Worker <pre class="command">cupsctl --share-printers 185*5e7646d2SAndroid Build Coastguard Workerlpadmin -p foo -o printer-is-shared=true 186*5e7646d2SAndroid Build Coastguard Workerlpadmin -p bar -o printer-is-shared=true</pre> 187*5e7646d2SAndroid Build Coastguard Worker 188*5e7646d2SAndroid Build Coastguard Worker 189*5e7646d2SAndroid Build Coastguard Worker <h2 class="title" id="CLASSES">Managing Classes</h2> 190*5e7646d2SAndroid Build Coastguard Worker 191*5e7646d2SAndroid Build Coastguard Worker <p>The <code>lpadmin</code> command is used to create, modify, or delete a class. The <code>-c</code> option specifies a class to create or modify and is combined with the <code>-p</code> option:</p> 192*5e7646d2SAndroid Build Coastguard Worker 193*5e7646d2SAndroid Build Coastguard Worker <pre class="command">lpadmin -p printername -c classname</pre> 194*5e7646d2SAndroid Build Coastguard Worker 195*5e7646d2SAndroid Build Coastguard Worker <p>The <code>-r</code> option specifies that the named printer is removed from the class:</p> 196*5e7646d2SAndroid Build Coastguard Worker 197*5e7646d2SAndroid Build Coastguard Worker <pre class="command">lpadmin -p printername -r classname</pre> 198*5e7646d2SAndroid Build Coastguard Worker 199*5e7646d2SAndroid Build Coastguard Worker <p>The <code>-x</code> option deletes the named class:</p> 200*5e7646d2SAndroid Build Coastguard Worker 201*5e7646d2SAndroid Build Coastguard Worker <pre class="command">lpadmin -x classname</pre> 202*5e7646d2SAndroid Build Coastguard Worker 203*5e7646d2SAndroid Build Coastguard Worker 204*5e7646d2SAndroid Build Coastguard Worker <h2 class="title" id="DEBUG">Debug Logging and Troubleshooting</h2> 205*5e7646d2SAndroid Build Coastguard Worker 206*5e7646d2SAndroid Build Coastguard Worker <p>The <a href="man-cupsd-logs.html">printing system log files</a> track the activity of the scheduler, printer drivers, and backends. If problems occur and the log files do not provide sufficient details to diagnose the problem, you can enable debug logging using the <code>cupsctl</code> command:</p> 207*5e7646d2SAndroid Build Coastguard Worker 208*5e7646d2SAndroid Build Coastguard Worker <pre class="command">cupsctl --debug-logging</pre> 209*5e7646d2SAndroid Build Coastguard Worker 210*5e7646d2SAndroid Build Coastguard Worker <p>To disable debug logging, run the same command with the <code>--no-debug-logging</code> option:</p> 211*5e7646d2SAndroid Build Coastguard Worker 212*5e7646d2SAndroid Build Coastguard Worker <pre class="command">cupsctl --no-debug-logging</pre> 213*5e7646d2SAndroid Build Coastguard Worker </body> 214*5e7646d2SAndroid Build Coastguard Worker</html> 215