[thirdparty/cups.git] / IPPTOOL.txt

IPPTOOL.txt - 2013-05-02
------------------------

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-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.


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