# subscriptions.conf

The CUPS scheduler (cupsd) uses the /etc/cups/subscriptions.conf 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.

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 (lp(1) and lpr(1)) or specific applications via IPP requests to manage your subscriptions.

## Events

### Examples

    <Subscription NNN>
      ...
      Events job-completed
    </Subscription>

### Description

The `Events` directive lists the events, separated by spaces, that the subscriber is interested in. Table 1 lists the supported event names.

The `Events` directive must appear inside a `Subscription` section.

Table 1: Event Names
Name | Description
--- | ---
all | All events
job-completed | Send notification when the job is completed
job-config-changed | Send notification when the job is changed
job-created | Send notification when a job is created
job-progress | Send notification for job progress
job-state-changed | Send notification when the job-state changes
job-stopped | Send notification when the job is stopped
printer-added | Send notification when a printer is added
printer-changed | Send notification when a printer is changed
printer-config-changed | Send notification when a printer's configuration is changed
printer-deleted | Send notification when a printer is deleted
printer-modified | Send notification when a printer is modified
printer-state-changed | Send notification when the printer-state changes
printer-stopped | Send notification when a printer is stopped
server-audit | Send notification when a bad request, security error, or authentication error occurs
server-restarted | Send notification when the server is restarted
server-started | Send notification when the server is initially started
server-stopped | Send notification when the server is shutdown

## ExpirationTime

### Examples

    <Subscription NNN>
      ...
      ExpirationTime 1012563145
    </Subscription>

### Description

The `ExpirationTime` directive specifies the expiration time of the subscription as a UNIX time value. It is 0 for subscriptions with no predefined expiration time.

The `ExpirationTime` directive must appear inside a `Subscription` section.

## Interval

### Examples

    <Subscription NNN>
      ...
      Interval 30
    </Subscription>

### Description

The `Interval` directive specifies the preferred time interval for event notifications in seconds.

The `Interval` directive must appear inside a `Subscription` section.

## JobId

### Examples

    <Subscription NNN>
      ...
      JobId 123
    </Subscription>

### Description

The `JobId` directive specifies the `job-id` for job subscriptions.

The `JobId` directive must appear inside a `Subscription` section.

## LeaseDuration

### Examples

    <Subscription NNN>
      ...
      LeaseDuration
    </Subscription>

### Description

The `LeaseDuration` 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.

The `LeaseDuration` directive must appear inside a `Subscription` section.

## NextEventId

### Examples

    <Subscription NNN>
      ...
      NextEventId 999
    </Subscription>

### Description

The `NextEventId` directive specifies the `notify-sequence-number` value for the next notification event. It starts at 1 and increases for every event that is delivered for the subscription.

The `NextEventId` directive must appear inside a `Subscription` section.

## NextSubscriptionId

### Examples

    NextSubscriptionId 999

### Description

The `NextSubscriptionId` directive specifies the next subscription ID to use. It defaults to 1 more than the highest subscription number seen.

## Owner

### Examples

    <Subscription NNN>
      ...
      Owner username
    </Subscription>

### Description

The `Owner` directive specifies the user that owns this subscription.

The `Owner` directive must appear inside a `Subscription` section.

## PrinterName

### Examples

    <Subscription NNN>
      ...
      PrinterName name
    </Subscription>

### Description

The `PrinterName` directive specifies the name of the printer or class that is associated with this subscription.

The `PrinterName` directive must appear inside a `Subscription` section.

## Recipient

### Examples

    <Subscription NNN>
      ...
      Recipient mailto:foo@domain.com
    </Subscription>

### Description

The `Recipient` directive specifies the `notify-recipient-uri` value for push-type notifications. The URI scheme name determines which notifier program is used to send the event(s).

The `Recipient` directive must appear inside a `Subscription` section.

## Subscription

### Examples

    <Subscription NNN>
      ...
    </Subscription>

### Description

The `Subscription` section defines a single subscription in the system. Each subscription is assigned a unique (to the server) number starting at 1.

## UserData

### Examples

    <Subscription NNN>
      ...
      UserData mailto:bar<40>domain.com
    </Subscription>

### Description

The `UserData` directive specifies the `notify-user-data` value, which is normally the "from" address used in `mailto` notifications. Binary values are introduced by encoding the bytes as hexadecimal values inside angle brackets, e.g. "<1234>".

The `UserData` directive must appear inside a `Subscription` section.