IPPTOOL.txt

   1 IPPTOOL.txt - 2013-07-15
   2 ------------------------
   3
   4 See the file CHANGES-IPPTOOL.txt for a list of changes to this software.
   5
   6
   7 INTRODUCTION
   8
   9     CUPS includes two user programs for IPP printers.  The first is called
  10     ipptool and can be used to send arbitrary IPP requests to a CUPS server or
  11     IPP printer.  This tool started life as part of the CUPS automated test
  12     suite and has grown to support complex conformance tests and a simple way
  13     to query printer, job, and subscription attributes.
  14
  15     The second program called ippfind that can be used to find IPP printers
  16     that have registered themselves using Bonjour (DNS-SD, mDNS, and Zeroconf)
  17     and run commands such as ipptool.
  18
  19
  20 READING THE DOCUMENTATION
  21
  22     Full documentation on the ipptool command can be found in the
  23     "man-ipptool.html" and "man-ipptoolfile.html" files; the latter describes
  24     the test file format supported by ipptool.
  25
  26     Full documentation on the ippfind command can be found in the
  27     "man-ippfind.html" file.
  28
  29
  30 IPPFIND BASIC USAGE
  31
  32     The ippfind command can be used to discover IPP printers on your network.
  33     For example, the following command prints the printer URI of registered IPP
  34     printers:
  35
  36         ippfind
  37
  38     To find all color IPP printers, run:
  39
  40         ippfind --txt-color T
  41
  42     And to run the IPP Everywhere conformance test file on every registered IPP
  43     printer, run the following command:
  44
  45         ippfind _ipp._tcp,_print --exec ipptool -t '{}' ipp-everywhere.test \;
  46
  47
  48 IPPTOOL BASIC USAGE
  49
  50     The ipptool command requires a printer URI and one or more "test" files that
  51     describe the operations, attributes to display, and expected status and
  52     attribute values. Several standard files are included with CUPS, for example
  53     to show a list of pending print jobs on a CUPS printer called "myprinter"
  54     you'd run:
  55
  56         ipptool ipp://localhost/printers/myprinter get-jobs.test
  57
  58     which would produce something like this:
  59
  60         job-id job-state    job-name     job-originating-user-name
  61         ------ ------------ ------------ -------------------------
  62         72     pending      testfile.pdf msweet
  63         73     pending      testfile.ps  msweet
  64         74     pending-held testfile.jpg msweet
  65         75     pending-held testfile.txt msweet
  66
  67     To get output suitable for import into a spreadsheet, use the "-c" (CSV)
  68     option:
  69
  70         ipptool -c ipp://localhost/printers/myprinter get-jobs.test
  71
  72     which will produce something like this:
  73
  74         job-id,job-state,job-name,job-originating-user-name
  75         72,pending,testfile.pdf,msweet
  76         73,pending,testfile.ps,msweet
  77         74,pending-held,testfile.jpg,msweet
  78         75,pending-held,testfile.txt,msweet
  79
  80
  81 STANDARD TEST FILES
  82
  83     The following standard test files are included with ipptool:
  84
  85         create-printer-subscription.test    Creates a printer subscription for
  86                                             state change notifications
  87         get-completed-jobs.test             Shows a list of completed jobs
  88         get-jobs.test                       Shows a list of pending jobs
  89         get-notifications.test              Shows events for an ippget
  90                                             subscription.
  91         get-printer-attributes.test         Shows printer attributes
  92         get-subscriptions.test              Shows a list of subscriptions
  93         ipp-1.1.test                        IPP/1.1 conformance test suite
  94         ipp-2.0.test                        IPP/2.0 conformance test suite
  95         ipp-2.1.test                        IPP/2.1 conformance test suite
  96         ipp-2.2.test                        IPP/2.2 conformance test suite
  97         ipp-everywhere.test                 IPP Everywhere conformance test
  98                                             suite
  99         print-job.test                      Prints a file
 100         print-job-deflate.test              Prints a file, compressing with
 101                                             deflate.
 102         print-job-gzip.test                 Prints a file, compressing with gzip
 103         validate-job.test                   Validates attributes for a job
 104                                             submission.
 105
 106
 107 CONFORMANCE TESTS
 108
 109     We provide basic IPP conformance tests for IPP/1.1, IPP/2.0, IPP/2.1,
 110     IPP/2.2, and IPP Everywhere.  For a given printer URI, the following
 111     commands perform tests at each level:
 112
 113         ipptool -tf filename [options] -I printer-uri ipp-1.1.test
 114         ipptool -tf filename [options] -I -V 2.0 printer-uri ipp-2.0.test
 115         ipptool -tf filename [options] -I -V 2.1 printer-uri ipp-2.1.test
 116         ipptool -tf filename [options] -I -V 2.2 printer-uri ipp-2.2.test
 117
 118     The filename must use a format supported by the printer; ipptool will guess
 119     the MIME media type using the extension, otherwise application/octet stream
 120     will be used.  The following standard test files are included:
 121
 122         color.jpg
 123         document-a4.pdf
 124         document-a4.ps
 125         document-letter.pdf
 126         document-letter.ps
 127         gray.jpg
 128         onepage-a4.pdf
 129         onepage-a4.ps
 130         onepage-letter.pdf
 131         onepage-letter.ps
 132         testfile.jpg
 133         testfile.pcl
 134         testfile.pdf
 135         testfile.ps
 136         testfile.txt
 137
 138     Useful options include the following:
 139
 140         -4           Connect using IPv4
 141         -6           Connect using IPv6
 142         -C           Send chunked requests (default)
 143         -d name=val  Define a variable
 144         -E           Test IPP with HTTP Upgrade to TLS
 145         -L           Send requests using the Content-Length header (HTTP/1.0)
 146         -S           Test IPP over HTTPS (default for ipps: URIs)
 147         -T seconds   Set a timeout for responses in seconds
 148         -v           Be verbose, showing all attributes sent and received
 149         -X           Produce XML (Apple plist) output
 150
 151     The printer-uri must be a URI supported by the printer using the "ipp" or
 152     "ipps" scheme, for example:
 153
 154         ipp://192.168.0.1/ipp
 155         ipps://192.168.0.1/ipp/print
 156
 157     Print-by-reference (URL) printing can be tested by defining the document-uri
 158     variable as a URL, for example:
 159
 160         ipptool -tf filename -d document-uri=url -I printer-uri ipp-1.1.test
 161
 162     The standard test files are available on cups.org under the "test"
 163     directory, for example:
 164
 165         ipptool -tf document-a4.pdf \
 166             -d document-uri=http://www.cups.org/test/document-a4.pdf \
 167             ipp://192.168.0.1/ipp -I -V 2.0 ipp-2.0.test
 168
 169     The "document" test files contain 4 pages each.  Doing the IPP conformance
 170     tests will will produce up to 90 pages on various media, depending on the
 171     printer.
 172
 173
 174 IPP EVERYWHERE TESTING
 175
 176     The IPP Everywhere tests use sample PWG raster files available from:
 177
 178         ftp://ftp.pwg.org/pub/pwg/ipp/examples
 179
 180     Extract the corresponding ZIP archives into the current directory before
 181     running the ipp-everywhere.test file.  The test file will attempt to print
 182     each PWG Raster file that is supported by the printer being tested - up to
 183     372 pages including the 90 pages produced by the regular IPP test suite.
 184
 185
 186 GETTING SUPPORT AND OTHER RESOURCES
 187
 188     If you have problems, READ THE DOCUMENTATION FIRST!  We also provide
 189     discussion forums which are available at:
 190
 191         http://www.cups.org/
 192
 193
 194 REPORTING BUGS
 195
 196     If you believe you have discovered a bug in ippfind or ipptool, please fill
 197     out the bug form at:
 198
 199         http://www.cups.org/str.php
 200
 201     Be sure to identify the version of CUPS and ippfind/ipptool (if you
 202     downloaded the standalone version) you are using, the printer (if any) and
 203     firmware version, and include any files that apply.
 204
 205     If you downloaded the standalone version of ippfind/ipptool, please also
 206     re-run the command with debug logging enabled.  Run the following commands
 207     on Windows to enable debug logging:
 208
 209         setdebug.bat
 210
 211     For Linux and Mac OS X use:
 212
 213         CUPS_DEBUG_LOG=ipptool.log; export CUPS_DEBUG_LOG
 214         CUPS_DEBUG_LEVEL=6; export CUPS_DEBUG_LEVEL
 215
 216     Then when you run the ippfind or ipptool command a new "ipptool.log" file
 217     will be created with detailed information - attach this file to the bug you
 218     file as well.
 219
 220
 221 LEGAL STUFF
 222
 223     CUPS is Copyright 2007-2013 by Apple Inc.  CUPS and the CUPS logo are
 224     trademarks of Apple Inc.
 225
 226     The MD5 Digest code is Copyright 1999 Aladdin Enterprises.
 227
 228     CUPS is provided under the terms of version 2 of the GNU General Public
 229     License and GNU Library General Public License. This program is distributed
 230     in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even
 231     the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
 232     See the "doc/help/license.html" or "LICENSE.txt" files for more information.