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.