Documentation

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.

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 6
com.liferay.portal.search.elasticsearch6.configuration.ElasticsearchConfiguration.config

Liferay 7.2.x
Elasticsearch 7.x

Elasticsearch 7
com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConfiguration.config

Liferay 7.3+
Elasticsearch 7.x

Elasticsearch 7
com.liferay.portal.search.elasticsearch7.configuration.ElasticsearchConfiguration.config

Elasticsearch 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

trackTotalHits=B"true"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

productionModeEnabled=B"false"Enable production mode. In Liferay 7.3, productionModeEnabled replaces the deprecated setting operationMode. If this is checked, production mode is enabled and the Operation Mode configuration is ignored. Enabling production mode requires connecting to a remote standalone Elasticsearch cluster. If left disabled, the Operation Mode configuration is used.

Liferay 7.3+

Index Name Prefix

indexNamePrefix="liferay-"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 re-index all operation for the portal and then manually delete the old index using the Elasticsearch administration console.

Liferay 7.2+

7.3.x→Number of Company and System Index Replicas
7.2.x→Index Number of Replicas

indexNumberOfReplicas="0-all"Set the number of replicas for each Liferay company and system index. If unset, no replicas are used. Changing this value requires a full re-index. The default value is defined in a file called “index-settings-defaults.json” shipped with the connector.

Liferay 7.2+

7.3.x→Number of Company and System Index Shards
7.2.x→Index Number of Shards

indexNumberOfShards="1"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 a full re-index. The default value is defined in a file called “index-settings-defaults.json” shipped with the connector.

Liferay 7.2+

Log Exceptions Only

logExceptionsOnly=B"true"A boolean setting that, when true, only logs exceptions from Elasticsearch, and does not re-throw them.

Liferay 7.2+

Retry On Conflict

retryOnConflict="5"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

SECURITY SETTINGS

Authentication Enabled

authenticationEnabled=B"false"Enable or disable authentication to Elasticsearch with a user name and password.

Liferay 7.3+

Username

username="elastic"Set the user name for authenticating to Elasticsearch if Authentication Enabled is checked.

Liferay 7.3+

Password

password=""Set the password for authenticating to Elasticsearch if Authentication Enabled is checked.

Liferay 7.3+

Http SSL Enabled

httpSSLEnabled="false"Enable or disable TLS/SSL.

Liferay 7.3+

Truststore Type

truststoreType="pkcs12"Set the truststore type if HTTP SSL Enabled is checked.

Liferay 7.3+

Truststore Path

truststorePath="/path/to/localhost.p12"Set the path to the truststore file if HTTP SSL Enabled is checked.

Liferay 7.3+

Truststore Password

truststorePassword=""Set the password to the truststore if HTTP SSL Enabled is checked.

Liferay 7.3+

ELASTICSEARCH CONNECTIONS SETTINGS

Active

active=B"false"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

connectionId=""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

networkHostAddresses="[http://localhost:9200]"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

RESTClientLoggerLevel="ERROR"Set the logging level for the Elasticsearch REST client.

Liferay 7.3+

TRANSPORT CLIENT SETTINGS (EMBEDDED & REMOTE)

Operation Mode

operationMode="EMBEDDED"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

clusterName="LiferayElasticsearchCluster"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

transportAddresses=["localhost:9300"]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

clientTransportSniff=B"true"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

clientTransportIgnoreClusterName=B"false"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

clientTransportPingTimeout=""Set the time (in seconds) the client node waits for a ping response from a node. If unset, the default Elasticsearch client.transport.ping_timeout is used.

Liferay 7.2

Client Transport Nodes Sampler Interval

clientTransportNodesSamplerInterval=""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

remoteClusterConnectionId=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

additionalConfigurations=""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

bootstrapMlockAll="false"A boolean setting that, when set to true, tries to lock the process address space into RAM, preventing any Elasticsearch memory from being swapped out (see here) for more information).

Liferay 7.2+

Embedded HTTP Port

embeddedHttpPort="9201"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

