You may provide your own Elasticsearch REST client, to enable custom behavior for your dotCMS implementation. For example, you may create a client that will fail over to another ES cluster if the primary is not available, provide load balancing, or support custom connection parameters not supported by the Elasticsearch REST client provided by dotCMS.
Getting and Setting the REST Client
Getting the Client
To retrieve the REST client from Java code, call the following method:
### Setting the Client {#SetClient}
To set the REST client via configuration, modify the following [environment variable](configuration-properties#EnvironmentVariables):
<code>DOT_ES_REST_CLIENT_PROVIDER_CLASS=<font color="green">FullyQualifiedClassName</font></code>
To change the REST Client **at runtime** (e.g. via a plugin), call the following method:
<code>RestHighLevelClientProvider.getInstance().setClient(<font color="green">YOUR_CUSTOM_CLIENT</font>);</code>
## The Default REST Client {#DefaultClient}
By default, a high level rest client is provided (com.dotcms.content.elasticsearch.util.DotRestHighLevelClient), which supports two authentication types (`BASIC` and `JWT`), allows the use of TLS certificates for REST API and transport encryption.
This default client can be configured using the following environment variables:
| Property | Default Value | Description |
|:------------------------------|:--------------------------|:------------|
| DOT_ES_AUTH_TYPE | `BASIC` | Accepted values are:<ul><li>`BASIC`</li><ul><li>When this is set, credentials must be set through the properties `DOT_ES_AUTH_BASIC_USER` and `DOT_ES_AUTH_BASIC_PASSWORD`.</li></ul><li>`JWT`</li><ul><li>When this is set, a valid token (`DOT_ES_AUTH_JWT_TOKEN property`) must be set.</li></ul></ul>
| DOT_ES_AUTH_BASIC_USER | `admin` | User name for `BASIC` authentication.
| DOT_ES_AUTH_BASIC_PASSWORD | `admin` | Password for `BASIC` authentication.
| DOT_ES_AUTH_JWT_TOKEN | _See Notes_ | Token for `JWT` authentication.
| DOT_ES_TLS_ENABLED | `false` | If set to `true`, enables TLS encryption.<ul><li>When true, certificates must be specified (`DOT_ES_AUTH_TLS_CLIENT_CERT`, `DOT_ES_AUTH_TLS_CLIENT_KEY`, and `DOT_ES_AUTH_TLS_CA_CERT`)</li></ul>
| DOT_ES_AUTH_TLS_CLIENT_CERT | `certs/elasticsearch.pem` | Path (relative to the `assets` folder) where the client certificate is stored.
| DOT_ES_AUTH_TLS_CLIENT_KEY | `certs/elasticsearch.key` | Path (relative to the `assets` folder) to the certificate’s key file (PKCS # 8).
| DOT_ES_AUTH_TLS_CA_CERT | `certs/root-ca.pem` | Path (relative to the `assets` folder) where the authority certificate is stored.
| DOT_ES_REST_CLIENT_PROVIDER_CLASS | <code>com.dotcms.content.elasticsearch<br/>.util.DotRestHighLevelClient</code> | Fully qualified name of the class of your custom client.
**Notes:**
* It is strongly recommended that all changes to system properties be made through [environment variables](configuration-properties#EnvironmentVariables).
* You should always generate your own JWT token, and configure your Elasticsearch server to accept that token.
* The default token is valid only with the dotCMS custom Elasticsearch open distro image.
## Custom REST Clients {#CustomClient}
You can write your own `RestHighLevelClientProvider` and deliver your own custom configured REST client. For sample code to use as a basis for your own client, please see the <a href="https://github.com/dotCMS/core/blob/main/dotCMS/src/main/java/com/dotcms/content/elasticsearch/util/DotRestHighLevelClientProvider.java" rel="noopener noreferrer" target="_blank">dotCMS Github Repo</a>.
Once you have created your own client, you can set the client for dotCMS to use via [either configuration or Java code](#SetClient).
