| 1 |
Notes for Packagers |
| 2 |
=================== |
| 3 |
|
| 4 |
Binary naming |
| 5 |
------------- |
| 6 |
|
| 7 |
Prevent namespace clashes. We suggest renaming all binaries with ``cyr_`` at |
| 8 |
the front, including renaming the ``ctl_*`` to ``cyr_``. |
| 9 |
|
| 10 |
The Cyrus team are looking to fix this in the core bundle in upcoming releases |
| 11 |
so packagers have less to do. |
| 12 |
|
| 13 |
Sample configuration files |
| 14 |
-------------------------- |
| 15 |
|
| 16 |
There are several samples of :cyrusman:`cyrus.conf(5)` and |
| 17 |
:cyrusman:`imapd.conf(5)` located in the ``doc/examples`` directory of |
| 18 |
the distribution tarball. Please install these to your preferred |
| 19 |
documentation directory (i.e. ``/usr/share/doc/cyrus-imapd``) as a |
| 20 |
reference for your users. |
| 21 |
|
| 22 |
Predefined configurations |
| 23 |
------------------------- |
| 24 |
|
| 25 |
The configuration file for master: cyrus.conf |
| 26 |
````````````````````````````````````````````` |
| 27 |
|
| 28 |
When installing a predefined :cyrusman:`cyrus.conf(5)` for your users, |
| 29 |
please pay attention to new features and how these may impact users. |
| 30 |
For example, for some time now, Cyrus has supported placing several |
| 31 |
standard DB files in temporary, or ephemeral, storage, such as memory |
| 32 |
backed filesystems like tmpfs (see below). This both boosts efficiency |
| 33 |
and ensures DB consistency in event of a crash or other system |
| 34 |
disruptive events. But, in light of this, actions which depend on the |
| 35 |
existence of these database files *should not* be placed in the |
| 36 |
**START** section of :cyrusman:`cyrus.conf(5)`. |
| 37 |
|
| 38 |
Section Purpose |
| 39 |
############### |
| 40 |
|
| 41 |
A new section, DAEMON, was added to :cyrusman:`cyrus.conf(5)` in |
| 42 |
version 2.5. Please consult :cyrusman:`cyrus.conf(5)` for details. |
| 43 |
Please refer to the notes in **Section Descriptions** pertaining to the |
| 44 |
distinctions between **START**, **EVENTS** and **DAEMON** sections. |
| 45 |
|
| 46 |
In brief, the sorts of things which should go into the different |
| 47 |
sections are: |
| 48 |
|
| 49 |
* **START** |
| 50 |
|
| 51 |
* Programs which should be spawned by :cyrusman:`master(8)` which |
| 52 |
are expected to cleanup after themselves |
| 53 |
* do not rely on any ephemeral files or resources |
| 54 |
* :cyrusman:`master(8)` will not start until all entries in |
| 55 |
**START** have either ended or backgrounded themselves. |
| 56 |
|
| 57 |
* **SERVICES** |
| 58 |
|
| 59 |
* Service daemons managed by :cyrusman:`master(8)` |
| 60 |
* :cyrusman:`master(8)` will listen on ports or sockets as specified |
| 61 |
and dispatch new child processes as needed, destroy old or stale |
| 62 |
processes, etc. |
| 63 |
|
| 64 |
* **EVENTS** |
| 65 |
|
| 66 |
* Periodic processes which will be started by :cyrusman:`master(8)` |
| 67 |
as specified. |
| 68 |
|
| 69 |
* **DAEMON** |
| 70 |
|
| 71 |
* Programs which should be spawned by :cyrusman:`master(8)` which |
| 72 |
it should shut down and clean up after. |
| 73 |
|
| 74 |
The configuration file for the various programs: imapd.conf |
| 75 |
``````````````````````````````````````````````````````````` |
| 76 |
|
| 77 |
The sample :cyrusman:`imapd.conf(5)` files must be adapted for use from |
| 78 |
site to site. Here, therefore, we'll attempt to point you towards some |
| 79 |
reasonable settings which take advantage of recent improvements and |
| 80 |
features, and may help guide you and your users to a better performing |
| 81 |
Cyrus installation. |
| 82 |
|
| 83 |
Ephemeral files and temporary filesystems |
| 84 |
######################################### |
| 85 |
|
| 86 |
In addition to Unix domain sockets and lock files, several databases |
| 87 |
used by Cyrus programs may be located in temporary filesystems, such as |
| 88 |
those backed by RAM (i.e. tmpfs, md, etc.). Here's a list of such |
| 89 |
files. In this example, the filesystem ``/run`` is on tmpfs:: |
| 90 |
|
| 91 |
proc_path: /run/cyrus/proc |
| 92 |
mboxname_lockpath: /run/cyrus/lock |
| 93 |
duplicate_db_path: /run/cyrus/deliver.db |
| 94 |
statuscache_db_path: /run/cyrus/statuscache.db |
| 95 |
ptscache_db_path: /run/cyrus/ptscache.db |
| 96 |
tls_sessions_db_path: /run/cyrus/tls_sessions.db |
| 97 |
lmtpsocket: /run/cyrus/socket/lmtp |
| 98 |
idlesocket: /run/cyrus/socket/idle |
| 99 |
notifysocket: /run/cyrus/socket/notify |
| 100 |
|
| 101 |
.. note:: |
| 102 |
|
| 103 |
Any process which depends on these files already existing **should |
| 104 |
not** be placed in the **START** section of |
| 105 |
:cyrusman:`cyrus.conf(5)`, or the server will not start as |
| 106 |
expected. |
| 107 |
|
| 108 |
New default settings |
| 109 |
#################### |
| 110 |
|
| 111 |
A new stable series means the defaults for some settings may have changed. |
| 112 |
Please consult :ref:`upgrade` for details. |
| 113 |
|
| 114 |
New or improved features |
| 115 |
######################## |
| 116 |
|
| 117 |
A new stable series means new features, and improvements to existing features. |
| 118 |
Some of these may be features which previously were not considered ripe for |
| 119 |
packaging, but merit new consideration. |
| 120 |
|
| 121 |
Please see :ref:`imap-release-notes-3.2` for details, and consider enabling |
| 122 |
these features in the :cyrusman:`imapd.conf(5)` you ship in your packages. |
| 123 |
|
| 124 |
Services in ``/etc/services`` |
| 125 |
----------------------------- |
| 126 |
|
| 127 |
Listing named services through ``/etc/services`` aids in cross-system |
| 128 |
consistency and cross-platform interoperability. Furthermore, it enables |
| 129 |
administrators and users to refer to the service by name (for example in |
| 130 |
``/etc/cyrus.conf``, 'listen=mupdate' can be specified instead of |
| 131 |
'listen=3905'). |
| 132 |
|
| 133 |
Some of the services Cyrus IMAP would like to see available through |
| 134 |
``/etc/services`` have not been assigned an IANA port number, and few have |
| 135 |
configuration options. |
| 136 |
|
| 137 |
.. include:: /assets/services.rst |