Using lpadmin to Install Printers in macOS

Today we are going to look a bit at using lpadmin to install printers. If you are unfamiliar with lpadmin, I highly suggest running “man lpadmin” in Terminal and doing some reading. Either way, keep reading here as I will be covering it in-depth. Even if you use a different method to manage printers in your environment, it is good to be well-versed in this as it is easily scriptable. This means you will be able to whip up a solution in almost any scenario.

Here are some reasons lpadmin is a great option for installing printers in a managed environment:

  1. It allows the method of authentication to be named. This means Kerberos authentication can be named in the script. If you are using an app like NoMAD to generate Kerberos tickets for your domain, you will want to take advantage of this.
  2. It allows the local device driver to be named through a local path. There is a small downfall to this, in that it requires the driver to be present on the local machine at the correct path. There are a few ways you can handle this… If you want the script to go and get the respective printer driver at the time of installation, I suppose you could curl this down from a location of your choice any time you want. In the past, I have solved this by including all of the necessary printer drivers in the main image, and keeping them up to date on the local machines through various deployments. On the plus side, there are no generic drivers being used and the user doesn’t have to pick the driver. This ensures all printers are installed with the correct driver and will have all of the features available.
  3. It allows us to name the default options used when the printer is installed. Most commonly, color printers will install with color printing as the default, which almost always results in billing problems for end users when an app such as PaperCut is being used. Thus, we can name black and white, two-sided printing, or whatever we would like as the default options.
  4. It allows us to name the finisher, paper source, hole punch unit, etc. installed on the printer. No other installation method allows for this to be automated. Instead, users would have to install the printer, then navigate to System Preferences > Printers & Scanners > Select the Printer to Modify > Options & Supplies > Options and then select the correct options in the various drop-down menus (which no one likely knows, the names are pretty cryptic). Otherwise, users will not be able to use stapling or hole punching, folding, different paper trays, etc.

While all of these benefits are available to us when using a custom script, it requires some specialized knowledge and testing to get all of this right. It also requires that with every new printer or printer move on your printer fleet, the script needs to be modified and updated. Because of this, it requires a great deal of attention.

The Basic Printer Install Script

As stated earlier, the main delivery method for installing printers uses the lpadmin command in a shell script. This script can be copied and duplicated, and only the variables that need to be modified per printer need to be changed. Here is an example of the script:

/usr/sbin/lpadmin -p RicohC4501 -v smb://prntsrv/RicohC4501 -P /Library/Printers/PPDs/Contents/Resources/RICOH\ Aficio\ MP\ C4501 -o printer-is-shared=false -o auth-info-required=negotiate -o OptionTray=2Cassette -o Finisher=FinEUPHIMPOS -L Room200 -E

Note at first that we are using lpadmin for this script. All of the various flags here can be referenced in the lpadmin man page. I will break down the script below to explain how each flag operates in the script.

/usr/sbin/lpadmin

is just the full path to the lpadmin command (program).

-p RicohC4501

refers to the printer name. This can be called whatever you want it to be called. If your printer is on a domain, the name doesn’t need to match in order for this to work. However, just for lack of confusion and ease of configuration, it helps to keep this the same as the DNS name (which we will see in the next section). But if you wish for the name to display as something different in System Preferences, you can change it here.

-v smb://prntsrv/RicohC4501

