This is an automated email from the ASF dual-hosted git repository. btellier pushed a commit to branch master in repository https://gitbox.apache.org/repos/asf/james-project.git
commit 2699e74e6d9b347de6aa627d682c5d297d3cb2cb Author: Rene Cordier <[email protected]> AuthorDate: Fri Jul 26 15:41:21 2019 +0700 JAMES-2839 Update the how-to vault documentation --- src/homepage/howTo/deleted-messages-vault.html | 233 ++++++++++++++++--------- 1 file changed, 155 insertions(+), 78 deletions(-) diff --git a/src/homepage/howTo/deleted-messages-vault.html b/src/homepage/howTo/deleted-messages-vault.html index d1c5824..6459044 100644 --- a/src/homepage/howTo/deleted-messages-vault.html +++ b/src/homepage/howTo/deleted-messages-vault.html @@ -28,38 +28,39 @@ layout: howTo <div class=""> <div class="content align-left"> <header class="major"> - <h1><b>Deleted Messages Vault</b></h1> + <h1>Deleted Messages Vault</h1> </header> <p> - This document will help you understand what is Deleted Messages Vault. And finally, - present to you, how to setup James Server with this feature. + The goal of this document is to help you to understand better about this feature and to present you the following topics: </p> <ul> - <li>What is Deleted Messages Vault</li> + <li>What is Deleted Messages Vault ?</li> <li>How to setup James with Deleted Messages Vault</li> - <li>How to administrate Deleted Messages Vault</li> + <li>Deleted Messages Vault administration</li> + <li>Example: Starting James with enabled Deleted Messages Vault by docker compose</li> </ul> <header class="major"> - <h2><b>What is Deleted Messages Vault</b></h2> + <h2>What is Deleted Messages Vault ?</h2> </header> - <p>Deleted Messages Vault is a feature in James, it allows you to:</p> + <p>Deleted Messages Vault is a feature in James allowing you to:</p> <ul> - <li>retain user deleted messages for some time</li> + <li>retain users deleted messages for some time</li> <li>restore & export deleted messages by various criteria</li> <li>permanently delete some retained messages</li> </ul> <p> - If Deleted Messages Vault is enabled, when users delete their mails, James will retain these mails into Deleted Messages Vault. + If the Deleted Messages Vault is enabled, when users delete their mails, and by that we mean when he tries + to definitely delete them by emptying the trash, James will retain these mails into the Deleted Messages Vault. And only administrators can interact with this component via WebAdmin REST APIs. </p> <p> One useful use of that feature is to allow an administrator to restore some mails an user may have deleted by accident. - However, mails are not retained forever as you have to configure a retention period before using it (we'll see later how to trigger the collection of mails). + However, mails are not retained forever as you have to configure a retention period before using it (with a one year retention by default if not defined). It's also possible to permanently delete a mail if needed. </p> <p> @@ -67,34 +68,39 @@ layout: howTo At the moment, these are supported mail properties for filtering: </p> <ul> - <li>deletion date(ISO-8601 Date String) + <li>deletion date (ISO-8601 Date String) <ul> <li>supports before or equals operator</li> <li>supports after or equals operator</li> </ul> </li> - <li>delivery date(ISO-8601 Date String) + <li>delivery date (ISO-8601 Date String) <ul> <li>supports before or equals operator</li> <li>supports after or equals operator</li> </ul> </li> - <li>recipients(List of string) + <li>recipients (List of strings) <ul> <li>supports contains operator</li> </ul> </li> - <li>sender(String) + <li>sender (String) <ul> <li>supports equal matching operator</li> </ul> </li> - <li>has attachment(Boolean) + <li>has attachment (Boolean) <ul> <li>supports equal matching operator</li> </ul> </li> - <li>subject(String) + <li>origin mailboxes (List of strings) + <ul> + <li>supports contains matching operator</li> + </ul> + </li> + <li>subject (String) <ul> <li>supports equal matching operator</li> <li>supports equal ignore case matching operator</li> @@ -105,32 +111,93 @@ layout: howTo </ul> <header class="major"> - <h2><b>How to setup James with Deleted Messages Vault</b></h2> + <h2>How to setup James with Deleted Messages Vault</h2> </header> <p> - In this section, we will guide you to setup James with Deleted Message Vault by following below steps: + In this section, we will guide you to setup James with Deleted Messages Vault by following the steps below: </p> <ul> - <li>Enable Deleted Messages Vault</li> - <li>Make James uses Deleted Messages Vault by configuring Pre Deletion Hooks</li> - <li>Starting James with enabled Deleted Message Vault by docker compose</li> + <li>Enable Deleted Messages Vault by configuring Pre Deletion Hooks</li> + <li>Configuring your BlobStore</li> + <li>Configuring the retention time for the Deleted Messages Vault</li> </ul> <header class="major"> - <h3><b>Enable Deleted Messages Vault</b></h3> + <h4>Enable Deleted Messages Vault by configuring Pre Deletion Hooks</h4> </header> <p> - To do this, you have to create a configuration file <b>deletedMessageVault.properties</b>, then put it into <b>conf</b> directory of James. - There are two available properties you may want to configure: + By default, you need to configure a Pre Deletion Hook to let James use it. + Before deleting a mail in James, PreDeletionHooks will be triggered to execute all declared hooks. If all hook executions success, then James will process to delete that mail. + There is already a DeletedMessageVaultHook in James, its job is to store deleted mails into Deleted Messages Vault. Thus, you need to configure this hook in listeners.xml configuration file. + </p> + + <p> + Sample DeletedMessageVaultHook configuration: + </p> + <pre><code> +<listeners> + <listener> + ... + </listener> + ... + <preDeletionHook> + <class>org.apache.james.vault.DeletedMessageVaultHook</class> + </preDeletionHook> +</listeners> + </code></pre> + <p> + More details about configuration & example is at <a href="/server/config-listeners.html">Pre Deletion Hook Configuration</a> + </p> + + <header class="major"> + <h4>Configuring your BlobStore</h4> + </header> + + <p> + The Deleted Messages Vault is using a BlobStore to store and manage the deleted messages. A BlobStore is a dedicated + component to store blobs, non-indexable content. There is different implementations available for the BlobStore on top + of Cassandra or file object storage services like Openstack Swift and AWS S3. + </p> + + <p> + Let's consider that we want to store those deleted messages into an Openstack Swift object storage. So the configuration + in the blob.properties file should look similar to this: + </p> + + <pre><code> +implementation=objectstorage + +# Configuration for swift BlobStore +objectstorage.payload.codec=DEFAULT +objectstorage.provider=swift +objectstorage.namespace=james +objectstorage.swift.authapi=tmpauth +objectstorage.swift.endpoint=http://swift:8080/auth/v1.0 +objectstorage.swift.credentials=testing +objectstorage.swift.tempauth.username=tester +objectstorage.swift.tempauth.tenantname=test +objectstorage.swift.tempauth.passheadername=X-Storage-Pass +objectstorage.swift.tempauth.userheadername=X-Storage-User + </code></pre> + + <p> + If you want to dig deeper into the subject, or use an other implementation, you can find more details about this at the + <a href="/server/config-blobstore.html">BlobStore Configuration</a> page. + </p> + + <header class="major"> + <h4>Configuring the retention time for the Deleted Messages Vault</h4> + </header> + + <p> + To do this, you have to create a configuration file <b>deletedMessageVault.properties</b>, then put it into the <b>conf</b> directory of James. + There is only one available property you may want to configure at the moment: </p> <ul> <li> - <b>urlPrefix</b>: represent for the prefix of namespace Deleted Messages Vault will use to store deleted messages. - </li> - <li> - <b>retentionPeriod</b>: represent for the period deleted messages allowed to be stored in Deleted Messages Vault. + <b>retentionPeriod</b>: represent for the period deleted messages allowed to be stored in Deleted Messages Vault (default of one year). </li> </ul> @@ -138,112 +205,122 @@ layout: howTo Example: </p> <pre><code> -urlPrefix=cassandra://var/deletedMessages/vault -retentionPeriod=1 year +retentionPeriod=1y </code></pre> <p> - More details about configuration & example is at <a href="/server/config-vault.html">Deleted Messages Vault Configuration</a> + More details about configuration & example can be found at + <a href="/server/config-vault.html">Deleted Messages Vault Configuration</a> </p> <header class="major"> - <h3><b>Make James uses Deleted Messages Vault by configuring Pre Deletion Hooks</b></h3> + <h2>Deleted Messages Vault administration</h2> </header> <p> - By default, although Deleted Messages Vault has been configured, but, to make it really work, you still need to configure Pre Deletion Hooks to lets James use it. - Before deleting a mail in James, PreDeletionHooks will be triggered to execute all hooks. If all hook executions success, then James will process to delete that mail. - There is already a DeletedMessageVaultHook in James, its job to store deleted mails into Deleted Messages Vault. Thus, you need to configure this hook in listeners.xml configuration file. + These are supported WebAdmin features on top of Deleted Messages Vault. + You can have a look at the WebAdmin Deleted Messages Vault documentation <a href="/server/manage-webadmin.html#Deleted_Messages_Vault">here</a> </p> + <header class="major"> + <h4>WebAdmin Deleted Messages Vault exporting</h4> + </header> + <p> - Sample DeletedMessageVaultHook configuration: + When the administrator needs to export some user's deleted messages, you are able to choose which exporting mechanism should be used. + At the moment there are two available exporting mechanisms: </p> + + <ul> + <li> + <b>localFile</b>: This is a simple exporting mechanism. Through an export request, it retrieves deleted mails from Deleted Messages Vault, + then store them as a zip file in James Server local file system. Then it sends a mail with the absolute path of exported file to the targeted mail address. + </li> + <li> + <b>linshare</b>: Instead of exporting blobs to the local file system, using + <a href="https://www.linshare.org/en/index.html";>LinShare</a> helps you upload your blobs and people + you have been sharing to can access those blobs by accessing the LinShare server and download them. + </li> + </ul> + + <p> + You can configure which kind of export mechanism you want to use in James by specifying <b>blob.export.implementation</b> property in blob.properties configuration file. + E.g: + </p> + <pre><code> -<listeners> - <listener> - ... - </listener> - ... - <preDeletionHook> - <class>org.apache.james.vault.DeletedMessageVaultHook</class> - </preDeletionHook> -</listeners> +blob.export.implementation=localFile </code></pre> + <p> - More details about configuration & example is at <a href="/server/config-listener.html">Pre Deletion Hook Configuration</a> + You can find more details about configuration & example at <a href="/server/config-blob-export.html">Blob Export Configuration</a> page </p> <header class="major"> - <h3><b>Starting James with enabled Deleted Message Vault by docker compose</b></h3> + <h2>Example: Starting James with enabled Deleted Messages Vault by docker compose</h2> </header> - <p>We will take James cassandra product for the example</p> + <p> + And now to sum up everything we have seen until now and put it into practice, we will take + James cassandra-rabbitmq product for the example + </p> + + <p>First, get the template cassandra-rabbitmq product configuration:</p> - <p>First, get template cassandra product configuration:</p> <pre><code> $ git clone https://github.com/apache/james-project -$ cp -rf james-project/dockerfiles/run/guice/cassandra/destination/conf conf +$ cp -rf james-project/dockerfiles/run/guice/cassandra-rabbitmq/destination/conf conf </code></pre> <p>Then create the keystore file in the conf/ directory with the default password <code>james72laBalle</code> + <pre><code> $ keytool -genkey -alias james -keyalg RSA -keystore conf/keystore </code></pre> - <p>Second, modify deletedMessageVault.properties configuration file like an example at previous paragraph</p> + <p>Second, modify deletedMessageVault.properties configuration file like in the previous example</p> <p>Third, modify listeners.xml to configure DeletedMessageVaultHook by adding preDeletionHook section at previous paragraph</p> - <p>Fourth, We will create a local folder for holding data out of the container:</p> + <p> + Fourth, modify blob.properties file to configure the BlobStore that will be used and the file exporting mechanism, like + we saw previously as well. + </p> + + <p>Fifth, we will create a local folder for holding data out of the container:</p> + <pre><code> -mkdir var +$ mkdir var </code></pre> <p>Finally, starting a James Server by docker compose</p> + <p>Getting James docker-compose.yml</p> + <pre><code> $ wget https://raw.githubusercontent.com/apache/james-project/master/dockerfiles/run/docker-compose.yml </code></pre> <p>Add the following volumes for james service:</p> + <pre><code> volumes: - $PWD/conf:/root/conf/ - $PWD/var:/root/var/ </code></pre> - <header class="major"> - <h2><b>How to administrate Deleted Messages Vault</b></h2> - </header> - <p> - These are supported WebAdmin features on top of Deleted Messages Vault. - You can have a look at WebAdmin Deleted Messages Vault document at <a href="https://james.apache.org/server/manage-webadmin.html#Deleted_Messages_Vault";>here</a> + Then you can run it and you should have a James server with an enabled Deleted Messages Vault. You can then + refer to <a href="/server/manage-webadmin.html">WebAdmin documentation</a> to create a few users, domains, + mailboxes, and then connecting to it your favorite mail client to start sending messages between + those users and deleting them. </p> - <header class="major"> - <h3><b>WebAdmin Deleted Messages Vault exporting</b></h3> - </header> - - <p> - This part is a bit special to you, you are able to choose which exporting mechanism to be used. At the moment there are one available exporting mechanism - </p> - <ul> - <li><b>localFile</b>: This is a simple exporting mechanism while with an export request, it retrieves deleted mails from Deleted Messages Vault, - then store them as a zip file in local file system in James Server. Then sending a mail with the absolute path of exported file to the targeted mail address.</li> - </ul> <p> - You can configure which kind of export mechanism to use in James by specifying <b>blob.export.implementation</b> in blobStore.properties configuration file. - E.g: + And finally you can check more specifically the <a href="/server/manage-webadmin.html#Deleted_Messages_Vault">WebAdmin Deleted Messages Vault documentation</a> to explore all the possibilities of the vault. </p> - <pre><code> -blob.export.implementation=localFile - </code></pre> - <p> - More details about configuration & example at <a href="/server/config-blob-export.html">Blob Export Configuration</a> - </p> </div> + <footer class="major"> <ul class="actions align-center"> <li><a href="index.html" class="button">go back to other how-tos</a></li> --------------------------------------------------------------------- To unsubscribe, e-mail: [email protected] For additional commands, e-mail: [email protected]
