doc/help/ref-subscriptions-conf.html

   1 <HTML>
   2 <!-- SECTION: References -->
   3 <HEAD>
   4         <TITLE>subscriptions.conf</TITLE>
   5         <LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
   6 </HEAD>
   7 <BODY>
   8
   9 <H1 CLASS="title">subscriptions.conf</H1>
  10
  11 <P>The CUPS scheduler (cupsd) uses the
  12 <VAR>/etc/cups/subscriptions.conf</VAR> file  to store the list
  13 of active subscriptions. Each directive is listed on a line by
  14 itself followed by its value.  Comments are introduced using the
  15 number sign ("#") character at the beginning of a line.
  16
  17 <P>While the subscriptions configuration file consists of plain
  18 text and can be modified using your favorite text editor, you
  19 should normally use the command-line programs (<A
  20 HREF="man-lp.html">lp(1)</A> and <A
  21 HREF="man-lpr.html">lpr(1)</A>) or specific applications via IPP
  22 requests to manage your subscriptions.</P>
  23
  24 <H2 CLASS="title"><A NAME="Events">Events</A></H2>
  25
  26 <H3>Examples</H3>
  27
  28 <PRE CLASS="command">
  29 &lt;Subscription NNN&gt;
  30   ...
  31   Events job-completed
  32 &lt;/Subscription&gt;
  33 </PRE>
  34
  35 <H3>Description</H3>
  36
  37 <P>The <CODE>Events</CODE> directive lists the events, separated
  38 by spaces, that the subscriber is interested in. Table 1 lists
  39 the supported event names.</P>
  40
  41 <P>The <CODE>Events</CODE> directive must appear inside a <A
  42 HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
  43
  44 <DIV CLASS="table"><TABLE SUMMARY="Event Names">
  45 <CAPTION>Table 1: <A NAME="TABLE1">Event Names</A></CAPTION>
  46 <THEAD>
  47 <TR>
  48         <TH>Name</TH>
  49         <TH>Description</TH>
  50 </TR>
  51 </THEAD>
  52 <TBODY>
  53 <TR>
  54         <TD>all</TD>
  55         <TD>All events</TD>
  56 </TR>
  57 <TR>
  58         <TD>job-completed</TD>
  59         <TD>Send notification when the job is completed</TD>
  60 </TR>
  61 <TR>
  62         <TD>job-config-changed</TD>
  63         <TD>Send notification when the job is changed</TD>
  64 </TR>
  65 <TR>
  66         <TD>job-created</TD>
  67         <TD>Send notification when a job is created</TD>
  68 </TR>
  69 <TR>
  70         <TD>job-progress</TD>
  71         <TD>Send notification for job progress</TD>
  72 </TR>
  73 <TR>
  74         <TD>job-state-changed</TD>
  75         <TD>Send notification when the job-state changes</TD>
  76 </TR>
  77 <TR>
  78         <TD>job-stopped</TD>
  79         <TD>Send notification when the job is stopped</TD>
  80 </TR>
  81 <TR>
  82         <TD>printer-added</TD>
  83         <TD>Send notification when a printer is added</TD>
  84 </TR>
  85 <TR>
  86         <TD>printer-changed</TD>
  87         <TD>Send notification when a printer is changed</TD>
  88 </TR>
  89 <TR>
  90         <TD>printer-config-changed</TD>
  91         <TD>Send notification when a printer's configuration is changed</TD>
  92 </TR>
  93 <TR>
  94         <TD>printer-deleted</TD>
  95         <TD>Send notification when a printer is deleted</TD>
  96 </TR>
  97 <TR>
  98         <TD>printer-modified</TD>
  99         <TD>Send notification when a printer is modified</TD>
 100 </TR>
 101 <TR>
 102         <TD>printer-state-changed</TD>
 103         <TD>Send notification when the printer-state changes</TD>
 104 </TR>
 105 <TR>
 106         <TD>printer-stopped</TD>
 107         <TD>Send notification when a printer is stopped</TD>
 108 </TR>
 109 <TR>
 110         <TD>server-audit</TD>
 111         <TD>Send notification when a bad request, security error, or
 112         authentication error occurs</TD>
 113 </TR>
 114 <TR>
 115         <TD>server-restarted</TD>
 116         <TD>Send notification when the server is restarted</TD>
 117 </TR>
 118 <TR>
 119         <TD>server-started</TD>
 120         <TD>Send notification when the server is initially started</TD>
 121 </TR>
 122 <TR>
 123         <TD>server-stopped</TD>
 124         <TD>Send notification when the server is shutdown</TD>
 125 </TR>
 126 </TBODY>
 127 </TABLE></DIV>
 128
 129
 130 <H2 CLASS="title"><A NAME="ExpirationTime">ExpirationTime</A></H2>
 131
 132 <H3>Examples</H3>
 133
 134 <PRE CLASS="command">
 135 &lt;Subscription NNN&gt;
 136   ...
 137   ExpirationTime 1012563145
 138 &lt;/Subscription&gt;
 139 </PRE>
 140
 141 <H3>Description</H3>
 142
 143 <P>The <CODE>ExpirationTime</CODE> directive specifies the
 144 expiration time of the subscription as a UNIX time value. It is 0
 145 for subscriptions with no predefined expiration time.</P>
 146
 147 <P>The <CODE>ExpirationTime</CODE> directive must appear inside a
 148 <A HREF="#Subscription"><CODE>Subscription</CODE></A>
 149 section.</P>
 150
 151
 152 <H2 CLASS="title"><A NAME="Interval">Interval</A></H2>
 153
 154 <H3>Examples</H3>
 155
 156 <PRE CLASS="command">
 157 &lt;Subscription NNN&gt;
 158   ...
 159   Interval 30
 160 &lt;/Subscription&gt;
 161 </PRE>
 162
 163 <H3>Description</H3>
 164
 165 <P>The <CODE>Interval</CODE> directive specifies the preferred
 166 time interval for event notifications in seconds.</P>
 167
 168 <P>The <CODE>Interval</CODE> directive must appear inside a <A
 169 HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
 170
 171
 172 <H2 CLASS="title"><A NAME="JobId">JobId</A></H2>
 173
 174 <H3>Examples</H3>
 175
 176 <PRE CLASS="command">
 177 &lt;Subscription NNN&gt;
 178   ...
 179   JobId 123
 180 &lt;/Subscription&gt;
 181 </PRE>
 182
 183 <H3>Description</H3>
 184
 185 <P>The <CODE>JobId</CODE> directive specifies the
 186 <CODE>job-id</CODE> for job subscriptions.</P>
 187
 188 <P>The <CODE>JobId</CODE> directive must appear inside a <A
 189 HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
 190
 191
 192 <H2 CLASS="title"><A NAME="LeaseDuration">LeaseDuration</A></H2>
 193
 194 <H3>Examples</H3>
 195
 196 <PRE CLASS="command">
 197 &lt;Subscription NNN&gt;
 198   ...
 199   LeaseDuration
 200 &lt;/Subscription&gt;
 201 </PRE>
 202
 203 <H3>Description</H3>
 204
 205 <P>The <CODE>LeaseDuration</CODE> directive specifies the number
 206 of seconds that the subscription is valid. A value of 0 means
 207 that the subscription will last forever or the life of the print
 208 job the subscription is attached to.</P>
 209
 210 <P>The <CODE>LeaseDuration</CODE> directive must appear inside a <A
 211 HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
 212
 213
 214 <H2 CLASS="title"><A NAME="NextEventId">NextEventId</A></H2>
 215
 216 <H3>Examples</H3>
 217
 218 <PRE CLASS="command">
 219 &lt;Subscription NNN&gt;
 220   ...
 221   NextEventId 999
 222 &lt;/Subscription&gt;
 223 </PRE>
 224
 225 <H3>Description</H3>
 226
 227 <P>The <CODE>NextEventId</CODE> directive specifies the
 228 <CODE>notify-sequence-number</CODE> value for the next
 229 notification event. It starts at 1 and increases for every event
 230 that is delivered for the subscription.</P>
 231
 232 <P>The <CODE>NextEventId</CODE> directive must appear inside a <A
 233 HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
 234
 235
 236 <H2 CLASS="title"><A NAME="NextSubscriptionId">NextSubscriptionId</A></H2>
 237
 238 <H3>Examples</H3>
 239
 240 <PRE CLASS="command">
 241 NextSubscriptionId 999
 242 </PRE>
 243
 244 <H3>Description</H3>
 245
 246 <P>The <CODE>NextSubscriptionId</CODE> directive specifies the
 247 next subscription ID to use. It defaults to 1 more than the
 248 highest subscription number seen.</P>
 249
 250
 251 <H2 CLASS="title"><A NAME="Owner">Owner</A></H2>
 252
 253 <H3>Examples</H3>
 254
 255 <PRE CLASS="command">
 256 &lt;Subscription NNN&gt;
 257   ...
 258   Owner username
 259 &lt;/Subscription&gt;
 260 </PRE>
 261
 262 <H3>Description</H3>
 263
 264 <P>The <CODE>Owner</CODE> directive specifies the user that owns
 265 this subscription.</P>
 266
 267 <P>The <CODE>Owner</CODE> directive must appear inside a <A
 268 HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
 269
 270
 271 <H2 CLASS="title"><A NAME="PrinterName">PrinterName</A></H2>
 272
 273 <H3>Examples</H3>
 274
 275 <PRE CLASS="command">
 276 &lt;Subscription NNN&gt;
 277   ...
 278   PrinterName name
 279 &lt;/Subscription&gt;
 280 </PRE>
 281
 282 <H3>Description</H3>
 283
 284 <P>The <CODE>PrinterName</CODE> directive specifies the name of
 285 the printer or class that is associated with this
 286 subscription.</P>
 287
 288 <P>The <CODE>PrinterName</CODE> directive must appear inside a <A
 289 HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
 290
 291
 292 <H2 CLASS="title"><A NAME="Recipient">Recipient</A></H2>
 293
 294 <H3>Examples</H3>
 295
 296 <PRE CLASS="command">
 297 &lt;Subscription NNN&gt;
 298   ...
 299   Recipient mailto:foo@domain.com
 300 &lt;/Subscription&gt;
 301 </PRE>
 302
 303 <H3>Description</H3>
 304
 305 <P>The <CODE>Recipient</CODE> directive specifies the
 306 <CODE>notify-recipient-uri</CODE> value for push-type
 307 notifications. The URI scheme name determines which notifier
 308 program is used to send the event(s).</P>
 309
 310 <P>The <CODE>Recipient</CODE> directive must appear inside a <A
 311 HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
 312
 313
 314 <H2 CLASS="title"><A NAME="Subscription">Subscription</A></H2>
 315
 316 <H3>Examples</H3>
 317
 318 <PRE CLASS="command">
 319 &lt;Subscription NNN&gt;
 320   ...
 321 &lt;/Subscription&gt;
 322 </PRE>
 323
 324 <H3>Description</H3>
 325
 326 <P>The <CODE>Subscription</CODE> section defines a single
 327 subscription in the system. Each subscription is assigned a
 328 unique (to the server) number starting at 1.</P>
 329
 330
 331 <H2 CLASS="title"><A NAME="UserData">UserData</A></H2>
 332
 333 <H3>Examples</H3>
 334
 335 <PRE CLASS="command">
 336 &lt;Subscription NNN&gt;
 337   ...
 338   UserData mailto:bar&lt;40&gt;example.com
 339 &lt;/Subscription&gt;
 340 </PRE>
 341
 342 <H3>Description</H3>
 343
 344 <P>The <CODE>UserData</CODE> directive specifies the
 345 <CODE>notify-user-data</CODE> value, which is normally the "to"
 346 address used in <CODE>mailto</CODE> notifications. Binary values
 347 are introduced by encoding the bytes as hexadecimal values inside
 348 angle brackets, e.g. "&lt;1234&gt;".</P>
 349
 350 <P>The <CODE>UserData</CODE> directive must appear inside a <A
 351 HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
 352
 353 </BODY>
 354 </HTML>