Skip to content

Latest commit

 

History

History
176 lines (119 loc) · 8.15 KB

REPORTING_ISSUES.md

File metadata and controls

176 lines (119 loc) · 8.15 KB
Raw

REPORTING ISSUES FOR CUPS PROJECT

Disclaimer: We provide only best effort support for CUPS releases older than the latest release. This means we try to reproduce the issue on the latest release if it is possible, and if we can't reproduce, we can give a hint what can be the problem and ask you to contact your distribution support.

All commands are written from point of view of user which has superuser rights (f.e. he is in wheel on Linux system) or he is in a group defined in SystemGroup directive in /etc/cups/cups-files.conf. Other users will have to use sudo with certain commands.

The steps you are asked to do differ based on how your printer is connected (USB/network) and whether you use driverless printing or not. Since the connection is obvious for the user, the paragraph below will tell you how to find out whether driverless printing is used.

HOW TO FIND OUT THAT I USE DRIVERLESS PRINTING

For network printers:

  • your printer is seen by lpstat -e, but not by lpstat -a - this means you print via temporary queue, which works only via driverless means,

or

  • your printer is seen by lpstat -a, its PPD file at /etc/cups/ppd has IPP Everywhere or driverless in its Nickname entry and its connection is ipp or ipps when you check the connection uri (f.e. by lpstat -v <printer_name>)

If any of them apply, your device works in driverless mode.

For USB printers:

  • your printer is listed if you enter:
    $ sudo ipp-usb check

in case the printer is not listed or the command is not found, your device doesn't work in driverless mode.

HOW TO REPORT THE ISSUE TO CUPS PROJECT

