Proxying CUPS IPP using nginx

Written by Rob Peck · 5 minute read

So I have this older Dell laser printer, a B1160w. It was released back in 2012, but it is a totally fine home printer for when I occasionally need to print something and it still works great after all these years, so I see no compelling reason to buy a new one.

But there’s a problem: macOS support. Namely, no drivers have been released for macOS since 2017. Starting with Catalina, Apple started requiring code signing for executables, and the official Dell driver has an executable in it that refuses to execute because it isn’t signed. And despite my best efforts, short of turning off Gatekeeper entirely, I was not able to get it to work.

But the printer itself is fine; there is absolutely no reason to create additional electronic waste purely for software reasons. But thanks to open-source software, we have another options: CUPS.

Configuring the CUPS and the Printer

Being that I am moving a lot of things to Docker, I decided to run a CUPS Docker image on one of my servers. Configuring the Dell printer was very straightforward, as the Linux driver is still available. Setting it up in macOS was a bit of a challenge mostly because the GUI for adding network CUPS printers is very obtuse (especially when you consider that macOS is using CUPS beneath the GUI). Basically the settings for a CUPS printer are as follows:

• IP Printer (tab at top)
• Address: the IP address of your CUPS server
• Protocol: IPP
• Queue: “printers/” + the printer name in CUPS

The last item was what tripped me up. It is absolutely not clear anywhere that you had to prepend “printers/” to the name. I only stumbled on it through trial and error.

So now you should be able to print a file and everything works great! Except that I hate hard-coding IP addresses. I would much rather use something like “printers.internal.domain” instead. But if you try that, you’ll quickly notice that pretty much everything breaks. And this is because of some security settings in CUPS.

Proxying Requests

CUPS config looks a lot like Apache, so if you are familiar with Apache configs the format should be familiar. Notably, there is a ServerAlias setting that needs to be set if you are going to use hostnames. Otherwise it will answer with either Bad Request or ask for authentication. And because I am using a Docker image, adding this setting to the image requires one of a couple different approaches.

1. You could just store the entire cupsd.conf file outside and mount it as a volume into the image. This is perhaps the easiest, but the problem is that if the image changes in the future, your config might be out of date.

2. You could create your own Docker image based on the CUPS image, which would be a simple 2-line file that FROM‘d the CUPS image and then ran cupsctl ServerAlias=*. The downside is that you now have to maintain this image instead of just pulling the most recent from Docker Hub.

I decided to take a third approach: I decided to use nginx, my Swiss Army knife, to proxy the requests to CUPS. And best of all: because IPP is just HTTP with some additions, nginx is perfectly capable of handling this as well!

I used Docker Compose to configure the image as follows:

version: '3'
services:
  cups:
    container_name: cupsd
    image: olbat/cupsd
    volumes:
      - /var/run/dbus:/var/run/dbus
      - /var/lib/cupsd/printers.conf:/etc/cups/printers.conf
      - /var/lib/cupsd/ppd:/etc/cups/ppd
    ports:
      - "127.0.0.1:6631:631"

Note that I am mapping port 6631 to 631 inside the container. That is the IPP port that also answers to web requests as well.

With that, we can use the following nginx config:

server {
    listen 80;
    listen 631;
    server_name printers.internal.domain;

    location / {
        proxy_pass http://localhost:6631/;
        proxy_set_header Host "127.0.0.1";
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forward-For $proxy_add_x_forwarded_for;
    }
}

A couple of things to note here. First, we are listening on both 80, the standard HTTP port, and 631, the IPP port. And we are proxying both of them to port 6631 - the container’s IP port. We are also setting the Host header to localhost to fool the CUPS into thinking that it is a local request and allowing it through.

With this in place, you can add a printer using the method above, but using your domain name instead, and it all works great! And, you can access the CUPS web interface using printers.internal.domain without having to use the port.

• CUPS
• Mac
• macOS
• nginx
• Printers