Best practices for configuring printers on CUPS systems (macOS, Linux)

“What’s the best way to configure printers on my CUPS print server or device to get the most out of PaperCut?” CUPS is the printing system used by macOS and virtually all UNIX variants. You might be accustomed to using the macOS Printers & Scanners section in System Settings to add and remove printers to a macOS machine, but under the hood macOS actually uses CUPS. On a Linux installation that has no graphical user interface CUPS can be used to manage printers from a remote machine too. CUPS runs a web server that can accept and deliver jobs, as well as offering an administration console called the CUPS Web Interface. In order to make sure PaperCut products and features operate as expected on these types of machines, learning to use the CUPS Web Interface is important, as there are many common tasks that are actually only possible to do in this interface. The intention of this guide is to show you how to use the CUPS Web Interface to perform common tasks, as well as to explain what certain options and settings mean. We’ll also impart some best practices when setting up printers, and show you where files related to your printers are stored in the operating system. Accessing the CUPS Web Interface and basic administration Adding a new printer using the CUPS Web Interface Modifying/administering an existing printer using the CUPS Web Interface Resetting CUPS and removing drivers Accessing the CUPS Web Interface and basic administration CUPS runs a web interface on port 631 on every machine where it is installed. macOS comes with CUPS pre-installed, but you might need to install it manually on a UNIX variant, depending on what you’re using. To install CUPS on a UNIX variant you’ll need to consult the documentation for the particular operating system you’re using. NOTEIf you're using Debian/Ubuntu you will likely need to ensure that the cups-bsd package is installed, particularly if you're using Web Print or Mobility Print on the machine, as these features require options that are only present in this package.To do this, you can run the following command: sudo apt install cups-bsd To access the CUPS Web Interface, typically you would open a browser on the machine you intend to administer and navigate to the following page (we’re using localhost here because the web server is running on the machine we’re logged into): http://localhost:631 If the page does not resolve or load, usually you can get things going again by forcing CUPS to restart. To do that… On a macOS device, open Terminal and run sudo launchctl stop org.cups.cupsd On a UNIX device, run either sudo /etc/init.d/cupsys restart or sudo /etc/init.d/cups restart These commands will likely require you to enter the password associated with the admin account you’re logged into the operating system as. Try to navigate to the page again and you should see something similar to this: The three main tabs you should be familair with are the Administration, Printers, and Jobs tabs. If you try to click on any of these tabs right now, you may encounter this message: If not, you’re good to go, but if you do see this message you simply need to enable the interface by running the command displayed on that page in Terminal or equivalent: cupsctl WebInterface=yes When you return to the web interface and refresh, you should be able to continue… Administration The most important aspects of the Administration tab are the Printers and Server sections. In the Printers section, the Add Printer button is how a printer object can be added to the system . The Manage Printers button simply redirects to the Printers tab to administer existing printers . In the Server section there are a number of important, global settings for CUPS. The four most important settings here are: Share printers connected to this system - This controls whether other machines on the network can submit print jobs to printers hosted on this machine. On a macOS device, this is coupled to System Settings > General > Sharing > Printer Sharing in the operating system UI, and also enables mDNS/Bonjour broadcasting of these printers on the same subnet (there is no way to share printers without enabling mDNS/Bonjour on macOS, unfortunately). It’s also worth pointing out that whether or not this is enabled has no bearing on how Mobility Print functions in any of the available discovery modes. Allow printing from the internet - This is an extension of the above setting, and controls whether or not jobs that originate from outside the subnet this machine is connected to should be allowed or denied. As before though, it’s worth noting that whether or not this is enabled has no bearing on how Mobility Print functions in any of the available discovery modes. Allow remote administration - This controls whether this web interface should be accessible from other machines on your network; typically this should be left disabled, but if you do enable it most actions will still require you to authenticate with credentials of a user who exists on the machine we’re accessing. Save debugging information for troubleshooting - This is another way to enable debug logging in CUPS. If you make any changes to these settings, you must click the Change Settings button to apply them, which will also restart CUPS. Jobs This is where you can manage active print jobs, as well as view the status of active and past jobs. Whereas the operating system UI might only let you see jobs that are currently printing in any given print queue, or those that are paused, this view will let you see the details of past jobs by clicking Show Completed Jobs or even Show All Jobs. Printers This is where you can see all of your configured printers, and access printer specific settings by clicking on each. Adding a new printer using the CUPS Web Interface Adding a printer through the operating system UI is definitely possible, but for the widest array of options and configurable settings, and to ensure the printer works with PaperCut, using the CUPS Web Interface is your best bet. It’s worth noting that virtually everything you can do in the CUPS Web Interface can also be done using the command-line, but for the sake of usability, we’re going to be go with the web interface exclusively. NOTEThe instructions below are intended to be used...On a print server where you intend to host print queues, or...On a Print Deploy reference machine that you intend to clone printers from, or...When configuring the use of a manufacturer driver with PaperCut Pocket/Hive, or...On an end-user machine where you intend to install direct printers, running the PaperCut NG/MF Direct Print Monitor without using Print Deploy, or...On an end-user machine where you intend to add connections to printers hosted on a server, without using Print Deploy. WARNINGOn macOS devices, it is tempting to simply discover the printer on your network using Printers & Scanners and have macOS configure everything automatically by communicating with the printer over IPP/S. This should be avoided though, because printers created this way will be incompatible with many PaperCut products and features.For example, Print Deploy will be unable to deploy printers created this way if you clone them, and PaperCut Pocket/Hive will be unable to use a manufacturer driver from such a printer either. The Print Provider and Direct Print Monitor in PaperCut NG/MF are also unlikely to be able to correctly track and control print jobs submitted to a printer setup this way, let alone apply spool file modifications to support features such as filters and restrictions. For those who have more of a technical understanding of CUPS, we do not yet support IPP Everywhere. Login to the CUPS Web Interface and navigate to the Administration tab. Under the Printers section, click Add Printer. The first piece of information you’ll need to supply is what protocol you want to use to make the connection to the printer: If this is a print server, or an end-user/reference machine where you’re trying to configure direct connections to the printers, the reccommended protocol to use here is AppSocket/HP JetDirect. This is the CUPS equivalent of using a Standard TCP/IP Port Windows, and uses port 9100 to submit a job to the printer. It is the fastest and most reliable printing protocol that exists on these systems, though CUPS uses IPP/S natively. If this is an end-user/reference machine where you’re trying to configure a connection to a print queue hosted on a Windows server, you can use this guide instead. If this is an end-user machine where you’re trying to configure a connection to a print queue hosted on a CUPS print server, use the Internet Printing Protocol (ipps) or Internet Printing Protocol (ipp). If this isn’t a real printer, and you’re setting up a virtual queue for use with PaperCut NG/MF, you can use this guide to create a null port printer. For the purposes of this guide we’ll be using AppSocket/HP JetDirect. When you’ve selected a protocol you can click Continue. The next screen requires you to enter the Connection string to the printer, and there are examples provided for different protocol types (and in the other articles linked above when using SMB or LPD, or a null port). The IP address of the printer in this example is 10.10.10.10, so the connection string will be socket://10.10.10.10 (though you can use the hostname/FQDN of your printer instead): The next screen requires to to enter a Name for the printer, with an option to also set a Description, Location, and whether the printer should be shared (Share This Printer). The Name is the string which uniquely identifies the printer in CUPS, whereas the Description is typically what the operating system UI would display to a user. IMPORTANTAthough the Description field can contain spaces, when using any PaperCut products and features it is very important that both of these fields are an exact match, and that they only contain alphanumeric characters. That means you should avoid using spaces, underscores, dashes, or any other special characters.It might be tempting to use spaces/underscores/dashes in the Description field but it will almost invariably cause a problem somewhere down the line. What's more, when you rename a printer in the macOS UI for example, only the Description field value is changed; the actual Name of a printer can never be changed once it is created, and so renaming printers is typically dangerous and can cause unintended consequences when using PaperCut. The Location field should again probably only contain alphanumeric characters, and is intended to describe to the user where the printer is physically located. Sharing should typically be left off, unless this is a print server where client machines need to submit jobs over IPP/S or LPD, or if you’re happy for client to discover printers using the native macOS printer sharing functionality which uses mDNS/Bonjour to broadcast printer advertisements across the network. Again, this setting has no bearing on how Mobility Print functions in any of the available discovery modes. Once you’ve filled these fields out, you can click Continue: The next screen will ask you to select a Make and then a Model for your printer. What CUPS means by this is the Manufacturer and the Driver Name. This is where the print driver is actually set. Print drivers on macOS and UNIX variants can typically be downloaded from the manufacturers website. On macOS, you may run a .dmg file to install the driver, and the related files will be mostly contained within the /Library/Printers directory. Once installed, you should be able to select the manufacturers name from the list in the Make field, and then click Continue: You will then be prompted for the Model and this is where the driver that is relevant for your particular printer can be selected. In this example we are using the Generic PostScript Printer driver that is bundled with macOS. On some UNIX variants, depending on the driver, you may need to select Choose File instead, and manually navigate to the PPD you have downloaded. When you’re ready, you can click Add Printer to create the printer object, which can then be administered from the Printers tab mentioned above: If this device is running the Print Provider or Direct Print Monitor (without Print Deploy), we should pickup and begin tracking this new printer immediately. If we don’t register the printer immediately, it’s worth submitting a test page to it, restarting CUPS using the commands listed above, and then potentially also restarting the Print Provider. This page also details how to manually control which printers are tracked. Modifying/administering an existing printer using the CUPS Web Interface There are a number of reasons why you might need to modify an existing printer on a device running CUPS. Depending on your operating system, many configurable options may be completely hidden in the operating system UI. For example, changing a driver on macOS without deleting and recreating the printer from scratch is only possible when interfacing with CUPS directly. NOTEThe instructions below are intended to be used to...Change the driver in use on a particular printer, such as when cloning a Mobility Print queue with Print Deploy or configuring the use of a manufacturer driver with PaperCut Pocket/Hive, or to...Set the printing defaults and options on a particular printer, such as when cloning print queues with Print Deploy or configuring the use of a manufacturer driver with PaperCut Pocket/Hive, or to...Change the address or protocol of a particular printer, potentially as the result of an IP change, or to...Change the Location field of a particular printer, or to...Change the sharing status of a particular printer, or to...Make a printer the default on the machine, or to...Delete a printer. Login to the CUPS Web Interface and navigate to the Printers tab. Click on the Queue Name of the printer you want to modify: On the next screen you can see details about the printer and jobs submitted to it: There are also two drop-down fields; the Maintenance and the Administration menus. The most important options in the Maintenance menu are the Print Test Page, Pause Printer, and Cancel All Jobs items, which are self-explanatory: The most important options in the Administration menu are the Modify Printer, Set Default Options, Delete Printer, and Set As Server Default items which will be explained below: Modify Printer This option in the Administration menu will let you run through the same series of options that you ran through if you initially created the printer using the web interface (though you will not be able to change the Name, and you should almost never adjust the Description either). This is the option we need to select if we want to change the driver, address, protocol or Location field of this printer. The first screen will show you the connection/protocol details again. If you don’t need to change the address or protocol you can leave the radial option for Current Connection selected and click Continue. Otherwise it is best practice to copy the existing connection string from the Current Connection line and then click another of the radial options before clicking Continue: If you opted to change the option before continuing, you can now edit the connection string of the printer. If you copied it from the previous screen you can now paste it back here and modify just the portion you need before clicking Continue once more: The next screen will let you change the Description, Location, and whether the printer should be shared (Share This Printer): IMPORTANTAthough the Description field can contain spaces, when using any PaperCut products and features it is very important that both the Name and Description fields are an exact match, and that they only contain alphanumeric characters. That means you should avoid using spaces, underscores, dashes, or any other special characters.It might be tempting to use spaces/underscores/dashes in the Description field but it will almost invariably cause a problem somewhere down the line. What's more, when you rename a printer in the macOS UI for example, only the Description field value is changed; the actual Name of a printer can never be changed once it is created, and so renaming printers is typically dangerous and can cause unintended consequences when using PaperCut. The Location field should again probably only contain alphanumeric characters, and is intended to describe to the user where the printer is physically located. Sharing should typically be left off, unless this is a print server where client machines need to submit jobs over IPP/S or LPD, or if you’re happy for client to discover printers using the native macOS printer sharing functionality which uses mDNS/Bonjour to broadcast printer advertisements across the network. Once you’ve changed the fields you need to, or if you have no changes to make, you can then click Continue. The next screen will let you change the driver in use on the printer. If you want to keep the driver as-is, you can click Modify Printer to complete the process, but if you do need to change the driver you’ll need to click Select Another Make/Manufacturer: What CUPS means by Make and Model is the Manufacturer and the Driver Name. Print drivers on macOS and UNIX variants can typically be downloaded from the manufacturers website. On macOS, you may run a .dmg file to install the driver, and the related files will be mostly contained within the /Library/Printers directory. Once installed, you should be able to select the manufacturers name from the list in the Make field, and then click Continue: You will then be prompted for the Model and this is where the driver that is relevant for your particular printer can be selected. In this example we are using the Generic PostScript Printer driver that is bundled with macOS. On some UNIX variants, depending on the driver, you may need to select Choose File instead, and manually navigate to the PPD you have downloaded: When you’re ready, you can click Modify Printer to commit your changes to the printer object: Set Default Options This option in the Administration menu will let you change the printing defaults and options of this printer. You can click around the blue headings and change settings you make by clicking Set Default Options: Set As Server Default This option in the Administration menu will let you set this printer as the default for the machine: Delete Printer This option in the Administration menu will let you delete this printer, but please remember that the associated driver well be left intact: Resetting CUPS and removing drivers In some circumstances it can be useful to delete all printers on a CUPS device, and return CUPS to its default stare. On a macOS device, in Printers & Scanners you can do this by right-clicking on an existing printer and selecting Reset Printing System… : In order to remove driver files from a macOS device, you can use Finder to navigate to /Library/Printers using the Go to Folder… option in the Go menu. In this directory you will typically find each manufacturer has encapsulated their driver files into a folder. Because there are rarely formal uninstallers on these devices, removing the driver can often only be achieved by deleting the files from this direcrory, but it’s worth noting that other, related files might still exist elsewhere throughout the operating system. Still have questions? Let us know! Feel free to leave a comment below if you have any questions at all.