Elasticsearch Connector Configuration Reference
The configuration information here applies to the latest available (bundled or through Marketplace) version of the Elasticsearch 6 and Elasticsearch 7 connectors for Liferay Portal 7.2-7.4 CE and for Liferay DXP 7.2-7.4. Appropriate information about the exact GA/Service Pack/Fix Pack and Marketplace versions are provided where needed.
Important
The Elasticsearch 7 system settings entry and corresponding configuration file are also used for configuring the connection to Elasticsearch 8.
The connection to Elasticsearch is primarily defined in the Elasticsearch 6/7 configuration entry in System Settings (or via the corresponding configuration file). In Liferay 7.3+ you can define multiple connections to Elasticsearch, through the factory configuration Elasticsearch Connections. Both entries are configurable through System Settings or an OSGi configuration file. Configuration files are the recommended approach for production environments.
Configuration Files and System Settings Entries
| Connecting Servers | System Settings Entry/Configuration File |
|---|---|
| Liferay 7.2.x Elasticsearch 6.x | Elasticsearch 6com.liferay.portal.search.elasticsearch6.configuration.ElasticsearchConfiguration.config |
| Liferay 7.2.x Elasticsearch 7.x | Elasticsearch 7com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConfiguration.config |
| Liferay 7.3+ Elasticsearch 7.x/8.x | Elasticsearch 7com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConfiguration.configElasticsearch Connections (factory) com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConnectionConfiguration-[connectionId].config |
In Liferay 7.3 and beyond, there’s an additional connection configuration entry, Elasticsearch Connections. You can use this to define any connection to Elasticsearch, but if you are only configuring one connection you can still use the main Elasticsearch 7 configuration entry. If using multiple connections in 7.3+, define connections with files named accordingly:
com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConnectionConfiguration-[connectionId].config
If configuring security on Elasticsearch 6, a separate Liferay configuration (as well as a LES subscription) is required. See Securing Elasticsearch for more information.
Deploy configuration files to [Liferay_Home]/osgi/configs and a listener auto-detects the configurations and writes them to the database.
Configuration Properties
| System Settings Field Name | Configuration File Syntax and Default Value Description (Click to Expand) | Availability |
|---|---|---|
| GENERAL CONNECTION SETTINGS | ||
| Track Total Hits |
If enabled, hits are accurately counted when there are more than 10,000 results for a search. Leaving this enabled may have an impact on performance when there is a large number of hits for a search. | Liferay 7.2+ (Connector to Elasticsearch 7) |
| Production Mode Enabled |
Enable production mode. In Liferay 7.3, | Liferay 7.3+ |
| Requires Reindex Index Name Prefix |
Set a String value to use as the prefix for the search index name. The default value should not be changed under normal conditions. If you change it, you must also perform a reindex all operation for the portal and then manually delete the old index using the Elasticsearch administration console. | Liferay 7.2+ |
| Requires Reindex 7.3.x→Number of Company and System Index Replicas 7.2.x→Index Number of Replicas |
Set the number of replicas for each Liferay company and system index. If unset, no replicas are used. Changing this value requires reindexing all content. The default value is defined in a file called “index-settings-defaults.json” shipped with the connector. | Liferay 7.2+ |
| Requires Reindex 7.3.x→Number of Company and System Index Shards 7.2.x→Index Number of Shards |
Set the number of shards to use when a Liferay company and system index is created. If unset, a single shard is used. Changing this value requires reindexing all content. The default value is defined in a file called “index-settings-defaults.json” shipped with the connector. | Liferay 7.2+ |
| Max Result Window |
Set the maximum number of results to return from a search query. Do not use this property while simultaneously setting | Liferay 7.4 U72/GA72+ |
| Log Exceptions Only |
A boolean setting that, when true, only logs exceptions from Elasticsearch, and does not re-throw them. | Liferay 7.2+ |
| Retry On Conflict |
Set an integer value for the number of retries to attempt if a version conflict occurs because the document was updated between getting it and updating it (see here for more information. | No longer used as of Liferay 7.1 |
| Maximum Connections |
Set the maximum number of HTTP connections. | Liferay 7.4 U67/GA67+ |
| Maximum Connections Per Route |
Set the maximum number of HTTP connections per route. | Liferay 7.4 U67/GA67+ |
| SECURITY SETTINGS | ||
| Authentication Enabled |
Enable or disable authentication to Elasticsearch with a user name and password. | Liferay 7.3+ |
| Username |
Set the user name for authenticating to Elasticsearch if Authentication Enabled is checked. | Liferay 7.3+ |
| Password |
Set the password for authenticating to Elasticsearch if Authentication Enabled is checked. | Liferay 7.3+ |
| Http SSL Enabled |
Enable or disable TLS/SSL. | Liferay 7.3+ |
| Truststore Type |
If HTTP SSL is enabled, set the truststore type. Choose a format supported by your JDK version (e.g., | Liferay 7.3+ |
| Truststore Path |
Set the path to the truststore file if HTTP SSL Enabled is checked. | Liferay 7.3+ |
| Truststore Password |
Set the password to the truststore if HTTP SSL Enabled is checked. | Liferay 7.3+ |
| ELASTICSEARCH CONNECTIONS SETTINGS | ||
| Active |
Activate or deactivate the connection as needed. Do not deactivate a connection if it’s selected in the Elasticsearch 7 configuration’s Remote Cluster Connection ID setting. | Liferay 7.3+ |
| Connection ID |
Set a unique ID for the connection. If active, this connection becomes available to select in the Elasticsearch 7 configuration’s Remote Cluster Connection ID property. | Liferay 7.3+ |
| REST CLIENT SETTINGS | ||
| Network Host Addresses |
Set the remote HTTP hosts to connect to. This is required in Liferay 7.3 as it configures the REST client connection. | Liferay 7.3+ |
| REST Client Logger Level |
Obsolete from DXP 7.3 U4+, DXP 7.4 GA1+, and Portal 7.4 GA5+. | Liferay 7.3+ |
| TRANSPORT CLIENT SETTINGS (EMBEDDED & REMOTE) | ||
| Operation Mode |
There are two operation modes you can choose from: EMBEDDED or REMOTE. Set to REMOTE to connect to a remote standalone Elasticsearch cluster. Set to EMBEDDED to start Liferay with an internal Elasticsearch instance. EMBEDDED operation mode is unsupported for production environments and can be considered a “development mode” feature. | Liferay 7.2. Deprecated as of Liferay 7.3, replaced with Production Mode Enabled |
| Cluster Name |
The cluster name is only needed for the Transport Client in Liferay 7.2. Set a String value to declare the cluster to integrate with. In Liferay 7.3+, where the connection is managed through the REST client, this property is only used for naming the embedded cluster when in development mode. | Liferay 7.2- On 7.3+, applies to development mode |
| Transport Addresses |
Set the String values for the addresses of the remote Elasticsearch nodes to connect to. This value is required when Operation Mode is set to remote (see here for more information). Specify as many or few nodes as you see fit. | Liferay 7.2 |
| Client Transport Sniff |
Set this boolean to true to enable cluster sniffing and dynamically discover available data nodes in the cluster (see here for more information). | Liferay 7.2 |
| Client Transport Ignore Cluster Name |
Set this boolean to true to ignore cluster name validation of connected nodes (see here for more information). | Liferay 7.2 |
| Client Transport Ping Timeout |
Set the time (in seconds) the client node waits for a ping response from a node. If unset, the default Elasticsearch | Liferay 7.2 |
| Client Transport Nodes Sampler Interval |
Set this String value to instruct the client node on how often to sample / ping the nodes listed and connected (see here for more information). | Liferay 7.2 |
| OTHER SETTINGS | ||
| Remote Cluster Connection ID |
Choose the connection ID for a connection to the remote Elasticsearch cluster. The available connections are defined in the Elasticsearch Connections System Settings entry. If this value is not set then the connection configurations in the Elasticsearch 7 entry are used for the remote cluster connection. | Liferay 7.3+ when using LES Cross-Cluster Replication |
| DEVELOPMENT MODE SETTINGS (EMBEDDED & SIDECAR) | ||
| Additional Configurations |
Set the String values for custom settings for embedded Elasticsearch, in YML format. See: Advanced Configuration of the Liferay Elasticsearch Connector. | Liferay 7.2+ |
| Bootstrap Mlock All |
A boolean setting that, when set to | Liferay 7.2+ |
| Embedded HTTP Port |
This configuration only applies to EMBEDDED mode. Set the HTTP port of the embedded Elasticsearch node that is created when Operation Mode is set to EMBEDDED. | Liferay 7.2. Deprecated as of Liferay 7.3.x, replaced with Sidecar HTTP Port |
| Http Enabled |
If this is checked, the HTTP layer is enabled. If unchecked, the HTTP layer is disabled on nodes which are not meant to serve REST requests directly. | Deprecated as of Liferay 7.1.x |
| Http CORS Allow Origin |
Set the String origins to allow when HTTP CORS is enabled (see here for more information). | Liferay 7.2+ |
| Http CORS Configurations |
Set the String values for custom settings for HTTP CORS, in YML format ( | Liferay 7.2+ |
| Http CORS Enabled |
Set this Boolean to false to disable cross-origin resource sharing. When set to | Liferay 7.2+ |
| Network Host |
Set this String value to instruct the node to bind to this hostname or IP address and publish (advertise) this host to other nodes in the cluster. This is a shortcut which sets the bind host and the publish host at the same time (see here for more information). | Liferay 7.2+ |
| Network Bind Host |
Set the String value of the network interface(s) a node should bind to so it can listen for incoming requests (see here for more information). | Liferay 7.2+ |
| Network Publish Host |
Set the String value of a single interface that the node advertises to other nodes in the cluster, so that those nodes can connect to it (see here for more information). | Liferay 7.2+ |
| Transport Tcp Port |
Set the String value for the port to bind for communication between nodes. Accepts a single value or a range (see here for more information). | Liferay 7.2+ |
| Zen Discovery Unicast Hosts Port |
Set a String value for the range of ports to use when building the value for | Liferay 7.2 |
| SIDECAR SETTINGS | ||
| Node Name |
Name the embedded Elasticsearch server’s node. A remote Elasticsearch server’s node name is configured in its | Liferay 7.3+ |
| Sidecar Debug |
Set this to true to enable debug mode for the sidecar process. | Liferay 7.3+ |
| Sidecar Debug Settings |
Set the JVM options used to debug the sidecar process. | Liferay 7.3+ |
| Sidecar Heartbeat Interval |
Set the heartbeat interval in milliseconds used to detect the health of the sidecar process. | Liferay 7.3+ |
| Sidecar Home |
Set the path of the sidecar base folder used to start the sidecar process. | Liferay 7.3+ |
| Sidecar HTTP Port |
This configuration only applies to Liferay 7.3 with the sidecar Elasticsearch. Set the HTTP port range of the sidecar Elasticsearch node. Set to AUTO to automatically find a port in the 9201-9300 range. If unset, the value of Embedded HTTP port ( | Liferay 7.3+ |
| Sidecar JVM Options |
Set the JVM options used by the sidecar process. | Liferay 7.3+ |
| Sidecar Shutdown Timeout |
Set the time in milliseconds to wait before the sidecar process is forcibly shut down. | Liferay 7.3+ |
| ADVANCED SETTINGS | ||
| Requires Reindex Additional Index Configurations |
Set the String values for custom settings for the Liferay index, in JSON or YML format (refer to the Elasticsearch Create Index API for more information). See: Advanced Configuration of the Liferay Elasticsearch Connector. | Liferay 7.2+ |
| Requires Reindex Additional Type Mappings |
Set the String values for custom mappings for the | Liferay 7.2+ |
| Requires Reindex Override Type Mappings |
Settings here override Liferay’s default type mappings. This is an advanced feature that should be used only if strictly necessary. If you set this value, the default mappings in Liferay’s source code (for example, | Liferay 7.2+ |
| Proxy Host |
Set the proxy host for the client connection. | Liferay DXP 7.3 FP1+/SP1+ and Liferay Portal GA7+ |
| Proxy Port |
Set the proxy port for the client connection. | Liferay DXP 7.3 FP1+/SP1+ and Liferay Portal GA7+ |
| Proxy Username |
Set the proxy user name for a proxy connection. | Liferay DXP 7.3 FP1+/SP1+ and Liferay Portal GA7+ |
| Proxy Password |
Set the password for connecting to the proxy. | Liferay DXP 7.3 FP1+/SP1+ and Liferay Portal GA7+ |