| 1 |
.. _cyrus-eventsource: |
| 2 |
|
| 3 |
================== |
| 4 |
Cyrus Event Source |
| 5 |
================== |
| 6 |
|
| 7 |
Overview |
| 8 |
======== |
| 9 |
|
| 10 |
Cyrus can be configured to send events to another program any time something changes in a mailbox. The event contains details about the type of action that occurred, identifying information about the message and other useful information. Cyrus generates events for pretty much everything – every user action, data change, and other interesting things like calendar alarms. |
| 11 |
|
| 12 |
The notifications are compliant with :rfc:`5423`, though Cyrus includes some additional events outside of the RFC. |
| 13 |
|
| 14 |
By default, Cyrus ships with :cyrusman:`notifyd(8)` which listens for events from Cyrus. Mostly it is used for sending email notifications triggered by Sieve scripts, or by calendar alarms triggered by ``calalarmd``. |
| 15 |
|
| 16 |
Compile options |
| 17 |
=============== |
| 18 |
|
| 19 |
You can control what kind of events Cyrus generates during the ``configure`` step of compilation. |
| 20 |
|
| 21 |
``--enable_event_notification``: Set this to "yes" to have Cyrus generate mailbox related events. This is enabled by default. |
| 22 |
|
| 23 |
``--enable-apple-push-service``: Set this to "yes" to enable support for the Apple Push service. This is *disabled* by default as Apple does not provide licenses for Push support to developers at this stage. |
| 24 |
|
| 25 |
Configuration options |
| 26 |
===================== |
| 27 |
|
| 28 |
These need to be set in :cyrusman:`imapd.conf(5)`. |
| 29 |
|
| 30 |
.. include:: ../manpages/configs/imapd.conf.rst |
| 31 |
:start-after: startblob event_content_inclusion_mode |
| 32 |
:end-before: endblob event_content_inclusion_mode |
| 33 |
|
| 34 |
.. include:: ../manpages/configs/imapd.conf.rst |
| 35 |
:start-after: startblob event_content_size |
| 36 |
:end-before: endblob event_content_size |
| 37 |
|
| 38 |
.. include:: ../manpages/configs/imapd.conf.rst |
| 39 |
:start-after: startblob event_exclude_flags |
| 40 |
:end-before: endblob event_exclude_flags |
| 41 |
|
| 42 |
.. include:: ../manpages/configs/imapd.conf.rst |
| 43 |
:start-after: startblob event_exclude_specialuse |
| 44 |
:end-before: endblob event_exclude_specialuse |
| 45 |
|
| 46 |
.. include:: ../manpages/configs/imapd.conf.rst |
| 47 |
:start-after: startblob event_extra_params |
| 48 |
:end-before: endblob event_extra_params |
| 49 |
|
| 50 |
.. include:: ../manpages/configs/imapd.conf.rst |
| 51 |
:start-after: startblob event_groups |
| 52 |
:end-before: endblob event_groups |
| 53 |
|
| 54 |
.. include:: ../manpages/configs/imapd.conf.rst |
| 55 |
:start-after: startblob event_notifier |
| 56 |
:end-before: endblob event_notifier |
| 57 |
|
| 58 |
Event Types |
| 59 |
=========== |
| 60 |
|
| 61 |
These are detailed in :ref:`imap-features-event-notifications`. |
| 62 |
|
| 63 |
Accessing events |
| 64 |
================ |
| 65 |
|
| 66 |
While Cyrus only communicates with a single notification process, it doesn't have to be its standard :cyrusman:`notifyd(8)`. It's possible to write your own, providing it conforms with :rfc:`5465`. |
| 67 |
|
| 68 |
Apple Push Service |
| 69 |
================== |
| 70 |
|
| 71 |
While Cyrus supports the Apple Push Service, Apple has only licensed Apple Push |
| 72 |
for mail to a couple of large mail providers: Fastmail and Yahoo. If you own an |
| 73 |
OS X Server license, you also get a key for personal use. But it's not generally |
| 74 |
a supported option for third party developers that we're aware of, |
| 75 |
unfortunately. |
| 76 |
|
| 77 |
We have discussed pulling the XAPPLEPUSH code out from upstream Cyrus, but right |
| 78 |
now it remains against the day that Apple do decide to open up access. |