2019/09/04

Adding a reverse proxy for the CUPS web ui in nginx is a little harder than just passing all its requests to port 631. In fact, if you require authentication, it is simply impossible. Still, if you run CUPS locally and do not require authentication, you can follow these instructions to put CUPS behind a reverse proxy with nginx.

Prerequisites

• an installation of CUPS
• an installation of nginx
• no need to authenticate actions in the CUPS web ui

Setting up the reverse proxy

In your preferred server block, add the following location block. I will go over the most important lines to explain why they are included.

location ~ /cups/(.*) {
    proxy_pass https://127.0.0.1:631/$1;

    proxy_http_version 1.1;
    proxy_set_header Accept-Encoding "";
    proxy_set_header Upgrade $http_upgrade;
    proxy_set_header Connection 'upgrade';
    proxy_set_header Host '127.0.0.1';
    proxy_cache_bypass $http_upgrade;

    proxy_set_header X-Real-IP $remote_addr;

    sub_filter ' href="/' ' href="/cups/';
    sub_filter ' action="/' ' action="/cups/';
    sub_filter ' src="/' ' src="/cups/';
    sub_filter_types *;
    sub_filter_once off;

• proxy_pass is just a normal reverse proxy entry. In the location block, I have defined a capture group which is reused to forward the pathname to CUPS.
• proxy_set_header Host is explicitly set to localhost because I have set CUPS to only allow localhost requests. In practice, this means all requests to CUPS are forced to go through the reverse proxy.
• sub_filter entries have been added because CUPS actually hardcodes some paths in the DOM to the webroot! This means that the browser will try to redirect you to, for example, /admin/ instead of /cups/admin, effectively reversing our reverse proxy. Unfortunately some redirects still point to the webroot, but this does not affect the functionality of the web UI.

If you restart your nginx service and try to visit the address to which CUPS is bound, you will notice some pages fail to load or load infinitely. This is caused by CUPS failing to authenticate you with the service. As far as I know, there is no way to proxy its authentication through nginx, so I have decided to completely remove the authentication from the web ui. I have personally always found the authentication to be a nuisance, but if you require it, this solution is not for you.

Disable CUPS authentication

In your CUPS configuration file, search for the line DefaultAuthType Basic and change the Basic value to None. This will change the authentication type to none for all of the locations in the configuration file. In addition to this, remove any lines which start with Require user.

If you restart your CUPS service, your reverse-proxied CUPS web ui should function as intended.