Configure a CUPS Client with client.conf

Get client.conf wrong and CUPS clients quietly talk to the wrong server, or trust a certificate they should reject. This guide points clients at a chosen server, requires encryption, and checks the settings actually took. The examples use cups-client 2.4.7-1.2ubuntu7.14, installed on this machine.

1. Check the installed client and choose the scope

Confirm which package and command you are using. These are ordinary, read-only commands:

$ dpkg-query -W -f='${Package} ${Version}\n' cups-client
cups-client 2.4.7-1.2ubuntu7.14
$ command -v lpstat
/usr/bin/lpstat

Checkpoint: write down the exact server name you intend to use, for example print-server.example.com. Do not substitute a guessed name and then weaken certificate checks to make the connection work.

2. Back up an existing system file

Editing /etc/cups/client.conf requires elevated privileges. Before changing an existing file, make a dated copy:

$ sudo cp -p /etc/cups/client.conf "/etc/cups/client.conf.bak.$(date +%Y%m%d-%H%M%S)"

If the file does not exist, skip this step. The copy is a recovery point, not a substitute for checking the new configuration. Do not overwrite the backup blindly if you are working through several changes.

3. Add a small, explicit configuration

Open the relevant file in an editor. Use the system path for a shared setting:

$ sudoedit /etc/cups/client.conf

For one user's setting, create the directory and edit the file without sudo:

$ mkdir -p "$HOME/.cups"
$ chmod 700 "$HOME/.cups"
$ editor "$HOME/.cups/client.conf"

Start with this configuration, replacing the server placeholder with the real hostname or address:

# Send CUPS client requests to this server.
ServerName print-server.example.com:631

# Refuse a connection unless encryption is used.
Encryption Required

# Require the certificate name to match the server hostname.
ValidateCerts Yes

# Do not accept expired certificates or unknown certificates by default.
AllowExpiredCerts No
TrustOnFirstUse No

Each non-blank line is a directive. Lines beginning with # are comments. The port is optional for ServerName; including :631 makes the intended endpoint visible during review. A Unix-domain socket path is also accepted, but do not put a socket path in a hostname example.

The installed manual lists AllowAnyRoot as defaulting to Yes, TrustOnFirstUse as defaulting to Yes, and ValidateCerts as defaulting to No. The explicit values above make the security decision visible and avoid silently trusting a new or mismatched certificate. They may expose an existing certificate or trust-store problem: do not fix that by turning all checks off.

4. Verify that clients use the destination

Start a new shell command after saving the file. lpstat -r is unprivileged and asks the configured CUPS server about its scheduler:

$ lpstat -r
% scheduler status from print-server.example.com, or a connection error

The exact success text depends on the server and locale. A response such as scheduler is running shows that the client reached a scheduler. A name-resolution, connection, TLS, or certificate error is useful evidence that the endpoint or trust configuration needs attention.

For a second read-only check, list destinations:

$ lpstat -p -d
% printers and the default destination reported by the configured server

Output is host-specific, so do not treat an empty printer list as a syntax failure. To isolate the network path from client.conf, you can pass an explicit host with -h, but that tests the command-line override rather than the file:

$ lpstat -h print-server.example.com:631 -r

Compare the result with the file-driven command. If the explicit-host command works but the file-driven command does not, inspect the path, spelling, permissions, and the selected per-user versus system file.

5. Set authentication and request details only when needed

User name sets the default user name for requests. Add it only when the server's authentication arrangement requires a fixed identity:

User print-operator

This does not provide a password and does not grant permission on the server. Authentication prompts and server-side authorisation still apply. GSSServiceName changes the Kerberos service name, whose default is http; use it only when the Kerberos administrator has specified a different service such as host or ipp.

Leave SSLOptions alone unless you have a documented compatibility requirement. It is read only from /etc/cups/client.conf. Options such as AllowRC4 and AllowSSL3 reduce security, while minimum and maximum TLS options restrict protocol versions. The safer direction is to remove obsolete compatibility exceptions, not to add them as a first troubleshooting step.

6. Recover from a bad change

Recovery: if the new file prevents the client from connecting, first check which scope you changed. A per-user file can be moved aside without elevated privileges:

$ mv "$HOME/.cups/client.conf" "$HOME/.cups/client.conf.disabled"
$ lpstat -r

For the system file, restore the backup you made in step 2, or remove the file only if it was newly created and you have confirmed that no other administrator relies on it:

$ sudo cp -p /etc/cups/client.conf.bak.YYYYMMDD-HHMMSS /etc/cups/client.conf
$ lpstat -r

Replace the backup name with the exact file on your machine. Restoring a backup changes the active client configuration, so review the source and destination before pressing Enter. CUPS client settings are read by new client processes; you normally do not need to restart a print service for this file-only change.

Done means