| 1 |
.. cyrusman:: cyr_expire(8) |
| 2 |
|
| 3 |
.. author: Nic Bernstein (Onlight) |
| 4 |
.. author: Jeroen van Meeuwen (Kolab Systems) |
| 5 |
|
| 6 |
.. _imap-reference-manpages-systemcommands-cyr_expire: |
| 7 |
|
| 8 |
============== |
| 9 |
**cyr_expire** |
| 10 |
============== |
| 11 |
|
| 12 |
Expire messages and duplicate delivery database entries |
| 13 |
|
| 14 |
Synopsis |
| 15 |
======== |
| 16 |
|
| 17 |
.. parsed-literal:: |
| 18 |
|
| 19 |
**cyr_expire** [ **-C** *config-file* ] [ **-A** *archive-duration* ] |
| 20 |
[ **-D** *delete-duration* ] [ **-E** *expire-duration* ] [ **-X** *expunge-duration* ] |
| 21 |
[ **-p** *mailbox-pre‐fix* ] [ **-u** *username* ] [ **-t** ] [ **-v** ] |
| 22 |
[ **-a** ] [ **-c** ] [ **-x** ] |
| 23 |
|
| 24 |
Description |
| 25 |
=========== |
| 26 |
|
| 27 |
**cyr_expire** is used to run a number of regular maintenance tasks |
| 28 |
on Cyrus databases, specifically: |
| 29 |
|
| 30 |
- expire messages from mailboxes, and |
| 31 |
- expire entries from the duplicate delivery database, and |
| 32 |
- cleanse mailboxes of partially expunged messages (when using the "delayed" expunge mode), and |
| 33 |
- remove deleted mailboxes (when using the "delayed" delete mode), and |
| 34 |
- expire entries from conversations databases, and |
| 35 |
- archive messages from mailbox. |
| 36 |
|
| 37 |
There are various annotations that **cyr_expire** respects: |
| 38 |
|
| 39 |
- ``/vendor/cmu/cyrus-imapd/expire`` which controls the expirations of |
| 40 |
messages |
| 41 |
- ``/vendor/cmu/cyrus-imapd/archive`` which controls the archival of |
| 42 |
messages |
| 43 |
- ``/vendor/cmu/cyrus-imapd/delete`` which controls the deletion of |
| 44 |
messages |
| 45 |
- ``/vendor/cmu/cyrus-imapd/noexpire_until`` which disables the expire |
| 46 |
and delete operations per user |
| 47 |
|
| 48 |
The first three mailbox annotations specify the age of messages in the |
| 49 |
given mailbox that should be expired/archived/deleted. The |
| 50 |
age is specified as a duration, the default unit are days. |
| 51 |
The duration format is defined in :cyrusman:`imapd.conf(5)`. |
| 52 |
|
| 53 |
The last mailbox annotation specifies the UNIX epoch time in seconds |
| 54 |
until which expiring messages or removing deleted mailboxes is blocked. |
| 55 |
The zero epoch time represents infinity. This annotation has precedence |
| 56 |
over any of the other annotations or command line flags. It must only |
| 57 |
be set on the user inbox and applies to all mailboxes of that user. |
| 58 |
|
| 59 |
The value of the ``/vendor/cmu/cyrus-imapd/expire`` annotation is |
| 60 |
inherited by all children of the mailbox on which it is set, so an |
| 61 |
entire mailbox tree can be configured by setting a single annotation on |
| 62 |
the root of that tree. If a mailbox does not have a |
| 63 |
``/vendor/cmu/cyrus-imapd/expire`` annotation set on it (or does not |
| 64 |
inherit one), then no messages are expired from the mailbox. |
| 65 |
|
| 66 |
The annotation can be examined using the **info** command of |
| 67 |
:cyrusman:`cyradm(8)`, and modified using the **mboxconfig** and |
| 68 |
**setinfo** commands of :cyrusman:`cyradm(8)`. |
| 69 |
|
| 70 |
Expiration of duplicate delivery database entries for a given mailbox |
| 71 |
is also controlled by the ``/vendor/cmu/cyrus-imapd/expire`` annotation |
| 72 |
which applies to that mailbox. A value of 0 on the annotation means |
| 73 |
that no expiration is to be performed on that mailbox. Unlike message expiration, if no |
| 74 |
annotation applies to the mailbox then duplicate database entries are |
| 75 |
expired using the value given to the **-E** option. |
| 76 |
|
| 77 |
Expiration of conversations database entries occurs if the |
| 78 |
**conversations** option is present in :cyrusman:`imapd.conf(5)`. |
| 79 |
Expiration can be disabled using the **-c** option. The period used to |
| 80 |
expire entries is controlled by the **conversations_expire_days** |
| 81 |
option in :cyrusman:`imapd.conf(5)`. |
| 82 |
|
| 83 |
**cyr_expire** |default-conf-text| |
| 84 |
|
| 85 |
**cyr_expire** requires at least one of **-A -D -E -X** or **-t** to be |
| 86 |
supplied. |
| 87 |
|
| 88 |
Options |
| 89 |
======= |
| 90 |
|
| 91 |
.. program:: cyr_expire |
| 92 |
|
| 93 |
.. option:: -C config-file |
| 94 |
|
| 95 |
|cli-dash-c-text| |
| 96 |
|
| 97 |
.. option:: -A archive-duration, --archive-duration=archive-duration |
| 98 |
|
| 99 |
Archive non-flagged messages older than *archive-duration* to the |
| 100 |
archive partition, allowing mailbox messages to be split between fast |
| 101 |
storage and slow large storage. Only does anything if |
| 102 |
``archivepartition-*`` has been set in your config. |
| 103 |
This value is only used for entries which do not have a |
| 104 |
corresponding ``/vendonr/cmu/cyrus-imapd/archive`` mailbox annotation. |
| 105 |
The duration format is defined in :cyrusman:`imapd.conf(5)`. The default |
| 106 |
unit are days. |
| 107 |
|
| 108 |
|v3-new-feature| |
| 109 |
|
| 110 |
.. option:: -D delete-duration, --delete-duration=delete-duration |
| 111 |
|
| 112 |
Remove previously deleted mailboxes older than *delete-duration* |
| 113 |
(when using the "delayed" delete mode). |
| 114 |
This value is only used for entries which do not have a |
| 115 |
corresponding ``/verdor/cmu/cyrus-imapd/delete`` mailbox annotation. |
| 116 |
The duration format is defined in :cyrusman:`imapd.conf(5)`. The default |
| 117 |
unit are days. |
| 118 |
|
| 119 |
.. option:: -E expire-duration, --expire-duration=expire-duration |
| 120 |
|
| 121 |
Prune the duplicate database of entries older than *expire-duration*. |
| 122 |
This value is only used for entries which do not have a corresponding |
| 123 |
``/vendor/cmu/cyrus-imapd/expire`` mailbox annotation. |
| 124 |
The duration format is defined in :cyrusman:`imapd.conf(5)`. The default |
| 125 |
unit are days. |
| 126 |
|
| 127 |
.. option:: -X expunge-duration, --expunge-duration=expunge-duration |
| 128 |
|
| 129 |
Expunge previously deleted messages older than *expunge-duration* |
| 130 |
(when using the "delayed" expunge mode). |
| 131 |
The duration format is defined in :cyrusman:`imapd.conf(5)`. The default |
| 132 |
unit are days. |
| 133 |
|
| 134 |
.. option:: -c, --no-conversations |
| 135 |
|
| 136 |
Do not expire conversation database entries, even if the conversations |
| 137 |
feature is enabled. |
| 138 |
|
| 139 |
|v3-new-feature| |
| 140 |
|
| 141 |
.. option:: -x, --no-expunge |
| 142 |
|
| 143 |
Do not expunge messages even if using delayed expunge mode. This |
| 144 |
reduces IO traffic considerably, allowing ``cyr_expire`` to be run |
| 145 |
frequently to clean up the duplicate database without overloading |
| 146 |
the machine. |
| 147 |
|
| 148 |
.. option:: -p mailbox-prefix, --prefix=mailbox-prefix |
| 149 |
|
| 150 |
Only find mailboxes starting with this prefix, e.g. |
| 151 |
"user.justgotspammedlots". |
| 152 |
|
| 153 |
.. option:: -u userid, --userid=userid |
| 154 |
|
| 155 |
Only find mailboxes belonging to this user, e.g. |
| 156 |
"[email protected]". |
| 157 |
|
| 158 |
.. option:: -t, --prune-userflags |
| 159 |
|
| 160 |
Remove any user flags which are not used by remaining (not expunged) |
| 161 |
messages. |
| 162 |
|
| 163 |
.. option:: -v, --verbose |
| 164 |
|
| 165 |
Enable verbose output. |
| 166 |
|
| 167 |
.. option:: -a, --ignore-annotations |
| 168 |
|
| 169 |
Skip the annotation lookup, so all ``/vendor/cmu/cyrus-imapd/expire`` |
| 170 |
annotations are ignored entirely. It behaves as if they were not |
| 171 |
set, so only *expire-days* is considered for all mailboxes. |
| 172 |
|
| 173 |
Examples |
| 174 |
======== |
| 175 |
|
| 176 |
.. parsed-literal:: |
| 177 |
|
| 178 |
**cyr_expire -E** *3* **-D** *60* **-X** *60* |
| 179 |
|
| 180 |
.. |
| 181 |
|
| 182 |
Purge duplicates database of all entries older than *3* days, remove |
| 183 |
deleted mailboxes older than *60* days and deleted messages older than |
| 184 |
*60* days. |
| 185 |
|
| 186 |
|
| 187 |
.. parsed-literal:: |
| 188 |
|
| 189 |
**cyr_expire -x -c -A** *7d* |
| 190 |
|
| 191 |
.. |
| 192 |
|
| 193 |
Perform migration of message older than *7* days to Archive |
| 194 |
partition whilst not altering conversation database nor |
| 195 |
expunging messages. |
| 196 |
|
| 197 |
History |
| 198 |
======= |
| 199 |
|
| 200 |
Archive partition and conversation support was first introduced in Cyrus |
| 201 |
version 3.0. |
| 202 |
|
| 203 |
Files |
| 204 |
===== |
| 205 |
|
| 206 |
/etc/imapd.conf |
| 207 |
|
| 208 |
See Also |
| 209 |
======== |
| 210 |
|
| 211 |
:cyrusman:`imapd.conf(5)`, :cyrusman:`master(8)`, :cyrusman:`cyradm(8)` |