doc/help/ref-subscriptions-conf.html

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