| IPPTOOL.txt - 2013-07-15 |
| ------------------------ |
| |
| See the file CHANGES-IPPTOOL.txt for a list of changes to this software. |
| |
| |
| INTRODUCTION |
| |
| CUPS includes two user programs for IPP printers. The first is called |
| ipptool and can be used to send arbitrary IPP requests to a CUPS server or |
| IPP printer. This tool started life as part of the CUPS automated test |
| suite and has grown to support complex conformance tests and a simple way |
| to query printer, job, and subscription attributes. |
| |
| The second program called ippfind that can be used to find IPP printers |
| that have registered themselves using Bonjour (DNS-SD, mDNS, and Zeroconf) |
| and run commands such as ipptool. |
| |
| |
| READING THE DOCUMENTATION |
| |
| Full documentation on the ipptool command can be found in the |
| "man-ipptool.html" and "man-ipptoolfile.html" files; the latter describes |
| the test file format supported by ipptool. |
| |
| Full documentation on the ippfind command can be found in the |
| "man-ippfind.html" file. |
| |
| |
| IPPFIND BASIC USAGE |
| |
| The ippfind command can be used to discover IPP printers on your network. |
| For example, the following command prints the printer URI of registered IPP |
| printers: |
| |
| ippfind |
| |
| To find all color IPP printers, run: |
| |
| ippfind --txt-color T |
| |
| And to run the IPP Everywhere conformance test file on every registered IPP |
| printer, run the following command: |
| |
| ippfind _ipp._tcp,_print --exec ipptool -t '{}' ipp-everywhere.test \; |
| |
| |
| IPPTOOL BASIC USAGE |
| |
| The ipptool command requires a printer URI and one or more "test" files that |
| describe the operations, attributes to display, and expected status and |
| attribute values. Several standard files are included with CUPS, for example |
| to show a list of pending print jobs on a CUPS printer called "myprinter" |
| you'd run: |
| |
| ipptool ipp://localhost/printers/myprinter get-jobs.test |
| |
| which would produce something like this: |
| |
| job-id job-state job-name job-originating-user-name |
| ------ ------------ ------------ ------------------------- |
| 72 pending testfile.pdf msweet |
| 73 pending testfile.ps msweet |
| 74 pending-held testfile.jpg msweet |
| 75 pending-held testfile.txt msweet |
| |
| To get output suitable for import into a spreadsheet, use the "-c" (CSV) |
| option: |
| |
| ipptool -c ipp://localhost/printers/myprinter get-jobs.test |
| |
| which will produce something like this: |
| |
| job-id,job-state,job-name,job-originating-user-name |
| 72,pending,testfile.pdf,msweet |
| 73,pending,testfile.ps,msweet |
| 74,pending-held,testfile.jpg,msweet |
| 75,pending-held,testfile.txt,msweet |
| |
| |
| STANDARD TEST FILES |
| |
| The following standard test files are included with ipptool: |
| |
| create-printer-subscription.test Creates a printer subscription for |
| state change notifications |
| get-completed-jobs.test Shows a list of completed jobs |
| get-jobs.test Shows a list of pending jobs |
| get-notifications.test Shows events for an ippget |
| subscription. |
| get-printer-attributes.test Shows printer attributes |
| get-subscriptions.test Shows a list of subscriptions |
| ipp-1.1.test IPP/1.1 conformance test suite |
| ipp-2.0.test IPP/2.0 conformance test suite |
| ipp-2.1.test IPP/2.1 conformance test suite |
| ipp-2.2.test IPP/2.2 conformance test suite |
| ipp-everywhere.test IPP Everywhere conformance test |
| suite |
| print-job.test Prints a file |
| print-job-deflate.test Prints a file, compressing with |
| deflate. |
| print-job-gzip.test Prints a file, compressing with gzip |
| validate-job.test Validates attributes for a job |
| submission. |
| |
| |
| CONFORMANCE TESTS |
| |
| We provide basic IPP conformance tests for IPP/1.1, IPP/2.0, IPP/2.1, |
| IPP/2.2, and IPP Everywhere. For a given printer URI, the following |
| commands perform tests at each level: |
| |
| ipptool -tf filename [options] -I printer-uri ipp-1.1.test |
| ipptool -tf filename [options] -I -V 2.0 printer-uri ipp-2.0.test |
| ipptool -tf filename [options] -I -V 2.1 printer-uri ipp-2.1.test |
| ipptool -tf filename [options] -I -V 2.2 printer-uri ipp-2.2.test |
| |
| The filename must use a format supported by the printer; ipptool will guess |
| the MIME media type using the extension, otherwise application/octet stream |
| will be used. The following standard test files are included: |
| |
| color.jpg |
| document-a4.pdf |
| document-a4.ps |
| document-letter.pdf |
| document-letter.ps |
| gray.jpg |
| onepage-a4.pdf |
| onepage-a4.ps |
| onepage-letter.pdf |
| onepage-letter.ps |
| testfile.jpg |
| testfile.pcl |
| testfile.pdf |
| testfile.ps |
| testfile.txt |
| |
| Useful options include the following: |
| |
| -4 Connect using IPv4 |
| -6 Connect using IPv6 |
| -C Send chunked requests (default) |
| -d name=val Define a variable |
| -E Test IPP with HTTP Upgrade to TLS |
| -L Send requests using the Content-Length header (HTTP/1.0) |
| -S Test IPP over HTTPS (default for ipps: URIs) |
| -T seconds Set a timeout for responses in seconds |
| -v Be verbose, showing all attributes sent and received |
| -X Produce XML (Apple plist) output |
| |
| The printer-uri must be a URI supported by the printer using the "ipp" or |
| "ipps" scheme, for example: |
| |
| ipp://192.168.0.1/ipp |
| ipps://192.168.0.1/ipp/print |
| |
| Print-by-reference (URL) printing can be tested by defining the document-uri |
| variable as a URL, for example: |
| |
| ipptool -tf filename -d document-uri=url -I printer-uri ipp-1.1.test |
| |
| The standard test files are available on cups.org under the "test" |
| directory, for example: |
| |
| ipptool -tf document-a4.pdf \ |
| -d document-uri=http://www.cups.org/test/document-a4.pdf \ |
| ipp://192.168.0.1/ipp -I -V 2.0 ipp-2.0.test |
| |
| The "document" test files contain 4 pages each. Doing the IPP conformance |
| tests will will produce up to 90 pages on various media, depending on the |
| printer. |
| |
| |
| IPP EVERYWHERE TESTING |
| |
| The IPP Everywhere tests use sample PWG raster files available from: |
| |
| ftp://ftp.pwg.org/pub/pwg/ipp/examples |
| |
| Extract the corresponding ZIP archives into the current directory before |
| running the ipp-everywhere.test file. The test file will attempt to print |
| each PWG Raster file that is supported by the printer being tested - up to |
| 372 pages including the 90 pages produced by the regular IPP test suite. |
| |
| |
| GETTING SUPPORT AND OTHER RESOURCES |
| |
| If you have problems, READ THE DOCUMENTATION FIRST! We also provide |
| discussion forums which are available at: |
| |
| http://www.cups.org/ |
| |
| |
| REPORTING BUGS |
| |
| If you believe you have discovered a bug in ippfind or ipptool, please fill |
| out the bug form at: |
| |
| http://www.cups.org/str.php |
| |
| Be sure to identify the version of CUPS and ippfind/ipptool (if you |
| downloaded the standalone version) you are using, the printer (if any) and |
| firmware version, and include any files that apply. |
| |
| If you downloaded the standalone version of ippfind/ipptool, please also |
| re-run the command with debug logging enabled. Run the following commands |
| on Windows to enable debug logging: |
| |
| setdebug.bat |
| |
| For Linux and Mac OS X use: |
| |
| CUPS_DEBUG_LOG=ipptool.log; export CUPS_DEBUG_LOG |
| CUPS_DEBUG_LEVEL=6; export CUPS_DEBUG_LEVEL |
| |
| Then when you run the ippfind or ipptool command a new "ipptool.log" file |
| will be created with detailed information - attach this file to the bug you |
| file as well. |
| |
| |
| LEGAL STUFF |
| |
| CUPS is Copyright 2007-2013 by Apple Inc. CUPS and the CUPS logo are |
| trademarks of Apple Inc. |
| |
| The MD5 Digest code is Copyright 1999 Aladdin Enterprises. |
| |
| CUPS is provided under the terms of version 2 of the GNU General Public |
| License and GNU Library General Public License. This program is distributed |
| in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even |
| the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. |
| See the "doc/help/license.html" or "LICENSE.txt" files for more information. |
