You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@ponymail.apache.org by hu...@apache.org on 2017/06/04 14:17:02 UTC
[1/2] incubator-ponymail-site git commit: add a bit about picking a
generator
Repository: incubator-ponymail-site
Updated Branches:
refs/heads/asf-site a0d9013c1 -> f1cd2859f
add a bit about picking a generator
Project: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/commit/75f4eb12
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/tree/75f4eb12
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/diff/75f4eb12
Branch: refs/heads/asf-site
Commit: 75f4eb1229c21234c8f8ca04be3f20ecd442e804
Parents: a0d9013
Author: Daniel Gruno <hu...@apache.org>
Authored: Sun Jun 4 16:16:32 2017 +0200
Committer: Daniel Gruno <hu...@apache.org>
Committed: Sun Jun 4 16:16:32 2017 +0200
----------------------------------------------------------------------
source/markdown/docs/ARCHIVING.md | 13 +++++++++++++
source/markdown/docs/INSTALLING.md | 8 +-------
2 files changed, 14 insertions(+), 7 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/blob/75f4eb12/source/markdown/docs/ARCHIVING.md
----------------------------------------------------------------------
diff --git a/source/markdown/docs/ARCHIVING.md b/source/markdown/docs/ARCHIVING.md
index 75246ba..4fe88f8 100644
--- a/source/markdown/docs/ARCHIVING.md
+++ b/source/markdown/docs/ARCHIVING.md
@@ -69,6 +69,19 @@ defined as a member via OAuth full access to all private lists.
If you use LDAP, you can modify the LDAP queries in the example AAA file to suit
your organization.
+## Using the right ID generator
+Pony Mail relies on ID generators to produce a unique document ID for each email.
+Depending on the setup of your installation, we recommend using one of two generators:
+
+- If you have a single-node setup, we recommend using the `full` generator. This generator
+ uses the full message body, including MTA trails (Received headers etc), to generate an ID.
+- If you have a clustered/redundant setup (multiple archiver nodes), we recommend using the
+ `redundant` generator. This will use as many unique traits in an email as possible, but
+ discard the MTA trail (which differs from machine to machine).
+
+We do not recommend using the older generators (`medium` and `short`)
+for new installations, as they are theoretically prone to create
+duplicate IDs (See issues #176 #177 #178).
## Importing/Archiving HTML-only emails
Should you need to import HTML-only emails into the archive, you may enable this
http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/blob/75f4eb12/source/markdown/docs/INSTALLING.md
----------------------------------------------------------------------
diff --git a/source/markdown/docs/INSTALLING.md b/source/markdown/docs/INSTALLING.md
index e7244de..e45ef64 100644
--- a/source/markdown/docs/INSTALLING.md
+++ b/source/markdown/docs/INSTALLING.md
@@ -205,10 +205,4 @@ By default, headers such as to/cc are not shown in the normal email view.
To enable these headers, set `full_headers` to `true` in the `site/api/lib/config.lua` file.
### Lastly, a note about Message-ID (MID) generators
-The default MID generator is called 'medium' and digests the message
-body, timestamp and list-ID to generate the MID. There is also a 'short'
-that only digests the body, and a 'full' that uses the entire message as
-a bytestring to generate an ID. Medium is recommended for most setups
-(especially clustered setups), while full can be used for single-machine
-setups.
-N.B. At present, all the generators have issues, see (#176 #177 #178)
+Please see [this paragraph](archiving.html#usingtherightidgenerator) about document ID generators.
[2/2] incubator-ponymail-site git commit: rebuild
Posted by hu...@apache.org.
rebuild
Project: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/repo
Commit: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/commit/f1cd2859
Tree: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/tree/f1cd2859
Diff: http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/diff/f1cd2859
Branch: refs/heads/asf-site
Commit: f1cd2859f7d3dab23181ba8c3e07dfc0d7c2d4fe
Parents: 75f4eb1
Author: Daniel Gruno <hu...@apache.org>
Authored: Sun Jun 4 16:16:45 2017 +0200
Committer: Daniel Gruno <hu...@apache.org>
Committed: Sun Jun 4 16:16:45 2017 +0200
----------------------------------------------------------------------
content/docs/archiving.html | 13 +++++++++++++
content/docs/installing.html | 8 +-------
2 files changed, 14 insertions(+), 7 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/blob/f1cd2859/content/docs/archiving.html
----------------------------------------------------------------------
diff --git a/content/docs/archiving.html b/content/docs/archiving.html
index 9914218..ea047c0 100644
--- a/content/docs/archiving.html
+++ b/content/docs/archiving.html
@@ -89,6 +89,19 @@ provided it is set as an authority in config.lua. This will provide anyone
defined as a member via OAuth full access to all private lists.</p>
<p>If you use LDAP, you can modify the LDAP queries in the example AAA file to suit
your organization.</p>
+<h2 id='usingtherightidgenerator'>Using the right ID generator<a href='#usingtherightidgenerator' style='color: rgba(0,0,0,0);'>¶</a></h2>
+<p>Pony Mail relies on ID generators to produce a unique document ID for each email.
+Depending on the setup of your installation, we recommend using one of two generators:</p>
+<ul>
+<li>If you have a single-node setup, we recommend using the <code>full</code> generator. This generator
+ uses the full message body, including MTA trails (Received headers etc), to generate an ID.</li>
+<li>If you have a clustered/redundant setup (multiple archiver nodes), we recommend using the
+ <code>redundant</code> generator. This will use as many unique traits in an email as possible, but
+ discard the MTA trail (which differs from machine to machine).</li>
+</ul>
+<p>We do not recommend using the older generators (<code>medium</code> and <code>short</code>)
+for new installations, as they are theoretically prone to create
+duplicate IDs (See issues #176 #177 #178).</p>
<h2 id='importingarchivinghtmlonlyemails'>Importing/Archiving HTML-only emails<a href='#importingarchivinghtmlonlyemails' style='color: rgba(0,0,0,0);'>¶</a></h2>
<p>Should you need to import HTML-only emails into the archive, you may enable this
with the <code>--html2text</code> command line arg. This requires that the <code>html2text</code> Python3 package
http://git-wip-us.apache.org/repos/asf/incubator-ponymail-site/blob/f1cd2859/content/docs/installing.html
----------------------------------------------------------------------
diff --git a/content/docs/installing.html b/content/docs/installing.html
index f59984d..d17fad8 100644
--- a/content/docs/installing.html
+++ b/content/docs/installing.html
@@ -203,13 +203,7 @@ You may use the following variables in the footer:</p>
<p>By default, headers such as to/cc are not shown in the normal email view.
To enable these headers, set <code>full_headers</code> to <code>true</code> in the <code>site/api/lib/config.lua</code> file.</p>
<h3 id='lastlyanoteaboutmessageidmidgenerators'>Lastly, a note about Message-ID (MID) generators<a href='#lastlyanoteaboutmessageidmidgenerators' style='color: rgba(0,0,0,0);'>¶</a></h3>
-<p>The default MID generator is called 'medium' and digests the message
-body, timestamp and list-ID to generate the MID. There is also a 'short'
-that only digests the body, and a 'full' that uses the entire message as
-a bytestring to generate an ID. Medium is recommended for most setups
-(especially clustered setups), while full can be used for single-machine
-setups.
-N.B. At present, all the generators have issues, see (#176 #177 #178)</p>
+<p>Please see <a href="archiving.html#usingtherightidgenerator">this paragraph</a> about document ID generators.</p>
<div style="display: inline-block; background: #BBB; margin: -10px; padding: 10px;">
<h4><a id="disclaimer"></a>Disclaimer</h4>
<div style="width: 65%; float: left;">