Query and Change CUPS Settings with cupsctl

One wrong cupsctl flag can throw a busy print server open to the whole network, so treat every change as a small, reversible experiment. You will read the current settings, change exactly one of them, verify it, and put it back if it was only a test. The examples use cupsctl from the Debian/Ubuntu cups-client package, version 2.4.7-1.2ubuntu7.14. Allow about ten minutes, plus a maintenance window if the scheduler serves other people.

• You need: a shell, a running CUPS scheduler, and permission to administer it.
• Reading is cheap: checking settings is normally an ordinary user operation.
• Changing is not: it may need authentication or elevated privileges, depending on the server's policy.
• This does not replace: a careful read of cupsd.conf when the change matters.

1. Check the installed command and scheduler

Confirm the binary and package version before trusting any example, including this one. This step is read-only:

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

Now ask the local scheduler for its current settings:

$ cupsctl
name=value
name=value

The real output has one setting per line. If you see Unable to connect to server, stop here: check the CUPS service and its logs through your normal service-management procedure. Do not start changing client options to paper over a server outage.

2. Record the setting before you touch it

Use a narrow query when you only need one value. The names printed by cupsctl carry an underscore prefix, so match the full name rather than a loose word search:

$ cupsctl | grep '^_share_printers='

For debug logging, the equivalent check is:

$ cupsctl | grep '^_debug_logging='

Save the returned name=value line in your change notes. If the command prints nothing, do not assume the value is safely off: query the full output, confirm the scheduler you selected, and check its access policy first.

3. Make one focused change

The boolean switches this version supports are explicit. Use the --no- form to disable a feature, and change one setting at a time.

• Stop advertising printers to other computers on the network.

  $ cupsctl --no-share-printers

• Turn sharing back on once the maintenance is done.

  $ cupsctl --share-printers

A successful command may print nothing at all. Verify with the same query you ran before:

$ cupsctl | grep '^_share_printers='

Do not reach for sudo by reflex. If the server rejects the change because authentication is required, run the operation with the privilege your local policy expects, or authenticate as a named administrator. A typical local retry looks like:

$ sudo cupsctl --no-share-printers

That command changes server state. Read the target host and the option back to yourself before you press Enter, especially on a production print server.

4. Treat debug logging as a temporary diagnostic

Debug logging helps investigate a scheduler problem, but it writes far more detail to the CUPS error_log. Turn it on for the shortest useful window:

$ cupsctl --debug-logging
$ cupsctl | grep '^_debug_logging='
_debug_logging=1

Reproduce the problem, collect the log entries through your normal incident process, then turn it back off:

$ cupsctl --no-debug-logging
$ cupsctl | grep '^_debug_logging='
_debug_logging=0

The exact output can differ if another administrator changes the scheduler between your commands. Do not leave debug logging enabled longer than you need it: it inflates log volume and can capture more operational detail than a routine service warrants.

5. Treat remote access options as a security boundary

If a documented maintenance task genuinely needs remote administration, capture the original values first, make the smallest change, test it from the approved network, then switch it off again:

$ cupsctl | grep -E '^_(remote_admin|remote_any)='
$ cupsctl --remote-admin
$ cupsctl | grep '^_remote_admin='
$ cupsctl --no-remote-admin

Do not turn on --remote-any as a shortcut around a printer-discovery problem you have not diagnosed. Look at routing, firewall policy, name resolution and the intended CUPS sharing model instead. To undo it after an emergency test:

$ cupsctl --no-remote-any

6. Point at another server carefully

The -h option selects a server and optional port, and it must come before every other option:

$ cupsctl -h print-server.example:631
$ cupsctl -h print-server.example:631 --no-share-printers

Replace print-server.example:631 with a hostname and port you have actually confirmed. The first command only queries; the second changes the remote scheduler. If the connection needs encryption, add -E after the server option:

$ cupsctl -h print-server.example:631 -E

-U USERNAME picks an alternate username for authentication; it does not by itself grant that account any permission. Never put a password in the command line, the shell history, or a write-up like this one.

Common traps

The --user-cancel-any option also moves an authorisation boundary: it lets users cancel jobs owned by somebody else. Turn it on only when that policy is deliberate, and reverse it with --no-user-cancel-any if it was ever meant to be temporary.