Configuring and using a CUPS printing server

Red Hat Enterprise Linux 9

Configure your system to operate as a CUPS server and manage printers, print queues and your printing environment.

Red Hat Customer Content Services

Abstract

This document describes activating the cups service, accessing and configuring the CUPS web UI, working with CUPS logs and introduces driverless printing.

Providing feedback on Red Hat documentation

We appreciate your input on our documentation. Please let us know how we could make it better.

  • For simple comments on specific passages:

    1. Make sure you are viewing the documentation in the Multi-page HTML format. In addition, ensure you see the Feedback button in the upper right corner of the document.
    2. Use your mouse cursor to highlight the part of text that you want to comment on.
    3. Click the Add Feedback pop-up that appears below the highlighted text.
    4. Follow the displayed instructions.
  • For submitting feedback via Bugzilla, create a new ticket:

    1. Go to the Bugzilla website.
    2. As the Component, use Documentation.
    3. Fill in the Description field with your suggestion for improvement. Include a link to the relevant part(s) of documentation.
    4. Click Submit Bug.

Chapter 1. Configuring printing

Printing on Red Hat Enterprise Linux 8 is based on the Common Unix Printing System (CUPS).

This documentation describes how to configure your system to be able to operate as a CUPS server.

1.1. Activating the cups service

This section describes how to activate the cups service on your system.

Prerequisites

  • The cups package, which is available in the Appstream repository, must be installed on your system:

    # dnf install cups

Procedure

  1. Start the cups service:

    # systemctl start cups
  2. Configure the cups service to be automatically started at boot time:

    # systemctl enable cups
  3. Optionally, check the status of the cups service:

    $ systemctl status cups

1.3. Accessing and configuring the CUPS web UI

This section describes accessing the CUPS web user interface (web UI) and configuring it to be able to manage printing through this interface.

Procedure

To access the CUPS web UI:

  1. Allow the CUPS server to listen to connections from the network by setting Port 631 in the /etc/cups/cupsd.conf file:

    #Listen localhost:631
    Port 631
    Warning

    Enabling the CUPS server to listen on port 631 opens this port for any address accessible by the server. Therefore, use this setting only in local networks that are unreachable from an external network. Red Hat doesn’t recommend configuring CUPS server on a publicly accessible server.

  2. Allow your system to access the CUPS server by including the following directive in the /etc/cups/cupsd.conf file:

    <Location />
    Allow from <your_ip_address>
    Order allow,deny
    </Location>

    where <your_ip_address> is the real IP address of your system. You can also use regular expressions for subnets.

    Warning

    The CUPS configuration offers the Allow from all directive in the <Location> tags, but Red Hat recommends using this directive only in trusted networks. The setup Allow from all enables access for all users who can connect to the server through port 631. If you set the Port directive to 631, and the server is accessible from an outside network, anyone on the Internet can access the CUPS service on your system.

  3. Restart the cups.service:

    # systemctl restart cups
  4. Open your browser, and go to http://<IP_address_of_the_CUPS_server>:631/.

    cups ui intro

    All menus except for the Administration menu are now available.

    If you click on the Administration menu, you receive the Forbidden message:

    forbidden message

    To acquire the access to the Administration menu, follow the instructions in Acquiring administration access to CUPS web UI.

1.4. Acquiring administration access to the CUPS web UI

This section describes how to acquire administration access to the CUPS web UI.

Procedure

  1. To be able to access the Administration menu in the CUPS web UI, include the following lines in the /etc/cups/cupsd.conf file:

    <Location /admin>
    Allow from <your_ip_address>
    Order allow,deny
    </Location>
    Note

    Replace <your_ip_address> with the real IP address of your system.

  2. To be able to access configuration files in the CUPS web UI, include the following in the /etc/cups/cupsd.conf file:

    <Location /admin/conf>
    AuthType Default
    Require user @SYSTEM
    Allow from <your_ip_address>
    Order allow,deny
    </Location>
    Note

    Replace <your_ip_address> with the real IP address of your system.

  3. To be able to access log files in the CUPS web UI, include the following in the /etc/cups/cupsd.conf file:

    <Location /admin/log>
    AuthType Default
    Require user @SYSTEM
    Allow from <your_ip_address>
    Order allow,deny
    </Location>
    Note

    Replace <your_ip_address> with the real IP address of your system.

  4. To specify the use of encryption for authenticated requests in the CUPS web UI, include DefaultEncryption in the /etc/cups/cupsd.conf file:

    DefaultEncryption IfRequested

    With this setting, you will receive an authentication window to enter the username of a user allowed to add printers when you attempt to access the Administration menu. However, there are also other options on how to set DefaultEncryption. For more details, see the cupsd.conf man page.

  5. Restart the cups service:

    # systemctl restart cups
    Warning

    If you do not restart the cups service, the changes in /etc/cups/cupsd.conf will not be applied. Consequently, you will not be able to obtain administration access to the CUPS web UI.

Additional resources

  • The cupsd.conf man page

1.5. Configuring driverless printing

As an administrator, you can configure driverless printing to use printers or remote CUPS queues without any special software.

RHEL 9 provides driverless printing support for following driverless standards:

  • IPP Everywhere model in CUPS supports AirPrint, IPP Everywhere and Wi-Fi Direct standards.
  • Driverless model in cups-filters supports the same standards as CUPS and in addition also PCLm document format.

These standards use the Internet Printing Protocol (IPP) 2.0 or higher to communicate the printer setup, and eliminate the need to install specific drivers for specific printers. To use the printer without a specific driver, you need to have a printer, which supports one of the driverless standards. To determine if your printer supports a driverless standard, choose one of the following options:

To install a print queue on the client with IPP Everywhere model, which points to a queue on the print server, you need to have both your remote print server and your client with RHEL 8.6 installation or newer.

Note

You can verify the driverless support based on the attributes of a print server with the ipptool command.

1.5.1. Determining printer attributes using ipptool

To determine if your printer or print server supports a driverless standard, you can inspect your printer attributes using the ipptool command available in the ipptool package.

Procedure

  • Display attributes of a printer or a print server:

    $ ipptool -tv <URI> get-printer-attributes.test
    Note

    Replace <URI> with the URI of your printer, for example ipp://<hostname_or_IP_address>:631/ipp/print for printers or ipp://<hostname_or_IP_address>:631/printers/<remote_print_queue> for remote print queues from print servers.

Your printer or print server supports driverless printing if:

  • the ipp-version-supported attribute contains 2.0 or higher for IPP protocol 2.0, and
  • the document-format-supported attribute contains one of the supported document formats listed in the driverless printing standards.

1.5.2. Adding a driverless printer in CUPS web UI

Since RHEL 8.6, you can add a driverless printer in the CUPS web UI and use it to print directly from an application to network printers or print servers using CUPS, without installing any specific drivers or software for specific printers.

Prerequisites

  • You have administration access to the CUPS web UI as described in Acquiring administration access to CUPS web UI.
  • Your printer or print server has the IPP Everywhere standard implementation.
  • Open IPP port: port 631 for IPP, or port 443 for secure printing with IPPS.
  • Enable the ipp and ipp-client communication in the firewall of the print server.
  • If your destination is another CUPS server, allow remote access on the remote server, or if you are using a network printer, open the web user interface, search for IPP related settings: IPP or AirPrint, and enable those settings.

Procedure

  1. Start the CUPS web UI as described in Accessing and configuring the CUPS.
  2. In your browser, go to localhost:631 and select the Administration tab.
  3. Under Printers click Add printer.

    add printer in cups ui 2
  4. Authenticate with your username and password:

    add printer in cups ui auth n
    Important

    To be able to add a new printer by using the CUPS web UI, you must authenticate as a user who belongs to a group defined by the SystemGroup directive in /etc/cups/cups-files. The default groups are:

    • root
    • sys
    • wheel
  5. In the Administrator tab, under Add Printer, select one of the options:

    • Internet Printing Protocol (ipp) or
    • Internet Printing Protocol (ipps) option, and click Continue.

      Add printer IPP frame
  6. In the Connection field, enter the URI of your device and click Continue.

    Add printer connection frame
    Note

    The URI consists of the following parts:

    • protocol ipp:// or ipps:// if printer or print server supports encryption,
    • hostname or IP address of the printer,
    • port,
    • resource part /ipp/print for printers, or /printers/<remote_queue_name> for remote CUPS queues.

      For example: ipp://myprinter.mydomain:631/ipp/print or ipp://myserver.mydomain:631/printers/myqueue.

  7. Add details about the new printer: name, description and location. To set a printer to be shared over the network, check the Share This Printer checkbox.

    Add printer location frame
    Note

    'Name' is the only required field, other fields are optional.

  8. From the Make dropdown menu, select the printer manufacturer, and click Continue.

    Add printer make frame
  9. To proceed with the installation of a driverless printer, from the dropdown menu, select IPP Everywhere, and click Add Printer.

    Add printer model IPP frame
  10. After adding the new printer, you can set the default print options of your choice.

    cups web ui set defaults n2

The last window confirms that you set the driverless printer and it is ready to use.

Add printer final screen frame

1.6. Adding a printer with a classic driver in the CUPS web UI

This section describes how to add a new printer using the CUPS web user interface.

Prerequisites

Procedure

  1. Start the CUPS web UI as described in Starting CUPS web UI
  2. In your browser, go to localhost:631 and select the Administration tab.
  3. Under Printers click Add printer.

    add printer in cups ui 2
  4. Authenticate by username and password:

    add printer in cups ui auth n
    Important

    To be able to add a new printer by using the CUPS web UI, you must authenticate as a user who belongs to groups defined by SystemGroup directive in /etc/cups/cups-files.

    Default groups:

    • root
    • sys
    • wheel
  5. If a local printer is connected, or CUPS finds a network printer available, select the printer. If neither local printer nor network printer is available, select one of the printer types from Other Network Printers, for example APP Socket/HP Jet direct, enter the IP address of the printer, and then click Continue.

    add printer in cups ui 4 new
  6. If you have selected for example APP Socket/HP Jet direct as shown above, enter the IP address of the printer, and then click Continue.

    add printer in cups ui 5 new
  7. You can add more details about the new printer, such as the name, description and location. To set a printer to be shared over the network, check the Share This Printer checkbox.

    add printer in cups ui 6 new
  8. Select the printer manufacturer, and then click Continue.

    add printer in cups ui 7 new

    Alternatively, you can provide a postscript printer description (PPD) file to be used as a driver for the printer, by clicking the Browse…​ button at the bottom.

  9. Select the model of the printer, and then click Add Printer.

    add printer in cups ui 8 new
  10. After the printer has been added, the next window allows you to set the default print options.

    cups web ui set defaults n2

After clicking Set Default Options, you will receive a confirmation that the new printer has been added successfully.

add printer in cups ui final confirm

Verification steps

  • Print a test page especially if you have set up a printer:

    • Go to Printers menu, and click MaintenancePrint Test Page.

      printing test page cups web ui

1.7. Configuring a printer in the CUPS web UI

This section describes how to configure a new printer, and how to maintain a configuration of a printer using the CUPS web UI.

Prerequisites

Procedure

  1. Click the Printers menu to see available printers that you can configure.

    conf printer cups 1
  2. Choose one printer that you want to configure.

    conf printer cups 2
  3. Perform your selected task by using one of the available menus:

    • Choose Maintenance from the first drop-down menu.

      conf printer cups 3
    • Choose Administration from the second drop-down menu.

      conf printer cups 4
    • You can also check completed print jobs or all active print jobs by clicking the Show Completed Jobs or Show All Jobs buttons.

Verification steps

  • Print a test page especially if you have changed a printer configuration:

    • Go to Printers menu, and click MaintenancePrint Test Page.

      printing test page cups web ui

1.8. Setting print options using the CUPS web UI

This section describes how to set common print options, such as the media size and type, print quality or the color mode, in the CUPS web UI.

Prerequisites

You have administration access to the CUPS web UI as described in Acquiring administration access to CUPS web UI.

Procedure

  1. Go to Administration menu, and click MaintenanceSet Default Options.

    cups web ui set defaults n1
  2. Set the print options.

    cups web ui set defaults n2

1.9. Installing certificates for a print server

To install certificates for a print server, you can choose one of the following options:

  • Automatic installation using a self-signed certificate
  • Manual installation using a certificate and a private key generated by a Certification Authority

Prerequisites

For the cupsd daemon on the server:

  1. Set the following directive in the /etc/cups/cupsd.conf file to:

    Encryption Required

  2. Restart the cups service:

    $ sudo systemctl restart cups

