diff --git a/docs/reference/basic-config.md b/docs/reference/basic-config.md index dd3452217..c1e3ec234 100644 --- a/docs/reference/basic-config.md +++ b/docs/reference/basic-config.md @@ -5,7 +5,7 @@ mapped_pages: # Basic configuration [basic-config] -This page shows you the possible basic configuration options that the clients offers. +This page explains the basic configuration options for the JavaScript client. ```js const { Client } = require('@elastic/elasticsearch') @@ -18,34 +18,380 @@ const client = new Client({ }) ``` -| | | -| --- | --- | -| `node` or `nodes` | The Elasticsearch endpoint to use.
It can be a single string or an array of strings:

```js
node: 'http://localhost:9200'
```

Or it can be an object (or an array of objects) that represents the node:

```js
node: {
url: new URL('http://localhost:9200'),
tls: 'tls options',
agent: 'http agent options',
id: 'custom node id',
headers: { 'custom': 'headers' }
roles: {
master: true,
data: true,
ingest: true,
ml: false
}
}
```
| -| `auth` | Your authentication data. You can use both basic authentication and [ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key).
See [Authentication](/reference/connecting.md#authentication) for more details.
*Default:* `null`

Basic authentication:

```js
auth: {
username: 'elastic',
password: 'changeme'
}
```

[ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) authentication:

```js
auth: {
apiKey: 'base64EncodedKey'
}
```

Bearer authentication, useful for [service account tokens](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-service-token). Be aware that it does not handle automatic token refresh:

```js
auth: {
bearer: 'token'
}
```
| -| `maxRetries` | `number` - Max number of retries for each request.
*Default:* `3` | -| `requestTimeout` | `number` - Max request timeout in milliseconds for each request.
*Default:* No value | -| `pingTimeout` | `number` - Max ping request timeout in milliseconds for each request.
*Default:* `3000` | -| `sniffInterval` | `number, boolean` - Perform a sniff operation every `n` milliseconds. Sniffing might not be the best solution for you, take a look [here](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how) to know more.
*Default:* `false` | -| `sniffOnStart` | `boolean` - Perform a sniff once the client is started. Sniffing might not be the best solution for you, take a look [here](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how) to know more.
*Default:* `false` | -| `sniffEndpoint` | `string` - Endpoint to ping during a sniff.
*Default:* `'_nodes/_all/http'` | -| `sniffOnConnectionFault` | `boolean` - Perform a sniff on connection fault. Sniffing might not be the best solution for you, take a look [here](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how) to know more.
*Default:* `false` | -| `resurrectStrategy` | `string` - Configure the node resurrection strategy.
*Options:* `'ping'`, `'optimistic'`, `'none'`
*Default:* `'ping'` | -| `suggestCompression` | `boolean` - Adds `accept-encoding` header to every request.
*Default:* `false` | -| `compression` | `string, boolean` - Enables gzip request body compression.
*Options:* `'gzip'`, `false`
*Default:* `false` | -| `tls` | `http.SecureContextOptions` - tls [configuraton](https://nodejs.org/api/tls.md).
*Default:* `null` | -| `proxy` | `string, URL` - If you are using an http(s) proxy, you can put its url here. The client will automatically handle the connection to it.
*Default:* `null`

```js
const client = new Client({
node: 'http://localhost:9200',
proxy: 'http://localhost:8080'
})

const client = new Client({
node: 'http://localhost:9200',
proxy: 'http://user:pwd@localhost:8080'
})
```
| -| `agent` | `http.AgentOptions, function` - http agent [options](https://nodejs.org/api/http.md#http_new_agent_options), or a function that returns an actual http agent instance. If you want to disable the http agent use entirely (and disable the `keep-alive` feature), set the agent to `false`.
*Default:* `null`

```js
const client = new Client({
node: 'http://localhost:9200',
agent: { agent: 'options' }
})

const client = new Client({
node: 'http://localhost:9200',
// the function takes as parameter the option
// object passed to the Connection constructor
agent: (opts) => new CustomAgent()
})

const client = new Client({
node: 'http://localhost:9200',
// Disable agent and keep-alive
agent: false
})
```
| -| `nodeFilter` | `function` - Filters which node not to use for a request.
*Default:*

```js
function defaultNodeFilter (node) {
// avoid master only nodes
if (node.roles.master === true &&
node.roles.data === false &&
node.roles.ingest === false) {
return false
}
return true
}
```
| -| `nodeSelector` | `function` - custom selection strategy.
*Options:* `'round-robin'`, `'random'`, custom function
*Default:* `'round-robin'`
*Custom function example:*

```js
function nodeSelector (connections) {
const index = calculateIndex()
return connections[index]
}
```
| -| `generateRequestId` | `function` - function to generate the request id for every request, it takes two parameters, the request parameters and options.
By default it generates an incremental integer for every request.
*Custom function example:*

```js
function generateRequestId (params, options) {
// your id generation logic
// must be syncronous
return 'id'
}
```
| -| `name` | `string, symbol` - The name to identify the client instance in the events.
*Default:* `elasticsearch-js` | -| `opaqueIdPrefix` | `string` - A string that will be use to prefix any `X-Opaque-Id` header.
See [`X-Opaque-Id` support](/reference/observability.md#_x_opaque_id_support) for more details.
_Default:* `null` | -| `headers` | `object` - A set of custom headers to send in every request.
*Default:* `{}` | -| `context` | `object` - A custom object that you can use for observability in your events.It will be merged with the API level context option.
*Default:* `null` | -| `enableMetaHeader` | `boolean` - If true, adds an header named `'x-elastic-client-meta'`, containing some minimal telemetry data,such as the client and platform version.
*Default:* `true` | -| `cloud` | `object` - Custom configuration for connecting to [Elastic Cloud](https://cloud.elastic.co). See [Authentication](/reference/connecting.md) for more details.
*Default:* `null`
*Cloud configuration example:*

```js
const client = new Client({
cloud: {
id: ''
},
auth: {
username: 'elastic',
password: 'changeme'
}
})
```
| -| `disablePrototypePoisoningProtection` | `boolean`, `'proto'`, `'constructor'` - The client can protect you against prototype poisoning attacks. Read [this article](https://web.archive.org/web/20200319091159/https://hueniverse.com/square-brackets-are-the-enemy-ff5b9fd8a3e8?gi=184a27ee2a08) to learn more about this security concern. If needed, you can enable prototype poisoning protection entirely (`false`) or one of the two checks (`'proto'` or `'constructor'`). For performance reasons, it is disabled by default. Read the `secure-json-parse` [documentation](https://github.com/fastify/secure-json-parse) to learn more.
*Default:* `true` | -| `caFingerprint` | `string` - If configured, verify that the fingerprint of the CA certificate that has signed the certificate of the server matches the supplied fingerprint. Only accepts SHA256 digest fingerprints.
*Default:* `null` | -| `maxResponseSize` | `number` - When configured, it verifies that the uncompressed response size is lower than the configured number, if it’s higher it will abort the request. It cannot be higher than buffer.constants.MAX_STRING_LENGTH
*Default:* `null` | -| `maxCompressedResponseSize` | `number` - When configured, it verifies that the compressed response size is lower than the configured number, if it’s higher it will abort the request. It cannot be higher than buffer.constants.MAX_LENGTH
*Default:* `null` | +### `node` or `nodes` +The Elasticsearch endpoint to use. It can be a single string or an array of strings: + +```js +node: 'http://localhost:9200' +``` + +Or it can be an object (or an array of objects) that represents the node: + +```js +node: { + url: new URL('http://localhost:9200'), + tls: 'tls options', + agent: 'http agent options', + id: 'custom node id', + headers: { 'custom': 'headers' }, + roles: { + master: true, + data: true, + ingest: true, + ml: false + } +} +``` + +--- + +### `auth` + +Default: `null` + +Your authentication data. You can use both basic authentication and [ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key). + See [Authentication](/reference/connecting.md#authentication) for more details. + + +Basic authentication: + +```js +auth: { + username: 'elastic', + password: 'changeme' +} +``` + +[ApiKey](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-api-key) authentication: + +```js +auth: { + apiKey: 'base64EncodedKey' +} +``` + +Bearer authentication, useful for [service account tokens](https://www.elastic.co/docs/api/doc/elasticsearch/operation/operation-security-create-service-token). Be aware that it does not handle automatic token refresh: + +```js +auth: { + bearer: 'token' +} +``` + +--- + +### `maxRetries` + +Type: `number`
+Default: `3` + +Max number of retries for each request. + +--- + +### `requestTimeout` + +Type: `number`
+Default: `No value` + +Max request timeout in milliseconds for each request. + +--- + +### `pingTimeout` + +Type: `number`
+Default: `3000` + +Max ping request timeout in milliseconds for each request. + +--- + +### `sniffInterval` + +Type: `number, boolean`
+Default: `false` + +Perform a sniff operation every `n` milliseconds. + +:::{tip} +Sniffing might not be the best solution. Before using the various `sniff` options, review this [blog post](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how). +::: + +--- + +### `sniffOnStart` + +Type: `boolean`
+Default: `false` + +Perform a sniff once the client is started. Be sure to review the sniffing best practices [blog post](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how). + +--- + +### `sniffEndpoint` + +Type: `string`
+Default: `'_nodes/_all/http'` + +Endpoint to ping during a sniff. Be sure to review the sniffing best practices [blog post](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how). + +--- + +### `sniffOnConnectionFault` + +Type: `boolean`
+Default: `false` + +Perform a sniff on connection fault. Be sure to review the sniffing best practices [blog post](https://www.elastic.co/blog/elasticsearch-sniffing-best-practices-what-when-why-how). + +--- + +### `resurrectStrategy` + +Type: `string`
+Default: `'ping'` + +Configure the node resurrection strategy.
+Options: `'ping'`, `'optimistic'`, `'none'` + +--- + +### `suggestCompression` + +Type: `boolean`
+Default: `false` + +Adds an `accept-encoding` header to every request. + +--- + +### `compression` + +Type: `string, boolean`
+Default: `false` + +Enables gzip request body compression.
+Options: `'gzip'`, `false` + +--- + +### `tls` + +Type: `http.SecureContextOptions`
+Default: `null` + +The [tls configuraton](https://nodejs.org/api/tls.md). + +--- + +### `proxy` + +Type: `string, URL`
+Default: `null` + +If you are using an http(s) proxy, you can put its url here. The client will automatically handle the connection to it. + + +```js +const client = new Client({ + node: 'http://localhost:9200', + proxy: 'http://localhost:8080' +}) + +const client = new Client({ + node: 'http://localhost:9200', + proxy: 'http://user:pwd@localhost:8080' +}) +``` + +--- + +### `agent` + +Type: `http.AgentOptions, function`
+Default: `null` + +http agent [options](https://nodejs.org/api/http.md#http_new_agent_options), or a function that returns an actual http agent instance. If you want to disable the http agent use entirely (and disable the `keep-alive` feature), set the agent to `false`. + +```js +const client = new Client({ + node: 'http://localhost:9200', + agent: { agent: 'options' } +}) + +const client = new Client({ + node: 'http://localhost:9200', + // the function takes as parameter the option + // object passed to the Connection constructor + agent: (opts) => new CustomAgent() +}) + +const client = new Client({ + node: 'http://localhost:9200', + // Disable agent and keep-alive + agent: false +}) +``` + +--- + +### `nodeFilter` + +Type: `function` + +Filter that indicates whether a node should be used for a request. Default function definition: + +```js +function defaultNodeFilter (node) { + // avoid master only nodes + if (node.roles.master === true && + node.roles.data === false && + node.roles.ingest === false) { + return false + } + return true +} +``` + +--- + +### `nodeSelector` + +Type: `function`
+Default: `'round-robin'` + +Custom selection strategy.
+Options: `'round-robin'`, `'random'`, custom function + +Custom function example: + +```js +function nodeSelector (connections) { + const index = calculateIndex() + return connections[index] +} +``` + +--- + +### `generateRequestId` + +Type: `function`
+ +function to generate the request id for every request, it takes two parameters, the request parameters and options. By default, it generates an incremental integer for every request. + +Custom function example: + +```js +function generateRequestId (params, options) { + // your id generation logic + // must be syncronous + return 'id' +} +``` + +--- + +### `name` + +Type: `string, symbol`
+Default: `elasticsearch-js` + +The name to identify the client instance in the events. + +--- + +### `opaqueIdPrefix` + +Type: `string`
+Default: `null` + +A string that will be use to prefix any `X-Opaque-Id` header. +See [`X-Opaque-Id` support](/reference/observability.md#_x_opaque_id_support) for more details. + +--- + +### `headers` + +Type: `object`
+Default: `{}` + +A set of custom headers to send in every request. + +--- + +### `context` + +Type: `object`
+Default: `null` + +A custom object that you can use for observability in your events. It will be merged with the API level context option. + +--- + +### `enableMetaHeader` + +Type: `boolean`
+Default: `true` + +If true, adds an header named `'x-elastic-client-meta'`, containing some minimal telemetry data, such as the client and platform version. + +--- + +### `cloud` + +Type: `object`
+Default: `null` + +Custom configuration for connecting to [Elastic Cloud](https://cloud.elastic.co). See [Authentication](/reference/connecting.md) for more details. + +Cloud configuration example: + +```js +const client = new Client({ + cloud: { + id: '' + }, + auth: { + username: 'elastic', + password: 'changeme' + } +}) +``` + +--- + +### `disablePrototypePoisoningProtection` + +Default: `true` + +`boolean`, `'proto'`, `'constructor'` - The client can protect you against prototype poisoning attacks. For more information, refer to [Square Brackets are the Enemy](https://web.archive.org/web/20200319091159/https://hueniverse.com/square-brackets-are-the-enemy-ff5b9fd8a3e8?gi=184a27ee2a08). If needed, you can enable prototype poisoning protection entirely (`false`) or one of the two checks (`'proto'` or `'constructor'`). For performance reasons, it is disabled by default. To learn more, refer to the [`secure-json-parse` documentation](https://github.com/fastify/secure-json-parse). + +--- + +### `caFingerprint` + +Type: `string`
+Default: `null` + +If configured, verify that the fingerprint of the CA certificate that has signed the certificate of the server matches the supplied fingerprint. Only accepts SHA256 digest fingerprints. + +--- + +### `maxResponseSize` + +Type: `number`
+Default: `null` + +When configured, `maxResponseSize` verifies that the uncompressed response size is lower than the configured number. If it’s higher, the request will be canceled. The `maxResponseSize` cannot be higher than the value of `buffer.constants.MAX_STRING_LENGTH`. + +--- + +### `maxCompressedResponseSize` + +Type: `number`
+Default: `null` + +When configured, `maxCompressedResponseSize` verifies that the compressed response size is lower than the configured number. If it’s higher, the request will be canceled. The `maxCompressedResponseSize` cannot be higher than the value of `buffer.constants.MAX_STRING_LENGTH`. \ No newline at end of file