IPPTOOL.txt - 2012-02-06 ------------------------ See the file CHANGES-IPPTOOL.txt for a list of changes to this software. INTRODUCTION CUPS includes a user program called ipptool that 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. 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-printer-attributes.test Shows printer attributes 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 print-job.test Prints a file CONFORMANCE TESTS We provide basic IPP conformance tests for IPP/1.1, IPP/2.0, IPP/2.1, and IPP/2.2. 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 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 to 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. READING THE DOCUMENTATION The command usage is described in the ipptest(1) man page, while the file format is described in the ipptestfile(5) man page. Both are provided in HTML format with the standalone releases of ipptool. GETTING SUPPORT AND OTHER RESOURCES If you have problems, READ THE DOCUMENTATION FIRST! We also provide many discussion forums which are available at: http://www.cups.org/newsgroups.php See the CUPS web site at "http://www.cups.org/" for other resources. REPORTING BUGS If you believe you have discovered a bug in ipptool, please fill out the bug form at: http://www.cups.org/str.php Be sure to identify the version of CUPS and 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 ipptool, please also re-run the test 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 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-2012 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.