Google Git
Sign in
apache / james-site / a15da97d6f43d2450183d8ff4b8722aa4ad8b24d / . / james-distributed-app / 3.8.1 / configure / opensearch.html
blob: 688d862b3ec67a8962d92c28f278715b3718f6e4 [file] [log] [blame]
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>Distributed James Server &mdash; opensearch.properties :: Apache James</title>
<meta name="generator" content="Antora 3.1.2">
<link rel="stylesheet" href="../../../_/css/site.css">
</head>
<body class="article">
<header class="header">
<nav class="navbar">
<div class="navbar-brand">
<a class="navbar-item" href="https://james.apache.org"><img src="/_/img/james.svg" alt="james logo"> Apache James</a>
<button class="navbar-burger" data-target="topbar-nav">
<span></span>
<span></span>
<span></span>
</button>
</div>
<div id="topbar-nav" class="navbar-menu">
<div class="navbar-end">
<a class="navbar-item" href="#">Home</a>
<div class="navbar-item has-dropdown is-hoverable">
<a class="navbar-link" href="#">Products</a>
<div class="navbar-dropdown">
<div class="navbar-item"><strong>James server</strong></div>
<a class="navbar-item" href="https://github.com/apache/james-project">Repository</a>
<a class="navbar-item" href="https://issues.apache.org/jira/projects/JAMES/issues">Issue Tracker</a>
<hr class="navbar-divider">
<a class="navbar-item" href="https://james.apache.org/mime4j/index.html">Mime4J</a>
<a class="navbar-item" href="https://james.apache.org/jsieve/index.html">jSieve</a>
<a class="navbar-item" href="https://james.apache.org/jspf/index.html">jSPF</a>
<a class="navbar-item" href="https://james.apache.org/jdkim/index.html">jDKIM</a>
<a class="navbar-item" href="https://james.apache.org/hupa/index.html">HUPA</a>
</div>
</div>
<div class="navbar-item has-dropdown is-hoverable">
<a class="navbar-link" href="#">Community</a>
<div class="navbar-dropdown">
<!-- Not ideal but dropping the version in the href requires tweaking james-projet docs module first -->
<a class="navbar-item" href="/james-project/3.6.0/community/mailing-lists.html">Mailing lists</a>
<a class="navbar-item" href="https://gitter.im/apache/james-project"><svg version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 32 32" class="logo-gitter-sign" data-v-44ebcb1a=""><rect x="15" y="5" width="2" height="10"></rect> <rect x="10" y="5" width="2" height="20"></rect> <rect x="5" y="5" width="2" height="20"></rect> <rect width="2" height="15"></rect></svg> Gitter</a>
<a class="navbar-item" href="https://twitter.com/ApacheJames">
<span class="icon">
<svg aria-hidden="true" data-icon="twitter" role="img" xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
<path fill="#57aaee" d="M459.37 151.716c.325 4.548.325 9.097.325 13.645 0 138.72-105.583 298.558-298.558 298.558-59.452 0-114.68-17.219-161.137-47.106 8.447.974 16.568 1.299 25.34 1.299 49.055 0 94.213-16.568 130.274-44.832-46.132-.975-84.792-31.188-98.112-72.772 6.498.974 12.995 1.624 19.818 1.624 9.421 0 18.843-1.3 27.614-3.573-48.081-9.747-84.143-51.98-84.143-102.985v-1.299c13.969 7.797 30.214 12.67 47.431 13.319-28.264-18.843-46.781-51.005-46.781-87.391 0-19.492 5.197-37.36 14.294-52.954 51.655 63.675 129.3 105.258 216.365 109.807-1.624-7.797-2.599-15.918-2.599-24.04 0-57.828 46.782-104.934 104.934-104.934 30.213 0 57.502 12.67 76.67 33.137 23.715-4.548 46.456-13.32 66.599-25.34-7.798 24.366-24.366 44.833-46.132 57.827 21.117-2.273 41.584-8.122 60.426-16.243-14.292 20.791-32.161 39.308-52.628 54.253z"></path>
</svg>
</span> Twitter
</a>
<a class="navbar-item" href="#"> <svg class="octicon octicon-mark-github v-align-middle" viewBox="0 0 16 16" version="1.1" aria-hidden="true"><path fill-rule="evenodd" d="M8 0C3.58 0 0 3.58 0 8c0 3.54 2.29 6.53 5.47 7.59.4.07.55-.17.55-.38 0-.19-.01-.82-.01-1.49-2.01.37-2.53-.49-2.69-.94-.09-.23-.48-.94-.82-1.13-.28-.15-.68-.52-.01-.53.63-.01 1.08.58 1.23.82.72 1.21 1.87.87 2.33.66.07-.52.28-.87.51-1.07-1.78-.2-3.64-.89-3.64-3.95 0-.87.31-1.59.82-2.15-.08-.2-.36-1.02.08-2.12 0 0 .67-.21 2.2.82.64-.18 1.32-.27 2-.27.68 0 1.36.09 2 .27 1.53-1.04 2.2-.82 2.2-.82.44 1.1.16 1.92.08 2.12.51.56.82 1.27.82 2.15 0 3.07-1.87 3.75-3.65 3.95.29.25.54.73.54 1.48 0 1.07-.01 1.93-.01 2.2 0 .21.15.46.55.38A8.013 8.013 0 0016 8c0-4.42-3.58-8-8-8z"></path></svg> Github</a>
</div>
</div>
<!-- <div class="navbar-item">
<span class="control">
<a class="button is-primary" href="#">Download</a>
</span>
</div> -->
</div>
</div>
</nav>
</header>
<div class="body">
<div class="nav-container" data-component="james-distributed-app" data-version="3.8.1">
<aside class="nav">
<div class="panels">
<div class="nav-panel-menu is-active" data-panel="menu">
<nav class="nav-menu">
<button class="nav-menu-toggle" aria-label="Toggle expand/collapse all" style="display: none"></button>
<h3 class="title"><a href="../index.html">Apache James Distributed Server</a></h3>
<ul class="nav-list">
<li class="nav-item" data-depth="0">
<ul class="nav-list">
<li class="nav-item" data-depth="1">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="../index.html">Distributed James Application</a>
<ul class="nav-list">
<li class="nav-item" data-depth="2">
<a class="nav-link" href="../objectives.html">Objectives and motivation</a>
</li>
<li class="nav-item" data-depth="2">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="../architecture/index.html">Architecture</a>
<ul class="nav-list">
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../architecture/implemented-standards.html">Implemented standards</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../architecture/consistency-model.html">Consistency Model</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../architecture/specialized-instances.html">Specialized instances</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="2">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="../run/index.html">Run</a>
<ul class="nav-list">
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../run/run-java.html">Run with Java</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../run/run-docker.html">Run with Docker</a>
</li>
<li class="nav-item" data-depth="3">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="../run/run-kubernetes.html">Run with Kubernetes</a>
<ul class="nav-list">
<li class="nav-item" data-depth="4">
<a class="nav-link" href="../run/k8s-checklist.html">Deployment Checklist</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="../run/k8s-logsMetrics.html">Logs &amp; Metrics</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="../run/k8s-values.html">values.yaml</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="../run/k8s-secrets.html">secrets.yaml</a>
</li>
</ul>
</li>
</ul>
</li>
<li class="nav-item" data-depth="2">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="index.html">Configuration</a>
<ul class="nav-list">
<li class="nav-item" data-depth="3">
<button class="nav-item-toggle"></button>
<span class="nav-text">Protocols</span>
<ul class="nav-list">
<li class="nav-item" data-depth="4">
<a class="nav-link" href="imap.html">imapserver.xml</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="jmap.html">jmap.properties</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="jmx.html">jmx.properties</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="smtp.html">smtpserver.xml &amp; lmtpserver.xml</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="smtp-hooks.html">Packaged SMTP hooks</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="pop3.html">pop3server.xml</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="webadmin.html">webadmin.properties</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="ssl.html">SSL &amp; TLS</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="sieve.html">Sieve &amp; ManageSieve</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="3">
<button class="nav-item-toggle"></button>
<span class="nav-text">Storage dependencies</span>
<ul class="nav-list">
<li class="nav-item" data-depth="4">
<a class="nav-link" href="blobstore.html">blobstore.properties</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="cassandra.html">cassandra.properties</a>
</li>
<li class="nav-item is-current-page" data-depth="4">
<a class="nav-link" href="opensearch.html">opensearch.properties</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="rabbitmq.html">rabbitmq.properties</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="redis.html">redis.properties</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="tika.html">tika.properties</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="3">
<button class="nav-item-toggle"></button>
<span class="nav-text">Core components</span>
<ul class="nav-list">
<li class="nav-item" data-depth="4">
<a class="nav-link" href="batchsizes.html">batchsizes.properties</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="dns.html">dnsservice.xml</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="domainlist.html">domainlist.xml</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="healthcheck.html">healthcheck.properties</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="mailetcontainer.html">mailetcontainer.xml</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="mailets.html">Packaged Mailets</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="matchers.html">Packaged Matchers</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="mailrepositorystore.html">mailrepositorystore.xml</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="recipientrewritetable.html">recipientrewritetable.xml</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="search.html">search.properties</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="usersrepository.html">usersrepository.xml</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="3">
<button class="nav-item-toggle"></button>
<span class="nav-text">Extensions</span>
<ul class="nav-list">
<li class="nav-item" data-depth="4">
<a class="nav-link" href="vault.html">deletedMessageVault.properties</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="extensions.html">extensions.properties</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="listeners.html">listeners.xml</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="spam.html">Anti-Spam setup</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="remote-delivery-error-handling.html">About RemoteDelivery error handling</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="collecting-contacts.html">Contact collection</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="collecting-events.html">Event collection</a>
</li>
<li class="nav-item" data-depth="4">
<a class="nav-link" href="dsn.html">ESMTP DSN support</a>
</li>
</ul>
</li>
</ul>
</li>
<li class="nav-item" data-depth="2">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="../operate/index.html">Operate</a>
<ul class="nav-list">
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../operate/guide.html">Operator guide</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../operate/performanceChecklist.html">Performance checklist</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../operate/logging.html">Logging</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../operate/webadmin.html">WebAdmin REST administration API</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../operate/metrics.html">Metrics</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../operate/migrating.html">Migrating existing data</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../operate/cli.html">Command Line Interface</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../operate/cassandra-migration.html">Cassandra migration</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../operate/security.html">Security checklist</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="2">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="../extending/index.html">Extending server behavior</a>
<ul class="nav-list">
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../extending/mail-processing.html">Custom mail processing components</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../extending/mailbox-listeners.html">Custom Mailbox Listeners</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../extending/smtp-hooks.html">Custom SMTP hooks</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../extending/webadmin-routes.html">Custom WebAdmin routes</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../extending/imap.html">Custom IMAP processing</a>
</li>
</ul>
</li>
<li class="nav-item" data-depth="2">
<button class="nav-item-toggle"></button>
<a class="nav-link" href="../benchmark/index.html">Performance benchmark</a>
<ul class="nav-list">
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../benchmark/db-benchmark.html">Database benchmarks</a>
</li>
<li class="nav-item" data-depth="3">
<a class="nav-link" href="../benchmark/james-benchmark.html">James benchmarks</a>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</li>
</ul>
</nav>
</div>
<div class="nav-panel-explore" data-panel="explore">
<div class="context">
<span class="title">Apache James Distributed Server</span>
<span class="version">3.8.1 SNAPSHOT</span>
</div>
<ul class="components">
<li class="component is-current">
<div class="title"><a href="../index.html">Apache James Distributed Server</a></div>
<ul class="versions">
<li class="version is-current is-latest">
<a href="../index.html">3.8.1 SNAPSHOT</a>
</li>
</ul>
</li>
<li class="component">
<div class="title"><a href="../../../james-project/3.8.1/index.html">Apache James Server</a></div>
<ul class="versions">
<li class="version is-latest">
<a href="../../../james-project/3.8.1/index.html">3.8.1 SNAPSHOT</a>
</li>
<li class="version">
<a href="../../../james-project/3.6.0/index.html">3.6.0 Snapshot</a>
</li>
</ul>
</li>
<li class="component">
<div class="title"><a href="../../../james-site/latest/index.html">Apache James Site</a></div>
<ul class="versions">
<li class="version is-latest">
<a href="../../../james-site/latest/index.html">latest</a>
</li>
</ul>
</li>
</ul>
</div>
</div>
</aside>
</div>
<main class="article">
<div class="toolbar" role="navigation">
<button class="nav-toggle"></button>
<a href="../../../james-site/latest/homepage.html" class="home-link"></a>
<nav class="breadcrumbs" aria-label="breadcrumbs">
<ul>
<li><a href="../index.html">Apache James Distributed Server</a></li>
<li><a href="../index.html">Distributed James Application</a></li>
<li><a href="index.html">Configuration</a></li>
<li>Storage dependencies</li>
<li><a href="opensearch.html">opensearch.properties</a></li>
</ul>
</nav>
<div class="edit-this-page"><a href="https://github.com/apache/james-project/blob/master/server/apps/distributed-app/docs/modules/ROOT/pages/configure/opensearch.adoc">Edit this Page</a></div>
</div>
<div class="content">
<aside class="toc sidebar" data-title="Contents" data-levels="2">
<div class="toc-menu"></div>
</aside>
<article class="doc">
<h1 class="page">Distributed James Server &mdash; opensearch.properties</h1>
<div id="preamble">
<div class="sectionbody">
<div class="paragraph">
<p>Consult this <a href="https://github.com/apache/james-project/blob/master/server/apps/distributed-app/sample-configuration/opensearch.properties">example</a>
to get some examples and hints.</p>
</div>
<div class="paragraph">
<p>If you want more explanation about OpenSearch configuration, you should visit the dedicated <a href="https://opensearch.org/">documentation</a>.</p>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_opensearch_configuration"><a class="anchor" href="#_opensearch_configuration"></a>OpenSearch Configuration</h2>
<div class="sectionbody">
<div class="paragraph">
<p>This file section is used to configure the connection tp an OpenSearch cluster.</p>
</div>
<div class="paragraph">
<p>Here are the properties allowing to do so :</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 1. opensearch.properties content</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property name</th>
<th class="tableblock halign-left valign-top">explanation</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.clusterName</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Is the name of the cluster used by James.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.nb.shards</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Number of shards for index provisionned by James</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.nb.replica</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Number of replica for index provisionned by James (default: 0)</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.index.waitForActiveShards</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Wait for a certain number of active shard copies before proceeding with the operation. Defaults to 1.
You may consult the <a href="https://www.elastic.co/guide/en/elasticsearch/reference/7.10/docs-index_.html#active-shards">documentation</a> for more information.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.retryConnection.maxRetries</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Number of retries when connecting the cluster</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.retryConnection.minDelay</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Minimum delay between connection attempts</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.max.connections</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum count of HTTP connections allowed for the OpenSearch driver. Optional integer, if unspecified driver defaults
applies (30 connections).</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.max.connections.per.hosts</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Maximum count of HTTP connections per host allowed for the OpenSearch driver. Optional integer, if unspecified driver defaults
applies (10 connections).</p></td>
</tr>
</tbody>
</table>
<div class="sect2">
<h3 id="_mailbox_search"><a class="anchor" href="#_mailbox_search"></a>Mailbox search</h3>
<div class="paragraph">
<p>The main use of OpenSearch within the Distributed Server is indexing the mailbox content of users in order to enable
powerful and efficient full-text search of the mailbox content.</p>
</div>
<div class="paragraph">
<p>Data indexing is performed asynchronously in a reliable fashion via a MailboxListener.</p>
</div>
<div class="paragraph">
<p>Here are the properties related to the use of OpenSearch for Mailbox Search:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 2. opensearch.properties content</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property name</th>
<th class="tableblock halign-left valign-top">explanation</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.index.mailbox.name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the mailbox index backed by the alias. It will be created if missing.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.index.name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Deprecated</strong> Use <strong>opensearch.index.mailbox.name</strong> instead.
Name of the mailbox index backed by the alias. It will be created if missing.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.alias.read.mailbox.name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the alias to use by Apache James for mailbox reads. It will be created if missing.
The target of the alias is the index name configured above.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.alias.read.name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Deprecated</strong> Use <strong>opensearch.alias.read.mailbox.name</strong> instead.
Name of the alias to use by Apache James for mailbox reads. It will be created if missing.
The target of the alias is the index name configured above.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.alias.write.mailbox.name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Name of the alias to use by Apache James for mailbox writes. It will be created if missing.
The target of the alias is the index name configured above.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.alias.write.name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><strong>Deprecated</strong> Use <strong>opensearch.alias.write.mailbox.name</strong> instead.
Name of the alias to use by Apache James for mailbox writes. It will be created if missing.
The target of the alias is the index name configured above.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.indexAttachments</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates if you wish to index attachments or not (default: true).</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.indexHeaders</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates if you wish to index headers or not (default: true). Note that specific headers
(From, To, Cc, Bcc, Subject, Message-Id, Date, Content-Type) are still indexed in their dedicated type.
Header indexing is expensive as each header currently need to be stored as a nested document but
turning off headers indexing result in non-strict compliance with the IMAP / JMAP standards.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.message.index.optimize.move</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">When set to true, James will attempt to reindex from the indexed message when moved.
If the message is not found, it will fall back to the old behavior (The message will be indexed from the blobStore source)
Default to false.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.indexBody</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Indicates if you wish to index body or not (default: true). This can be used to decrease the performance cost associated with indexing.</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="_quota_search"><a class="anchor" href="#_quota_search"></a>Quota search</h3>
<div class="paragraph">
<p>Users are indexed by quota usage, allowing operators a quick audit of users quota occupation.</p>
</div>
<div class="paragraph">
<p>Users quota are asynchronously indexed upon quota changes via a dedicated MailboxListener.</p>
</div>
<div class="paragraph">
<p>The following properties affect quota search :</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 3. opensearch.properties content</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property name</th>
<th class="tableblock halign-left valign-top">explanation</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.index.quota.ratio.name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Specify the OpenSearch alias name used for quotas</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.alias.read.quota.ratio.name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Specify the OpenSearch alias name used for reading quotas</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.alias.write.quota.ratio.name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Specify the OpenSearch alias name used for writing quotas</p></td>
</tr>
</tbody>
</table>
</div>
<div class="sect2">
<h3 id="_disabling_opensearch"><a class="anchor" href="#_disabling_opensearch"></a>Disabling OpenSearch</h3>
<div class="paragraph">
<p>OpenSearch component can be disabled but consider it would make search feature to not work. In particular it will break JMAP protocol and SEARCH IMAP comment in an nondeterministic way.
This is controlled in the <code>search.properties</code> file via the <code>implementation</code> property (defaults
to <code>OpenSearch</code>). Setting this configuration parameter to <code>scanning</code> will effectively disable OpenSearch, no
further indexation will be done however searches will rely on the scrolling search, leading to expensive and longer
searches. Disabling OpenSearch requires no extra action, however
<a href="../operate/webadmin.html#_reindexing_all_mails" class="xref page">a full re-indexing</a>needs to be carried out when enabling OpenSearch.</p>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_ssl_trusting_configuration"><a class="anchor" href="#_ssl_trusting_configuration"></a>SSL Trusting Configuration</h2>
<div class="sectionbody">
<div class="paragraph">
<p>By default, James will use the system TrustStore to validate https server certificates, if the certificate on
ES side is already in the system TrustStore, you can leave the sslValidationStrategy property empty or set it to default.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 4. opensearch.properties content</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property name</th>
<th class="tableblock halign-left valign-top">explanation</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.hostScheme.https.sslValidationStrategy</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional. Accept only <strong>default</strong>, <strong>ignore</strong>, <strong>override</strong>. Default is <strong>default</strong>. default: Use the default SSL TrustStore of the system.
ignore: Ignore SSL Validation check (not recommended).
override: Override the SSL Context to use a custom TrustStore containing ES server&#8217;s certificate.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>In some cases, you want to secure the connection from clients to ES by setting up a <strong>https</strong> protocol
with a self signed certificate. And you prefer to left the system ca-certificates un touch.
There are possible solutions to let the ES RestHighLevelClient to trust your self signed certificate.</p>
</div>
<div class="paragraph">
<p>Second solution: importing a TrustStore containing the certificate into SSL context.
A certificate normally contains two parts: a public part in .crt file, another private part in .key file.
To trust the server, the client needs to be acknowledged that the server&#8217;s certificate is in the list of
client&#8217;s TrustStore. Basically, you can create a local TrustStore file containing the public part of a remote server
by execute this command:</p>
</div>
<div class="literalblock">
<div class="content">
<pre>keytool -import -v -trustcacerts -file certificatePublicFile.crt -keystore trustStoreFileName.jks -keypass fillThePassword -storepass fillThePassword</pre>
</div>
</div>
<div class="paragraph">
<p>When there is a TrustStore file and the password to read, fill two options <strong>trustStorePath</strong>
and <strong>trustStorePassword</strong> with the TrustStore location and the password. ES client will accept
the certificate of ES service.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 5. opensearch.properties content</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property name</th>
<th class="tableblock halign-left valign-top">explanation</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.hostScheme.https.trustStorePath</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional. Use it when https is configured in opensearch.hostScheme, and sslValidationStrategy is <strong>override</strong>
Configure OpenSearch rest client to use this trustStore file to recognize nginx&#8217;s ssl certificate.
Once you chose <strong>override</strong>, you need to specify both trustStorePath and trustStorePassword.</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.hostScheme.https.trustStorePassword</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional. Use it when https is configured in opensearch.hostScheme, and sslValidationStrategy is <strong>override</strong>
Configure OpenSearch rest client to use this trustStore file with the specified password.
Once you chose <strong>override</strong>, you need to specify both trustStorePath and trustStorePassword.</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>During SSL handshaking, the client can determine whether accept or reject connecting to a remote server by its hostname.
You can configure to use which HostNameVerifier in the client.</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 6. opensearch.properties content</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Property name</th>
<th class="tableblock halign-left valign-top">explanation</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">opensearch.hostScheme.https.hostNameVerifier</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock">Optional. Default is <strong>default</strong>. default: using the default hostname verifier provided by apache http client.
accept_any_hostname: accept any host (not recommended).</p></td>
</tr>
</tbody>
</table>
</div>
</div>
<div class="sect1">
<h2 id="_search_overrides"><a class="anchor" href="#_search_overrides"></a>Search overrides</h2>
<div class="sectionbody">
<div class="paragraph">
<p><strong>Search overrides</strong> allow resolution of predefined search queries against alternative sources of data
and allow bypassing OpenSearch. This is useful to handle most resynchronisation queries that
are simple enough to be resolved against Cassandra.</p>
</div>
<div class="paragraph">
<p>Possible values are:
- <code>org.apache.james.mailbox.cassandra.search.AllSearchOverride</code> Some IMAP clients uses SEARCH ALL to fully list messages in
a mailbox and detect deletions. This is typically done by clients not supporting QRESYNC and from an IMAP perspective
is considered an optimisation as less data is transmitted compared to a FETCH command. Resolving such requests against
Cassandra is enabled by this search override and likely desirable.
- <code>org.apache.james.mailbox.cassandra.search.UidSearchOverride</code>. Same as above but restricted by ranges.
- <code>org.apache.james.mailbox.cassandra.search.DeletedSearchOverride</code>. Find deleted messages by looking up in the relevant Cassandra
table.
- <code>org.apache.james.mailbox.cassandra.search.DeletedWithRangeSearchOverride</code>. Same as above but limited by ranges.
- <code>org.apache.james.mailbox.cassandra.search.NotDeletedWithRangeSearchOverride</code>. List non deleted messages in a given range.
Lists all messages and filters out deleted message thus this is based on the following heuristic: most messages are not marked as deleted.
- <code>org.apache.james.mailbox.cassandra.search.UnseenSearchOverride</code>. List unseen messages in the corresponding cassandra projection.</p>
</div>
<div class="paragraph">
<p>Please note that custom overrides can be defined here. <code>opensearch.search.overrides</code> allow specifying search overrides and is a
coma separated list of search override FQDNs. Default to none.</p>
</div>
<div class="paragraph">
<p>EG:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>opensearch.search.overrides=org.apache.james.mailbox.cassandra.search.AllSearchOverride,org.apache.james.mailbox.cassandra.search.DeletedSearchOverride, org.apache.james.mailbox.cassandra.search.DeletedWithRangeSearchOverride,org.apache.james.mailbox.cassandra.search.NotDeletedWithRangeSearchOverride,org.apache.james.mailbox.cassandra.search.UidSearchOverride,org.apache.james.mailbox.cassandra.search.UnseenSearchOverride</pre>
</div>
</div>
</div>
</div>
<div class="sect1">
<h2 id="_configure_dedicated_language_analyzers_for_mailbox_index"><a class="anchor" href="#_configure_dedicated_language_analyzers_for_mailbox_index"></a>Configure dedicated language analyzers for mailbox index</h2>
<div class="sectionbody">
<div class="paragraph">
<p>OpenSearch supports various language analyzers out of the box: <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-lang-analyzer.html" class="bare">https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-lang-analyzer.html</a>.</p>
</div>
<div class="paragraph">
<p>James could utilize this to improve the user searching experience upon his language.</p>
</div>
<div class="paragraph">
<p>While one could modify mailbox index mapping programmatically to customize this behavior, here we should just document a manual way to archive this without breaking our common index' mapping code.</p>
</div>
<div class="paragraph">
<p>The idea is modifying mailbox index mappings with the target language analyzer as a JSON file, then submit it directly
to OpenSearch via cURL command to create the mailbox index before James start. Let&#8217;s adapt dedicated language analyzers
where appropriate for the following fields:</p>
</div>
<table class="tableblock frame-all grid-all stretch">
<caption class="title">Table 7. Language analyzers propose change</caption>
<colgroup>
<col style="width: 50%;">
<col style="width: 50%;">
</colgroup>
<thead>
<tr>
<th class="tableblock halign-left valign-top">Field</th>
<th class="tableblock halign-left valign-top">Analyzer change</th>
</tr>
</thead>
<tbody>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">from.name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>keep_mail_and_url</code> analyzer &#8594; <code>keep_mail_and_url_language_a</code> analyzer</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">subject</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>keep_mail_and_url</code> analyzer &#8594; <code>keep_mail_and_url_language_a</code> analyzer</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">to.name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>keep_mail_and_url</code> analyzer &#8594; <code>keep_mail_and_url_language_a</code> analyzer</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">cc.name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>keep_mail_and_url</code> analyzer &#8594; <code>keep_mail_and_url_language_a</code> analyzer</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">bcc.name</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>keep_mail_and_url</code> analyzer &#8594; <code>keep_mail_and_url_language_a</code> analyzer</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">textBody</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>standard</code> analyzer &#8594; <code>language_a</code> analyzer</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">htmlBody</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>standard</code> analyzer &#8594; <code>language_a</code> analyzer</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">attachments.fileName</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>standard</code> analyzer &#8594; <code>language_a</code> analyzer</p></td>
</tr>
<tr>
<td class="tableblock halign-left valign-top"><p class="tableblock">attachments.textContent</p></td>
<td class="tableblock halign-left valign-top"><p class="tableblock"><code>standard</code> analyzer &#8594; <code>language_a</code> analyzer</p></td>
</tr>
</tbody>
</table>
<div class="paragraph">
<p>In there:</p>
</div>
<div class="ulist">
<ul>
<li>
<p><code>keep_mail_and_url</code> and <code>standard</code> are our current analyzers for mailbox index.</p>
</li>
<li>
<p><code>language_a</code> analyzer: the built-in analyzer of OpenSearch. EG: <code>french</code></p>
</li>
<li>
<p><code>keep_mail_and_url_language_a</code> analyzer: a custom of <code>keep_mail_and_url</code> analyzer with some language filters.Every language has
their own filters so please have a look at filters which your language need to add. EG which need to be added for French:</p>
</li>
</ul>
</div>
<div class="listingblock">
<div class="content">
<pre>"filter": {
"french_elision": {
"type": "elision",
"articles_case": true,
"articles": [
"l", "m", "t", "qu", "n", "s",
"j", "d", "c", "jusqu", "quoiqu",
"lorsqu", "puisqu"
]
},
"french_stop": {
"type": "stop",
"stopwords": "_french_"
},
"french_stemmer": {
"type": "stemmer",
"language": "light_french"
}
}</pre>
</div>
</div>
<div class="paragraph">
<p>After modifying above proposed change, you should have a JSON file that contains new setting and mapping of mailbox index. Here
we provide <a href="https://github.com/apache/james-project/blob/master/mailbox/opensearch/example_french_index.json">a sample JSON for French language</a>.
If you want to customize that JSON file for your own language need, please make these modifications:</p>
</div>
<div class="ulist">
<ul>
<li>
<p>Replace the <code>french</code> analyzer with your built-in language (have a look at <a href="https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-lang-analyzer.html">built-in language analyzers</a>)</p>
</li>
<li>
<p>Modify <code>keep_mail_and_url_french</code> analyzer' filters with your language filters, and customize the analyzer' name.</p>
</li>
</ul>
</div>
<div class="paragraph">
<p>Please change also <code>number_of_shards</code>, <code>number_of_replicas</code> and <code>index.write.wait_for_active_shards</code> values in the sample file according to your need.</p>
</div>
<div class="paragraph">
<p>Run this cURL command with above JSON file to create <code>mailbox_v1</code> (Mailbox index' default name) index before James start:</p>
</div>
<div class="listingblock">
<div class="content">
<pre>curl -X PUT ES_IP:ES_PORT/mailbox_v1 -H "Content-Type: application/json" -d @example_french_index.json</pre>
</div>
</div>
</div>
</div>
</article>
</div>
</main>
</div>
<footer class="footer">
<p>This page was built using the Antora default UI.</p>
<p>The source code for this UI is licensed under the terms of the MPL-2.0 license.</p>
</footer>
<script id="site-script" src="../../../_/js/site.js" data-ui-root-path="../../../_"></script>
<script async src="../../../_/js/vendor/highlight.js"></script>
</body>
</html>