Setting Up Printer Support with CUPS on FreeBSD

A comprehensive guide to setting up printer support with CUPS on FreeBSD
by İbrahim Korucuoğlu ( @siberoloji) |
Tags:
Categories:

  7 minute read  

FreeBSD is a powerful and stable operating system popular among system administrators and hobbyists alike. While FreeBSD excels at many tasks, printing functionality requires some additional configuration. The Common Unix Printing System (CUPS) provides a robust printing solution for FreeBSD users. This guide will walk you through the process of setting up CUPS on FreeBSD, from installation to printer configuration and troubleshooting.

Introduction to CUPS

The Common Unix Printing System (CUPS) is an open-source printing system developed by Apple Inc. that has become the standard printing solution for most Unix-like operating systems. CUPS uses the Internet Printing Protocol (IPP) to manage printers, print queues, and print jobs. It features a web-based administration interface, command-line tools, and supports various printer drivers and formats.

Prerequisites

Before proceeding with CUPS installation and configuration, ensure you have:

  • A FreeBSD system (version 12.0 or newer recommended)
  • Root or sudo access to the system
  • A supported printer (check the CUPS supported printer database for compatibility)
  • Network connectivity (if setting up a network printer)
  • Basic familiarity with FreeBSD package management and system administration

Installation Process

Step 1: Installing CUPS and Required Packages

First, update your FreeBSD system to ensure you have the latest package information:

# Update the package repository
pkg update

Next, install CUPS and related packages:

# Install CUPS
pkg install cups print/cups-filters print/gutenprint

The above command installs:

  • cups: The core CUPS printing system
  • cups-filters: Additional filters for processing various document formats
  • gutenprint: High-quality printer drivers for many printer models

For PDF support, install Ghostscript:

pkg install print/ghostscript9-base

Step 2: Enabling CUPS Service

After installation, you need to enable and start the CUPS service:

  1. Add the following line to /etc/rc.conf to enable CUPS at boot time:
# Enable CUPS service at boot
echo 'cupsd_enable="YES"' >> /etc/rc.conf
  1. Start the CUPS service:
# Start CUPS service
service cupsd start
  1. Verify that CUPS is running:
# Check CUPS status
service cupsd status

Step 3: User Setup

For proper access to CUPS and printer management, you should add your user to the cups group:

# Add user to cups group
pw groupmod cups -m yourusername

You may need to log out and log back in for this change to take effect.

Accessing the CUPS Web Interface

CUPS provides a web-based administration interface for managing printers and print jobs. To access it:

  1. Open a web browser on your FreeBSD system or another computer on the same network
  2. Navigate to: http://localhost:631/ (or replace localhost with your FreeBSD machine’s IP address if accessing from another computer)

By default, CUPS might restrict remote administration. To enable it:

  1. Edit the CUPS configuration file:
vi /usr/local/etc/cups/cupsd.conf
  1. Modify the Listen directive to listen on all network interfaces:
Listen 0.0.0.0:631
  1. Find the <Location />, <Location /admin>, and <Location /admin/conf> sections and add the following line inside each section:
Allow @LOCAL
  1. Restart CUPS to apply changes:
service cupsd restart

Adding and Configuring Printers

Local USB Printer Setup

  1. Connect your printer to the FreeBSD system via USB and power it on
  2. Access the CUPS web interface at http://localhost:631/
  3. Click on the “Administration” tab
  4. Click “Add Printer”
  5. You’ll be prompted for authentication - use your root username and password
  6. Select your USB printer from the list of detected devices
  7. Follow the prompts to provide a name, description, and location for your printer
  8. Select the appropriate driver for your printer model
  9. Set default printing options as needed

Network Printer Setup

  1. Ensure your network printer is powered on and connected to the same network as your FreeBSD system
  2. Access the CUPS web interface at http://localhost:631/
  3. Click on the “Administration” tab
  4. Click “Add Printer”
  5. Select the appropriate protocol for your network printer:
    • For IPP printers: Select “Internet Printing Protocol (ipp)”
    • For HP printers: Select “HP Jetdirect”
    • For Windows shared printers: Select “Windows Printer via SAMBA”
  6. Provide the printer’s network address or URI
    • For IPP: ipp://printer_ip/ipp/print or ipp://printer_ip/ipp
    • For HP Jetdirect: socket://printer_ip:9100
    • For SAMBA: smb://username:password@workgroup/server/printer
  7. Follow the prompts to provide a name, description, and location for your printer
  8. Select the appropriate driver
  9. Set default printing options as needed

