1# REPORTING ISSUES FOR CUPS PROJECT 2 3> 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. 4 5> 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. 6 7The 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. 8 9 10## HOW TO FIND OUT THAT I USE DRIVERLESS PRINTING 11 12For network printers: 13* 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, 14 15or 16 17* 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>`) 18 19If any of them apply, your device works in driverless mode. 20 21For USB printers: 22* your printer is listed if you enter: 23 24``` 25 $ sudo ipp-usb check 26``` 27 28in case the printer is not listed or the command is not found, your device doesn't work in driverless mode. 29 30 31## HOW TO REPORT THE ISSUE TO CUPS PROJECT 32 33Please 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: 34 351. tell us what is **your OS** 362. tell us your **CUPS version** 373. in case you compile CUPS by yourself, tell us **all configuration options** you pass into `./configure` 384. **describe** the problem 395. mention your **printer model** 406. try to **narrow the issue if possible**: 41 42 1. check how the printing works via CUPS CLI tools, f.e.: 43 44 See whether the printer is available (f.e. in case the printer is not shown in application) - shows both temporary and permanent queues: 45 46 ``` 47 $ lpstat -e 48 HP_LaserJet_M1536dnf_MFP_42307C 49 ``` 50 51 See whether there are installed printers which accept jobs: 52 53 ``` 54 $ lpstat -a 55 ``` 56 57 See its available options (in case an application doesn't show some options): 58 59 ``` 60 $ lpoptions -p HP_LaserJet_M1536dnf_MFP_42307C -l 61 PageSize/Media Size: 184x260mm 195x270mm *A4 A5 B5 DoublePostcardRotated Env10 EnvC5 EnvDL EnvMonarch Executive FanFoldGermanLegal ISOB5 Legal Letter Postcard roc16k 62 MediaType/Media Type: *Stationery StationeryLightweight Midweight StationeryHeavyweight ExtraHeavy ColorTransparency Labels StationeryLetterhead Envelope StationeryPreprinted StationeryPrepunched Color Bond Recycled Rough Vellum 63 cupsPrintQuality/cupsPrintQuality: Draft *Normal 64 ColorModel/Output Mode: *Gray 65 Duplex/Duplex: *None DuplexNoTumble DuplexTumble 66 OutputBin/OutputBin: *FaceDown 67 ``` 68 69 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 <document>): 70 71 ``` 72 $ lp -d HP_LaserJet_M1536dnf_MFP_42307C -o Duplex=DuplexNoTumble <document> 73 ``` 74 75 For more info check `man lp`, `man lpstat`, `man lpoptions`. 76 77 2. check if the issue happens with different documents 78 3. check if the issue happens when using different applications 79 4. 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. 80 81 Rule of thumb: 82 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. 83 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. 84 857. turn on **CUPS debug logging**: 86 87``` 88 $ cupsctl LogLevel=debug2 89``` 90 918. **reproduce the issue** 929. **collect the logs** - the logs can be in `/var/log/cups/error_log` or in `journalctl`: 93 94 For `error_log`: 95 ``` 96 $ sudo cp /var/log/cups/error_log ~/error_log.txt 97 $ sudo chmod 666 ~/error_log.txt 98 ``` 99 100 For `journalctl`: 101 ``` 102 $ journalctl -u cups --since=today > log.txt 103 ``` 104 105 and attach the file to the GitHub issue. 106 10710. provide output of **lpstat -e**, **lpstat -t** and **lpinfo -v** 10811. provide **PPD file** from `/etc/cups/ppd` if exists for the printer 10912. provide **the file you are trying to print**, if the issue happens with a specific file 11013. provide **the d file from /var/spool/cups** - this is the file CUPS actually gets from the application 11114. tell us the name of application where you experience the problem 11215. if needed, turn off the debug logging by: 113 114 ``` 115 $ cupsctl LogLevel=warn 116 ``` 117 118### INFORMATION REQUESTED FOR USB DEVICES 119 120* attach **output of `lsusb -v`** in a file as attachment 121* 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`: 122 123 ``` 124 $ lsusb 125 Bus 002 Device 010: ID 03f0:012a HP, Inc HP LaserJet M1536dnf MFP 126 = 127 $ sudo tcpdump -s0 -w usb.pcap -i usbmon2 128 ``` 129 compress the `usb.pcap` with `zip` and attach it to the issue if the problem is with USB printer. 130 131#### INFORMATION REQUESTED FOR DRIVERLESS USB PRINTERS 132 133* **provide the file attr.log** from `ipptool` command if the command passes: 134 135 ``` 136 $ ipptool --ippserver attr.log -v ipp://localhost:60000/ipp/print get-printer-attributes.test 137 ``` 138 139* compress **/var/log/ipp-usb** directory into `.zip` file and attach it to the issue 140 141 142### INFORMATION REQUESTED FOR NETWORK DEVICES 143 144* **provide network.pcap.zip** which is network packet capture - **catch the network traffic** f.e. with tcpdump: 145 146 ``` 147 $ sudo tcpdump -s0 -w network.pcap -i any host <server_or_printer_IP> 148 ``` 149 150compress the `network.pcap` with `zip` and attach it to the issue. 151 152The 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](https://wiki.wireshark.org/TLS) 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). 153 154#### INFORMATION REQUESTED FOR DRIVERLESS NETWORK PRINTERS 155 156* **provide the file attr.log** from `ipptool` command, if the command passes: 157 158For network driverless printer: 159``` 160 $ ipptool --ippserver attr.log -v ipp://<printer_IP>/ipp/print get-printer-attributes.test 161``` 162 163For driverless printer pointing to a printer at CUPS server: 164``` 165 $ ipptool --ippserver attr.log -v ipp://<server_IP>/printers/<remote_printer_name> get-printer-attributes.test 166``` 167 168For driverless printer installed in a printer application based on PAPPL: 169``` 170 $ ipptool --ippserver attr.log -v ipp://localhost:8000/ipp/print/<printer_name> get-printer-attributes.test 171``` 172 173 174## THANKS 175 176This 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! 177