httpEnabled=B"true"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

httpCORSAllowOrigin="/https?:\\/\\/localhost(:[0-9]+)?/"Set the String origins to allow when HTTP CORS is enabled (see here for more information).

Liferay 7.2+

Http CORS Configurations

httpCORSConfigurations=Set the String values for custom settings for HTTP CORS, in YML format (elasticsearch.yml) (see here for more information).

Liferay 7.2+

Http CORS Enabled

httpCORSEnabled=B"true"Set this boolean to false to disable cross-origin resource sharing. When set to false, a browser on another origin cannot make requests to Elasticsearch. Web front end tools like Elasticsearch Head may be unable to connect (see here for more information).

Liferay 7.2+

Network Host

networkHost=""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

networkBindHost=""Set the String value of the network interface(s) a node should bind to in order to listen for incoming requests (see here for more information).

Liferay 7.2+

Network Publish Host

networkPublishHost=""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

transportTcpPort=""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

discoveryZenPingUnicastHostsPort="9300-9400"Set a String value for the range of ports to use when building the value for discovery.zen.ping.unicast.hosts. Multiple Elasticsearch nodes on a range of ports can act as gossip routers at the same computer (see here for more information). Deprecated as of 7.3 with no direct replacement.

Liferay 7.2

SIDECAR SETTINGS

Node Name

nodeName=Name the embedded Elasticsearch server’s node. A remote Elasticsearch server’s node name is configured in its elasticsearch.yml.

Liferay 7.3+

Sidecar Debug

sidecarDebug=B"false"Set this to true to enable debug mode for the sidecar process.

Liferay 7.3+

Sidecar Debug Settings

sidecarDebugSettings="-agentlib:jdwp=transport=dt_socket,address=8001,server=y,suspend=y,quiet=y"Set the JVM options used to debug the sidecar process.

Liferay 7.3+

Sidecar Heartbeat Interval

sidecarHeartbeatInterval="10000"Set the heartbeat interval in milliseconds used to detect the health of the sidecar process.

Liferay 7.3+

Sidecar Home

sidecarHome="elasticsearch7"Set the path of the sidecar base folder used to start the sidecar process.

Liferay 7.3+

Sidecar HTTP Port

sidecarHttpPort="9200"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 (9201 by default) is used.

Liferay 7.3+

Sidecar JVM Options

sidecarJVMOptions="-Xms1g|-Xmx1g|-XX:+AlwaysPreTouch"Set the JVM options used by the sidecar process.

Liferay 7.3+

Sidecar Shutdown Timeout

sidecarShutdownTimeout="10000"Set the time in milliseconds to wait before the sidecar process is forcibly shut down.

Liferay 7.3+

ADVANCED SETTINGS

Additional Index Configurations

additionalIndexConfigurations=""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+

Additional Type Mappings

additionalTypeMappings=""Set the String values for custom mappings for the LiferayDocumentType, in JSON format (refer to the Elasticsearch Put Mapping API for more information) See: Advanced Configuration of the Liferay Elasticsearch Connector.

Liferay 7.2+

Override Type Mappings

overrideTypeMappings=""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 used to define the Liferay Document Type in Liferay source code (for example, liferay-type-mappings.json) are ignored entirely, so include the whole mappings definition in this property, not just the segment you’re modifying.

Liferay 7.2+

Proxy Host

proxyHost=""Set the proxy host for the client connection.

Liferay DXP 7.3 FP1+/SP1+ and Liferay Portal GA7+

Proxy Port

proxyPort="0"Set the proxy port for the client connection.

Liferay DXP 7.3 FP1+/SP1+ and Liferay Portal GA7+

Proxy Username

proxyUserName=""Set the proxy user name for a proxy connection.

Liferay DXP 7.3 FP1+/SP1+ and Liferay Portal GA7+

Proxy Password

proxyPassword=""Set the password for connecting to the proxy.

Liferay DXP 7.3 FP1+/SP1+ and Liferay Portal GA7+