Driver Installation

For many printers, the drivers included with CUPS and Gutenprint will be sufficient. However, some printers may require specific drivers:

PostScript Printers

Most PostScript printers work with the Generic PostScript driver included with CUPS.

HP Printers

For HP printers, install HPLIP:

pkg install print/hplip

After installation, you can use the hp-setup command to set up your HP printer:

hp-setup -i

Brother Printers

For Brother printers, you may need to download drivers from the Brother website and install them manually. Check the Brother website for FreeBSD-compatible drivers or Linux drivers that may work with FreeBSD.

Testing and Using Your Printer

Testing the Printer

After adding a printer, you should test it:

  1. From the CUPS web interface, click on the “Printers” tab
  2. Click on your printer’s name
  3. Click on “Maintenance” and select “Print Test Page”

Alternatively, use the command line:

lpr -P printer_name /usr/local/share/cups/data/testpage.pdf

Printing from Applications

Most FreeBSD applications that support printing should automatically detect CUPS printers. In applications, look for print options and select your configured printer.

Command-Line Printing

CUPS provides several command-line tools for printing:

  • lpr: Print files

    lpr -P printer_name filename

  • lpq: View print queue

    lpq -P printer_name

  • lprm: Remove print jobs

    lprm -P printer_name job_id

Advanced Configuration

Setting Default Printer

Set a default printer with:

lpoptions -d printer_name

Printer Classes

Printer classes allow you to group multiple printers. When printing to a class, the job is sent to the first available printer in that class.

To create a printer class:

  1. Access the CUPS web interface
  2. Click on “Administration” and then “Add Class”
  3. Provide a name, description, and location
  4. Select the printers to include in the class

Custom Paper Sizes

To define custom paper sizes:

  1. Access the CUPS web interface
  2. Click on “Administration” and then “Server Settings”
  3. Scroll down to “Custom Paper Sizes” and click “Add Custom Paper Size”
  4. Define your custom paper dimensions and margins

Troubleshooting Common Issues

Printer Not Detected

If your USB printer is not detected:

  1. Check USB connections

  2. Verify the printer is powered on

  3. Check if the device is recognized by the system:

    dmesg | grep -i usb

  4. Ensure necessary device drivers are loaded:

    kldstat

  5. You may need to load additional kernel modules for specific USB devices

If print jobs get stuck in the queue:

  1. Check the printer status and make sure it’s online

  2. Cancel all pending jobs:

    cancel -a

  3. Restart CUPS:

    service cupsd restart

If you experience driver-related issues:

  1. Try alternative drivers from the CUPS web interface
  2. Check printer manufacturer’s website for FreeBSD-compatible drivers
  3. Consider using a generic driver if a specific one is not available

Permission Problems

If you encounter permission errors:

  1. Verify your user is in the cups group

  2. Check file permissions for CUPS configuration files:

    ls -la /usr/local/etc/cups/

  3. Ensure proper permissions on the printer device:

    ls -la /dev/ulpt*

Security Considerations

CUPS provides several security features to protect your printing environment:

Encrypting Print Jobs

To enable encryption for print jobs:

  1. Edit the CUPS configuration file:

    vi /usr/local/etc/cups/cupsd.conf

  2. Add or modify:

    DefaultEncryption IfRequested

  3. Restart CUPS:

    service cupsd restart

Restricting Access

To limit access to specific IP addresses:

  1. Edit the CUPS configuration file

  2. Modify the <Location> sections:

    <Location />
  Order allow,deny
  Allow from 192.168.1.0/24
  Allow from 127.0.0.1
</Location>

  3. Apply similar restrictions to other <Location> sections as needed

  4. Restart CUPS

Conclusion

Setting up CUPS on FreeBSD provides a robust printing solution compatible with a wide range of printers. By following this guide, you should have a fully functional printing system for your FreeBSD environment. While the initial configuration may require some effort, CUPS offers excellent reliability and flexibility once set up.

Remember to keep your CUPS installation updated along with your FreeBSD system to benefit from the latest features and security fixes. For more advanced configurations or specific printer models, consult the CUPS documentation or the FreeBSD Handbook.

Additional Resources


< How to Enable HiDPI Display ScalingAutomating GUI Application Installations >