Complete Guide to CUPS: Configuration, Usage, and Troubleshooting on Linux

Posted on by BlockmyIP | Category: Programas Linux

Introduction

In the Linux world, printer management can seem like a simple task until you need to share devices on a network, configure advanced options, or troubleshoot printing errors. This is where the Common Unix Printing System (CUPS) comes in, the de facto standard for handling print queues, drivers, and protocols on virtually all modern distributions. This article will guide you step‑by‑step from installation to advanced administration, offering practical examples and troubleshooting tips so you can keep your printing environment running without interruptions.

What is CUPS?

CUPS, an acronym for Common Unix Printing System, was initially developed by Apple and released under the GPL license. It acts as a print server that receives print jobs from client applications, processes them through filters, and sends them to the appropriate printer using protocols such as IPP (Internet Printing Protocol), LPD, or SMB. Its modular architecture allows adding new drivers, filters, and backends without modifying the core system, making it extremely flexible both in desktop environments and in corporate print servers.

Installation on major distributions

On most Debian‑based distributions, the package is installed with:

  • sudo apt update
  • sudo apt install cups

On RHEL, Fedora, or CentOS‑based systems, the equivalent command is:

  • sudo dnf install cups (Fedora)
  • sudo yum install cups (RHEL/CentOS)

After installation, the service starts automatically, but you can verify and enable it for boot with:

  • sudo systemctl status cups
  • sudo systemctl enable --now cups

If you prefer a graphical interface, many desktop environments include tools such as system-config-printer or the GNOME/KDE printer settings, which simply act as frontends for CUPS.

Basic configuration

The main CUPS configuration file is located at /etc/cups/cupsd.conf. Here you can define the listening port (default 631), access directives, and the logging level. A typical example to allow access from the local network is:

# Listen on all interfaces
Port 631
# Allow access from the 192.168.1.0/24 subnet

  Order allow,deny
  Allow 192.168.1.0/24

After editing the file, restart the service:

  • sudo systemctl restart cups

To add a printer, you can use the web interface (see next section) or the lpadmin command. For example, to add an automatically detected USB printer:

  • sudo lpadmin -p Impresora_USB -E -v usb://HP/Deskjet?serial=ABC123 -m everywhere

The -E flag enables the printer and accepts jobs, while -m everywhere tells CUPS to use the recommended generic driver.

Administration via web interface

CUPS includes an administration interface accessible via a browser at http://localhost:631. From there you can:

  • View the status of print queues.
  • Add, modify, or delete printers.
  • Configure specific options such as resolution, paper type, and duplex.
  • Review the job log and perform actions like pausing, resuming, or canceling jobs.
  • Manage users and permissions via the Administration tab.

To access the administration section you must authenticate with a user belonging to the lpadmin group or with the root account. You can add your user to the group with:

  • sudo usermod -aG lpadmin $USER
  • newgrp lpadmin (or log out and back in)

The web interface also allows loading custom PPD (PostScript Printer Description) files, which is useful when you have a specific driver provided by the manufacturer.

Command‑line usage

Besides the graphical interface, CUPS offers a set of CLI tools ideal for scripts and remote administration. The most used commands are:

  • lpstat -p: lists all configured printers and their status.
  • lpstat -a: shows printers accepting jobs.
  • lp -d Impresora_USB archivo.pdf: sends a job to the specified printer.
  • cancel -a: cancels all pending jobs.
  • cupsaccept Impresora_USB: allows the printer to accept new jobs.
  • cupsreject Impresora_USB: rejects new jobs (useful for maintenance).

To view the detailed service log, you can consult:

  • journalctl -u cups
  • tail -f /var/log/cups/error_log

These logs are essential for diagnosing filter, permission, or communication problems with the printer.

Troubleshooting common problems

Although CUPS is robust, certain scenarios can cause failures. Below is a list of the most frequent problems and their solutions:

  • Printer not detected: Verify that the device is connected and that the kernel recognizes it with lsusb or dmesg. If it is a network printer, ensure it has a static IP and that port 631 is reachable (nc -zv IP 631).
  • Jobs stuck in the queue: Use lpstat -o to see the halted jobs. Then run cancel ID_DEL_TRABAJO or restart the service with sudo systemctl restart cups.
  • Missing filter error: Indicates that a backend or filter is missing (e.g., foomatic-rip). Install the corresponding driver package (sudo apt install printer-driver-foo2zjs) or check /var/log/cups/error_log to identify the missing module.
  • Access denied from other machines: Review the directive in cupsd.conf and ensure the subnet is included. Also verify that the firewall allows TCP traffic on port 631 (sudo firewall-cmd --add-service=ipp --permanent with firewalld).
  • Slow printing or garbled characters: May be due to an unsuitable driver. Try changing the PPD to a more generic version (everywhere) or download the specific driver from the manufacturer’s website.

Keeping the system updated and periodically reviewing logs helps prevent most of these issues.

Conclusion and best practices

CUPS remains the backbone of printing in Linux environments thanks to its flexibility, support for multiple protocols, and an active community. To get the most out of it, consider following these practices:

  • Keep the service and driver packages up to date.
  • Document each printer’s configuration (IP, PPD, options) in an internal wiki or repository.
  • Use printer groups (lpadmin -p Grupo -v ipp://...) to simplify management in large offices.
  • Enable debug level logging temporarily only when troubleshooting a specific issue, then revert to info to avoid filling the disk.
  • Back up the /etc/cups/cupsd.conf file and the /etc/cups/ppd directory to facilitate migration to new servers.

With the steps described in this article, you will be able to install, configure, administer, and troubleshoot CUPS on any Linux distribution, ensuring that printing is a reliable and transparent service for all users.