Automatic installation using a self-signed certificate

With this option, CUPS generates the certificate and the key automatically.

Note

The self-signed certificate does not provide as strong security as certificates generated by Identity Management (IdM), Active Directory (AD), or Red Hat Certificate System (RHCS) Certification Authorities, but it can be used for print servers located within a secure local network.

Procedure

  1. To access the CUPS Web UI, open your browser and go to https://<server>:631

    where <server> is either the server IP address or the server host name.

    Note

    When CUPS connects to a system for the first time, the browser shows a warning about the self-signed certificate being a potential security risk.

  2. To confirm that it is safe to proceed, click the Advanced…​ button.

    cups ui certificate warning
  3. Click Accept the Risk and Continue button.

    cups ui certificate warning2

CUPS now starts to use the self-generated certificate and the key.

Note

When you access the CUPS Web UI after an automatic installation, the browser displays a warning icon in the address bar. This is because you added the security exception by confirming the security risk warning. If you want to remove this warning icon permanently, perform the manual installation with a certificate and a private key generated by a Certification Authority.

Manual installation using a certificate and a private key generated by a Certification Authority

For print servers located within a public network or to permanently remove the warning in the browser, import the certificate and the key manually.

Prerequisites

  • You have certificate and private key files generated by IdM, AD, or by RHCS Certification Authorities.

Procedure

  1. Copy the .crt and .key files into the /etc/cups/ssl directory of the system on which you want to use the CUPS Web UI.
  2. Rename the copied files to <hostname>.crt and <hostname>.key.

    Replace <hostname> with the host name of the system to which you want to connect the CUPS Web UI.

  3. Set the following permissions to the renamed files:

    • # chmod 644 /etc/cups/ssl/<hostname>.crt
    • # chmod 644 /etc/cups/ssl/<hostname>.key
    • # chown root:root /etc/cups/ssl/<hostname>.crt
    • # chown root:root /etc/cups/ssl/<hostname>.key
  4. Restart the cups service:

    • # systemctl restart cupsd

1.10. Using Samba to print to a Windows print server with Kerberos authentication

With the samba-krb5-printing wrapper, Active Directory (AD) users who are logged in to Red Hat Enterprise Linux can authenticate to Active Directory (AD) by using Kerberos and then print to a local CUPS print server that forwards the print job to a Windows print server.

The benefit of this configuration is that the administrator of CUPS on Red Hat Enterprise Linux does not need to store a fixed user name and password in the configuration. CUPS authenticates to AD with the Kerberos ticket of the user that sends the print job.

This section describes how to configure CUPS for this scenario.

Note

Red Hat only supports submitting print jobs to CUPS from your local system, and not to re-share a printer on a Samba print server.

Prerequisites

  • The printer that you want to add to the local CUPS instance is shared on an AD print server.
  • You joined the Red Hat Enterprise Linux host as a member to the AD.
  • CUPS is installed on Red Hat Enterprise Linux and the cups service is running. For details, see Activating CUPS service.
  • The PostScript Printer Description (PPD) file for the printer is stored in the /usr/share/cups/model/ directory.

Procedure

  1. Install the samba-krb5-printing, samba-client, and krb5-workstation packages:

    # dnf install samba-krb5-printing samba-client krb5-workstation
  2. Optional: Authenticate as a domain administrator and display the list of printers that are shared on the Windows print server:

    # smbclient -L win_print_srv.ad.example.com -U administrator@AD_KERBEROS_REALM --use-kerberos=required
    
    	Sharename       Type      Comment
    	---------       ----      -------
    	...
    	Example         Printer   Example
    	...
  3. Optional: Display the list of CUPS models to identify the PPD name of your printer:

    lpinfo -m
    ...
    samsung.ppd Samsung M267x 287x Series PXL
    ...

    You require the name of the PPD file when you add the printer in the next step.

  4. Add the printer to CUPS:

    # lpadmin -p "example_printer" -v smb://win_print_srv.ad.example.com/Example -m samsung.ppd -o auth-info-required=negotiate -E

    The command uses the following options:

    • -p printer_name sets the name of the printer in CUPS.
    • -v URI_to_Windows_printer sets the URI to the Windows printer. Use the following format: smb://host_name/printer_share_name.
    • -m PPD_file sets the PPD file the printer uses.
    • -o auth-info-required=negotiate configures CUPS to use Kerberos authentication when it forwards print jobs to the remote server.
    • -E enables the printer and CUPS accepts jobs for the printer.

