From: Zdenek Dohnal Date: Mon, 27 Mar 2023 14:50:34 +0000 (+0200) Subject: REPORTING_ISSUES.md: Make the file more readable X-Git-Tag: v2.4.3~39 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=55f86e0fb349b3c3a95a3dc2eb681b42bdceb211;p=thirdparty%2Fcups.git REPORTING_ISSUES.md: Make the file more readable --- diff --git a/REPORTING_ISSUES.md b/REPORTING_ISSUES.md index bc5fb1b367..a2a5001776 100644 --- a/REPORTING_ISSUES.md +++ b/REPORTING_ISSUES.md @@ -32,109 +32,109 @@ in case the printer is not listed or the command is not found, your device doesn 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: -* tell us what is **your OS** -* tell us your **CUPS version** -* in case you compile CUPS by yourself, tell us **all configuration options** you pass into `./configure` -* **describe** the problem -* mention your **printer model** -* 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 -``` - -For more info check `man lp`, `man lpstat`, `man lpoptions`. - -2. check if the issue happens with different documents -3. check if the issue happens when using different applications -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. - -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. - -* turn on **CUPS debug logging**: +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 + ``` + + For more info check `man lp`, `man lpstat`, `man lpoptions`. + + 2. check if the issue happens with different documents + 3. check if the issue happens when using different applications + 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. + + 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 ``` -* **reproduce the issue** -* **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. - -* provide output of **lpstat -e**, **lpstat -t** and **lpinfo -v** -* provide **PPD file** from `/etc/cups/ppd` if exists for the printer -* provide **the file you are trying to print**, if the issue happens with a specific file -* provide **the d file from /var/spool/cups** - this is the file CUPS actually gets from the application -* tell us the name of application where you experience the problem -* if needed, turn off the debug logging by: - -``` - $ cupsctl LogLevel=warn -``` +8. **reproduce the issue** +9. **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. + +10. provide output of **lpstat -e**, **lpstat -t** and **lpinfo -v** +11. provide **PPD file** from `/etc/cups/ppd` if exists for the printer +12. provide **the file you are trying to print**, if the issue happens with a specific file +13. provide **the d file from /var/spool/cups** - this is the file CUPS actually gets from the application +14. tell us the name of application where you experience the problem +15. 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. + ``` + $ 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 -``` + ``` + $ 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 @@ -143,9 +143,9 @@ compress the `usb.pcap` with `zip` and attach it to the issue if the problem is * **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 -``` + ``` + $ sudo tcpdump -s0 -w network.pcap -i any host + ``` compress the `network.pcap` with `zip` and attach it to the issue.