specifies the URI at which the desired resource (or printer) can be found. If your printer fleet is managed via a Windows Server, you may need to use the SMB protocol (as seen in the sample script). Otherwise, you can connect directly via the LPD protocol with either a DNS name or the IP address (e.g. lpd://10.10.10.10). This all depends on how your respective environment is configured.

-P /Library/Printers/PPDs/Contents/Resources/RICOH\ Aficio\ MP\ C4501

specifies the local path to the driver file. You’ll want to make sure that whatever printer model you are installing is using the correct driver. Make sure to escape spaces in the name correctly. If unsure, just drag the driver into Terminal from its respective location and it will populate the properly escaped path.

-o printer-is-shared=false

Now starts the series of -o flags. These are option flags that can specify pretty much anything about the printer. This -o flag is universal for all printers, and specifies that printer sharing for this printer will not be enabled. You almost never want printers being shared on a network as a general rule, so this only makes sense to add as a standard option for each printer.

-o auth-info-required=negotiate

This flag specifies Kerberos as the authentication method. If you are using NoMAD along with domain-hosted printers, you are going to want to take advantage of this option. You can omit this entirely if not using Kerberos.

-o OptionTray=2Cassette -o Finisher=FinEUPHIMPOS

There are two different option flags here, and this is where it gets complicated. As you can see, these options are a bit cryptic and don’t mean much to anyone reading it. But the first flag specifies the paper trays available, and the second specifies the finisher type. These flags are written into the driver, and therefore can be specified in the script. Later in this article I will explain how to extract these various options from the driver for use in a script.

-L Room200

specifies the location of the printer. If your printer fleet is hosted on a domain, this information may already be available (you’ll have to copy the respective data into each script though). Like the printer name above, it doesn’t have to match anything… but for sake of consistency, it would be smart to match whatever your domain specifies.

This just enables the printer once it has been installed. Pretty basic but also very necessary.

So that explains each component of the basic script. You should now be able to take that script and modify any components necessary in order to install a printer from your fleet.

Discovering Options for a Printer

This gets relatively complicated.

Each driver file for every printer comes with various option flags that are specific to that model printer (or sometimes vendor). It is nearly impossible to figure out these flags by simply scanning through the source code of the driver, so there are a few tricks you can use to decipher them. Below, I will walk through how to find particular options for a Konica Minolta C452 printer as an example.

Just as a fallback, here is the install script for this printer:

/usr/sbin/lpadmin -p KonicaMinolta452 -v smb://prntsrv/KonicaMinolta452 -P /Library/Printers/PPDs/Contents/Resources/KONICAMINOLTAC452.GZ -o printer-is-shared=false -o auth-info-required=negotiate -o ColorModel=Gray -o SelectColor=Grayscale -o Finisher=FS527JS -o KMPunchUnit=PK517-23 -L Room200 -E

The goal here is to install the printer first without any hardware or default options, then manually add in the desired options, and finally to query the differences between the modified driver of the installed printer vs. the original unmodified driver in /Library/Printers/PPDs to find any differences between them.

First, let’s install the printer with a command that has no options specified.

/usr/sbin/lpadmin -p KonicaMinolta452 -v smb://prntsrv/KonicaMinolta452 -P /Library/Printers/PPDs/Contents/Resources/KONICAMINOLTAC452.GZ -L Room200 -E

After the printer is installed, we need to modify the default options for the printer in order to determine the correct option flags for the script. We can start with the hardware options.

If your printers are hosted on a domain, the finisher, hole punch, etc. information can usually be found by installing the printer on a PC. Once the printer is installed, check the printer properties to see if the information is there. If a universal driver is being used, there may be no information present, or the information may be incorrect. The only way to find the information at this point would be to check the original purchase order, or to open the printer up and see if units are labeled. Once the hardware options have been determined, they need to be entered on the Mac. First, navigate to System Preferences > Printers & Scanners > KonicaMinolta452 > Options & Supplies. Modify the drop-down menus according to the hardware information found for the printer:

After modifying the hardware options for the printer, we need to modify the default settings such as color options, two-sided printing, etc. in CUPS (Common Unix Printing System). You can access CUPS by opening a web browser and entering localhost:631 in the address field. If the local CUPS server has never been accessed on your machine, you may need to run

cupsctl WebInterface=yes

to enable it. Once you are in, navigate to Administration > Manage Printers > KonicaMinolta452 > Set Default Options > Finishing Options. There are many, many options here that can be modified, but we are most interested in the color options, which are here:

You can see two select color categories, and those have been modified to Gray Scale. Once your desired settings have been modified, scroll to the bottom and select Set Default Options.

Now we can use the printer diff command to determine the option codes to use in a script. I found the script here, props to this guy brunerd for writing it!

You can navigate to the same driver we specified in the original install command and drag it into the terminal window:

Upon hitting enter, you’ll be asked to provide a driver from /etc/cups/ppd:

Navigate to Finder > Menu Bar > Go > Go to Folder > /etc/cups/ppd and drag in the driver for the 452 (mine has a different name in this instance, just ignore it):

Hit enter, and you will see the differences listed for you:

The options are as follows:

-o ColorModel=Gray -o SelectColor=Grayscale -o Finisher=FS527JS -o KMPunchUnit=PK517-23

You should now be able to see that those are the very options used in the original install script mentioned at the beginning of this section.

You’ll notice there are two other option flags present above that weren’t outputted by the diff command:

-o printer-is-shared=false -o auth-info-required=negotiate

These flags are able to be used for every printer, regardless of brand or model, because they are flags CUPS and macOS recognize, not the specific driver.

-o printer-is-shared=false

flag modifies whether printer sharing is turned on or not for the printer. This can be seen in the GUI at System Preferences > Printers & Scanners.

This of course will be overridden if Printer Sharing is turned off at System Preferences > Sharing. By default, we do not want printers to be shared. This option is named in the man page for lpadmin.

The other option flag,

-o auth-info-required=negotiate

is to enable kerberos authentication for each printer. If you are managing domain printers, then you want to make sure that a kerberos ticket is used for authentication and not the user’s login keychain. Otherwise, if you are connecting directly to the printer, omit this flag.

Finally, there is another way to list out all of the options for a particular printer, although the names of the options are so cryptic that it isn’t necessarily helpful. But there may be an occasion to use this. Entering

lpoptions -l name_of_printer_here

will list all of the possible driver option flags available for that particular printer:

As you can see it is just a giant list of a bunch of flags, and it is hard to discern what is what. But it could be useful to query a bunch of options at once.

Once you have all of the various options of the printer, you can compile all of them into separate -o flags and incorporate them into your script.

And that’s it! Super easy, right? Don’t get discouraged, this took quite a bit of time and effort on my part to get down. Keep at it until you can write lpadmin scripts from scratch that configure a printer successfully! It is a good tool to have, especially when printers won’t install via tools from an MDM or a printer manufacturer.