Verification steps

  1. Log into the Red Hat Enterprise Linux host as an AD domain user.
  2. Authenticate as an AD domain user:

    # kinit domain_user_name@AD_KERBEROS_REALM
  3. Print a file to the printer you added to the local CUPS print server:

    # lp -d example_printer file

1.11. Working with CUPS logs

1.11.1. Types of CUPS logs

CUPS provides three different kinds of logs:

  • Error log - Stores error messages, warnings and debugging messages.
  • Access log - Stores messages about how many times CUPS clients and web UI have been accessed.
  • Page log - Stores messages about the total number of pages printed for each print job.

In Red Hat Enterprise Linux 8, all three types are logged centrally in systemd-journald together with logs from other programs.

Warning

In Red Hat Enterprise Linux 8, the logs are no longer stored in specific files within the /var/log/cups directory, which was used in Red Hat Enterprise Linux 7.

1.11.2. Accessing all CUPS logs

You can list all CUPS logs available in systemd-journald.

Procedure

  • Filter CUPS logs:
$ journalctl -u cups

1.11.3. Accessing CUPS logs for a specific print job

If you need to find a CUPS log for a specific print job, you can do it by filtering the logs using the number of a print job.

Procedure

  • Filter logs for a specific print job:
$ journalctl -u cups JID=N

Where N is a number of a print job.

1.11.4. Accessing CUPS logs by specific time frame

If you need to access CUPS logs during a certain time period, you can filter the logs in systemd-journald.

Procedure

  • Filter logs within the specified time frame:
$ journalctl -u cups --since=YYYY-MM-DD --until=YYYY-MM-DD

Where YYYY is year, MM is month and DD is day.

Additional resources

  • The journalctl(1) man page

1.11.5. Configuring the CUPS log location

This section describes how to configure the location of CUPS logs.

In Red Hat Enterprise Linux 8, CUPS logs are by default logged into systemd-journald, which is ensured by the following default setting in the /etc/cups/cups-files.conf file:

ErrorLog syslog
Important

Red Hat recommends keeping the default location of CUPS logs.

If you want to send the logs into a different location, you need to change the settings in the /etc/cups/cups-files.conf file as follows:

ErrorLog <your_required_location>
Warning

If you change the default location of CUPS log, you might experience SELinux issues.

Legal Notice

Copyright © 2022 Red Hat, Inc.
The text of and illustrations in this document are licensed by Red Hat under a Creative Commons Attribution–Share Alike 3.0 Unported license ("CC-BY-SA"). An explanation of CC-BY-SA is available at http://creativecommons.org/licenses/by-sa/3.0/. In accordance with CC-BY-SA, if you distribute this document or an adaptation of it, you must provide the URL for the original version.
Red Hat, as the licensor of this document, waives the right to enforce, and agrees not to assert, Section 4d of CC-BY-SA to the fullest extent permitted by applicable law.
Red Hat, Red Hat Enterprise Linux, the Shadowman logo, the Red Hat logo, JBoss, OpenShift, Fedora, the Infinity logo, and RHCE are trademarks of Red Hat, Inc., registered in the United States and other countries.
Linux® is the registered trademark of Linus Torvalds in the United States and other countries.
Java® is a registered trademark of Oracle and/or its affiliates.
XFS® is a trademark of Silicon Graphics International Corp. or its subsidiaries in the United States and/or other countries.
MySQL® is a registered trademark of MySQL AB in the United States, the European Union and other countries.
Node.js® is an official trademark of Joyent. Red Hat is not formally related to or endorsed by the official Joyent Node.js open source or commercial project.
The OpenStack® Word Mark and OpenStack logo are either registered trademarks/service marks or trademarks/service marks of the OpenStack Foundation, in the United States and other countries and are used with the OpenStack Foundation's permission. We are not affiliated with, endorsed or sponsored by the OpenStack Foundation, or the OpenStack community.
All other trademarks are the property of their respective owners.