Debian Codegraph @

doc/html/imap/concepts/features/mailbox-distribution.html

raw
1 <!DOCTYPE html>
2 <html class="writer-html5" lang="en" data-content_root="../../../">
3 <head>
4 <meta charset="utf-8" /><meta name="viewport" content="width=device-width, initial-scale=1" />
5
6 <meta name="viewport" content="width=device-width, initial-scale=1.0" />
7 <title>Mailbox Distribution &mdash; Cyrus IMAP 3.12.3 documentation</title>
8 <link rel="stylesheet" type="text/css" href="../../../_static/pygments.css?v=fa44fd50" />
9 <link rel="stylesheet" type="text/css" href="../../../_static/css/theme.css?v=86f27845" />
10 <link rel="stylesheet" type="text/css" href="../../../_static/graphviz.css?v=eafc0fe6" />
11 <link rel="stylesheet" href="../../../_static/cyrus.css" type="text/css" />
12
13
14
15 <script src="../../../_static/jquery.js?v=8dae8fb0"></script>
16 <script src="../../../_static/_sphinx_javascript_frameworks_compat.js?v=2cd50e6c"></script>
17 <script src="../../../_static/documentation_options.js?v=2c828074"></script>
18 <script src="../../../_static/doctools.js?v=888ff710"></script>
19 <script src="../../../_static/sphinx_highlight.js?v=dc90522c"></script>
20 <script async="async" src="https://cdn.mathjax.org/mathjax/latest/MathJax.js"></script>
21 <script src="../../../_static/js/theme.js"></script>
22 <link rel="index" title="Index" href="../../../genindex.html" />
23 <link rel="search" title="Search" href="../../../search.html" />
24 <link rel="next" title="Delayed Delete" href="delayed-delete.html" />
25 <link rel="prev" title="Mailbox Annotations (METADATA)" href="mailbox-annotations.html" />
26 </head>
27
28 <body class="wy-body-for-nav">
29 <div class="wy-grid-for-nav">
30 <nav data-toggle="wy-nav-shift" class="wy-nav-side">
31 <div class="wy-side-scroll">
32 <div class="wy-side-nav-search" >
33
34
35
36 <a href="../../../index.html" class="icon icon-home">
37 Cyrus IMAP
38 </a>
39 <div class="version">
40 3.12.3
41 </div>
42 <div role="search">
43 <form id="rtd-search-form" class="wy-form" action="../../../search.html" method="get">
44 <input type="text" name="q" placeholder="Search docs" aria-label="Search docs" />
45 <input type="hidden" name="check_keywords" value="yes" />
46 <input type="hidden" name="area" value="default" />
47 </form>
48 </div>
49 </div><div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="Navigation menu">
50 <p class="caption" role="heading"><span class="caption-text">Cyrus IMAP</span></p>
51 <ul class="current">
52 <li class="toctree-l1"><a class="reference internal" href="../../../download.html">Download</a></li>
53 <li class="toctree-l1"><a class="reference internal" href="../../../quickstart.html">Quickstart Guide</a></li>
54 <li class="toctree-l1 current"><a class="reference internal" href="../../../overview.html">Overview</a><ul class="current">
55 <li class="toctree-l2 current"><a class="reference internal" href="../features.html">Features</a><ul class="current">
56 <li class="toctree-l3"><a class="reference internal" href="../features.html#security-and-authentication">Security and Authentication</a></li>
57 <li class="toctree-l3 current"><a class="reference internal" href="../features.html#mailbox-management">Mailbox Management</a><ul class="current">
58 <li class="toctree-l4"><a class="reference internal" href="automatic-creation-of-mailboxes.html">Automatic Creation of Mailboxes</a></li>
59 <li class="toctree-l4"><a class="reference internal" href="namespaces.html">Mailbox Namespaces</a></li>
60 <li class="toctree-l4"><a class="reference internal" href="virtual-domains.html">Virtual Domains</a></li>
61 <li class="toctree-l4"><a class="reference internal" href="mailbox-annotations.html">Mailbox Annotations (METADATA)</a></li>
62 <li class="toctree-l4 current"><a class="current reference internal" href="#">Mailbox Distribution</a></li>
63 </ul>
64 </li>
65 <li class="toctree-l3"><a class="reference internal" href="../features.html#message-management">Message Management</a></li>
66 <li class="toctree-l3"><a class="reference internal" href="../features.html#calendar-and-contact-dav-collection-management">Calendar and Contact (DAV) Collection Management</a></li>
67 <li class="toctree-l3"><a class="reference internal" href="../features.html#storage">Storage</a></li>
68 <li class="toctree-l3"><a class="reference internal" href="../features.html#load-management">Load Management</a></li>
69 </ul>
70 </li>
71 <li class="toctree-l2"><a class="reference internal" href="../overview_and_concepts.html">Concepts</a></li>
72 </ul>
73 </li>
74 <li class="toctree-l1"><a class="reference internal" href="../../../setup.html">Setup</a></li>
75 <li class="toctree-l1"><a class="reference internal" href="../../../operations.html">Operations</a></li>
76 <li class="toctree-l1"><a class="reference internal" href="../../../developers.html">Developers</a></li>
77 <li class="toctree-l1"><a class="reference internal" href="../../../support.html">Support/Community</a></li>
78 </ul>
79 <p class="caption" role="heading"><span class="caption-text">Cyrus SASL</span></p>
80 <ul>
81 <li class="toctree-l1"><a class="reference external" href="http://www.cyrusimap.org/sasl">Cyrus SASL</a></li>
82 </ul>
83
84 </div>
85 </div>
86 </nav>
87
88 <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap"><nav class="wy-nav-top" aria-label="Mobile navigation menu" >
89 <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
90 <a href="../../../index.html">Cyrus IMAP</a>
91 </nav>
92
93 <div class="wy-nav-content">
94 <div class="rst-content">
95 <div role="navigation" aria-label="Page navigation">
96 <ul class="wy-breadcrumbs">
97 <li><a href="../../../index.html" class="icon icon-home" aria-label="Home"></a></li>
98 <li class="breadcrumb-item"><a href="../../../overview.html">Overview</a></li>
99 <li class="breadcrumb-item"><a href="../features.html">Features</a></li>
100 <li class="breadcrumb-item active">Mailbox Distribution</li>
101 <li class="wy-breadcrumbs-aside">
102 <a href="https://github.com/cyrusimap/cyrus-imapd/blob/master/docsrc/imap/concepts/features/mailbox-distribution.rst" class="fa fa-github"> Edit on GitHub</a>
103 </li>
104 </ul>
105 <hr/>
106 </div>
107 <div role="main" class="document" itemscope="itemscope" itemtype="http://schema.org/Article">
108 <div itemprop="articleBody">
109
110 <section id="mailbox-distribution">
111 <span id="imap-features-mailbox-distribution"></span><h1>Mailbox Distribution<a class="headerlink" href="#mailbox-distribution" title="Link to this heading"></a></h1>
112 <p>Prior to Cyrus IMAP version 2.5.0, when creating a mailbox, should no
113 target partition have been specified, the mailbox is either created on:</p>
114 <ul class="simple">
115 <li><p>the configured <code class="docutils literal notranslate"><span class="pre">defaultserver</span></code>, or</p></li>
116 <li><p>the server that is found to have the most free disk space, and</p></li>
117 <li><p>the configured <code class="docutils literal notranslate"><span class="pre">defaultpartition</span></code>, or</p></li>
118 <li><p>the most fitting partition if <code class="docutils literal notranslate"><span class="pre">defaultpartition</span></code> is not
119 configured.</p></li>
120 </ul>
121 <p>New configuration options are available since Cyrus IMAP 2.5.0, that
122 allow more weighted and better balanced backend and partition
123 selection.</p>
124 <section id="partition-selection-mode">
125 <h2>Partition Selection Mode<a class="headerlink" href="#partition-selection-mode" title="Link to this heading"></a></h2>
126 <p>Among the partitions, how the most fitting one is selected depends on
127 the configured selection mode, using the <code class="docutils literal notranslate"><span class="pre">partition_select_mode</span></code>
128 setting in <a class="reference internal" href="../../reference/manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a>.</p>
129 <p class="rubric">Available Selection Modes</p>
130 <aside class="sidebar">
131 <p class="sidebar-title">Example Scenario for Selection Modes</p>
132 <p>Suppose that the partitions configured are:</p>
133 <table class="docutils align-default">
134 <thead>
135 <tr class="row-odd"><th class="head"><p>Partition</p></th>
136 <th class="head"><p>Total</p></th>
137 <th class="head"><p>Free</p></th>
138 <th class="head"><p>%</p></th>
139 </tr>
140 </thead>
141 <tbody>
142 <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">part1</span></code></p></td>
143 <td><p>1000 GB</p></td>
144 <td><p>400 GB</p></td>
145 <td><p>40%</p></td>
146 </tr>
147 <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">part2</span></code></p></td>
148 <td><p>1000 GB</p></td>
149 <td><p>600 GB</p></td>
150 <td><p>60%</p></td>
151 </tr>
152 <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">part3</span></code></p></td>
153 <td><p>100 GB</p></td>
154 <td><p>30 GB</p></td>
155 <td><p>30%</p></td>
156 </tr>
157 <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">part4</span></code></p></td>
158 <td><p>100 GB</p></td>
159 <td><p>70 GB</p></td>
160 <td><p>70%</p></td>
161 </tr>
162 </tbody>
163 </table>
164 </aside>
165 <ul>
166 <li><p><strong>random</strong></p>
167 <p>Choice is (pseudo-)random. Each partition has the same probability
168 of being selected.</p>
169 </li>
170 <li><p><strong>freespace-most</strong></p>
171 <p>The partition which has the most absolute free space (counted in KiB
172 units) is selected.</p>
173 <p>In the example scenario, <code class="docutils literal notranslate"><span class="pre">part2</span></code> would be selected as most
174 fitting, since 600 GB of free space is the biggest of all
175 partitions.</p>
176 </li>
177 <li><p><strong>freespace-percent-most</strong></p>
178 <p>The partition which has the most relative free space (counted in
179 percentiles) is selected.</p>
180 <p>In the example scenario, <code class="docutils literal notranslate"><span class="pre">part4</span></code> would be selected as most
181 fitting, since 70% of free space is the biggest of all partitions.</p>
182 </li>
183 <li><p><strong>freespace-percent-weighted</strong></p>
184 <p>For each partition, the percentage of free space is its weight. Then
185 a weighted choice is performed to select one of those partitions.</p>
186 <p>As such, the more free space the partition has, the higher its
187 chances to be selected.</p>
188 <p>In the example scenario, the weight of each partition would be:</p>
189 <ul class="simple">
190 <li><p>40 for <code class="docutils literal notranslate"><span class="pre">part1</span></code></p></li>
191 <li><p>60 for <code class="docutils literal notranslate"><span class="pre">part2</span></code></p></li>
192 <li><p>30 for <code class="docutils literal notranslate"><span class="pre">part3</span></code></p></li>
193 <li><p>70 for <code class="docutils literal notranslate"><span class="pre">part4</span></code></p></li>
194 </ul>
195 <p>The sum of all weights being 200, the probability for each
196 partition to be selected as most fitting is:</p>
197 <ul class="simple">
198 <li><p>20% for <code class="docutils literal notranslate"><span class="pre">part1</span></code></p></li>
199 <li><p>30% for <code class="docutils literal notranslate"><span class="pre">part2</span></code></p></li>
200 <li><p>15% for <code class="docutils literal notranslate"><span class="pre">part3</span></code></p></li>
201 <li><p>35% for <code class="docutils literal notranslate"><span class="pre">part4</span></code></p></li>
202 </ul>
203 <p>Out of 20 (hypothetically empty) mailboxes to be created,
204 chances are:</p>
205 <ul class="simple">
206 <li><p>4 are created on <code class="docutils literal notranslate"><span class="pre">part1</span></code></p></li>
207 <li><p>6 are created on <code class="docutils literal notranslate"><span class="pre">part2</span></code></p></li>
208 <li><p>3 are created on <code class="docutils literal notranslate"><span class="pre">part3</span></code></p></li>
209 <li><p>7 are created on <code class="docutils literal notranslate"><span class="pre">part4</span></code></p></li>
210 </ul>
211 <div class="admonition note">
212 <p class="admonition-title">Note</p>
213 <p>In <code class="docutils literal notranslate"><span class="pre">freespace-percent-weighted</span></code> mode, partitions percentage
214 usages converge towards 100%. So if they have different usages,
215 those differences will stay and only really diminish upon
216 reaching 100% of usage.</p>
217 <p>You may also observe growing differences between partitions
218 usage when those partitions do not have the same total disk
219 space.</p>
220 </div>
221 </li>
222 </ul>
223 <p><strong>freespace-percent-weighted-delta</strong></p>
224 <blockquote>
225 <div><p>As for <code class="docutils literal notranslate"><span class="pre">freespace-percent-weighted</span></code>, a weight is associated to
226 each partition. It is computed as follows:</p>
227 <div class="math notranslate nohighlight">
228 \[free - leastfree + 0.5\]</div>
229 <p>Then a weighted choice is performed to select one of those
230 partitions.</p>
231 <p>As such, considering the percentages of usage, the more the
232 partition is lagging behind the most used partition (which is the
233 one with the lowest <strong>percentage</strong> of free space), the higher its
234 chances are to be selected.</p>
235 <div class="admonition note">
236 <p class="admonition-title">Note</p>
237 <p>The added 0.5 in partitions weight causes the selection to get
238 smoother the more partitions get close to each other.</p>
239 </div>
240 <p>In the example scenario, the weight of each partition would be:</p>
241 <ul class="simple">
242 <li><p>For <code class="docutils literal notranslate"><span class="pre">part1</span></code>: <span class="math notranslate nohighlight">\(40 - 30 + 0.5 = 10.5\)</span></p></li>
243 <li><p>For <code class="docutils literal notranslate"><span class="pre">part2</span></code>: <span class="math notranslate nohighlight">\(60 - 30 + 0.5 = 30.5\)</span></p></li>
244 <li><p>For <code class="docutils literal notranslate"><span class="pre">part3</span></code>: <span class="math notranslate nohighlight">\(30 - 30 + 0.5 = 00.5\)</span></p></li>
245 <li><p>For <code class="docutils literal notranslate"><span class="pre">part4</span></code>: <span class="math notranslate nohighlight">\(70 - 30 + 0.5 = 40.5\)</span></p></li>
246 </ul>
247 <p>The sum of all weights amounting to 82, the probability for each
248 partition to be selected as most fitting would be:</p>
249 <ul class="simple">
250 <li><p>For <code class="docutils literal notranslate"><span class="pre">part1</span></code>: 12.8%</p></li>
251 <li><p>For <code class="docutils literal notranslate"><span class="pre">part2</span></code>: 37.2%</p></li>
252 <li><p>For <code class="docutils literal notranslate"><span class="pre">part3</span></code>: 00.6%</p></li>
253 <li><p>For <code class="docutils literal notranslate"><span class="pre">part4</span></code>: 49.4%</p></li>
254 </ul>
255 <div class="admonition note">
256 <p class="admonition-title">Note</p>
257 <p>In <code class="docutils literal notranslate"><span class="pre">freespace-percent-weighted-delta</span></code> mode, partitions
258 percentage usages converge towards the most used one, after
259 which partitions usages grow equally.</p>
260 </div>
261 </div></blockquote>
262 <section id="special-cases">
263 <h3>Special Cases<a class="headerlink" href="#special-cases" title="Link to this heading"></a></h3>
264 <section id="q-what-happens-when-two-partitions-are-equal-as-most-fitting">
265 <h4>Q: What happens when two partitions are equal as most fitting?<a class="headerlink" href="#q-what-happens-when-two-partitions-are-equal-as-most-fitting" title="Link to this heading"></a></h4>
266 <p>Suppose you are using the <code class="docutils literal notranslate"><span class="pre">freespace-most</span></code> selection mode, that two
267 (or more) partitions have the same free size, and that this freespace
268 happens to be the biggest one of all configured partitions.</p>
269 <p>In that case, only one of those partitions will be selected. You may not
270 know in advance which one will be: it depends of the order in which
271 configured partitions are stored in memory (<code class="docutils literal notranslate"><span class="pre">hashtable</span></code>). In
272 particular, it may not be the first one that appears listed in your
273 <a class="reference internal" href="../../reference/manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a> configuration file.</p>
274 <p>Also note that since the selected partition will now have less free
275 space, it shall not be seen as most fitting next time.</p>
276 </section>
277 <section id="q-what-happens-when-two-partitions-point-to-the-same-device">
278 <h4>Q: What happens when two partitions point to the same device?<a class="headerlink" href="#q-what-happens-when-two-partitions-point-to-the-same-device" title="Link to this heading"></a></h4>
279 <p>Suppose you are using the <code class="docutils literal notranslate"><span class="pre">freespace-most</span></code> or
280 <code class="docutils literal notranslate"><span class="pre">freespace-percent-most</span></code> selection mode, and that two (or more)
281 partitions actually point to a different directory on the same
282 filesystem.</p>
283 <p>In that case, only one of those partitions will be checked, as if the
284 others were not configured. Cyrus IMAP uses the device id of the
285 partition hierarchy for this. You may not know in advance which one will
286 be: it depends of the order in which configured partitions are stored in
287 memory (<code class="docutils literal notranslate"><span class="pre">hashtable</span></code>). In particular, it may not be the first one that
288 appears listed in your <a class="reference internal" href="../../reference/manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a> configuration file.</p>
289 </section>
290 </section>
291 <section id="excluding-partitions">
292 <h3>Excluding Partitions<a class="headerlink" href="#excluding-partitions" title="Link to this heading"></a></h3>
293 <p><strong>partition_select_exclude</strong></p>
294 <blockquote>
295 <div><p>Partitions listed in the <code class="docutils literal notranslate"><span class="pre">partition_select_exclude</span></code> setting in
296 <a class="reference internal" href="../../reference/manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a> are permanently excluded from being
297 selected.</p>
298 <p>Listed partition's names are separated by spaces and/or commas. Only
299 configured partition names (and not paths) are expected.</p>
300 <p>With the following configuration in <a class="reference internal" href="../../reference/manpages/configs/imapd.conf.html#std-cyrusman-imapd.conf-5">imapd.conf(5)</a>,
301 <code class="docutils literal notranslate"><span class="pre">parta</span></code> and <code class="docutils literal notranslate"><span class="pre">partb</span></code> would be permanently excluded from being
302 selected:</p>
303 <div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">partition</span><span class="o">-</span><span class="n">part1</span><span class="p">:</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">part1</span>
304 <span class="n">partition</span><span class="o">-</span><span class="n">part2</span><span class="p">:</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">part2</span>
305 <span class="n">partition</span><span class="o">-</span><span class="n">part3</span><span class="p">:</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">part3</span>
306 <span class="n">partition</span><span class="o">-</span><span class="n">part4</span><span class="p">:</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">part4</span>
307 <span class="n">partition</span><span class="o">-</span><span class="n">parta</span><span class="p">:</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">parta</span>
308 <span class="n">partition</span><span class="o">-</span><span class="n">partb</span><span class="p">:</span> <span class="o">/</span><span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">partb</span>
309
310 <span class="n">partition_mode_exclude</span><span class="p">:</span> <span class="n">parta</span> <span class="n">partb</span>
311 </pre></div>
312 </div>
313 </div></blockquote>
314 <p><strong>partition_select_soft_usage_limit</strong></p>
315 <blockquote>
316 <div><p>When using a selection mode other than <code class="docutils literal notranslate"><span class="pre">random</span></code>, partitions are
317 automatically excluded if their usage percentage is beyond the
318 <code class="docutils literal notranslate"><span class="pre">partition_select_soft_usage_limit</span></code> integer setting.</p>
319 <p>If all partitions are beyond the configured value, this feature is
320 automatically deactivated. A partition is thus selected as if the
321 setting was not configured.</p>
322 <p>In the example scenario, setting <code class="docutils literal notranslate"><span class="pre">partition_mode_soft_usage_limit</span></code>
323 to <code class="docutils literal notranslate"><span class="pre">50</span></code> would exclude partitions <code class="docutils literal notranslate"><span class="pre">part1</span></code> and <code class="docutils literal notranslate"><span class="pre">part3</span></code> since
324 their disk usages are 60% and 70% respectively.</p>
325 <p>But setting the option to <code class="docutils literal notranslate"><span class="pre">20</span></code> would have no immediate effect on
326 the selection of a partition, since the usage of all partitions is
327 beyond 20%.</p>
328 </div></blockquote>
329 <div class="admonition important">
330 <p class="admonition-title">Important</p>
331 <p><strong>Exclusion is not absolute</strong></p>
332 <p>Partitions are only excluded when creating a new user mailbox
333 according to the configured selection mode.</p>
334 <p>If you explicitly specify an excluded partition, the mailbox will
335 be created on that partition.</p>
336 <p>Mailboxes previously created on such partitions are of course still
337 accessible, and subfolders are by default still created on the same
338 partition as the parent folder.</p>
339 </div>
340 </section>
341 <section id="partition-s-usage-information-reset">
342 <h3>Partition's Usage Information Reset<a class="headerlink" href="#partition-s-usage-information-reset" title="Link to this heading"></a></h3>
343 <p>By default, partition's usage information is retrieved only once -- when
344 the service first initializes.</p>
345 <p>If you tend to use the same service instance for a long lapse of time
346 and performs a large amount of mailbox creations, it may be useful to
347 configure the <code class="docutils literal notranslate"><span class="pre">partition_select_usage_reinit</span></code> setting so that
348 each partition's usage information is refreshed after the configured
349 number of creation requests.</p>
350 <div class="admonition note">
351 <p class="admonition-title">Note</p>
352 <p>This only concerns selection modes other than <cite>random`</cite>.</p>
353 </div>
354 </section>
355 </section>
356 <section id="backend-selection-mode-cyrus-imap-murder">
357 <h2>Backend Selection Mode (Cyrus IMAP Murder)<a class="headerlink" href="#backend-selection-mode-cyrus-imap-murder" title="Link to this heading"></a></h2>
358 <p>Upon creating a user mailbox, if the target server is not given as
359 extra parameter, the mailbox is created on either;</p>
360 <ul class="simple">
361 <li><p>the configured <code class="docutils literal notranslate"><span class="pre">defaultserver</span></code> backend</p></li>
362 <li><p>the most fitting backend (partition) among the servers listed in the
363 <code class="docutils literal notranslate"><span class="pre">serverlist</span></code> setting, if <code class="docutils literal notranslate"><span class="pre">defaultserver</span></code> is not configured.</p></li>
364 </ul>
365 <p class="rubric">Related Settings</p>
366 <ul class="simple">
367 <li><p><code class="docutils literal notranslate"><span class="pre">serverlist_select_mode</span></code></p></li>
368 <li><p><code class="docutils literal notranslate"><span class="pre">serverlist_select_usage_reinit</span></code></p></li>
369 <li><p><code class="docutils literal notranslate"><span class="pre">serverlist_select_soft_usage_limit</span></code></p></li>
370 </ul>
371 <section id="available-selection-modes-on-frontend">
372 <h3>Available Selection Modes on Frontend<a class="headerlink" href="#available-selection-modes-on-frontend" title="Link to this heading"></a></h3>
373 <p><strong>random</strong></p>
374 <blockquote>
375 <div><p>The selection is (pseudo-)random. Each backend has the same
376 probability of being selected.</p>
377 </div></blockquote>
378 <aside class="sidebar">
379 <p class="sidebar-title">Example Scenario for Selection Modes</p>
380 <p>Suppose that the partitions configured are:</p>
381 <table class="docutils align-default">
382 <thead>
383 <tr class="row-odd"><th class="head"><p>Backend</p></th>
384 <th class="head"><p>Partition</p></th>
385 <th class="head"><p>Total</p></th>
386 <th class="head"><p>Free</p></th>
387 <th class="head"><p>%</p></th>
388 </tr>
389 </thead>
390 <tbody>
391 <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">be1</span></code></p></td>
392 <td></td>
393 <td><p>2000 GB</p></td>
394 <td><p>1000 GB</p></td>
395 <td><p>50%</p></td>
396 </tr>
397 <tr class="row-odd"><td></td>
398 <td><p><code class="docutils literal notranslate"><span class="pre">part1</span></code></p></td>
399 <td><p>1000 GB</p></td>
400 <td><p>500 GB</p></td>
401 <td><p>50%</p></td>
402 </tr>
403 <tr class="row-even"><td></td>
404 <td><p><code class="docutils literal notranslate"><span class="pre">part2</span></code></p></td>
405 <td><p>1000 GB</p></td>
406 <td><p>500 GB</p></td>
407 <td><p>50%</p></td>
408 </tr>
409 <tr class="row-odd"><td><p><code class="docutils literal notranslate"><span class="pre">be2</span></code></p></td>
410 <td></td>
411 <td><p>2000 GB</p></td>
412 <td><p>900 GB</p></td>
413 <td><p>45%</p></td>
414 </tr>
415 <tr class="row-even"><td></td>
416 <td><p><code class="docutils literal notranslate"><span class="pre">part1</span></code></p></td>
417 <td><p>1000 GB</p></td>
418 <td><p>200 GB</p></td>
419 <td><p>20%</p></td>
420 </tr>
421 <tr class="row-odd"><td></td>
422 <td><p><code class="docutils literal notranslate"><span class="pre">part2</span></code></p></td>
423 <td><p>1000 GB</p></td>
424 <td><p>700 GB</p></td>
425 <td><p>70%</p></td>
426 </tr>
427 <tr class="row-even"><td><p><code class="docutils literal notranslate"><span class="pre">be3</span></code></p></td>
428 <td></td>
429 <td><p>200 GB</p></td>
430 <td><p>110 GB</p></td>
431 <td><p>55%</p></td>
432 </tr>
433 <tr class="row-odd"><td></td>
434 <td><p><code class="docutils literal notranslate"><span class="pre">part1</span></code></p></td>
435 <td><p>100 GB</p></td>
436 <td><p>30 GB</p></td>
437 <td><p>30%</p></td>
438 </tr>
439 <tr class="row-even"><td></td>
440 <td><p><code class="docutils literal notranslate"><span class="pre">part2</span></code></p></td>
441 <td><p>100 GB</p></td>
442 <td><p>80 GB</p></td>
443 <td><p>80%</p></td>
444 </tr>
445 </tbody>
446 </table>
447 </aside>
448 <p><strong>freespace-most</strong></p>
449 <blockquote>
450 <div><p>The backend which has the most absolute free space (counted in KiB
451 units) is selected.</p>
452 <div class="admonition note">
453 <p class="admonition-title">Note</p>
454 <p>The considered free space is the sum of the free space on all
455 available partitions on the backend.</p>
456 </div>
457 <p>In the example scenario, <code class="docutils literal notranslate"><span class="pre">be1</span></code> would be selected as most fitting,
458 since 1000 GB of free space is the most of all backends.</p>
459 </div></blockquote>
460 <p><strong>freespace-percent-most</strong></p>
461 <blockquote>
462 <div><p>On each backend, only the partition with the most percentage of free
463 space is considered. The selected backend is the one whose partition
464 has the highest percentage of free space.</p>
465 <p>In the example scenario, <code class="docutils literal notranslate"><span class="pre">be3</span></code> would be selected as most fitting,
466 since it has a partition with 80% of free space which is the
467 highest of all backends.</p>
468 </div></blockquote>
469 <p><strong>freespace-percent-weighted</strong></p>
470 <blockquote>
471 <div><p>On each backend, only the partition with the most percentage of free
472 space is considered: this is the backend weight. Then a weighted
473 choice is performed to select one of the backends.</p>
474 <p>In the example scenario, the weight of each backend would be:</p>
475 <ul class="simple">
476 <li><p>50 for <code class="docutils literal notranslate"><span class="pre">be1</span></code></p></li>
477 <li><p>70 for <code class="docutils literal notranslate"><span class="pre">be2</span></code></p></li>
478 <li><p>80 for <code class="docutils literal notranslate"><span class="pre">be3</span></code></p></li>
479 </ul>
480 <p>The sum of all weights being 200, the probability for each backend
481 to be selected as most fitting would be:</p>
482 <ul class="simple">
483 <li><p>25% for <code class="docutils literal notranslate"><span class="pre">be1</span></code></p></li>
484 <li><p>35% for <code class="docutils literal notranslate"><span class="pre">be2</span></code></p></li>
485 <li><p>40% for <code class="docutils literal notranslate"><span class="pre">be3</span></code></p></li>
486 </ul>
487 </div></blockquote>
488 <p><strong>freespace-percent-weighted-delta</strong></p>
489 <blockquote>
490 <div><p>On each backend, only the partition with the most percentage of free
491 space is considered.</p>
492 <p>Like with <code class="docutils literal notranslate"><span class="pre">freespace-percent-weighted</span></code>, a weight is associated to
493 each backend. It is computed as follows:</p>
494 <div class="math notranslate nohighlight">
495 \[free - leastfree + 0.5\]</div>
496 <p>Then a weighted choice is performed to select one of the backends.</p>
497 <p>In the example scenario, the weight of each backend would be:</p>
498 <ul class="simple">
499 <li><p>For <code class="docutils literal notranslate"><span class="pre">be1</span></code>: <span class="math notranslate nohighlight">\(50 - 50 + 0.5 = 0.5\)</span></p></li>
500 <li><p>For <code class="docutils literal notranslate"><span class="pre">be2</span></code>: <span class="math notranslate nohighlight">\(70 - 50 + 0.5 = 20.5\)</span></p></li>
501 <li><p>For <code class="docutils literal notranslate"><span class="pre">be3</span></code>: <span class="math notranslate nohighlight">\(80 - 50 + 0.5 = 30.5\)</span></p></li>
502 </ul>
503 <p>Then the probability for each backend to be selected as most fitting would be:</p>
504 <ul class="simple">
505 <li><p>1.0% for <code class="docutils literal notranslate"><span class="pre">be1</span></code></p></li>
506 <li><p>39.8% for <code class="docutils literal notranslate"><span class="pre">be2</span></code></p></li>
507 <li><p>59.2% for <code class="docutils literal notranslate"><span class="pre">be3</span></code></p></li>
508 </ul>
509 </div></blockquote>
510 </section>
511 <section id="excluding-backends">
512 <h3>Excluding Backends<a class="headerlink" href="#excluding-backends" title="Link to this heading"></a></h3>
513 <p>When using a selection mode other than <code class="docutils literal notranslate"><span class="pre">random</span></code>, backends are
514 automatically excluded if their considered usage percentage is beyond
515 the <code class="docutils literal notranslate"><span class="pre">serverlist_select_soft_usage_limit</span></code> integer setting.</p>
516 </section>
517 <section id="backend-s-usage-information-reset">
518 <h3>Backend's Usage Information Reset<a class="headerlink" href="#backend-s-usage-information-reset" title="Link to this heading"></a></h3>
519 <p>By default backends usage data are retrieved only once upon service
520 initialization.</p>
521 <div class="admonition note">
522 <p class="admonition-title">Note</p>
523 <p>This only concerns selection modes other than <code class="docutils literal notranslate"><span class="pre">random</span></code>.</p>
524 </div>
525 <p>If you tend to use the same service instance for a long lapse of time
526 and performs a large amounts of mailbox creations, it may be useful to
527 configure the <code class="docutils literal notranslate"><span class="pre">serverlist_select_usage_reinit</span></code> so that the backend's
528 disk usage information is refreshed after the configured number of
529 creation requests.</p>
530 <p>Back to <a class="reference internal" href="../features.html#imap-features"><span class="std std-ref">Features</span></a></p>
531 </section>
532 </section>
533 </section>
534
535
536 </div>
537 </div>
538 <footer><div class="rst-footer-buttons" role="navigation" aria-label="Footer">
539 <a href="mailbox-annotations.html" class="btn btn-neutral float-left" title="Mailbox Annotations (METADATA)" accesskey="p" rel="prev"><span class="fa fa-arrow-circle-left" aria-hidden="true"></span> Previous</a>
540 <a href="delayed-delete.html" class="btn btn-neutral float-right" title="Delayed Delete" accesskey="n" rel="next">Next <span class="fa fa-arrow-circle-right" aria-hidden="true"></span></a>
541 </div>
542
543 <hr/>
544
545 <div role="contentinfo">
546 <p>&#169; Copyright 1993–2026, The Cyrus Team.</p>
547 </div>
548
549 Built with <a href="https://www.sphinx-doc.org/">Sphinx</a> using a
550 <a href="https://github.com/readthedocs/sphinx_rtd_theme">theme</a>
551 provided by <a href="https://readthedocs.org">Read the Docs</a>.
552
553
554 </footer>
555 </div>
556 </div>
557 </section>
558 </div>
559 <script>
560 jQuery(function () {
561 SphinxRtdTheme.Navigation.enable(true);
562 });
563 </script>
564
565
566
567
568 </body>
569 </html>