Please do the steps below and provide the mentioned information (use attachments for blocks of text longer than 10 lines - put the text into a file, rename it to have .txt suffix and click on pasting them string under comment box in the issue) in your initial comment if you file an issue:

  1. tell us what is your OS

  2. tell us your CUPS version

  3. in case you compile CUPS by yourself, tell us all configuration options you pass into ./configure

  4. describe the problem

  5. mention your printer model

  6. try to narrow the issue if possible:

    1. check how the printing works via CUPS CLI tools, f.e.:

    See whether the printer is available (f.e. in case the printer is not shown in application) - shows both temporary and permanent queues:

        $ lpstat -e
    HP_LaserJet_M1536dnf_MFP_42307C

    See whether there are installed printers which accept jobs:

        $ lpstat -a

    See its available options (in case an application doesn't show some options):

        $ lpoptions -p HP_LaserJet_M1536dnf_MFP_42307C -l
    PageSize/Media Size: 184x260mm 195x270mm *A4 A5 B5 DoublePostcardRotated Env10 EnvC5 EnvDL EnvMonarch Executive FanFoldGermanLegal ISOB5 Legal Letter Postcard roc16k
    MediaType/Media Type: *Stationery StationeryLightweight Midweight StationeryHeavyweight ExtraHeavy ColorTransparency Labels StationeryLetterhead Envelope StationeryPreprinted StationeryPrepunched Color Bond Recycled Rough Vellum
    cupsPrintQuality/cupsPrintQuality: Draft *Normal
    ColorModel/Output Mode: *Gray
    Duplex/Duplex: *None DuplexNoTumble DuplexTumble
    OutputBin/OutputBin: *FaceDown

    Print a file to a printer with specific options (in case the printout from application is incorrect - print the same file and set the same options as you did in application, in case they are seen in lpoptions), f.e. to check duplex printing on a document you want to print (put the path to the document instead of ):

        $ lp -d HP_LaserJet_M1536dnf_MFP_42307C -o Duplex=DuplexNoTumble <document>

    For more info check man lp, man lpstat, man lpoptions.

    1. check if the issue happens with different documents
    2. check if the issue happens when using different applications
    3. in case you use mDNS hostnames (hostnames with .local), check mDNS resolution by pinging such hostname - mDNS is used for temporary queues (printers which are seen by lpstat -e, but not by lpstat -a) or for permanent queues which have .local in its URI (check lpstat -a). However the hostname from URI is not resolvable as it is, you need to get usual printer's mDNS hostname from hostname entry in avahi-browse -avrt output.

    Rule of thumb:

    1. in case printing works from CUPS CLI tools or CUPS Web UI, but not via an application, file the issue to the application for the initial investigation.
    2. in case mDNS resolution doesn't work and you use driverless printing or mDNS hostnames in CUPS, file the issue to your mDNS resolution provider - it can be nss-mdns or systemd-resolved depending on your configuration.

  7. turn on CUPS debug logging:

    $ cupsctl LogLevel=debug2

  1. reproduce the issue

  2. collect the logs - the logs can be in /var/log/cups/error_log or in journalctl:

    For error_log:

        $ sudo cp /var/log/cups/error_log ~/error_log.txt
    $ sudo chmod 666 ~/error_log.txt

    For journalctl:

        $ journalctl -u cups --since=today > log.txt

    and attach the file to the GitHub issue.

  3. provide output of lpstat -e, lpstat -t and lpinfo -v

  4. provide PPD file from /etc/cups/ppd if exists for the printer

  5. provide the file you are trying to print, if the issue happens with a specific file

  6. provide the d file from /var/spool/cups - this is the file CUPS actually gets from the application

  7. tell us the name of application where you experience the problem

  8. if needed, turn off the debug logging by:

        $ cupsctl LogLevel=warn

INFORMATION REQUESTED FOR USB DEVICES

  • attach output of lsusb -v in a file as attachment

  • in case of communication issues with USB device, it is helpful to capture USB communication - you have to know bus number where your device is connected to with tcpdump:

        $ lsusb
    Bus 002 Device 010: ID 03f0:012a HP, Inc HP LaserJet M1536dnf MFP
          =
    $ sudo tcpdump -s0 -w usb.pcap -i usbmon2

    compress the usb.pcap with zip and attach it to the issue if the problem is with USB printer.

INFORMATION REQUESTED FOR DRIVERLESS USB PRINTERS

  • provide the file attr.log from ipptool command if the command passes:

        $ ipptool --ippserver attr.log -v ipp://localhost:60000/ipp/print get-printer-attributes.test

  • compress /var/log/ipp-usb directory into .zip file and attach it to the issue

INFORMATION REQUESTED FOR NETWORK DEVICES

  • provide network.pcap.zip which is network packet capture - catch the network traffic f.e. with tcpdump:

        $ sudo tcpdump -s0 -w network.pcap -i any host <server_or_printer_IP>

compress the network.pcap with zip and attach it to the issue.

The communication can be encrypted - the person who investigates the issue can contact you off-issue for further data, because session keys will be needed as it is explained at Wireshark wiki and a change in CUPS configuration (Wireshark is not able to decode IPPS directly, so the printer's connection has to be via HTTPS, which Wireshark can decrypt correctly).

INFORMATION REQUESTED FOR DRIVERLESS NETWORK PRINTERS

  • provide the file attr.log from ipptool command, if the command passes:

For network driverless printer:

    $ ipptool --ippserver attr.log -v ipp://<printer_IP>/ipp/print get-printer-attributes.test

For driverless printer pointing to a printer at CUPS server:

    $ ipptool --ippserver attr.log -v ipp://<server_IP>/printers/<remote_printer_name> get-printer-attributes.test

For driverless printer installed in a printer application based on PAPPL:

    $ ipptool --ippserver attr.log -v ipp://localhost:8000/ipp/print/<printer_name> get-printer-attributes.test

THANKS

This document uses knowledge from documentation and tips written by Till Kamppeter, Brian Potkin, Mike R. Sweet, Johannes Meixner, Tim Waugh, Jiri Popelka and Zdenek Dohnal. Thank you for all your work!