man/ippeveprinter.1

   1 .\"
   2 .\" ippeveprinter man page for CUPS.
   3 .\"
   4 .\" Copyright © 2014-2019 by Apple Inc.
   5 .\"
   6 .\" Licensed under Apache License v2.0.  See the file "LICENSE" for more
   7 .\" information.
   8 .\"
   9 .TH ippeveprinter 1 "CUPS" "2 December 2019" "Apple Inc."
  10 .SH NAME
  11 ippeveprinter \- an ipp everywhere printer application for cups
  12 .SH SYNOPSIS
  13 .B ippeveprinter
  14 [
  15 .B \-\-help
  16 ] [
  17 .B \-\-no\-web\-forms
  18 ] [
  19 .B \-\-pam\-service
  20 .I service
  21 ] [
  22 .B \-\-version
  23 ] [
  24 .B \-2
  25 ] [
  26 .B \-A
  27 ] [
  28 .B \-D
  29 .I device-uri
  30 ] [
  31 .B \-F
  32 .I output-type/subtype
  33 ] [
  34 .B \-K
  35 .I keypath
  36 ] [
  37 .B \-M
  38 .I manufacturer
  39 ] [
  40 .B \-P
  41 .I filename.ppd
  42 ] [
  43 .B \-V
  44 .I ipp-version
  45 ] [
  46 .B \-a
  47 .I filename.conf
  48 ] [
  49 .B \-c
  50 .I command
  51 ] [
  52 .B \-d
  53 .I spool-directory
  54 ] [
  55 .B \-f
  56 .I type/subtype[,...]
  57 ] [
  58 .B \-i
  59 .I iconfile.png
  60 ] [
  61 .B \-k
  62 ] [
  63 .B \-l
  64 .I location
  65 ] [
  66 .B \-m
  67 .I model
  68 ] [
  69 .B \-n
  70 .I hostname
  71 ] [
  72 .B \-p
  73 .I port
  74 ] [
  75 .B \-r
  76 .I subtype[,subtype]
  77 ] [
  78 .B \-s
  79 .I speed[,color-speed]
  80 ] [
  81 .B \-v[vvv]
  82 ]
  83 .I service-name
  84 .SH DESCRIPTION
  85 .B ippeveprinter
  86 is a simple Internet Printing Protocol (IPP) server conforming to the IPP Everywhere (PWG 5100.14) specification. It can be used to test client software or act as a very basic print server that runs a command for every job that is printed.
  87 .SH OPTIONS
  88 The following options are recognized by
  89 .B ippeveprinter:
  90 .TP 5
  91 .B \-\-help
  92 Show program usage.
  93 .TP 5
  94 .B \-\-no\-web\-forms
  95 Disable the web interface forms used to update the media and supply levels.
  96 .TP 5
  97 \fB\-\-pam\-service \fIservice\fR
  98 Set the PAM service name.
  99 The default service is "cups".
 100 .TP 5
 101 .B \-\-version
 102 Show the CUPS version.
 103 .TP 5
 104 .B \-2
 105 Report support for two-sided (duplex) printing.
 106 .TP 5
 107 .B \-A
 108 Enable authentication for the created printer.
 109 .B ippeveprinter
 110 uses PAM to authenticate HTTP Basic credentials.
 111 .TP 5
 112 \fB\-D \fIdevice-uri\fR
 113 Set the device URI for print output.
 114 The URI can be a filename, directory, or a network socket URI of the form "socket://ADDRESS[:PORT]" (where the default port number is 9100).
 115 When specifying a directory,
 116 .B ippeveprinter
 117 will create an output file using the job ID and name.
 118 .TP 5
 119 \fB\-F \fIoutput-type/subtype[,...]\fR
 120 Specifies the output MIME media type.
 121 The default is "application/postscript" when the \fB\-P\fR option is specified.
 122 .TP 5
 123 \fB\-M \fImanufacturer\fR
 124 Set the manufacturer of the printer.
 125 The default is "Example".
 126 .TP 5
 127 \fB\-P \fIfilename.ppd\fR
 128 Load printer attributes from the specified PPD file.
 129 This option is typically used in conjunction with the
 130 .BR ippeveps (7)
 131 printer command ("\-c ippeveps").
 132 .TP 5
 133 \fB\-V 1.1\fR
 134 .TP 5
 135 \fB\-V 2.0\fR
 136 Specifies the maximum IPP version to report.
 137 2.0 is the default.
 138 .TP 5
 139 \fB\-c \fIcommand\fR
 140 Run the specified command for each document that is printed.
 141 If "command" is not an absolute path ("/path/to/command"),
 142 .B ippeveprinter
 143 looks for the command in the "command" subdirectory of the CUPS binary directory, typically /usr/lib/cups/command or /usr/libexec/cups/command.
 144 The
 145 .BR cups-config (1)
 146 command can be used to discover the correct binary directory ("cups-config --serverbin").
 147 In addition, the CUPS_SERVERBIN environment variable can be used to override the default location of this directory - see the
 148 .BR cups (1)
 149 man page for more details.
 150 .TP 5
 151 \fB\-d \fIspool-directory\fR
 152 Specifies the directory that will hold the print files.
 153 The default is a directory under the user's current temporary directory.
 154 .TP 5
 155 \fB\-f \fItype/subtype[,...]\fR
 156 Specifies a list of MIME media types that the server will accept.
 157 The default depends on the type of printer created.
 158 .TP 5
 159 \fB\-i \fIiconfile.png\fR
 160 Specifies the printer icon file for the server.
 161 The file must be a PNG format image.
 162 The default is an internally-provided PNG image.
 163 .TP 5
 164 .B \-k
 165 Keeps the print documents in the spool directory rather than deleting them.
 166 .TP 5
 167 \fB\-l \fIlocation\fR
 168 Specifies the human-readable location string that is reported by the server.
 169 The default is the empty string.
 170 .TP 5
 171 \fB\-m \fImodel\fR
 172 Specifies the model name of the printer.
 173 The default is "Printer".
 174 .TP 5
 175 \fB\-n \fIhostname\fR
 176 Specifies the hostname that is reported by the server.
 177 The default is the name returned by the
 178 .BR hostname (1)
 179 command.
 180 .TP 5
 181 \fB\-p \fIport\fR
 182 Specifies the port number to listen on.
 183 The default is a user-specific number from 8000 to 8999.
 184 .TP 5
 185 .B \-r off
 186 Turns off DNS-SD service advertisements entirely.
 187 .TP 5
 188 \fB\-r \fIsubtype[,subtype]\fR
 189 Specifies the DNS-SD subtype(s) to advertise.
 190 Separate multiple subtypes with a comma.
 191 The default is "_print".
 192 .TP 5
 193 \fB\-s \fIspeed[,color-speed]\fR
 194 Specifies the printer speed in pages per minute.
 195 If two numbers are specified and the second number is greater than zero, the server will report support for color printing.
 196 The default is "10,0".
 197 .TP 5
 198 .B \-v[vvv]
 199 Be (very) verbose when logging activity to standard error.
 200 .SH EXIT STATUS
 201 The
 202 .B ippeveprinter
 203 program returns 1 if it is unable to process the command-line arguments or register the IPP service.
 204 Otherwise
 205 .B ippeveprinter
 206 will run continuously until terminated.
 207 .SH CONFORMING TO
 208 The
 209 .B ippeveprinter
 210 program is unique to CUPS and conforms to the IPP Everywhere (PWG 5100.14) specification.
 211 .SH ENVIRONMENT
 212 .B ippeveprinter
 213 adds environment variables starting with "IPP_" for all IPP Job attributes in the print request.
 214 For example, when executing a command for an IPP Job containing the "media" Job Template attribute, the "IPP_MEDIA" environment variable will be set to the value of that attribute.
 215 .LP
 216 In addition, all IPP "xxx-default" and "pwg-xxx" Printer Description attributes are added to the environment.
 217 For example, the "IPP_MEDIA_DEFAULT" environment variable will be set to the default value for the "media" Job Template attribute.
 218 .LP
 219 Enumerated values are converted to their keyword equivalents.
 220 For example, a "print-quality" Job Template attribute with a enum value of 3 will become the "IPP_PRINT_QUALITY" environment variable with a value of "draft".
 221 This string conversion only happens for standard Job Template attributes, currently "finishings", "orientation-requested", and "print-quality".
 222 .LP
 223 Finally, the "CONTENT_TYPE" environment variable contains the MIME media type of the document being printed, the "DEVICE_URI" environment variable contains the device URI as specified with the "\-D" option, the "OUTPUT_FORMAT" environment variable contains the output MIME media type, and the "PPD" environment variable contains the PPD filename as specified with the "\-P" option.
 224 .SH COMMAND OUTPUT
 225 Unless they communicate directly with a printer, print commands send printer-ready data to the standard output.
 226 .LP
 227 Print commands can send messages back to
 228 .B ippeveprinter
 229 on the standard error with one of the following prefixes:
 230 .TP 5
 231 \fBATTR: \fIattribute=value[ attribute=value]\fR
 232 Sets the named attribute(s) to the given values.
 233 Currently only the "job-impressions" and "job-impressions-completed" Job Status attributes and the "marker-xxx", "printer-alert", "printer-alert-description", "printer-supply", and "printer-supply-description" Printer Status attributes can be set.
 234 .TP 5
 235 \fBDEBUG: \fIDebugging message\fR
 236 Logs a debugging message if at least two \-v's have been specified.
 237 .TP 5
 238 \fBERROR: \fIError message\fR
 239 Logs an error message and copies the message to the "job-state-message" attribute.
 240 .TP 5
 241 \fBINFO: \fIInformational message\fR
 242 Logs an informational/progress message if \-v has been specified and copies the message to the "job-state-message" attribute unless an error has been reported.
 243 .TP 5
 244 \fBSTATE: \fIkeyword[,keyword,...]\fR
 245 Sets the printer's "printer-state-reasons" attribute to the listed keywords.
 246 .TP 5
 247 \fBSTATE: -\fIkeyword[,keyword,...]\fR
 248 Removes the listed keywords from the printer's "printer-state-reasons" attribute.
 249 .TP 5
 250 \fBSTATE: +\fIkeyword[,keyword,...]\fR
 251 Adds the listed keywords to the printer's "printer-state-reasons" attribute.
 252 .SH EXAMPLES
 253 Run
 254 .B ippeveprinter
 255 with a service name of My Cool Printer:
 256 .nf
 257
 258     ippeveprinter "My Cool Printer"
 259 .fi
 260 .LP
 261 Run the
 262 .BR file (1)
 263 command whenever a job is sent to the server:
 264 .nf
 265
 266     ippeveprinter \-c /usr/bin/file "My Cool Printer"
 267 .fi
 268 .SH SEE ALSO
 269 .BR ippevepcl (7),
 270 .BR ippeveps (7),
 271 PWG Internet Printing Protocol Workgroup (http://www.pwg.org/ipp)
 272 .SH COPYRIGHT
 273 Copyright \[co] 2007-2019 by Apple Inc.