ref-subscriptions-conf.html [plain text]
<HTML>
<!-- SECTION: References -->
<HEAD>
<TITLE>subscriptions.conf</TITLE>
<LINK REL="STYLESHEET" TYPE="text/css" HREF="../cups-printable.css">
</HEAD>
<BODY>
<H1 CLASS="title">subscriptions.conf</H1>
<P>The CUPS scheduler (cupsd) uses the
<VAR>/etc/cups/subscriptions.conf</VAR> file to store the list
of active subscriptions. Each directive is listed on a line by
itself followed by its value. Comments are introduced using the
number sign ("#") character at the beginning of a line.
<P>While the subscriptions configuration file consists of plain
text and can be modified using your favorite text editor, you
should normally use the command-line programs (<A
HREF="man-lp.html">lp(1)</A> and <A
HREF="man-lpr.html">lpr(1)</A>) or specific applications via IPP
requests to manage your subscriptions.</P>
<H2 CLASS="title"><A NAME="Events">Events</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
<Subscription NNN>
...
Events job-completed
</Subscription>
</PRE>
<H3>Description</H3>
<P>The <CODE>Events</CODE> directive lists the events, separated
by spaces, that the subscriber is interested in. Table 1 lists
the supported event names.</P>
<P>The <CODE>Events</CODE> directive must appear inside a <A
HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
<DIV CLASS="table"><TABLE SUMMARY="Event Names">
<CAPTION>Table 1: <A NAME="TABLE1">Event Names</A></CAPTION>
<THEAD>
<TR>
<TH>Name</TH>
<TH>Description</TH>
</TR>
</THEAD>
<TBODY>
<TR>
<TD>all</TD>
<TD>All events</TD>
</TR>
<TR>
<TD>job-completed</TD>
<TD>Send notification when the job is completed</TD>
</TR>
<TR>
<TD>job-config-changed</TD>
<TD>Send notification when the job is changed</TD>
</TR>
<TR>
<TD>job-created</TD>
<TD>Send notification when a job is created</TD>
</TR>
<TR>
<TD>job-progress</TD>
<TD>Send notification for job progress</TD>
</TR>
<TR>
<TD>job-state-changed</TD>
<TD>Send notification when the job-state changes</TD>
</TR>
<TR>
<TD>job-stopped</TD>
<TD>Send notification when the job is stopped</TD>
</TR>
<TR>
<TD>printer-added</TD>
<TD>Send notification when a printer is added</TD>
</TR>
<TR>
<TD>printer-changed</TD>
<TD>Send notification when a printer is changed</TD>
</TR>
<TR>
<TD>printer-config-changed</TD>
<TD>Send notification when a printer's configuration is changed</TD>
</TR>
<TR>
<TD>printer-deleted</TD>
<TD>Send notification when a printer is deleted</TD>
</TR>
<TR>
<TD>printer-modified</TD>
<TD>Send notification when a printer is modified</TD>
</TR>
<TR>
<TD>printer-state-changed</TD>
<TD>Send notification when the printer-state changes</TD>
</TR>
<TR>
<TD>printer-stopped</TD>
<TD>Send notification when a printer is stopped</TD>
</TR>
<TR>
<TD>server-audit</TD>
<TD>Send notification when a bad request, security error, or
authentication error occurs</TD>
</TR>
<TR>
<TD>server-restarted</TD>
<TD>Send notification when the server is restarted</TD>
</TR>
<TR>
<TD>server-started</TD>
<TD>Send notification when the server is initially started</TD>
</TR>
<TR>
<TD>server-stopped</TD>
<TD>Send notification when the server is shutdown</TD>
</TR>
</TBODY>
</TABLE></DIV>
<H2 CLASS="title"><A NAME="ExpirationTime">ExpirationTime</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
<Subscription NNN>
...
ExpirationTime 1012563145
</Subscription>
</PRE>
<H3>Description</H3>
<P>The <CODE>ExpirationTime</CODE> directive specifies the
expiration time of the subscription as a UNIX time value. It is 0
for subscriptions with no predefined expiration time.</P>
<P>The <CODE>ExpirationTime</CODE> directive must appear inside a
<A HREF="#Subscription"><CODE>Subscription</CODE></A>
section.</P>
<H2 CLASS="title"><A NAME="Interval">Interval</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
<Subscription NNN>
...
Interval 30
</Subscription>
</PRE>
<H3>Description</H3>
<P>The <CODE>Interval</CODE> directive specifies the preferred
time interval for event notifications in seconds.</P>
<P>The <CODE>Interval</CODE> directive must appear inside a <A
HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
<H2 CLASS="title"><A NAME="JobId">JobId</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
<Subscription NNN>
...
JobId 123
</Subscription>
</PRE>
<H3>Description</H3>
<P>The <CODE>JobId</CODE> directive specifies the
<CODE>job-id</CODE> for job subscriptions.</P>
<P>The <CODE>JobId</CODE> directive must appear inside a <A
HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
<H2 CLASS="title"><A NAME="LeaseDuration">LeaseDuration</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
<Subscription NNN>
...
LeaseDuration
</Subscription>
</PRE>
<H3>Description</H3>
<P>The <CODE>LeaseDuration</CODE> directive specifies the number
of seconds that the subscription is valid. A value of 0 means
that the subscription will last forever or the life of the print
job the subscription is attached to.</P>
<P>The <CODE>LeaseDuration</CODE> directive must appear inside a <A
HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
<H2 CLASS="title"><A NAME="NextEventId">NextEventId</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
<Subscription NNN>
...
NextEventId 999
</Subscription>
</PRE>
<H3>Description</H3>
<P>The <CODE>NextEventId</CODE> directive specifies the
<CODE>notify-sequence-number</CODE> value for the next
notification event. It starts at 1 and increases for every event
that is delivered for the subscription.</P>
<P>The <CODE>NextEventId</CODE> directive must appear inside a <A
HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
<H2 CLASS="title"><A NAME="NextSubscriptionId">NextSubscriptionId</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
NextSubscriptionId 999
</PRE>
<H3>Description</H3>
<P>The <CODE>NextSubscriptionId</CODE> directive specifies the
next subscription ID to use. It defaults to 1 more than the
highest subscription number seen.</P>
<H2 CLASS="title"><A NAME="Owner">Owner</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
<Subscription NNN>
...
Owner username
</Subscription>
</PRE>
<H3>Description</H3>
<P>The <CODE>Owner</CODE> directive specifies the user that owns
this subscription.</P>
<P>The <CODE>Owner</CODE> directive must appear inside a <A
HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
<H2 CLASS="title"><A NAME="PrinterName">PrinterName</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
<Subscription NNN>
...
PrinterName name
</Subscription>
</PRE>
<H3>Description</H3>
<P>The <CODE>PrinterName</CODE> directive specifies the name of
the printer or class that is associated with this
subscription.</P>
<P>The <CODE>PrinterName</CODE> directive must appear inside a <A
HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
<H2 CLASS="title"><A NAME="Recipient">Recipient</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
<Subscription NNN>
...
Recipient mailto:foo@domain.com
</Subscription>
</PRE>
<H3>Description</H3>
<P>The <CODE>Recipient</CODE> directive specifies the
<CODE>notify-recipient-uri</CODE> value for push-type
notifications. The URI scheme name determines which notifier
program is used to send the event(s).</P>
<P>The <CODE>Recipient</CODE> directive must appear inside a <A
HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
<H2 CLASS="title"><A NAME="Subscription">Subscription</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
<Subscription NNN>
...
</Subscription>
</PRE>
<H3>Description</H3>
<P>The <CODE>Subscription</CODE> section defines a single
subscription in the system. Each subscription is assigned a
unique (to the server) number starting at 1.</P>
<H2 CLASS="title"><A NAME="UserData">UserData</A></H2>
<H3>Examples</H3>
<PRE CLASS="command">
<Subscription NNN>
...
UserData mailto:bar<40>domain.com
</Subscription>
</PRE>
<H3>Description</H3>
<P>The <CODE>UserData</CODE> directive specifies the
<CODE>notify-user-data</CODE> value, which is normally the "from"
address used in <CODE>mailto</CODE> notifications. Binary values
are introduced by encoding the bytes as hexadecimal values inside
angle brackets, e.g. "<1234>".</P>
<P>The <CODE>UserData</CODE> directive must appear inside a <A
HREF="#Subscription"><CODE>Subscription</CODE></A> section.</P>
</BODY>
</HTML>