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.