Set up Elasticsearch¶
Zammad’s search function is powered by Elasticsearch, and requires the ingest attachment plugin.
This guide uses the zammad run
command prefix in command line examples.
This prefix is only applicable to package installations
(i.e., via apt/yum/zypper, or .deb
/.rpm
files).
If you installed from source, be sure to omit this prefix
and run the bare rails ...
or rake ...
commands instead.
Step 1: Installation¶
Starting with Zammad 4.0, our packages allow you to decide whether to use
elasticsearch
or elasticsearch-oss
.
elasticsearch-oss
users please use below “direct download” tab for
further installation steps.
Warning
Above does not apply to CentOS because of compatibility reasons.
$ apt install apt-transport-https sudo wget curl gnupg
$ echo "deb [signed-by=/etc/apt/trusted.gpg.d/elasticsearch.gpg] https://artifacts.elastic.co/packages/7.x/apt stable main"| \
tee -a /etc/apt/sources.list.d/elastic-7.x.list > /dev/null
$ curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | \
gpg --dearmor | tee /etc/apt/trusted.gpg.d/elasticsearch.gpg> /dev/null
$ apt update
$ apt install elasticsearch
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
$ apt install apt-transport-https sudo wget curl gnupg
$ echo "deb [signed-by=/etc/apt/trusted.gpg.d/elasticsearch.gpg] https://artifacts.elastic.co/packages/7.x/apt stable main"| \
tee -a /etc/apt/sources.list.d/elastic-7.x.list > /dev/null
$ curl -fsSL https://artifacts.elastic.co/GPG-KEY-elasticsearch | \
gpg --dearmor | tee /etc/apt/trusted.gpg.d/elasticsearch.gpg> /dev/null
$ apt update
$ apt install elasticsearch
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
$ rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch
$ echo "[elasticsearch-7.x]
name=Elasticsearch repository for 7.x packages
baseurl=https://artifacts.elastic.co/packages/7.x/yum
gpgcheck=1
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=1
autorefresh=1
type=rpm-md"| tee /etc/yum.repos.d/elasticsearch-7.x.repo
$ yum install -y elasticsearch
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
$ rpm --import https://artifacts.elastic.co/GPG-KEY-elasticsearch
$ echo "[elasticsearch-7.x]
name=Elasticsearch repository for 7.x packages
baseurl=https://artifacts.elastic.co/packages/7.x/yum
gpgcheck=1
gpgkey=https://artifacts.elastic.co/GPG-KEY-elasticsearch
enabled=1
autorefresh=1
type=rpm-md"| tee /etc/zypp/repos.d/elasticsearch-7.x.repo
$ zypper install elasticsearch
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
Find the latest release on the downloads page, or see the installation guide for in-depth instructions. Ensure to also install the fitting (and mandatory!) attachment plugin for elasticsearch.
If you prefer the Open Source version of Elasticsearch, please use the Elasticsearch-OSS download page.
# Install the attachment plugin
$ /usr/share/elasticsearch/bin/elasticsearch-plugin install ingest-attachment
# Increase the virtual memory map limit
$ sysctl -w vm.max_map_count=262144
After you installed Elasticsearch and its attachment plugin, ensure to enable it by default and start it.
$ systemctl start elasticsearch
$ systemctl enable elasticsearch
Note
🐋 Docker installations on macOS/Windows:
Setting the vm.max_map_count
kernel parameter requires
additional steps.
Step 2: Suggested Configuration¶
We use the following settings to optimize the performance of our Elasticsearch servers. Your mileage may vary.
# /etc/elasticsearch/elasticsearch.yml
# Tickets above this size (articles + attachments + metadata)
# may fail to be properly indexed (Default: 100mb).
#
# When Zammad sends tickets to Elasticsearch for indexing,
# it bundles together all the data on each individual ticket
# and issues a single HTTP request for it.
# Payloads exceeding this threshold will be truncated.
#
# Performance may suffer if it is set too high.
http.max_content_length: 400mb
# Allows the engine to generate larger (more complex) search queries.
# Elasticsearch will raise an error or deprecation notice if this value is too low,
# but setting it too high can overload system resources (Default: 1024).
#
# Available in version 6.6+ only.
indices.query.bool.max_clause_count: 2000
Note
For more information on the indices.query.bool.max_clause_count
setting,
see the Elasticsearch 6.6 release notes.
Step 3: Connect Zammad¶
Before proceeding here, make sure to install Zammad before running below commands, as this will fail otherwise.
# Set the Elasticsearch server address
$ zammad run rails r "Setting.set('es_url', 'http://localhost:9200')"
# Build the search index
$ zammad run rake zammad:searchindex:rebuild
# Optionally, you can specify a number of CPU cores which are used for
# rebuilding the searchindex, as in the following example with 8 cores:
$ zammad run rake zammad:searchindex:rebuild[8]
Starting with Elasticsearch 8+, you need to use a HTTPS URL in ‘es_url’ as ‘https://localhost:9200’ and configure an authentication (see HTTP Basic below).
Optional settings¶
# HTTP Basic
$ zammad run rails r "Setting.set('es_user', '<username>')"
$ zammad run rails r "Setting.set('es_password', '<password>')"
Hint
🤔 How do I set up authentication on my Elasticsearch server?
Elasticsearch provides many different authentication methods. Some of them may require paid X-Pack, please check the elastic documentation for more information.
Useful when connecting multiple services or Zammad instances to a single Elasticsearch server (to prevent name collisions during indexing).
$ zammad run rails r "Setting.set('es_index', Socket.gethostname.downcase + '_zammad')"
Zammad supports searching by the contents of file attachments, which means Elasticsearch has to index those, too.
Limiting such indexing can help conserve system resources.
# Files with these extensions will not be indexed
$ zammad run rails r "Setting.set('es_attachment_ignore',\
[ '.png', '.jpg', '.jpeg', '.mpeg', '.mpg', '.mov', '.bin', '.exe', '.box', '.mbox' ] )"
# Files larger than this size (in MB) will not be indexed
$ zammad run rails r "Setting.set('es_attachment_max_size_in_mb', 50)"
Change your Elasticsearch URL if you have a separate Elasticsearch server.
Default is localhost
.
$ zammad run rails r "Setting.set('es_url', 'https://example.com')"
You can define if a SSL verification will be performed. Default is
true
.
# Deactivating SSL verification is NOT recommended
$ zammad run rails r "Setting.set('es_ssl_verify', false)"
Hint
🤔 But how to handle an Elasticsearch server with custom certificates?
You can import custom certificates and custom CA certificates to Zammad. Please have a look in the admin documentation.