oo

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 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/8.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 re-indexing all content. 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 re-indexing all content. 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
Maximum Connections
maxConnections="75"Set the maximum number of HTTP connections.
Liferay 7.4 U67/GA67+
Maximum Connections Per Route
maxConnectionsPerRoute="75"Set the maximum number of HTTP connections per route.
Liferay 7.4 U67/GA67+
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"If HTTP SSL is enabled, set the truststore type. Choose a format supported by your JDK version (e.g., jks or pkcs12).
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"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
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 in Liferay’s 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+
Capability:
Deployment Approach: