Understanding search servers¶
Shops, wikis, log platforms and many applications use a search server to find text in millions of documents within milliseconds. The two common ones are Elasticsearch and OpenSearch.
Elasticsearch or OpenSearch?¶
In 2021 Elastic changed the license of Elasticsearch. Amazon then forked the last open source version as OpenSearch. Both work the same way and share most of the REST API.
| Elasticsearch | OpenSearch | |
|---|---|---|
| Maintained by | Elastic | OpenSearch Software Foundation (Linux Foundation) |
| Web interface | Kibana | OpenSearch Dashboards |
| Security | built in, active by default since version 8 | security plugin, active by default |
| Admin user | elastic |
admin |
Tools in bin/ |
elasticsearch-reset-password, elasticsearch-keystore, elasticsearch-plugin |
opensearch-keystore, opensearch-plugin; users in the security plugin |
Installation and paths¶
Neither is in the repositories of the distributions. Use the package repository of the vendor, or a container image.
| Debian | Ubuntu | RHEL | Arch | |
|---|---|---|---|---|
| Elasticsearch | APT repository of Elastic | APT repository of Elastic | YUM repository of Elastic | AUR or container |
| OpenSearch | APT repository of OpenSearch | APT repository of OpenSearch | YUM repository of OpenSearch | AUR or container |
| What | Elasticsearch (package) | OpenSearch (package) |
|---|---|---|
| Programs | /usr/share/elasticsearch/bin/ |
/usr/share/opensearch/bin/ |
| Configuration | /etc/elasticsearch/elasticsearch.yml |
/etc/opensearch/opensearch.yml |
| Heap size | /etc/elasticsearch/jvm.options.d/*.options |
/etc/opensearch/jvm.options |
| Data and logs | /var/lib/elasticsearch/, /var/log/elasticsearch/ |
/var/lib/opensearch/, /var/log/opensearch/ |
| Service | elasticsearch |
opensearch |
The programs aren't in the PATH. Call them with the full path, for example
sudo /usr/share/elasticsearch/bin/elasticsearch-reset-password.
| Port | Use |
|---|---|
| 9200 | REST API over HTTPS, for applications and admins |
| 9300 | Communication between the nodes of a cluster |
The REST API with curl¶
Almost all administration runs over HTTP. With the package installation, Elasticsearch
creates its own CA; curl needs its certificate:
$ curl --cacert /etc/elasticsearch/certs/http_ca.crt -u elastic https://localhost:9200/_cluster/health?pretty
| Request | Answer |
|---|---|
GET / |
Name, version, cluster name |
GET /_cluster/health?pretty |
State of the cluster: green, yellow or red |
GET /_cat/indices?v |
All indices with document count and size |
GET /_cat/shards?v |
Every shard with state and node |
GET /_cat/nodes?v |
Nodes with heap, RAM, CPU and load |
GET /_cat/allocation?v |
Disk usage per node |
GET /_cluster/allocation/explain?pretty |
Why a shard isn't assigned |
PUT /INDEX/_settings |
Change settings, e.g. the number of replicas |
DELETE /INDEX |
Delete an index |
?v adds column headings to the _cat APIs, ?pretty formats JSON.
Green, yellow, red¶
| State | Meaning | Typical cause |
|---|---|---|
| green | All primary shards and replicas are assigned | |
| yellow | All data is available, but some replicas are missing | A single node: replicas can't be on the same node as their primary |
| red | At least one primary shard is missing: data is unavailable | Node failed, disk full, broken index |
On a single server, yellow is normal. Set "number_of_replicas": 0 for your indices, then
the cluster becomes green.
Memory and system settings¶
| Setting | Recommendation |
|---|---|
Heap (-Xms, -Xmx) |
Half of the RAM at most, never more than about 31 GB; both values equal |
vm.max_map_count |
At least 262144, set with sysctl; the packages set it themselves |
| Swap | Off, or bootstrap.memory_lock: true |
| Free disk | Above 15 %: from 85 % no new shards, from 95 % indices become read only |
Snapshots instead of file copies
Back up indices with the snapshot API into a repository (path.repo in the
configuration, or S3). Copying /var/lib/elasticsearch while the service runs gives
an inconsistent backup.
Don't expose port 9200
Old Elasticsearch versions without a password are a classic data leak. Even with security enabled, allow port 9200 only for application servers.