Compare commits
4 Commits
| Author | SHA1 | Date | |
|---|---|---|---|
 keithhc2
|
a186b46302 | ||
|
keithhc2
|
7ed1c64a35 | ||
|
keithhc2
|
b4642195e7 | ||
|
keithhc2
|
3c98e4b297 |
@@ -27,18 +27,12 @@ PUT _cluster/settings
|
||||
}
|
||||
```
|
||||
|
||||
[Just like any other setting]({{site.url}}{{site.baseurl}}/opensearch/configuration/), the alternative is to add the following line to `opensearch.yml` on each node and then restart the node:
|
||||
|
||||
```yml
|
||||
compatibility.override_main_response_version: true
|
||||
```
|
||||
|
||||
|
||||
## Downloads
|
||||
|
||||
You can download the OpenSearch output plugin for Logstash from [OpenSearch downloads](https://opensearch.org/downloads.html). The Logstash output plugin is compatible with OpenSearch and Elasticsearch OSS (7.10.2 or lower).
|
||||
|
||||
These are the latest versions of Beats OSS with OpenSearch compatibility. For more information, see the [compatibility matrices](#compatibility-matrices).
|
||||
These versions of Beats offer the best compatibility with OpenSearch. For more information, see the [compatibility matrices](#compatibility-matrices).
|
||||
|
||||
- [Filebeat OSS 7.12.1](https://www.elastic.co/downloads/past-releases/filebeat-oss-7-12-1)
|
||||
- [Metricbeat OSS 7.12.1](https://www.elastic.co/downloads/past-releases/metricbeat-oss-7-12-1)
|
||||
@@ -47,7 +41,7 @@ These are the latest versions of Beats OSS with OpenSearch compatibility. For mo
|
||||
- [Winlogbeat OSS 7.12.1](https://www.elastic.co/downloads/past-releases/winlogbeat-oss-7-12-1)
|
||||
- [Auditbeat OSS 7.12.1](https://elastic.co/downloads/past-releases/auditbeat-oss-7-12-1)
|
||||
|
||||
Some users report compatibility issues with ingest pipelines on these versions of Beats. If you use ingest pipelines with OpenSearch, consider using the 7.10.2 versions of Beats instead.
|
||||
Some users report compatibility issues with ingest pipelines on these versions of Beats. If you use ingest pipelines with OpenSearch, consider using the 7.10.2 versions of Beats OSS instead.
|
||||
{: .note }
|
||||
|
||||
|
||||
|
||||
@@ -90,36 +90,36 @@ You can specify the following options.
|
||||
|
||||
Options | Description | Type | Required
|
||||
:--- | :--- |:--- |:--- |
|
||||
`source_index` | The name of the detector. | String | Yes
|
||||
`target_index` | Specify the target index that the rolled up data is ingested into. You could either create a new target index or use an existing index. The target index cannot be a combination of raw and rolled up data. | String | Yes
|
||||
`schedule` | Schedule of the index rollup job which can be an interval or a cron expression. | Object | Yes
|
||||
`schedule.interval` | Specify the frequency of execution of the rollup job. | Object | No
|
||||
`schedule.interval.start_time` | Start time of the interval. | Timestamp | Yes
|
||||
`schedule.interval.period` | Define the interval period. | String | Yes
|
||||
`schedule.interval.unit` | Specify the time unit of the interval. | String | Yes
|
||||
`schedule.interval.cron` | Optionally, specify a cron expression to define therollup frequency. | List | No
|
||||
`schedule.interval.cron.expression` | Specify a Unix cron expression. | String | Yes
|
||||
`schedule.interval.cron.timezone` | Specify timezones as defined by the IANA Time Zone Database. Defaults to UTC. | String | No
|
||||
`description` | Optionally, describe the rollup job. | String | No
|
||||
`enabled` | When true, the index rollup job is scheduled. Default is true. | Boolean | Yes
|
||||
`continuous` | Specify whether or not the index rollup job continuously rolls up data forever or just executes over the current data set once and stops. Default is false. | Boolean | Yes
|
||||
`error_notification` | Set up a Mustache message template sent for error notifications. For example, if an index rollup job fails, the system sends a message to a Slack channel. | Object | No
|
||||
`page_size` | Specify the number of buckets to paginate through at a time while rolling up. | Number | Yes
|
||||
`delay` | The number of milliseconds to delay execution of the index rollup job. | Long | No
|
||||
`dimensions` | Specify aggregations to create dimensions for the roll up time window. | Object | Yes
|
||||
`dimensions.date_histogram` | Specify either fixed_interval or calendar_interval, but not both. Either one limits what you can query in the target index. | Object | No
|
||||
`dimensions.date_histogram.fixed_interval` | Specify the fixed interval for aggregations in milliseconds, seconds, minutes, hours, or days. | String | No
|
||||
`dimensions.date_histogram.calendar_interval` | Specify the calendar interval for aggregations in minutes, hours, days, weeks, months, quarters, or years. | String | No
|
||||
`dimensions.date_histogram.field` | Specify the date field used in date histogram aggregation. | String | No
|
||||
`dimensions.date_histogram.timezone` | Specify the timezones as defined by the IANA Time Zone Database. The default is UTC. | String | No
|
||||
`dimensions.terms` | Specify the term aggregations that you want to roll up. | Object | No
|
||||
`dimensions.terms.fields` | Specify terms aggregation for compatible fields. | Object | No
|
||||
`dimensions.histogram` | Specify the histogram aggregations that you want to roll up. | Object | No
|
||||
`dimensions.histogram.field` | Add a field for histogram aggregations. | String | Yes
|
||||
`dimensions.histogram.interval` | Specify the histogram aggregation interval for the field. | Long | Yes
|
||||
`dimensions.metrics` | Specify a list of objects that represent the fields and metrics that you want to calculate. | Nested object | No
|
||||
`dimensions.metrics.field` | Specify the field that you want to perform metric aggregations on. | String | No
|
||||
`dimensions.metrics.field.metrics` | Specify the metric aggregations you want to calculate for the field. | Multiple strings | No
|
||||
`source_index` | The name of the detector. | `string` | Yes
|
||||
`target_index` | Specify the target index that the rolled up data is ingested into. You could either create a new target index or use an existing index. The target index cannot be a combination of raw and rolled up data. | `string` | Yes
|
||||
`schedule` | Schedule of the index rollup job which can be an interval or a cron expression. | `object` | Yes
|
||||
`schedule.interval` | Specify the frequency of execution of the rollup job. | `object` | No
|
||||
`schedule.interval.start_time` | Start time of the interval. | `timestamp` | Yes
|
||||
`schedule.interval.period` | Define the interval period. | `string` | Yes
|
||||
`schedule.interval.unit` | Specify the time unit of the interval. | `string` | Yes
|
||||
`schedule.interval.cron` | Optionally, specify a cron expression to define therollup frequency. | `list` | No
|
||||
`schedule.interval.cron.expression` | Specify a Unix cron expression. | `string` | Yes
|
||||
`schedule.interval.cron.timezone` | Specify timezones as defined by the IANA Time Zone Database. Defaults to UTC. | `string` | No
|
||||
`description` | Optionally, describe the rollup job. | `string` | No
|
||||
`enabled` | When true, the index rollup job is scheduled. Default is true. | `boolean` | Yes
|
||||
`continuous` | Specify whether or not the index rollup job continuously rolls up data forever or just executes over the current data set once and stops. Default is false. | `boolean` | Yes
|
||||
`error_notification` | Set up a Mustache message template sent for error notifications. For example, if an index rollup job fails, the system sends a message to a Slack channel. | `object` | No
|
||||
`page_size` | Specify the number of buckets to paginate through at a time while rolling up. | `number` | Yes
|
||||
`delay` | Specify time value to delay execution of the index rollup job. | `time_unit` | No
|
||||
`dimensions` | Specify aggregations to create dimensions for the roll up time window. | `object` | Yes
|
||||
`dimensions.date_histogram` | Specify either fixed_interval or calendar_interval, but not both. Either one limits what you can query in the target index. | `object` | No
|
||||
`dimensions.date_histogram.fixed_interval` | Specify the fixed interval for aggregations in milliseconds, seconds, minutes, hours, or days. | `string` | No
|
||||
`dimensions.date_histogram.calendar_interval` | Specify the calendar interval for aggregations in minutes, hours, days, weeks, months, quarters, or years. | `string` | No
|
||||
`dimensions.date_histogram.field` | Specify the date field used in date histogram aggregation. | `string` | No
|
||||
`dimensions.date_histogram.timezone` | Specify the timezones as defined by the IANA Time Zone Database. The default is UTC. | `string` | No
|
||||
`dimensions.terms` | Specify the term aggregations that you want to roll up. | `object` | No
|
||||
`dimensions.terms.fields` | Specify terms aggregation for compatible fields. | `object` | No
|
||||
`dimensions.histogram` | Specify the histogram aggregations that you want to roll up. | `object` | No
|
||||
`dimensions.histogram.field` | Add a field for histogram aggregations. | `string` | Yes
|
||||
`dimensions.histogram.interval` | Specify the histogram aggregation interval for the field. | `long` | Yes
|
||||
`dimensions.metrics` | Specify a list of objects that represent the fields and metrics that you want to calculate. | `nested object` | No
|
||||
`dimensions.metrics.field` | Specify the field that you want to perform metric aggregations on. | `string` | No
|
||||
`dimensions.metrics.field.metrics` | Specify the metric aggregations you want to calculate for the field. | `multiple strings` | No
|
||||
|
||||
|
||||
#### Sample response
|
||||
|
||||
@@ -55,8 +55,6 @@ PUT _plugins/_ism/policies/policy_id
|
||||
}
|
||||
```
|
||||
|
||||
If you have more than one template that matches an index pattern, ISM uses the priority value to determine which template to apply.
|
||||
|
||||
For an example ISM template policy, see [Sample policy with ISM template]({{site.url}}{{site.baseurl}}/im-plugin/ism/policies#sample-policy-with-ism-template).
|
||||
|
||||
Older versions of the plugin include the `policy_id` in an index template, so when an index is created that matches the index template pattern, the index will have the policy attached to it:
|
||||
@@ -91,7 +89,6 @@ Make sure that the alias that you enter already exists. For more information abo
|
||||
|
||||
After you attach a policy to an index, ISM creates a job that runs every 5 minutes by default to perform policy actions, check conditions, and transition the index into different states. To change the default time interval for this job, see [Settings]({{site.url}}{{site.baseurl}}/im-plugin/ism/settings/).
|
||||
|
||||
ISM does not run jobs if the cluster state is red.
|
||||
|
||||
### Step 3: Manage indices
|
||||
|
||||
|
||||
@@ -19,10 +19,12 @@ Use the alerting API to programmatically manage monitors and alerts.
|
||||
|
||||
---
|
||||
|
||||
## Create monitor
|
||||
## Create query-level monitor
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Query-level monitors run the query and check whether the results should trigger any alerts. As such, query-level monitors can only trigger one alert at a time. For more information about query-level monitors versus bucket-level monitors, see [Create monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/#create-monitors).
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
@@ -30,6 +32,7 @@ POST _plugins/_alerting/monitors
|
||||
{
|
||||
"type": "monitor",
|
||||
"name": "test-monitor",
|
||||
"monitor_type": "query_level_monitor",
|
||||
"enabled": true,
|
||||
"schedule": {
|
||||
"period": {
|
||||
@@ -166,7 +169,7 @@ If you use a custom webhook for your destination and need to embed JSON in the m
|
||||
},
|
||||
"throttle_enabled": false,
|
||||
"subject_template": {
|
||||
"source": "TheSubject",
|
||||
"source": "Subject",
|
||||
"lang": "mustache"
|
||||
}
|
||||
}]
|
||||
@@ -186,6 +189,7 @@ The following example creates a monitor that runs at 12:10 PM Pacific Time on th
|
||||
{
|
||||
"type": "monitor",
|
||||
"name": "test-monitor",
|
||||
"monitor_type": "query_level_monitor",
|
||||
"enabled": true,
|
||||
"schedule": {
|
||||
"cron" : {
|
||||
@@ -228,7 +232,7 @@ The following example creates a monitor that runs at 12:10 PM Pacific Time on th
|
||||
"name": "test-action",
|
||||
"destination_id": "ld7912sBlQ5JUWWFThoW",
|
||||
"message_template": {
|
||||
"source": "This is my message body."
|
||||
"source": "This is a message body."
|
||||
},
|
||||
"throttle_enabled": true,
|
||||
"throttle": {
|
||||
@@ -236,7 +240,7 @@ The following example creates a monitor that runs at 12:10 PM Pacific Time on th
|
||||
"unit": "MINUTES"
|
||||
},
|
||||
"subject_template": {
|
||||
"source": "TheSubject"
|
||||
"source": "Subject"
|
||||
}
|
||||
}]
|
||||
}]
|
||||
@@ -247,6 +251,265 @@ For a full list of timezone names, refer to [Wikipedia](https://en.wikipedia.org
|
||||
|
||||
---
|
||||
|
||||
## Create bucket-level monitor
|
||||
|
||||
Bucket-level monitors categorize results into buckets separated by fields. The monitor then runs your script with each bucket's results and evaluates whether to trigger an alert. For more information about bucket-level monitors versus query-level monitors, see [Create monitors]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/monitors/#create-monitors).
|
||||
|
||||
```json
|
||||
POST _plugins/_alerting/monitors
|
||||
{
|
||||
"type": "monitor",
|
||||
"name": "test-bucket-level-monitor",
|
||||
"monitor_type": "bucket_level_monitor",
|
||||
"enabled": true,
|
||||
"schedule": {
|
||||
"period": {
|
||||
"interval": 1,
|
||||
"unit": "MINUTES"
|
||||
}
|
||||
},
|
||||
"inputs": [
|
||||
{
|
||||
"search": {
|
||||
"indices": [
|
||||
"movies"
|
||||
],
|
||||
"query": {
|
||||
"size": 0,
|
||||
"query": {
|
||||
"bool": {
|
||||
"filter": [
|
||||
{
|
||||
"range": {
|
||||
"order_date": {
|
||||
"from": "{{period_end}}||-1h",
|
||||
"to": "{{period_end}}",
|
||||
"include_lower": true,
|
||||
"include_upper": true,
|
||||
"format": "epoch_millis"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
},
|
||||
"aggregations": {
|
||||
"composite_agg": {
|
||||
"composite": {
|
||||
"sources": [
|
||||
{
|
||||
"user": {
|
||||
"terms": {
|
||||
"field": "user"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"aggregations": {
|
||||
"avg_products_base_price": {
|
||||
"avg": {
|
||||
"field": "products.base_price"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"triggers": [
|
||||
{
|
||||
"bucket_level_trigger": {
|
||||
"name": "test-trigger",
|
||||
"severity": "1",
|
||||
"condition": {
|
||||
"buckets_path": {
|
||||
"_count": "_count",
|
||||
"avg_products_base_price": "avg_products_base_price"
|
||||
},
|
||||
"parent_bucket_path": "composite_agg",
|
||||
"script": {
|
||||
"source": "params._count > 50 || params.avg_products_base_price < 35",
|
||||
"lang": "painless"
|
||||
}
|
||||
},
|
||||
"actions": [
|
||||
{
|
||||
"name": "test-action",
|
||||
"destination_id": "E4o5hnsB6KjPKmHtpfCA",
|
||||
"message_template": {
|
||||
"source": """Monitor {{ctx.monitor.name}} just entered alert status. Please investigate the issue. - Trigger: {{ctx.trigger.name}} - Severity: {{ctx.trigger.severity}} - Period start: {{ctx.periodStart}} - Period end: {{ctx.periodEnd}} - Deduped Alerts: {{ctx.dedupedAlerts}} * {{id}} : {{bucket_keys}} {{ctx.dedupedAlerts}} - New Alerts: {{ctx.newAlerts}} * {{id}} : {{bucket_keys}} {{ctx.newAlerts}} - Completed Alerts: {{ctx.completedAlerts}} * {{id}} : {{bucket_keys}} {{ctx.completedAlerts}}""",
|
||||
"lang": "mustache"
|
||||
},
|
||||
"throttle_enabled": false,
|
||||
"throttle": {
|
||||
"value": 10,
|
||||
"unit": "MINUTES"
|
||||
},
|
||||
"action_execution_policy": {
|
||||
"action_execution_scope": {
|
||||
"per_alert": {
|
||||
"actionable_alerts": [
|
||||
"DEDUPED",
|
||||
"NEW"
|
||||
]
|
||||
}
|
||||
}
|
||||
},
|
||||
"subject_template": {
|
||||
"source": "The Subject",
|
||||
"lang": "mustache"
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
```json
|
||||
{
|
||||
"_id" : "Dfxr63sBwex6DxEhHV5N",
|
||||
"_version" : 1,
|
||||
"_seq_no" : 3,
|
||||
"_primary_term" : 1,
|
||||
"monitor" : {
|
||||
"type" : "monitor",
|
||||
"schema_version" : 4,
|
||||
"name" : "test-bucket-level-monitor",
|
||||
"monitor_type" : "bucket_level_monitor",
|
||||
"user" : {
|
||||
"name" : "",
|
||||
"backend_roles" : [ ],
|
||||
"roles" : [ ],
|
||||
"custom_attribute_names" : [ ],
|
||||
"user_requested_tenant" : null
|
||||
},
|
||||
"enabled" : true,
|
||||
"enabled_time" : 1631742270785,
|
||||
"schedule" : {
|
||||
"period" : {
|
||||
"interval" : 1,
|
||||
"unit" : "MINUTES"
|
||||
}
|
||||
},
|
||||
"inputs" : [
|
||||
{
|
||||
"search" : {
|
||||
"indices" : [
|
||||
"opensearch_dashboards_sample_data_flights"
|
||||
],
|
||||
"query" : {
|
||||
"size" : 0,
|
||||
"query" : {
|
||||
"bool" : {
|
||||
"filter" : [
|
||||
{
|
||||
"range" : {
|
||||
"order_date" : {
|
||||
"from" : "{{period_end}}||-1h",
|
||||
"to" : "{{period_end}}",
|
||||
"include_lower" : true,
|
||||
"include_upper" : true,
|
||||
"format" : "epoch_millis",
|
||||
"boost" : 1.0
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"adjust_pure_negative" : true,
|
||||
"boost" : 1.0
|
||||
}
|
||||
},
|
||||
"aggregations" : {
|
||||
"composite_agg" : {
|
||||
"composite" : {
|
||||
"size" : 10,
|
||||
"sources" : [
|
||||
{
|
||||
"user" : {
|
||||
"terms" : {
|
||||
"field" : "user",
|
||||
"missing_bucket" : false,
|
||||
"order" : "asc"
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
},
|
||||
"aggregations" : {
|
||||
"avg_products_base_price" : {
|
||||
"avg" : {
|
||||
"field" : "products.base_price"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
],
|
||||
"triggers" : [
|
||||
{
|
||||
"bucket_level_trigger" : {
|
||||
"id" : "C_xr63sBwex6DxEhHV5B",
|
||||
"name" : "test-trigger",
|
||||
"severity" : "1",
|
||||
"condition" : {
|
||||
"buckets_path" : {
|
||||
"_count" : "_count",
|
||||
"avg_products_base_price" : "avg_products_base_price"
|
||||
},
|
||||
"parent_bucket_path" : "composite_agg",
|
||||
"script" : {
|
||||
"source" : "params._count > 50 || params.avg_products_base_price < 35",
|
||||
"lang" : "painless"
|
||||
},
|
||||
"gap_policy" : "skip"
|
||||
},
|
||||
"actions" : [
|
||||
{
|
||||
"id" : "DPxr63sBwex6DxEhHV5B",
|
||||
"name" : "test-action",
|
||||
"destination_id" : "E4o5hnsB6KjPKmHtpfCA",
|
||||
"message_template" : {
|
||||
"source" : "Monitor {{ctx.monitor.name}} just entered alert status. Please investigate the issue. - Trigger: {{ctx.trigger.name}} - Severity: {{ctx.trigger.severity}} - Period start: {{ctx.periodStart}} - Period end: {{ctx.periodEnd}} - Deduped Alerts: {{ctx.dedupedAlerts}} * {{id}} : {{bucket_keys}} {{ctx.dedupedAlerts}} - New Alerts: {{ctx.newAlerts}} * {{id}} : {{bucket_keys}} {{ctx.newAlerts}} - Completed Alerts: {{ctx.completedAlerts}} * {{id}} : {{bucket_keys}} {{ctx.completedAlerts}}",
|
||||
"lang" : "mustache"
|
||||
},
|
||||
"throttle_enabled" : false,
|
||||
"subject_template" : {
|
||||
"source" : "The Subject",
|
||||
"lang" : "mustache"
|
||||
},
|
||||
"throttle" : {
|
||||
"value" : 10,
|
||||
"unit" : "MINUTES"
|
||||
},
|
||||
"action_execution_policy" : {
|
||||
"action_execution_scope" : {
|
||||
"per_alert" : {
|
||||
"actionable_alerts" : [
|
||||
"DEDUPED",
|
||||
"NEW"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
]
|
||||
}
|
||||
}
|
||||
],
|
||||
"last_update_time" : 1631742270785
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Update monitor
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
@@ -19,11 +19,11 @@ has_children: false
|
||||
|
||||
Term | Definition
|
||||
:--- | :---
|
||||
Monitor | A job that runs on a defined schedule and queries OpenSearch. The results of these queries are then used as input for one or more *triggers*.
|
||||
Monitor | A job that runs on a defined schedule and queries OpenSearch indices. The results of these queries are then used as input for one or more *triggers*.
|
||||
Trigger | Conditions that, if met, generate *alerts*.
|
||||
Alert | An event associated with a trigger. When an alert is created, the trigger performs *actions*, which can include sending a notification.
|
||||
Action | The information that you want the monitor to send out after being triggered. Actions have a *destination*, a message subject, and a message body.
|
||||
Destination | A reusable location for an action, such as Amazon Chime, Slack, or a webhook URL.
|
||||
Destination | A reusable location for an action. Supported locations are Amazon Chime, Email, Slack, or custom webhook.
|
||||
|
||||
|
||||
---
|
||||
@@ -34,9 +34,9 @@ Destination | A reusable location for an action, such as Amazon Chime, Slack, or
|
||||
1. Specify a name for the destination so that you can identify it later.
|
||||
1. For **Type**, choose Slack, Amazon Chime, custom webhook, or [email](#email-as-a-destination).
|
||||
|
||||
For Email type, refer to [Email as a destination](#email-as-a-destination) section below. For all other types, specify the webhook URL. For more information about webhooks, see the documentation for [Slack](https://api.slack.com/incoming-webhooks) and [Amazon Chime](https://docs.aws.amazon.com/chime/latest/ug/webhooks.html).
|
||||
For Email, refer to the [Email as a destination](#email-as-a-destination) section below. For all other types, specify the webhook URL. See the documentation for [Slack](https://api.slack.com/incoming-webhooks) and [Amazon Chime](https://docs.aws.amazon.com/chime/latest/ug/webhooks.html) to learn more about webhooks.
|
||||
|
||||
For custom webhooks, you must specify more information: parameters and headers. For example, if your endpoint requires basic authentication, you might need to add a header with a key of `Authorization` and a value of `Basic <Base64-encoded-credential-string>`. You might also need to change `Content-Type` to whatever your webhook requires. Popular values are `application/json`, `application/xml`, and `text/plain`.
|
||||
If you're using custom webhooks, you must specify more information: parameters and headers. For example, if your endpoint requires basic authentication, you might need to add a header with a key of `Authorization` and a value of `Basic <Base64-encoded-credential-string>`. You might also need to change `Content-Type` to whatever your webhook requires. Popular values are `application/json`, `application/xml`, and `text/plain`.
|
||||
|
||||
This information is stored in plain text in the OpenSearch cluster. We will improve this design in the future, but for now, the encoded credentials (which are neither encrypted nor hashed) might be visible to other OpenSearch users.
|
||||
|
||||
@@ -55,7 +55,7 @@ To configure a sender email, do the following:
|
||||
1. After you choose **Email** as the destination type, choose **Manage senders**.
|
||||
1. Choose **Add sender**, **New sender** and enter a unique name.
|
||||
1. Enter the email address, SMTP host (e.g. `smtp.gmail.com` for a Gmail account), and the port.
|
||||
1. Choose an encryption method, or use the default value of **None**. However, most email providers require SSL or TLS, which requires a username and password in OpenSearch keystore. Refer to [Authenticate sender account](#authenticate-sender-account) to learn more.
|
||||
1. Choose an encryption method, or use the default value of **None**. However, most email providers require SSL or TLS, which require a username and password in OpenSearch keystore. Refer to [Authenticate sender account](#authenticate-sender-account) to learn more.
|
||||
1. Choose **Save** to save the configuration and create the sender. You can create a sender even before you add your credentials to the OpenSearch keystore. However, you must [authenticate each sender account](#authenticate-sender-account) before you use the destination to send your alert.
|
||||
|
||||
You can reuse senders across many different destinations, but each destination only supports one sender.
|
||||
@@ -82,7 +82,7 @@ If your email provider requires SSL or TLS, you must authenticate each sender ac
|
||||
./bin/opensearch-keystore add plugins.alerting.destination.email.<sender_name>.password
|
||||
```
|
||||
|
||||
**Note**: Keystore settings are node-specific. You must run these commands on each node.
|
||||
Note: Keystore settings are node-specific. You must run these commands on each node.
|
||||
{: .note}
|
||||
|
||||
To change or update your credentials (after you've added them to the keystore on every node), call the reload API to automatically update those credentials without restarting OpenSearch:
|
||||
@@ -101,20 +101,9 @@ POST _nodes/reload_secure_settings
|
||||
|
||||
1. Choose **Alerting**, **Monitors**, **Create monitor**.
|
||||
1. Specify a name for the monitor.
|
||||
1. Choose either **Per query monitor** or **Per bucket monitor**.
|
||||
|
||||
The anomaly detection option is for pairing with the anomaly detection plugin. See [Anomaly Detection]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/).
|
||||
For anomaly detector, choose an appropriate schedule for the monitor based on the detector interval. Otherwise, the alerting monitor might miss reading the results.
|
||||
|
||||
For example, assume you set the monitor interval and the detector interval as 5 minutes, and you start the detector at 12:00. If an anomaly is detected at 12:05, it might be available at 12:06 because of the delay between writing the anomaly and it being available for queries. The monitor reads the anomaly results between 12:00 and 12:05, so it does not get the anomaly results available at 12:06.
|
||||
|
||||
To avoid this issue, make sure the alerting monitor is at least twice the detector interval.
|
||||
When you create a monitor using OpenSearch Dashboards, the anomaly detector plugin generates a default monitor schedule that's twice the detector interval.
|
||||
|
||||
Whenever you update a detector’s interval, make sure to update the associated monitor interval as well, as the anomaly detection plugin does not do this automatically.
|
||||
|
||||
1. Choose one or more indices. You can also use `*` as a wildcard to specify an index pattern.
|
||||
|
||||
If you use the security plugin, you can only choose indices that you have permission to access. For details, see [Alerting security]({{site.url}}{{site.baseurl}}/security-plugin/).
|
||||
Whereas query-level monitors run your specified query and then check whether the query's results triggers any alerts, bucket-level monitors let you select fields to create buckets and categorize your results into those buckets. The alerting plugin runs each bucket's unique results against a script you define later, so you have finer control over which results should trigger alerts. Each of those buckets can trigger an alert, but query-level monitors can only trigger one alert at a time.
|
||||
|
||||
1. Define the monitor in one of three ways: visually, using a query, or using an anomaly detector.
|
||||
|
||||
@@ -167,39 +156,57 @@ Whenever you update a detector’s interval, make sure to update the associated
|
||||
}
|
||||
```
|
||||
|
||||
"Start" and "end" refer to the interval at which the monitor runs. See [Available variables](#available-variables).
|
||||
"Start" and "end" refer to the interval at which the monitor runs. See [Available variables](#available-variables).
|
||||
|
||||
To define a monitor visually, choose **Visual editor**. Then choose a source index, a timeframe, an aggregation (for example, `count()` or `average()`), a data filter if you want to monitor a subset of your source index, and a group-by field if you want to include an aggregation field in your query. At least one group-by field is required if you're defining a bucket-level monitor. Visual definition works well for most monitors.
|
||||
|
||||
1. To define a monitor visually, choose **Define using visual graph**. Then choose an aggregation (for example, `count()` or `average()`), a set of documents, and a timeframe. Visual definition works well for most monitors.
|
||||
If you use the security plugin, you can only choose indices that you have permission to access. For details, see [Alerting security]({{site.url}}{{site.baseurl}}/security-plugin/).
|
||||
|
||||
To use a query, choose **Define using extraction query**, add your query (using [the OpenSearch query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text/)), and test it using the **Run** button.
|
||||
To use a query, choose **Extraction query editor**, add your query (using [the OpenSearch query DSL]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/full-text/)), and test it using the **Run** button.
|
||||
|
||||
The monitor makes this query to OpenSearch as often as the schedule dictates; check the **Query Performance** section and make sure you're comfortable with the performance implications.
|
||||
The monitor makes this query to OpenSearch as often as the schedule dictates; check the **Query Performance** section and make sure you're comfortable with the performance implications.
|
||||
|
||||
To use an anomaly detector, choose **Anomaly detector** and select your **Detector**.
|
||||
|
||||
The anomaly detection option is for pairing with the anomaly detection plugin. See [Anomaly Detection]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/).
|
||||
For anomaly detector, choose an appropriate schedule for the monitor based on the detector interval. Otherwise, the alerting monitor might miss reading the results.
|
||||
|
||||
For example, assume you set the monitor interval and the detector interval as 5 minutes, and you start the detector at 12:00. If an anomaly is detected at 12:05, it might be available at 12:06 because of the delay between writing the anomaly and it being available for queries. The monitor reads the anomaly results between 12:00 and 12:05, so it does not get the anomaly results available at 12:06.
|
||||
|
||||
To avoid this issue, make sure the alerting monitor is at least twice the detector interval.
|
||||
When you create a monitor using OpenSearch Dashboards, the anomaly detector plugin generates a default monitor schedule that's twice the detector interval.
|
||||
|
||||
Whenever you update a detector’s interval, make sure to update the associated monitor interval as well, as the anomaly detection plugin does not do this automatically.
|
||||
|
||||
**Note**: Anomaly detection is available only if you are defining a per query monitor.
|
||||
{: .note}
|
||||
|
||||
To use an anomaly detector, choose **Define using Anomaly detector** and select your **Detector**.
|
||||
1. Choose a frequency and timezone for your monitor. Note that you can only pick a timezone if you choose Daily, Weekly, Monthly, or [custom cron expression]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/cron/) for frequency.
|
||||
1. Choose **Create**.
|
||||
|
||||
1. Add a trigger to your monitor.
|
||||
|
||||
---
|
||||
|
||||
## Create triggers
|
||||
|
||||
The next step in creating a monitor is to create a trigger. These steps differ depending on whether you chose **Define using visual graph** or **Define using extraction query** or **Define using Anomaly detector** when you created the monitor.
|
||||
Steps to create a trigger differ depending on whether you chose **Visual editor**, **Extraction query editor**, or **Anomaly detector** when you created the monitor.
|
||||
|
||||
Either way, you begin by specifying a name and severity level for the trigger. Severity levels help you manage alerts. A trigger with a high severity level (e.g. 1) might page a specific individual, whereas a trigger with a low severity level might message a chat room.
|
||||
You begin by specifying a name and severity level for the trigger. Severity levels help you manage alerts. A trigger with a high severity level (e.g. 1) might page a specific individual, whereas a trigger with a low severity level might message a chat room.
|
||||
|
||||
Remember that query-level monitors run your trigger's script just once against the query's results, but bucket-level monitors execute your trigger's script on each bucket, so you should create a trigger that best fits the monitor you chose. If you want to execute multiple scripts, you must create multiple triggers.
|
||||
|
||||
### Visual graph
|
||||
### Visual editor
|
||||
|
||||
For **Trigger condition**, specify a threshold for the aggregation and timeframe you chose earlier, such as "is below 1,000" or "is exactly 10."
|
||||
For a query-level monitor's **Trigger condition**, specify a threshold for the aggregation and timeframe you chose earlier, such as "is below 1,000" or "is exactly 10."
|
||||
|
||||
The line moves up and down as you increase and decrease the threshold. Once this line is crossed, the trigger evaluates to true.
|
||||
|
||||
Bucket-level monitors also require you to specify a threshold and value for your aggregation and timeframe, but you can use a maximum of five conditions to better refine your trigger. Optionally, you can also use a keyword filter to filter for a specific field in your index.
|
||||
|
||||
|
||||
### Extraction query
|
||||
|
||||
For **Trigger condition**, specify a Painless script that returns true or false. Painless is the default OpenSearch scripting language and has a syntax similar to Groovy.
|
||||
If you're using a query-level monitor, specify a Painless script that returns true or false. Painless is the default OpenSearch scripting language and has a syntax similar to Groovy.
|
||||
|
||||
Trigger condition scripts revolve around the `ctx.results[0]` variable, which corresponds to the extraction query response. For example, your script might reference `ctx.results[0].hits.total.value` or `ctx.results[0].hits.hits[i]._source.error_code`.
|
||||
|
||||
@@ -208,6 +215,27 @@ A return value of true means the trigger condition has been met, and the trigger
|
||||
The **Info** link next to **Trigger condition** contains a useful summary of the variables and results available to your query.
|
||||
{: .tip }
|
||||
|
||||
Bucket-level monitors require you to specify more information in your trigger condition. At a minimum, you must have the following fields:
|
||||
|
||||
- `buckets_path`, which maps variable names to metrics to use in your script.
|
||||
- `parent_bucket_path`, which is a path to a multi-bucket aggregation. The path can include single-bucket aggregations, but the last aggregation must be multi-bucket. For example, if you have a pipeline such as `agg1>agg2>agg3`, `agg1` and `agg2` are single-bucket aggregations, but `agg3` must be a multi-bucket aggregation.
|
||||
- `script`, which is the script that OpenSearch runs to evaluate whether to trigger any alerts.
|
||||
|
||||
For example, you might have a script that looks like the following:
|
||||
|
||||
```json
|
||||
{
|
||||
"buckets_path": {
|
||||
"count_var": "_count"
|
||||
},
|
||||
"parent_bucket_path": "composite_agg",
|
||||
"script": {
|
||||
"source": "params.count_var > 5"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
After mapping the `count_var` variable to the `_count` metric, you can use `count_var` in your script and reference `_count` data. Finally, `composite_agg` is a path to a multi-bucket aggregation.
|
||||
|
||||
### Anomaly detector
|
||||
|
||||
@@ -264,11 +292,11 @@ Below are some variables you can include in your message using Mustache template
|
||||
|
||||
Variable | Data Type | Description
|
||||
:--- | :--- | :---
|
||||
`ctx.monitor` | JSON | Includes `ctx.monitor.name`, `ctx.monitor.type`, `ctx.monitor.enabled`, `ctx.monitor.enabled_time`, `ctx.monitor.schedule`, `ctx.monitor.inputs`, `triggers` and `ctx.monitor.last_update_time`.
|
||||
`ctx.monitor.user` | JSON | Includes information about the user who created the monitor. Includes `ctx.monitor.user.backend_roles` and `ctx.monitor.user.roles`, which are arrays that contain the backend roles and roles assigned to the user. See [alerting security]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/) for more information.
|
||||
`ctx.monitor` | Object | Includes `ctx.monitor.name`, `ctx.monitor.type`, `ctx.monitor.enabled`, `ctx.monitor.enabled_time`, `ctx.monitor.schedule`, `ctx.monitor.inputs`, `triggers` and `ctx.monitor.last_update_time`.
|
||||
`ctx.monitor.user` | Object | Includes information about the user who created the monitor. Includes `ctx.monitor.user.backend_roles` and `ctx.monitor.user.roles`, which are arrays that contain the backend roles and roles assigned to the user. See [alerting security]({{site.url}}{{site.baseurl}}/monitoring-plugins/alerting/security/) for more information.
|
||||
`ctx.monitor.enabled` | Boolean | Whether the monitor is enabled.
|
||||
`ctx.monitor.enabled_time` | Milliseconds | Unix epoch time of when the monitor was last enabled.
|
||||
`ctx.monitor.schedule` | JSON | Contains a schedule of how often or when the monitor should run.
|
||||
`ctx.monitor.schedule` | Object | Contains a schedule of how often or when the monitor should run.
|
||||
`ctx.monitor.schedule.period.interval` | Integer | The interval at which the monitor runs.
|
||||
`ctx.monitor.schedule.period.unit` | String | The interval's unit of time.
|
||||
`ctx.monitor.inputs` | Array | An array that contains the indices and definition used to create the monitor.
|
||||
@@ -282,7 +310,7 @@ Variable | Data Type | Description
|
||||
`ctx.trigger.id` | String | The trigger's ID.
|
||||
`ctx.trigger.name` | String | The trigger's name.
|
||||
`ctx.trigger.severity` | String | The trigger's severity.
|
||||
`ctx.trigger.condition`| JSON | Contains the Painless script used when creating the monitor.
|
||||
`ctx.trigger.condition`| Object | Contains the Painless script used when creating the monitor.
|
||||
`ctx.trigger.condition.script.source` | String | The language used to define the script. Must be painless.
|
||||
`ctx.trigger.condition.script.lang` | String | The script used to define the trigger.
|
||||
`ctx.trigger.actions`| Array | An array with one element that contains information about the action the monitor needs to trigger.
|
||||
@@ -309,7 +337,13 @@ Variable | Data Type | Description
|
||||
`ctx.periodStart` | String | Unix timestamp for the beginning of the period during which the alert triggered. For example, if a monitor runs every ten minutes, a period might begin at 10:40 and end at 10:50.
|
||||
`ctx.periodEnd` | String | The end of the period during which the alert triggered.
|
||||
`ctx.error` | String | The error message if the trigger was unable to retrieve results or unable to evaluate the trigger, typically due to a compile error or null pointer exception. Null otherwise.
|
||||
`ctx.alert` | JSON | The current, active alert (if it exists). Includes `ctx.alert.id`, `ctx.alert.version`, and `ctx.alert.isAcknowledged`. Null if no alert is active.
|
||||
`ctx.alert` | Object | The current, active alert (if it exists). Includes `ctx.alert.id`, `ctx.alert.version`, and `ctx.alert.isAcknowledged`. Null if no alert is active. Only available with query-level monitors.
|
||||
`ctx.dedupedAlerts` | Object | Alerts that have already been triggered. OpenSearch keeps the existing alert to prevent the plugin from creating endless amounts of the same alerts. Only available with bucket-level monitors.
|
||||
`ctx.newAlerts` | Object | Newly created alerts. Only available with bucket-level monitors.
|
||||
`ctx.completedAlerts` | Object | Alerts that are no longer ongoing. Only available with bucket-level monitors.
|
||||
`bucket_keys` | String | Comma-separated list of the monitor's bucket key values. Available only for `ctx.dedupedAlerts`, `ctx.newAlerts`, and `ctx.completedAlerts`. Accessed through `ctx.dedupedAlerts[0].bucket_keys`.
|
||||
`parent_bucket_path` | String | The parent bucket path of the bucket that triggered the alert. Accessed through `ctx.dedupedAlerts[0].parent_bucket_path`.
|
||||
|
||||
|
||||
|
||||
---
|
||||
@@ -334,6 +368,7 @@ If you don't want to receive notifications for alerts, you don't have to add act
|
||||
```
|
||||
|
||||
In this case, the message content must conform to the `Content-Type` header in the [custom webhook](#create-destinations).
|
||||
1. If you're using a bucket-level monitor, you can choose whether the monitor should perform an action for each execution or for each alert.
|
||||
|
||||
1. (Optional) Use action throttling to limit the number of notifications you receive within a given span of time.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
layout: default
|
||||
title: Create PerfTop Dashboards
|
||||
title: Create Dashboards
|
||||
parent: Performance Analyzer
|
||||
nav_order: 2
|
||||
---
|
||||
|
||||
@@ -48,11 +48,11 @@ Otherwise, just specify the OpenSearch endpoint:
|
||||
./opensearch-perf-top-macos --dashboard dashboards/<dashboard>.json --endpoint my-cluster.my-domain.com
|
||||
```
|
||||
|
||||
PerfTop has four pre-built dashboards in the `dashboards` directory, but you can also [create your own]({{site.url}}{{site.baseurl}}/monitoring-plugins/pa/dashboards/).
|
||||
PerfTop has four pre-built dashboards in the `dashboards` directory, but you can also [create your own]({{site.url}}{{site.baseurl}}/dashboards/).
|
||||
|
||||
You can also load the pre-built dashboards (ClusterOverview, ClusterNetworkMemoryAnalysis, ClusterThreadAnalysis, or NodeAnalysis) without the JSON files, such as `--dashboard ClusterThreadAnalysis`.
|
||||
|
||||
PerfTop has no interactivity. Start the application, monitor the dashboard, and press Esc, Q, or Ctrl + C to quit.
|
||||
PerfTop has no interactivity. Start the application, monitor the dashboard, and press esc, q, or Ctrl + C to quit.
|
||||
{: .note }
|
||||
|
||||
|
||||
|
||||
@@ -65,12 +65,4 @@ PUT _cluster/settings
|
||||
|
||||
You can find `opensearch.yml` in `/usr/share/opensearch/config/opensearch.yml` (Docker) or `/etc/opensearch/opensearch.yml` (most Linux distributions) on each node.
|
||||
|
||||
You don't mark settings in `opensearch.yml` as persistent or transient, and settings use the flat form:
|
||||
|
||||
```yml
|
||||
cluster.name: my-application
|
||||
action.auto_create_index: true
|
||||
compatibility.override_main_response_version: true
|
||||
```
|
||||
|
||||
The demo configuration includes a number of settings for the security plugin that you should modify before using OpenSearch for a production workload. To learn more, see [Security]({{site.url}}{{site.baseurl}}/security-plugin/).
|
||||
|
||||
@@ -31,16 +31,16 @@ The default Helm chart deploys a three-node cluster. We recommend that you have
|
||||
|
||||
## Install OpenSearch using Helm
|
||||
|
||||
1. Clone the [helm-charts](https://github.com/opensearch-project/helm-charts) repository:
|
||||
1. Clone the [opensearch-devops](https://github.com/opensearch-project/opensearch-devops/) repository:
|
||||
|
||||
```bash
|
||||
git clone https://github.com/opensearch-project/helm-charts
|
||||
git clone https://github.com/opensearch-project/opensearch-devops.git
|
||||
```
|
||||
|
||||
1. Change to the `opensearch` directory:
|
||||
|
||||
```bash
|
||||
cd charts/opensearch
|
||||
cd Helm/opensearch
|
||||
```
|
||||
|
||||
1. Package the Helm chart:
|
||||
|
||||
@@ -111,7 +111,7 @@ In a tarball installation, Performance Analyzer collects data when it is enabled
|
||||
1. Launch the agent CLI:
|
||||
|
||||
```bash
|
||||
OPENSEARCH_HOME="$PWD" ./bin/performance-analyzer-agent-cli
|
||||
ES_HOME="$PWD" ./bin/performance-analyzer-agent-cli
|
||||
```
|
||||
|
||||
1. In a separate window, enable the Performance Analyzer plugin:
|
||||
|
||||
@@ -5,11 +5,8 @@ nav_order: 27
|
||||
has_children: true
|
||||
redirect_from:
|
||||
- /opensearch/query-dsl/
|
||||
- /docs/opensearch/query-dsl/
|
||||
---
|
||||
|
||||
{%- comment -%}The `/docs/opensearch/query-dsl/` redirect is specifically to support the UI links in OpenSearch Dashboards 1.0.0.{%- endcomment -%}
|
||||
|
||||
# Query DSL
|
||||
|
||||
While you can use HTTP request parameters to perform simple searches, you can also use the OpenSearch query domain-specific language (DSL), which provides a wider range of search options. The query DSL uses the HTTP request body, so you can more easily customize your queries to get the exact results that you want.
|
||||
|
||||
@@ -156,6 +156,28 @@ POST _reindex
|
||||
}
|
||||
```
|
||||
|
||||
## Reindex sorted documents
|
||||
|
||||
You can copy certain documents after sorting specific fields in the document.
|
||||
|
||||
This command copies the last 10 documents based on the `timestamp` field:
|
||||
|
||||
```json
|
||||
POST _reindex
|
||||
{
|
||||
"size":10,
|
||||
"source":{
|
||||
"index":"source",
|
||||
"sort":{
|
||||
"timestamp":"desc"
|
||||
}
|
||||
},
|
||||
"dest":{
|
||||
"index":"destination"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Transform documents during reindexing
|
||||
|
||||
You can transform your data during the reindexing process using the `script` option.
|
||||
@@ -250,6 +272,7 @@ Option | Valid values | Description | Required
|
||||
`query` | Object | The search query to use for the reindex operation. | No
|
||||
`size` | Integer | The number of documents to reindex. | No
|
||||
`slice` | String | Specify manual or automatic slicing to parallelize reindexing. | No
|
||||
`sort` | List | Sort specific fields in the document before reindexing. | No
|
||||
|
||||
## Destination index options
|
||||
|
||||
|
||||
@@ -1,103 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Count
|
||||
parent: REST API reference
|
||||
nav_order: 150
|
||||
---
|
||||
|
||||
# Count
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
The count API gives you quick access to the number of documents that match a query.
|
||||
You can also use it to check the document count of an index, data stream, or cluster.
|
||||
|
||||
|
||||
## Example
|
||||
|
||||
To see the number of documents that match a query:
|
||||
|
||||
```json
|
||||
GET opensearch_dashboards_sample_data_logs/_count
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
"response": "200"
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
The following call to the search API produces equivalent results:
|
||||
|
||||
```json
|
||||
GET opensearch_dashboards_sample_data_logs/_search
|
||||
{
|
||||
"query": {
|
||||
"term": {
|
||||
"response": "200"
|
||||
}
|
||||
},
|
||||
"size": 0,
|
||||
"track_total_hits": true
|
||||
}
|
||||
```
|
||||
|
||||
To see the number of documents in an index:
|
||||
|
||||
```json
|
||||
GET opensearch_dashboards_sample_data_logs/_count
|
||||
```
|
||||
|
||||
To check for the number of documents in a [data stream]({{site.url}}{{site.baseurl}}/opensearch/data-streams/), replace the index name with the data stream name.
|
||||
|
||||
To see the number of documents in your cluster:
|
||||
|
||||
```json
|
||||
GET _count
|
||||
```
|
||||
|
||||
Alternatively, you could use the [cat indices]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/cat-indices/) and [cat count]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/cat-count/) APIs to see the number of documents per index or data stream.
|
||||
{: .note }
|
||||
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET <target>/_count/<id>
|
||||
POST <target>/_count/<id>
|
||||
```
|
||||
|
||||
|
||||
## URL parameters
|
||||
|
||||
All count parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
`allow_no_indices` | Boolean | If false, the request returns an error if any wildcard expression or index alias targets any closed or missing indices. Default is false.
|
||||
`analyzer` | String | The analyzer to use in the query string.
|
||||
`analyze_wildcard` | Boolean | Specifies whether to analyze wildcard and prefix queries. Default is false.
|
||||
`default_operator` | String | Indicates whether the default operator for a string query should be AND or OR. Default is OR.
|
||||
`df` | String | The default field in case a field prefix is not provided in the query string.
|
||||
`expand_wildcards` | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are `all` (match any index), `open` (match open, non-hidden indices), `closed` (match closed, non-hidden indices), `hidden` (match hidden indices), and `none` (deny wildcard expressions). Default is `open`.
|
||||
`ignore_unavailable` | Boolean | Specifies whether to include missing or closed indices in the response. Default is false.
|
||||
`lenient` | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false.
|
||||
`min_score` | Float | Include only documents with a minimum `_score` value in the result.
|
||||
`routing` | String | Value used to route the operation to a specific shard.
|
||||
`preference` | String | Specifies which shard or node OpenSearch should perform the count operation on.
|
||||
`terminate_after` | Integer | The maximum number of documents OpenSearch should process before terminating the request.
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"count" : 14074,
|
||||
"_shards" : {
|
||||
"total" : 1,
|
||||
"successful" : 1,
|
||||
"skipped" : 0,
|
||||
"failed" : 0
|
||||
}
|
||||
}
|
||||
```
|
||||
+6
-7
@@ -1,9 +1,8 @@
|
||||
---
|
||||
layout: default
|
||||
title: Create index
|
||||
parent: Index APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 1
|
||||
parent: REST API reference
|
||||
nav_order: 3
|
||||
---
|
||||
|
||||
# Create index
|
||||
@@ -97,10 +96,10 @@ index.auto_expand_replicas | Whether the cluster should automatically add replic
|
||||
index.search.idle.after | Amount of time a shard should wait for a search or get request until it goes idle. Default is `30s`.
|
||||
index.refresh_interval | How often the index should refresh, which publishes its most recent changes and makes them available for searching. Can be set to `-1` to disable refreshing. Default is `1s`.
|
||||
index.max_result_window | The maximum value of `from` + `size` for searches to the index. `from` is the starting index to search from, and `size` is the amount of results to return. Default: 10000.
|
||||
index.max_inner_result_window | Maximum value of `from` + `size` to return nested search hits and most relevant document aggregated during the query. `from` is the starting index to search from, and `size` is the amount of top hits to return. Default is 100.
|
||||
index.max_inner_result_window | aximum value of `from` + `size` to return nested search hits and most relevant document aggregated during the query. `from` is the starting index to search from, and `size` is the amount of top hits to return. Default is 100.
|
||||
index.max_rescore_window | The maximum value of `window_size` for rescore requests to the index. Rescore requests reorder the index's documents and return a new score, which can be more precise. Default is the same as index.max_inner_result_window or 10000 by default.
|
||||
index.max_docvalue_fields_search | Maximum amount of `docvalue_fields` allowed in a query. Default is 100.
|
||||
index.max_script_fields | Maximum amount of `script_fields` allowed in a query. Default is 32.
|
||||
index.max_script_fields | Maximum amount of`script_fields` allowed in a query. Default is 32.
|
||||
index.max_ngram_diff | Maximum difference between `min_gram` and `max_gram` values for `NGramTokenizer` and `NGramTokenFilter` fields. Default is 1.
|
||||
index.max_shingle_diff | Maximum difference between `max_shingle_size` and `min_shingle_size` to feed into the `shingle` token filter. Default is 3.
|
||||
index.max_refresh_listeners | Maximum amount of refresh listeners each shard is allowed to have.
|
||||
@@ -110,12 +109,12 @@ index.max_terms_count | The maximum amount of terms a terms query can accept. De
|
||||
index.max_regex_length | The maximum character length of regex that can be in a regexp query. Default is 1000.
|
||||
index.query.default_field | A field or list of fields that OpenSearch uses in queries in case a field isn't specified in the parameters.
|
||||
index.routing.allocation.enable | Specifies options for the index’s shard allocation. Available options are all (allow allocation for all shards), primaries (allow allocation only for primary shards), new_primaries (allow allocation only for new primary shards), and none (do not allow allocation). Default is all.
|
||||
index.routing.rebalance.enable | Enables shard rebalancing for the index. Available options are `all` (allow rebalancing for all shards), `primaries` (allow rebalancing only for primary shards), `replicas` (allow rebalancing only for replicas), and `none` (do not allow rebalancing). Default is `all`.
|
||||
index.routing.rebalance.enable - Shard rebalancing for the index. Available options are `all` (allow rebalancing for all shards), `primaries` (allow rebalancing only for primary shards), `replicas` (allow rebalancing only for replicas), and `none` (do not allow rebalancing). Default is `all`.
|
||||
index.routing.rebalance.enable | Enables shard rebalancing for the index. Available options are `all` (allow shard rebalancing for all shards), `primaries`, (allow shard rebalancing only for primary shards), `replicas` (allow shard rebalancing only for replicas), and `none` (do not allow shard rebalancing). Default is `all`.
|
||||
index.gc_deletes | Amount of time to retain a deleted document's version number. Default is `60s`.
|
||||
index.default_pipeline | The default ingest node pipeline for the index. If the default pipeline is set and the pipeline does not exist, then index requests fail. The pipeline name `_none` specifies that the index does not have an ingest pipeline.
|
||||
index.final_pipeline | The final ingest node pipeline for the index. If the final pipeline is set and the pipeline does not exist, then index requests fail. The pipeline name `_none` specifies that the index does not have an ingest pipeline.
|
||||
|
||||
|
||||
### Mappings
|
||||
|
||||
Mappings define how a documents and its fields are stored and indexed. If you're just starting to build out your cluster and data, you may not know exactly how your data should be stored. In those cases, you can use dynamic mappings, which tell OpenSearch to dynamically add data and their fields. However, if you know exactly what types your data fall under and want to enforce that standard, then you can use explicit mappings.
|
||||
@@ -1,121 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Reindex
|
||||
parent: Document APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 60
|
||||
---
|
||||
|
||||
# Index document
|
||||
Introduced 1.0
|
||||
{: .label .label-purple}
|
||||
|
||||
The reindex API operation lets you copy all or a subset of your data from a source index into a destination index.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
POST /_reindex
|
||||
{
|
||||
"source":{
|
||||
"index":"my-source-index"
|
||||
},
|
||||
"dest":{
|
||||
"index":"my-destination-index"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
POST /_reindex
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All URL parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
refresh | Boolean | If true, OpenSearch refreshes shards to make the reindex operation available to search results. Valid options are `true`, `false`, and `wait_for`, which tells OpenSearch to wait for a refresh before executing the operation. Default is `false`.
|
||||
timeout | Time | How long to wait for a response from the cluster. Default is `30s`.
|
||||
wait_for_active_shards | String | The number of active shards that must be available before OpenSearch processes the reindex request. Default is 1 (only the primary shard). Set to `all` or a positive integer. Values greater than 1 require replicas. For example, if you specify a value of 3, the index must have two replicas distributed across two additional nodes for the operation to succeed.
|
||||
wait_for_completion | Boolean | Waits for the matching tasks to complete. Default is `false`.
|
||||
requests_per_second | Integer | Specifies the request’s throttling in sub-requests per second. Default is -1, which means no throttling.
|
||||
require_alias | Boolean | Whether the destination index must be an index alias. Default is false.
|
||||
scroll | Time | How long to keep the search context open. Default is `5m`.
|
||||
slices | Integer | Number of sub-tasks OpenSearch should divide this task into. Default is 1, which means OpenSearch should not divide this task. Setting this parameter to `auto` indicates to OpenSearch that it should automatically decide how many slices to split the task into.
|
||||
max_docs | Integer | How many documents the update by query operation should process at most. Default is all documents.
|
||||
|
||||
## Request body
|
||||
|
||||
Your request body must contain the names of the source index and destination index. All other fields are optional.
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
conflicts | Indicates to OpenSearch what should happen if the delete by query operation runs into a version conflict. Valid options are `abort` and `proceed`. Default is abort.
|
||||
source | Information about the source index to include. Valid fields are `index`, `max_docs`, `query`, `remote`, `size`, `slice`, and `_source`.
|
||||
index | The name of the source index to copy data from.
|
||||
max_docs | The maximum number of documents to reindex.
|
||||
query | The search query to use for the reindex operation.
|
||||
remote | Information about a remote OpenSearch cluster to copy data from. Valid fields are `host`, `username`, `password`, `socket_timeout`, and `connect_timeout`.
|
||||
host | Host URL of the OpenSearch cluster to copy data from.
|
||||
username | Username to authenticate with the remote cluster.
|
||||
password | Password to authenticate with the remote cluster.
|
||||
socket_timeout | The wait time for socket reads. Default is 30s.
|
||||
connect_timeout | The wait time for remote connection timeouts. Default is 30s.
|
||||
size | The number of documents to reindex.
|
||||
slice | Whether to manually or automatically slice the reindex operation so it executes in parallel.
|
||||
_source | Whether to reindex source fields. Speicfy a list of fields to reindex or true to reindex all fields. Default is true.
|
||||
id | The ID to associate with manual slicing.
|
||||
max | Maximum number of slices.
|
||||
dest | Information about the destination index. Valid values are `index`, `version_type`, and `op_type`.
|
||||
index | Name of the destination index.
|
||||
version_type | The indexing operation's version type. Valid values are `internal`, `external`, `external_gt` (retrieve the document if the specified version number is greater than the document’s current version), and `external_gte` (retrieve the document if the specified version number is greater or equal to than the document’s current version).
|
||||
op_type | Whether to copy over documents that are missing in the destination index. Valid values are `create` (ignore documents with the same ID from the source index) and `index` (copy everything from the source index).
|
||||
script | A script that OpenSearch uses to apply transformations to the data during the reindex operation.
|
||||
source | The actual script that OpenSearch runs.
|
||||
lang | The scripting language. Valid options are `painless`, `expression`, `mustache`, and `java`.
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"took": 28829,
|
||||
"timed_out": false,
|
||||
"total": 111396,
|
||||
"updated": 0,
|
||||
"created": 111396,
|
||||
"deleted": 0,
|
||||
"batches": 112,
|
||||
"version_conflicts": 0,
|
||||
"noops": 0,
|
||||
"retries": {
|
||||
"bulk": 0,
|
||||
"search": 0
|
||||
},
|
||||
"throttled_millis": 0,
|
||||
"requests_per_second": -1.0,
|
||||
"throttled_until_millis": 0,
|
||||
"failures": []
|
||||
}
|
||||
```
|
||||
|
||||
## Response body fields
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
took | How long the operation took in milliseconds.
|
||||
timed_out | Whether the operation timed out.
|
||||
total | The total number of documents processed.
|
||||
updated | The number of documents updated in the destination index.
|
||||
created | The number of documents created in the destination index.
|
||||
deleted | The number of documents deleted.
|
||||
batches | Number of scroll responses.
|
||||
version_conflicts | Number of version conflicts.
|
||||
noops | How many documents OpenSearch ignored during the operation.
|
||||
retries | Number of bulk and search retry requests.
|
||||
throttled_millis | Number of throttled milliseconds during the request.
|
||||
requests_per_second | Number of requests executed per second during the operation.
|
||||
throttled_until_millis | The amount of time until OpenSearch executes the next throttled request.
|
||||
failures | Any failures that occurred during the operation.
|
||||
@@ -80,7 +80,7 @@ wait_for_active_shards | String | The number of shards that must be active befor
|
||||
|
||||
## Request body
|
||||
|
||||
To update your indices and documents by query, you must include a [query]({{site.url}}{{site.baseurl}}/opensearch/query-dsl/index) and a script in the request body that OpenSearch can run to update your documents. If you don't specify a query, then every document in the index gets updated.
|
||||
To update your indices and documents by query, you must include a [query]({{site.baseurl}}{{site.url}}/opensearch/query-dsl/index) and a script in the request body that OpenSearch can run to update your documents. If you don't specify a query, then every document in the index gets updated.
|
||||
|
||||
```json
|
||||
{
|
||||
|
||||
@@ -1,45 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Delete index
|
||||
parent: Index APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 5
|
||||
---
|
||||
|
||||
# Delete index
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
If you no longer need an index, you can use the delete index API operation to delete it.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
DELETE /sample-index
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
DELETE /<index-name>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
allow_no_indices | Boolean | Whether to ignore wildcards that don't match any indices. Default is true.
|
||||
expand_wildcards | String | Expands wildcard expressions to different indices. Combine multiple values with commas. Available values are all (match all indices), open (match open indices), closed (match closed indices), hidden (match hidden indices), and none (do not accept wildcard expressions), which must be used with open, closed, or both. Default is open.
|
||||
ignore_unavailable | Boolean | If true, OpenSearch does not include missing or closed indices in the response.
|
||||
master_timeout | Time | How long to wait for a connection to the master node. Default is `30s`.
|
||||
timeout | Time | How long to wait for the response to return. Default is `30s`.
|
||||
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"acknowledged": true
|
||||
}
|
||||
```
|
||||
@@ -1,76 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Get index
|
||||
parent: Index APIs
|
||||
grand_parent: REST API reference
|
||||
nav_order: 10
|
||||
---
|
||||
|
||||
# Get index
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
You can use the get index API operation to return information about an index.
|
||||
|
||||
## Example
|
||||
|
||||
```json
|
||||
GET /sample-index
|
||||
```
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET /<index-name>
|
||||
```
|
||||
|
||||
## URL parameters
|
||||
|
||||
All parameters are optional.
|
||||
|
||||
Parameter | Type | Description
|
||||
:--- | :--- | :---
|
||||
allow_no_indices | Boolean | Whether to ignore wildcards that don't match any indices. Default is true.
|
||||
expand_wildcards | String | Expands wildcard expressions to different indices. Combine multiple values with commas. Available values are all (match all indices), open (match open indices), closed (match closed indices), hidden (match hidden indices), and none (do not accept wildcard expressions), which must be used with open, closed, or both. Default is open.
|
||||
flat_settings | Boolean | Whether to return settings in the flat form, which can improve readability, especially for heavily nested settings. For example, the flat form of "index": { "creation_date": "123456789" } is "index.creation_date": "123456789".
|
||||
include_defaults | Boolean | Whether to include default settings as part of the response. This parameter is useful for identifying the names and current values of settings you want to update.
|
||||
ignore_unavailable | Boolean | If true, OpenSearch does not include missing or closed indices in the response.
|
||||
local | Boolean | Whether to return information from only the local node instead of from the master node. Default is false.
|
||||
master_timeout | Time | How long to wait for a connection to the master node. Default is `30s`.
|
||||
|
||||
|
||||
## Response
|
||||
```json
|
||||
{
|
||||
"sample-index1": {
|
||||
"aliases": {},
|
||||
"mappings": {},
|
||||
"settings": {
|
||||
"index": {
|
||||
"creation_date": "1633044652108",
|
||||
"number_of_shards": "2",
|
||||
"number_of_replicas": "1",
|
||||
"uuid": "XcXA0aZ5S0aiqx3i1Ce95w",
|
||||
"version": {
|
||||
"created": "135217827"
|
||||
},
|
||||
"provided_name": "sample-index1"
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
## Response body fields
|
||||
|
||||
Field | Description
|
||||
:--- | :---
|
||||
aliases | Any aliases associated with the index.
|
||||
mappings | Any mappings in the index.
|
||||
settings | The index's settings
|
||||
creation_date | The Unix epoch time of when the index was created.
|
||||
number_of_shards | How many shards the index has.
|
||||
number_of_replicas | How many replicas the index has.
|
||||
uuid | The index's uuid.
|
||||
created | The version of OpenSearch when the index was created.
|
||||
provided_name | Name of the index.
|
||||
@@ -1,16 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Index APIs
|
||||
parent: REST API reference
|
||||
has_children: true
|
||||
nav_order: 3
|
||||
redirect_from:
|
||||
- /opensearch/rest-api/index-apis/
|
||||
---
|
||||
|
||||
# Index APIs
|
||||
|
||||
The index API operations let you interact with indices in your cluster. Using these operations, you can create, delete, close, and complete other index-related operations.
|
||||
|
||||
If you use the security plugin, make sure you have the appropriate permissions.
|
||||
{: .note }
|
||||
@@ -1,40 +0,0 @@
|
||||
---
|
||||
layout: default
|
||||
title: Remote cluster information
|
||||
parent: REST API reference
|
||||
nav_order: 25
|
||||
---
|
||||
|
||||
# Remote cluster information
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
This operation provides connection information for any remote OpenSearch clusters that you've configured for the local cluster, such as the remote cluster alias, connection mode (`sniff` or `proxy`), IP addresses for seed nodes, and timeout settings.
|
||||
|
||||
The response is more comprehensive and useful than a call to `_cluster/settings`, which only includes the cluster alias and seed nodes.
|
||||
|
||||
|
||||
## Path and HTTP methods
|
||||
|
||||
```
|
||||
GET _remote/info
|
||||
```
|
||||
|
||||
|
||||
## Response
|
||||
|
||||
```json
|
||||
{
|
||||
"opensearch-cluster2": {
|
||||
"connected": true,
|
||||
"mode": "sniff",
|
||||
"seeds": [
|
||||
"172.28.0.2:9300"
|
||||
],
|
||||
"num_nodes_connected": 1,
|
||||
"max_connections_per_cluster": 3,
|
||||
"initial_connect_timeout": "30s",
|
||||
"skip_unavailable": false
|
||||
}
|
||||
}
|
||||
```
|
||||
@@ -6,8 +6,6 @@ nav_order: 6
|
||||
---
|
||||
|
||||
# Update mapping
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
If you want to update an index's mappings to add or update field types after index creation, you can do so with the update mapping API operation.
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: API
|
||||
parent: Access control
|
||||
parent: Access Control
|
||||
nav_order: 90
|
||||
---
|
||||
|
||||
@@ -1159,12 +1159,110 @@ Introduced 1.0
|
||||
|
||||
Updates the existing configuration using the REST API. This operation can easily break your existing configuration, so we recommend using `securityadmin.sh` instead, which is far safer. See [Access control for the API](#access-control-for-the-api) for how to enable this operation.
|
||||
|
||||
Before you can execute the operation, you must first add the following line to `opensearch.yml`:
|
||||
#### Request
|
||||
|
||||
```yml
|
||||
plugins.security.unsupported.restapi.allow_securityconfig_modification: true
|
||||
```json
|
||||
PATCH _plugins/_security/api/securityconfig
|
||||
[
|
||||
{
|
||||
"op": "replace", "path": "/config/dynamic/authc/basic_internal_auth_domain/transport_enabled", "value": "true"
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "OK",
|
||||
"message": "Resource updated."
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Certificates
|
||||
|
||||
### Get certificates
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Retrieves the current security plugin configuration in JSON format.
|
||||
|
||||
#### Request
|
||||
|
||||
```
|
||||
GET _plugins/_security/api/securityconfig
|
||||
```
|
||||
|
||||
|
||||
### Update configuration
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Creates or updates the existing configuration using the REST API rather than `securityadmin.sh`. This operation can easily break your existing configuration, so we recommend using `securityadmin.sh` instead. See [Access control for the API](#access-control-for-the-api) for how to enable this operation.
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
PUT _plugins/_security/api/securityconfig/config
|
||||
{
|
||||
"dynamic": {
|
||||
"filtered_alias_mode": "warn",
|
||||
"disable_rest_auth": false,
|
||||
"disable_intertransport_auth": false,
|
||||
"respect_request_indices_options": false,
|
||||
"opensearch-dashboards": {
|
||||
"multitenancy_enabled": true,
|
||||
"server_username": "kibanaserver",
|
||||
"index": ".opensearch-dashboards"
|
||||
},
|
||||
"http": {
|
||||
"anonymous_auth_enabled": false
|
||||
},
|
||||
"authc": {
|
||||
"basic_internal_auth_domain": {
|
||||
"http_enabled": true,
|
||||
"transport_enabled": true,
|
||||
"order": 0,
|
||||
"http_authenticator": {
|
||||
"challenge": true,
|
||||
"type": "basic",
|
||||
"config": {}
|
||||
},
|
||||
"authentication_backend": {
|
||||
"type": "intern",
|
||||
"config": {}
|
||||
},
|
||||
"description": "Authenticate via HTTP Basic against internal users database"
|
||||
}
|
||||
},
|
||||
"auth_failure_listeners": {},
|
||||
"do_not_fail_on_forbidden": false,
|
||||
"multi_rolespan_enabled": true,
|
||||
"hosts_resolver_mode": "ip-only",
|
||||
"do_not_fail_on_forbidden_empty": false
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "OK",
|
||||
"message": "'config' updated."
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Patch configuration
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Updates the existing configuration using the REST API rather than `securityadmin.sh`. This operation can easily break your existing configuration, so we recommend using `securityadmin.sh` instead. See [Access control for the API](#access-control-for-the-api) for how to enable this operation.
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
@@ -1187,147 +1285,6 @@ PATCH _plugins/_security/api/securityconfig
|
||||
|
||||
---
|
||||
|
||||
## Distinguished names
|
||||
|
||||
These REST APIs let a super admin add, retrieve, update, or delete any distinguished names from an allow list to enable communication between clusters and/or nodes.
|
||||
|
||||
Before you can use the REST API to configure the allow list, you must first add the following line to `opensearch.yml`:
|
||||
|
||||
```yml
|
||||
plugins.security.nodes_dn_dynamic_config_enabled: true
|
||||
```
|
||||
|
||||
|
||||
### Get distinguished names
|
||||
|
||||
Retrieves all distinguished names in the allow list.
|
||||
|
||||
#### Request
|
||||
|
||||
```
|
||||
GET _plugins/_security/api/nodesdn
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"cluster1": {
|
||||
"nodes_dn": [
|
||||
"CN=cluster1.example.com"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
To get the distinguished names from a specific cluster's or node's allow list, include the cluster's name in the request path.
|
||||
|
||||
#### Request
|
||||
|
||||
```
|
||||
GET _plugins/_security/api/nodesdn/<cluster-name>
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"cluster3": {
|
||||
"nodes_dn": [
|
||||
"CN=cluster3.example.com"
|
||||
]
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Update distinguished names
|
||||
|
||||
Adds or updates the specified distinguished names in the cluster's or node's allow list.
|
||||
|
||||
#### Request
|
||||
|
||||
```json
|
||||
PUT _plugins/_security/api/nodesdn/<cluster-name>
|
||||
{
|
||||
"nodes_dn": [
|
||||
"CN=cluster3.example.com"
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "CREATED",
|
||||
"message": "'cluster3' created."
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
### Delete distinguished names
|
||||
|
||||
Deletes all distinguished names in the specified cluster's or node's allow list.
|
||||
|
||||
#### Request
|
||||
|
||||
```
|
||||
DELETE _plugins/_security/api/nodesdn/<cluster-name>
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "OK",
|
||||
"message": "'cluster3' deleted."
|
||||
}
|
||||
```
|
||||
|
||||
|
||||
---
|
||||
|
||||
## Certificates
|
||||
|
||||
### Get certificates
|
||||
Introduced 1.0
|
||||
{: .label .label-purple }
|
||||
|
||||
Retrieves the cluster's security certificates.
|
||||
|
||||
#### Request
|
||||
|
||||
```
|
||||
GET _opendistro/_security/api/ssl/certs
|
||||
```
|
||||
|
||||
#### Sample response
|
||||
|
||||
```json
|
||||
{
|
||||
"http_certificates_list": [
|
||||
{
|
||||
"issuer_dn": "CN=Example Com Inc. Root CA,OU=Example Com Inc. Root CA,O=Example Com Inc.,DC=example,DC=com",
|
||||
"subject_dn": "CN=node-0.example.com,OU=node,O=node,L=test,DC=de",
|
||||
"san": "[[8, 1.2.3.4.5.5], [2, node-0.example.com]",
|
||||
"not_before": "2018-04-22T03:43:47Z",
|
||||
"not_after": "2028-04-19T03:43:47Z"
|
||||
}
|
||||
],
|
||||
"transport_certificates_list": [
|
||||
{
|
||||
"issuer_dn": "CN=Example Com Inc. Root CA,OU=Example Com Inc. Root CA,O=Example Com Inc.,DC=example,DC=com",
|
||||
"subject_dn": "CN=node-0.example.com,OU=node,O=node,L=test,DC=de",
|
||||
"san": "[[8, 1.2.3.4.5.5], [2, node-0.example.com]",
|
||||
"not_before": "2018-04-22T03:43:47Z",
|
||||
"not_after": "2028-04-19T03:43:47Z"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
---
|
||||
|
||||
## Cache
|
||||
|
||||
### Flush cache
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: Cross-cluster search
|
||||
parent: Access control
|
||||
title: Cross-Cluster Search
|
||||
parent: Access Control
|
||||
nav_order: 40
|
||||
---
|
||||
|
||||
@@ -65,11 +65,11 @@ Save this file as `docker-compose.yml` and run `docker-compose up` to start two
|
||||
```yml
|
||||
version: '3'
|
||||
services:
|
||||
opensearch-ccs-node1:
|
||||
opensearch-node1:
|
||||
image: opensearchproject/opensearch:{{site.opensearch_version}}
|
||||
container_name: opensearch-ccs-node1
|
||||
container_name: opensearch-node1
|
||||
environment:
|
||||
- cluster.name=opensearch-ccs-cluster1
|
||||
- cluster.name=opensearch-cluster1
|
||||
- discovery.type=single-node
|
||||
- bootstrap.memory_lock=true # along with the memlock settings below, disables swapping
|
||||
- "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # minimum and maximum Java heap size, recommend setting both to 50% of system RAM
|
||||
@@ -85,11 +85,11 @@ services:
|
||||
networks:
|
||||
- opensearch-net
|
||||
|
||||
opensearch-ccs-node2:
|
||||
opensearch-node2:
|
||||
image: opensearchproject/opensearch:{{site.opensearch_version}}
|
||||
container_name: opensearch-ccs-node2
|
||||
container_name: opensearch-node2
|
||||
environment:
|
||||
- cluster.name=opensearch-ccs-cluster2
|
||||
- cluster.name=opensearch-cluster2
|
||||
- discovery.type=single-node
|
||||
- bootstrap.memory_lock=true # along with the memlock settings below, disables swapping
|
||||
- "OPENSEARCH_JAVA_OPTS=-Xms512m -Xmx512m" # minimum and maximum Java heap size, recommend setting both to 50% of system RAM
|
||||
@@ -118,26 +118,26 @@ After the clusters start, verify the names of each:
|
||||
```json
|
||||
curl -XGET -u 'admin:admin' -k 'https://localhost:9200'
|
||||
{
|
||||
"cluster_name" : "opensearch-ccs-cluster1",
|
||||
"cluster_name" : "opensearch-cluster1",
|
||||
...
|
||||
}
|
||||
|
||||
curl -XGET -u 'admin:admin' -k 'https://localhost:9250'
|
||||
{
|
||||
"cluster_name" : "opensearch-ccs-cluster2",
|
||||
"cluster_name" : "opensearch-cluster2",
|
||||
...
|
||||
}
|
||||
```
|
||||
|
||||
Both clusters run on `localhost`, so the important identifier is the port number. In this case, use port 9200 (`opensearch-ccs-node1`) as the remote cluster, and port 9250 (`opensearch-ccs-node2`) as the coordinating cluster.
|
||||
Both clusters run on `localhost`, so the important identifier is the port number. In this case, use port 9200 (`opensearch-node1`) as the remote cluster, and port 9250 (`opensearch-node2`) as the coordinating cluster.
|
||||
|
||||
To get the IP address for the remote cluster, first identify its container ID:
|
||||
|
||||
```bash
|
||||
docker ps
|
||||
CONTAINER ID IMAGE PORTS NAMES
|
||||
6fe89ebc5a8e opensearchproject/opensearch:{{site.opensearch_version}} 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp, 9300/tcp opensearch-ccs-node1
|
||||
2da08b6c54d8 opensearchproject/opensearch:{{site.opensearch_version}} 9300/tcp, 0.0.0.0:9250->9200/tcp, 0.0.0.0:9700->9600/tcp opensearch-ccs-node2
|
||||
6fe89ebc5a8e opensearchproject/opensearch:{{site.opensearch_version}} 0.0.0.0:9200->9200/tcp, 0.0.0.0:9600->9600/tcp, 9300/tcp opensearch-node1
|
||||
2da08b6c54d8 opensearchproject/opensearch:{{site.opensearch_version}} 9300/tcp, 0.0.0.0:9250->9200/tcp, 0.0.0.0:9700->9600/tcp opensearch-node2
|
||||
```
|
||||
|
||||
Then get that container's IP address:
|
||||
@@ -154,7 +154,7 @@ curl -k -XPUT -H 'Content-Type: application/json' -u 'admin:admin' 'https://loca
|
||||
{
|
||||
"persistent": {
|
||||
"search.remote": {
|
||||
"opensearch-ccs-cluster1": {
|
||||
"opensearch-cluster1": {
|
||||
"seeds": ["172.31.0.3:9300"]
|
||||
}
|
||||
}
|
||||
@@ -171,11 +171,11 @@ curl -XPUT -k -H 'Content-Type: application/json' -u 'admin:admin' 'https://loca
|
||||
At this point, cross-cluster search works. You can test it using the `admin` user:
|
||||
|
||||
```bash
|
||||
curl -XGET -k -u 'admin:admin' 'https://localhost:9250/opensearch-ccs-cluster1:books/_search?pretty'
|
||||
curl -XGET -k -u 'admin:admin' 'https://localhost:9250/opensearch-cluster1:books/_search?pretty'
|
||||
{
|
||||
...
|
||||
"hits": [{
|
||||
"_index": "opensearch-ccs-cluster1:books",
|
||||
"_index": "opensearch-cluster1:books",
|
||||
"_type": "_doc",
|
||||
"_id": "1",
|
||||
"_score": 1.0,
|
||||
@@ -196,7 +196,7 @@ curl -XPUT -k -u 'admin:admin' 'https://localhost:9250/_plugins/_security/api/in
|
||||
Then run the same search as before with `booksuser`:
|
||||
|
||||
```json
|
||||
curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-ccs-cluster1:books/_search?pretty'
|
||||
curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-cluster1:books/_search?pretty'
|
||||
{
|
||||
"error" : {
|
||||
"root_cause" : [
|
||||
@@ -225,11 +225,11 @@ Both clusters must have the user, but only the remote cluster needs the role and
|
||||
Finally, repeat the search:
|
||||
|
||||
```bash
|
||||
curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-ccs-cluster1:books/_search?pretty'
|
||||
curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-cluster1:books/_search?pretty'
|
||||
{
|
||||
...
|
||||
"hits": [{
|
||||
"_index": "opensearch-ccs-cluster1:books",
|
||||
"_index": "opensearch-cluster1:books",
|
||||
"_type": "_doc",
|
||||
"_id": "1",
|
||||
"_score": 1.0,
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: Default action groups
|
||||
parent: Access control
|
||||
title: Default Action Groups
|
||||
parent: Access Control
|
||||
nav_order: 51
|
||||
---
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: Document-level security
|
||||
parent: Access control
|
||||
title: Document-Level Security
|
||||
parent: Access Control
|
||||
nav_order: 10
|
||||
---
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: Field-level security
|
||||
parent: Access control
|
||||
title: Field-Level Security
|
||||
parent: Access Control
|
||||
nav_order: 11
|
||||
---
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: Field masking
|
||||
parent: Access control
|
||||
title: Field Masking
|
||||
parent: Access Control
|
||||
nav_order: 12
|
||||
---
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: User impersonation
|
||||
parent: Access control
|
||||
title: User Impersonation
|
||||
parent: Access Control
|
||||
nav_order: 20
|
||||
---
|
||||
|
||||
@@ -41,8 +41,8 @@ plugins.security.authcz.impersonation_dn:
|
||||
|
||||
## Impersonating Users
|
||||
|
||||
To impersonate another user, submit a request to the system with the HTTP header `opendistro_security_impersonate_as` set to the name of the user to be impersonated. A good test is to make a GET request to the `_plugins/_security/authinfo` URI:
|
||||
To impersonate another user, submit a request to the system with the HTTP header `opensearch_security_impersonate_as` set to the name of the user to be impersonated. A good test is to make a GET request to the `_plugins/_security/authinfo` URI:
|
||||
|
||||
```bash
|
||||
curl -XGET -u 'admin:admin' -k -H "opendistro_security_impersonate_as: user_1" https://localhost:9200/_plugins/_security/authinfo?pretty
|
||||
curl -XGET -u 'admin:admin' -k -H "opensearch_security_impersonate_as: user_1" https://localhost:9200/_plugins/_security/authinfo?pretty
|
||||
```
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
---
|
||||
layout: default
|
||||
title: Access control
|
||||
title: Access Control
|
||||
nav_order: 10
|
||||
has_children: true
|
||||
has_toc: false
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: OpenSearch Dashboards multi-tenancy
|
||||
parent: Access control
|
||||
title: OpenSearch Dashboards Multi-Tenancy
|
||||
parent: Access Control
|
||||
nav_order: 30
|
||||
---
|
||||
|
||||
@@ -47,21 +47,21 @@ Setting | Description
|
||||
opensearch.username: kibanaserver
|
||||
opensearch.password: kibanaserver
|
||||
opensearch.requestHeadersWhitelist: ["securitytenant","Authorization"]
|
||||
opensearch_security.multitenancy.enabled: true
|
||||
opensearch_security.multitenancy.tenants.enable_global: true
|
||||
opensearch_security.multitenancy.tenants.enable_private: true
|
||||
opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"]
|
||||
opensearch_security.multitenancy.enable_filter: false
|
||||
plugins.security.multitenancy.enabled: true
|
||||
plugins.security.multitenancy.tenants.enable_global: true
|
||||
plugins.security.multitenancy.tenants.enable_private: true
|
||||
plugins.security.multitenancy.tenants.preferred: ["Private", "Global"]
|
||||
plugins.security.multitenancy.enable_filter: false
|
||||
```
|
||||
|
||||
Setting | Description
|
||||
:--- | :---
|
||||
`opensearch.requestHeadersWhitelist` | OpenSearch Dashboards requires that you whitelist all HTTP headers that it passes to OpenSearch. Multi-tenancy uses a specific header, `securitytenant`, that must be present with the standard `Authorization` header. If the `securitytenant` header is not whitelisted, OpenSearch Dashboards starts with a red status.
|
||||
`opensearch_security.multitenancy.enabled` | Enables or disables multi-tenancy in OpenSearch Dashboards. Default is true.
|
||||
`opensearch_security.multitenancy.tenants.enable_global` | Enables or disables the global tenant. Default is true.
|
||||
`opensearch_security.multitenancy.tenants.enable_private` | Enables or disables the private tenant. Default is true.
|
||||
`opensearch_security.multitenancy.tenants.preferred` | Lets you change ordering in the **Tenants** tab of OpenSearch Dashboards. By default, the list starts with global and private (if enabled) and then proceeds alphabetically. You can add tenants here to move them to the top of the list.
|
||||
`opensearch_security.multitenancy.enable_filter` | If you have many tenants, you can add a search bar to the top of the list. Default is false.
|
||||
`plugins.security.multitenancy.enabled` | Enables or disables multi-tenancy in OpenSearch Dashboards. Default is true.
|
||||
`plugins.security.multitenancy.tenants.enable_global` | Enables or disables the global tenant. Default is true.
|
||||
`plugins.security.multitenancy.tenants.enable_private` | Enables or disables the private tenant. Default is true.
|
||||
`plugins.security.multitenancy.tenants.preferred` | Lets you change ordering in the **Tenants** tab of OpenSearch Dashboards. By default, the list starts with global and private (if enabled) and then proceeds alphabetically. You can add tenants here to move them to the top of the list.
|
||||
`plugins.security.multitenancy.enable_filter` | If you have many tenants, you can add a search bar to the top of the list. Default is false.
|
||||
|
||||
|
||||
## Add tenants
|
||||
|
||||
@@ -1,135 +1,64 @@
|
||||
---
|
||||
layout: default
|
||||
title: Permissions
|
||||
parent: Access control
|
||||
parent: Access Control
|
||||
nav_order: 50
|
||||
---
|
||||
|
||||
# Permissions
|
||||
|
||||
Each permission in the security plugin controls access to some action that the OpenSearch cluster can perform, such as indexing a document or checking cluster health.
|
||||
This page is a complete list of available permissions in the security plugin. Each permission controls access to a data type or API.
|
||||
|
||||
Most permissions are self-describing. For example, `cluster:admin/ingest/pipeline/get` lets you retrieve information about ingest pipelines. _In many cases_, a permission correlates to a specific REST API operation, such as `GET _ingest/pipeline`.
|
||||
|
||||
Despite this correlation, permissions do **not** directly map to REST API operations. Operations such as `POST _bulk` and `GET _msearch` can access many indices and perform many actions in a single request. Even a simple request, such as `GET _cat/nodes`, performs several actions in order to generate its response.
|
||||
|
||||
In short, controlling access to the REST API is insufficient. Instead, the security plugin controls access to the underlying OpenSearch actions.
|
||||
|
||||
For example, consider the following `_bulk` request:
|
||||
|
||||
```json
|
||||
POST _bulk
|
||||
{ "delete": { "_index": "test-index", "_id": "tt2229499" } }
|
||||
{ "index": { "_index": "test-index", "_id": "tt1979320" } }
|
||||
{ "title": "Rush", "year": 2013 }
|
||||
{ "create": { "_index": "test-index", "_id": "tt1392214" } }
|
||||
{ "title": "Prisoners", "year": 2013 }
|
||||
{ "update": { "_index": "test-index", "_id": "tt0816711" } }
|
||||
{ "doc" : { "title": "World War Z" } }
|
||||
|
||||
```
|
||||
|
||||
For this request to succeed, you must have the following permissions for `test-index`:
|
||||
|
||||
- indices:data/write/bulk*
|
||||
- indices:data/write/delete
|
||||
- indices:data/write/index
|
||||
- indices:data/write/update
|
||||
|
||||
These permissions also allow you add, update, or delete documents (e.g. `PUT test-index/_doc/tt0816711`), because they govern the underlying OpenSearch actions of indexing and deleting documents rather than a specific API path and HTTP method.
|
||||
|
||||
|
||||
## Test permissions
|
||||
|
||||
If you want a user to have the absolute minimum set of permissions necessary to perform some function---the [principle of least privilege](https://en.wikipedia.org/wiki/Principle_of_least_privilege)----the best way is to send representative requests to your cluster as a new test user. In the case of a permissions error, the security plugin is very explicit about which permissions are missing. Consider this request and response:
|
||||
|
||||
```json
|
||||
GET _cat/shards?v
|
||||
|
||||
{
|
||||
"error": {
|
||||
"root_cause": [{
|
||||
"type": "security_exception",
|
||||
"reason": "no permissions for [indices:monitor/stats] and User [name=test-user, backend_roles=[], requestedTenant=null]"
|
||||
}]
|
||||
},
|
||||
"status": 403
|
||||
}
|
||||
```
|
||||
|
||||
[Create a user and a role]({{site.url}}{{site.baseurl}}/security-plugin/access-control/users-roles/), map the role to the user, and start sending signed requests using curl, Postman, or any other client. Then gradually add permissions to the role as you encounter errors. Even after you resolve one permissions error, the same request might generate new errors; the plugin only returns the first error it encounters, so keep trying until the request succeeds.
|
||||
|
||||
Rather than individual permissions, you can often achieve your desired security posture using a combination of the default action groups. See [Default action groups]({{site.url}}{{site.baseurl}}/security-plugin/access-control/default-action-groups/) for descriptions of the permissions that each group grants.
|
||||
Rather than creating new action groups from individual permissions, you can often achieve your desired security posture using some combination of the default action groups. To learn more, see [Default Action Groups]({{site.url}}{{site.baseurl}}/security-plugin/access-control/default-action-groups/).
|
||||
{: .tip }
|
||||
|
||||
|
||||
## Cluster permissions
|
||||
|
||||
These permissions are for the cluster and can't be applied granularly. For example, you either have permissions to take snapshots (`cluster:admin/snapshot/create`) or you don't. You can't have permissions to take snapshots only for certain indices.
|
||||
## Cluster
|
||||
|
||||
- cluster:admin/ingest/pipeline/delete
|
||||
- cluster:admin/ingest/pipeline/get
|
||||
- cluster:admin/ingest/pipeline/put
|
||||
- cluster:admin/ingest/pipeline/simulate
|
||||
- cluster:admin/ingest/processor/grok/get
|
||||
- cluster:admin/opendistro/ad/detector/delete
|
||||
- cluster:admin/opendistro/ad/detector/info
|
||||
- cluster:admin/opendistro/ad/detector/jobmanagement
|
||||
- cluster:admin/opendistro/ad/detector/preview
|
||||
- cluster:admin/opendistro/ad/detector/run
|
||||
- cluster:admin/opendistro/ad/detector/search
|
||||
- cluster:admin/opendistro/ad/detector/stats
|
||||
- cluster:admin/opendistro/ad/detector/write
|
||||
- cluster:admin/opendistro/ad/detectors/get
|
||||
- cluster:admin/opendistro/ad/result/search
|
||||
- cluster:admin/opendistro/ad/tasks/search
|
||||
- cluster:admin/opendistro/alerting/alerts/ack (acknowledge)
|
||||
- cluster:admin/opendistro/alerting/alerts/get
|
||||
- cluster:admin/opendistro/alerting/destination/delete
|
||||
- cluster:admin/opendistro/alerting/destination/email_account/delete
|
||||
- cluster:admin/opendistro/alerting/destination/email_account/get
|
||||
- cluster:admin/opendistro/alerting/destination/email_account/search
|
||||
- cluster:admin/opendistro/alerting/destination/email_account/write
|
||||
- cluster:admin/opendistro/alerting/destination/email_group/delete
|
||||
- cluster:admin/opendistro/alerting/destination/email_group/get
|
||||
- cluster:admin/opendistro/alerting/destination/email_group/search
|
||||
- cluster:admin/opendistro/alerting/destination/email_group/write
|
||||
- cluster:admin/opendistro/alerting/destination/get
|
||||
- cluster:admin/opendistro/alerting/destination/write
|
||||
- cluster:admin/opendistro/alerting/monitor/delete
|
||||
- cluster:admin/opendistro/alerting/monitor/execute
|
||||
- cluster:admin/opendistro/alerting/monitor/get
|
||||
- cluster:admin/opendistro/alerting/monitor/search
|
||||
- cluster:admin/opendistro/alerting/monitor/write
|
||||
- cluster:admin/opendistro/asynchronous_search/stats
|
||||
- cluster:admin/opendistro/asynchronous_search/delete
|
||||
- cluster:admin/opendistro/asynchronous_search/get
|
||||
- cluster:admin/opendistro/asynchronous_search/submit
|
||||
- cluster:admin/opendistro/ism/managedindex/add
|
||||
- cluster:admin/opendistro/ism/managedindex/change
|
||||
- cluster:admin/opendistro/ism/managedindex/remove
|
||||
- cluster:admin/opendistro/ism/managedindex/explain
|
||||
- cluster:admin/opendistro/ism/managedindex/retry
|
||||
- cluster:admin/opendistro/ism/policy/write
|
||||
- cluster:admin/opendistro/ism/policy/get
|
||||
- cluster:admin/opendistro/ism/policy/search
|
||||
- cluster:admin/opendistro/ism/policy/delete
|
||||
- cluster:admin/opendistro/rollup/index
|
||||
- cluster:admin/opendistro/rollup/get
|
||||
- cluster:admin/opendistro/rollup/search
|
||||
- cluster:admin/opendistro/rollup/delete
|
||||
- cluster:admin/opendistro/rollup/start
|
||||
- cluster:admin/opendistro/rollup/stop
|
||||
- cluster:admin/opendistro/rollup/explain
|
||||
- cluster:admin/opendistro/reports/definition/create
|
||||
- cluster:admin/opendistro/reports/definition/update
|
||||
- cluster:admin/opendistro/reports/definition/on_demand
|
||||
- cluster:admin/opendistro/reports/definition/delete
|
||||
- cluster:admin/opendistro/reports/definition/get
|
||||
- cluster:admin/opendistro/reports/definition/list
|
||||
- cluster:admin/opendistro/reports/instance/list
|
||||
- cluster:admin/opendistro/reports/instance/get
|
||||
- cluster:admin/opendistro/reports/menu/download
|
||||
- cluster:admin/opensearch/ad/detector/delete
|
||||
- cluster:admin/opensearch/ad/detector/jobmanagement
|
||||
- cluster:admin/opensearch/ad/detector/run
|
||||
- cluster:admin/opensearch/ad/detector/search
|
||||
- cluster:admin/opensearch/ad/detector/stats
|
||||
- cluster:admin/opensearch/ad/detector/write
|
||||
- cluster:admin/opensearch/ad/detectors/get
|
||||
- cluster:admin/opensearch/ad/result/search
|
||||
- cluster:admin/opensearch/alerting/alerts/ack
|
||||
- cluster:admin/opensearch/alerting/alerts/get
|
||||
- cluster:admin/opensearch/alerting/destination/delete
|
||||
- cluster:admin/opensearch/alerting/destination/email_account/delete
|
||||
- cluster:admin/opensearch/alerting/destination/email_account/get
|
||||
- cluster:admin/opensearch/alerting/destination/email_account/search
|
||||
- cluster:admin/opensearch/alerting/destination/email_account/write
|
||||
- cluster:admin/opensearch/alerting/destination/email_group/delete
|
||||
- cluster:admin/opensearch/alerting/destination/email_group/get
|
||||
- cluster:admin/opensearch/alerting/destination/email_group/search
|
||||
- cluster:admin/opensearch/alerting/destination/email_group/write
|
||||
- cluster:admin/opensearch/alerting/destination/get
|
||||
- cluster:admin/opensearch/alerting/destination/write
|
||||
- cluster:admin/opensearch/alerting/monitor/delete
|
||||
- cluster:admin/opensearch/alerting/monitor/execute
|
||||
- cluster:admin/opensearch/alerting/monitor/get
|
||||
- cluster:admin/opensearch/alerting/monitor/search
|
||||
- cluster:admin/opensearch/alerting/monitor/write
|
||||
- cluster:admin/opensearch/asynchronous_search/stats
|
||||
- cluster:admin/opensearch/asynchronous_search/delete
|
||||
- cluster:admin/opensearch/asynchronous_search/get
|
||||
- cluster:admin/opensearch/asynchronous_search/submit
|
||||
- cluster:admin/opensearch/reports/definition/create
|
||||
- cluster:admin/opensearch/reports/definition/delete
|
||||
- cluster:admin/opensearch/reports/definition/get
|
||||
- cluster:admin/opensearch/reports/definition/list
|
||||
- cluster:admin/opensearch/reports/definition/on_demand
|
||||
- cluster:admin/opensearch/reports/definition/update
|
||||
- cluster:admin/opensearch/reports/instance/get
|
||||
- cluster:admin/opensearch/reports/instance/list
|
||||
- cluster:admin/opensearch/reports/menu/download
|
||||
- cluster:admin/reindex/rethrottle
|
||||
- cluster:admin/repository/delete
|
||||
- cluster:admin/repository/get
|
||||
@@ -165,9 +94,7 @@ These permissions are for the cluster and can't be applied granularly. For examp
|
||||
- cluster:monitor/tasks/list
|
||||
|
||||
|
||||
## Index permissions
|
||||
|
||||
These permissions apply to an index or index pattern. You might want a user to have read access to all indices (i.e. `*`), but write access to only a few (e.g. `web-logs` and `product-catalog`).
|
||||
## Indices
|
||||
|
||||
- indices:admin/aliases
|
||||
- indices:admin/aliases/exists
|
||||
@@ -175,22 +102,13 @@ These permissions apply to an index or index pattern. You might want a user to h
|
||||
- indices:admin/analyze
|
||||
- indices:admin/cache/clear
|
||||
- indices:admin/close
|
||||
- indices:admin/close*
|
||||
- indices:admin/create (create indices)
|
||||
- indices:admin/data_stream/create
|
||||
- indices:admin/data_stream/delete
|
||||
- indices:admin/data_stream/get
|
||||
- indices:admin/delete (delete indices)
|
||||
- indices:admin/create
|
||||
- indices:admin/delete
|
||||
- indices:admin/exists
|
||||
- indices:admin/flush
|
||||
- indices:admin/flush*
|
||||
- indices:admin/forcemerge
|
||||
- indices:admin/get (retrieve index and mapping)
|
||||
- indices:admin/index_template/delete
|
||||
- indices:admin/index_template/get
|
||||
- indices:admin/index_template/put
|
||||
- indices:admin/index_template/simulate
|
||||
- indices:admin/index_template/simulate_index
|
||||
- indices:admin/get
|
||||
- indices:admin/mapping/put
|
||||
- indices:admin/mappings/fields/get
|
||||
- indices:admin/mappings/fields/get*
|
||||
@@ -219,23 +137,22 @@ These permissions apply to an index or index pattern. You might want a user to h
|
||||
- indices:data/read/mget*
|
||||
- indices:data/read/msearch
|
||||
- indices:data/read/msearch/template
|
||||
- indices:data/read/mtv (multi-term vectors)
|
||||
- indices:data/read/mtv
|
||||
- indices:data/read/mtv*
|
||||
- indices:data/read/scroll
|
||||
- indices:data/read/scroll/clear
|
||||
- indices:data/read/search
|
||||
- indices:data/read/search*
|
||||
- indices:data/read/search/template
|
||||
- indices:data/read/tv (term vectors)
|
||||
- indices:data/read/tv
|
||||
- indices:data/write/bulk
|
||||
- indices:data/write/bulk*
|
||||
- indices:data/write/delete (delete documents)
|
||||
- indices:data/write/delete
|
||||
- indices:data/write/delete/byquery
|
||||
- indices:data/write/index (add documents to existing indices)
|
||||
- indices:data/write/index
|
||||
- indices:data/write/reindex
|
||||
- indices:data/write/update
|
||||
- indices:data/write/update/byquery
|
||||
- indices:monitor/data_stream/stats
|
||||
- indices:monitor/recovery
|
||||
- indices:monitor/segments
|
||||
- indices:monitor/settings/get
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
---
|
||||
layout: default
|
||||
title: Users and roles
|
||||
parent: Access control
|
||||
title: Users and Roles
|
||||
parent: Access Control
|
||||
nav_order: 1
|
||||
---
|
||||
|
||||
@@ -109,7 +109,7 @@ Role | Description
|
||||
`anomaly_full_access` | Grants full permissions to all anomaly detection actions.
|
||||
`anomaly_read_access` | Grants permissions to view detectors, but not create, modify, or delete detectors.
|
||||
`all_access` | Grants full access to the cluster: all cluster-wide operations, write to all indices, write to all tenants.
|
||||
`kibana_read_only` | A special role that prevents users from making changes to visualizations, dashboards, and other OpenSearch Dashboards objects. See `opensearch_security.readonly_mode.roles` in `opensearch_dashboards.yml`. Pair with the `kibana_user` role.
|
||||
`kibana_read_only` | A special role that prevents users from making changes to visualizations, dashboards, and other OpenSearch Dashboards objects. See `plugins.security.readonly_mode.roles` in `opensearch_dashboards.yml`. Pair with the `kibana_user` role.
|
||||
`kibana_user` | Grants permissions to use OpenSearch Dashboards: cluster-wide searches, index monitoring, and write to various OpenSearch Dashboards indices.
|
||||
`logstash` | Grants permissions for Logstash to interact with the cluster: cluster-wide searches, cluster monitoring, and write to the various Logstash indices.
|
||||
`manage_snapshots` | Grants permissions to manage snapshot repositories, take snapshots, and restore snapshots.
|
||||
|
||||
@@ -42,10 +42,10 @@ You can optionally add the `-aes256` option to encrypt the key using the AES-256
|
||||
Next, use the key to generate a self-signed certificate for the root CA:
|
||||
|
||||
```bash
|
||||
openssl req -new -x509 -sha256 -key root-ca-key.pem -out root-ca.pem -days 730
|
||||
openssl req -new -x509 -sha256 -key root-ca-key.pem -out root-ca.pem -days 30
|
||||
```
|
||||
|
||||
The default `-days` value of 30 is only useful for testing purposes. This sample command specifies 730 (two years) for the certificate expiration date, but use whatever value makes sense for your organization.
|
||||
Change `-days 30` to 3650 (10 years) or some other number to set a non-default expiration date. The default value of 30 days is best for testing purposes.
|
||||
|
||||
- The `-x509` option specifies that you want a self-signed certificate rather than a certificate request.
|
||||
- The `-sha256` option sets the hash algorithm to SHA-256. SHA-256 is the default in later versions of OpenSSL, but earlier versions might use SHA-1.
|
||||
@@ -78,7 +78,7 @@ Follow the prompts to fill in the details. You don't need to specify a challenge
|
||||
Finally, generate the certificate itself:
|
||||
|
||||
```bash
|
||||
openssl x509 -req -in admin.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out admin.pem -days 730
|
||||
openssl x509 -req -in admin.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out admin.pem -days 30
|
||||
```
|
||||
|
||||
Just like the root certificate, use the `-days` option to specify an expiration date of longer than 30 days.
|
||||
@@ -91,7 +91,7 @@ Follow the steps in [Generate an admin certificate](#generate-an-admin-certifica
|
||||
If you generate node certificates and have `plugins.security.ssl.transport.enforce_hostname_verification` set to `true` (default), be sure to specify a common name (CN) for the certificate that matches the hostname of the intended node. If you want to use the same node certificate on all nodes (not recommended), set hostname verification to `false`. For more information, see [Configure TLS certificates]({{site.url}}{{site.baseurl}}/security-plugin/configuration/tls#advanced-hostname-verification-and-dns-lookup).
|
||||
|
||||
|
||||
## Sample script
|
||||
### Sample script
|
||||
|
||||
If you already know the certificate details and don't want to specify them interactively, use the `-subj` option in your `root-ca.pem` and CSR commands. This script creates a root certificate, admin certificate, two node certificates, and a client certificate, all with an expiration dates of two years (730 days):
|
||||
|
||||
|
||||
@@ -11,6 +11,7 @@ Active Directory and LDAP can be used for both authentication and authorization
|
||||
|
||||
In most cases, you want to configure both authentication and authorization. You can also use authentication only and map the users retrieved from LDAP directly to security plugin roles.
|
||||
|
||||
{% comment %}
|
||||
|
||||
## Docker example
|
||||
|
||||
@@ -37,7 +38,7 @@ We provide a fully functional example that can help you understand how to use an
|
||||
1. Index a document as `psantos`:
|
||||
|
||||
```bash
|
||||
curl -XPUT 'https://localhost:9200/new-index/_doc/1' -H 'Content-Type: application/json' -d '{"title": "Spirited Away"}' -u 'psantos:password' -k
|
||||
curl -XPUT https://localhost:9200/new-index/_doc/1 -H 'Content-Type: application/json' -d '{"title": "Spirited Away"}' -u psantos:password -k
|
||||
```
|
||||
|
||||
If you try the same request as `jroe`, it fails. The `Developers` group is mapped to the `readall`, `manage_snapshots`, and `kibana_user` roles and has no write permissions.
|
||||
@@ -45,13 +46,14 @@ We provide a fully functional example that can help you understand how to use an
|
||||
1. Search for the document as `jroe`:
|
||||
|
||||
```bash
|
||||
curl -XGET 'https://localhost:9200/new-index/_search?pretty' -u 'jroe:password' -k
|
||||
curl -XGET https://localhost:9200/new-index/_search?pretty -u jroe:password -k
|
||||
```
|
||||
|
||||
This request succeeds, because the `Developers` group is mapped to the `readall` role.
|
||||
|
||||
1. If you want to examine the contents of the various containers, run `docker ps` to find the container ID and then `docker exec -it <container-id> /bin/bash`.
|
||||
|
||||
{% endcomment %}
|
||||
|
||||
## Connection settings
|
||||
|
||||
|
||||
@@ -11,6 +11,7 @@ The security plugin supports user authentication through SAML single sign-on. Th
|
||||
|
||||
This profile is meant for use with web browsers. It is not a general-purpose way of authenticating users against the security plugin, so its primary use case is to support OpenSearch Dashboards single sign-on.
|
||||
|
||||
{% comment %}
|
||||
|
||||
## Docker example
|
||||
|
||||
@@ -34,6 +35,7 @@ We provide a fully functional example that can help you understand how to use SA
|
||||
|
||||
In particular, you might find it helpful to review the contents of the `/var/www/simplesamlphp/config/` and `/var/www/simplesamlphp/metadata/` directories.
|
||||
|
||||
{% endcomment %}
|
||||
|
||||
## Activating SAML
|
||||
|
||||
@@ -298,13 +300,13 @@ authc:
|
||||
|
||||
Because most of the SAML-specific configuration is done in the security plugin, just activate SAML in your `opensearch_dashboards.yml` by adding the following:
|
||||
|
||||
```yml
|
||||
opensearch_security.auth.type: "saml"
|
||||
```
|
||||
plugins.security.auth.type: "saml"
|
||||
```
|
||||
|
||||
In addition, the OpenSearch Dashboards endpoint for validating the SAML assertions must be whitelisted:
|
||||
|
||||
```yml
|
||||
```
|
||||
server.xsrf.whitelist: ["/_plugins/_security/saml/acs"]
|
||||
```
|
||||
|
||||
|
||||
@@ -126,7 +126,7 @@ plugins.security.restapi.password_validation_error_message: "Password must be mi
|
||||
|
||||
## whitelist.yml
|
||||
|
||||
You can use `whitelist.yml` to add any endpoints and HTTP requests to a list of allowed endpoints and requests. If enabled, all users except the super admin are allowed access to only the specified endpoints and HTTP requests, and all other HTTP requests associated with the endpoint are denied. For example, if GET `_cluster/settings` is added to the allow list, users cannot submit PUT requests to `_cluster/settings` to update cluster settings.
|
||||
You can use `whitelist.yml` to allow list any endpoints and HTTP requests. If enabled, all users except the SuperAdmin are allowed access to only the specified endpoints and HTTP requests, and all other HTTP requests associated with the endpoint are denied. For example, if GET `_cluster/settings` is allow listed, users cannot submit PUT requests to `_cluster/settings` to update cluster settings.
|
||||
|
||||
Note that while you can configure access to endpoints this way, for most cases, it is still best to configure permissions using the security plugin's users and roles, which have more granular settings.
|
||||
|
||||
@@ -165,7 +165,7 @@ requests:
|
||||
- PUT
|
||||
```
|
||||
|
||||
You can also add custom indices to the allow list. `whitelist.yml` doesn't support wildcards, so you must manually specify all of the indices you want to add.
|
||||
You can also allow list custom indices. `whitelist.yml` doesn't support wildcards, so you must manually specify all of the indices you want to allow list.
|
||||
|
||||
```yml
|
||||
requests: # Only allow GET requests to /sample-index1/_doc/1 and /sample-index2/_doc/1
|
||||
@@ -315,10 +315,6 @@ _meta:
|
||||
|
||||
## tenants.yml
|
||||
|
||||
You can use this file to specify and add any number of OpenSearch Dashboards tenants to your OpenSearch cluster. For more information about tenants, see [OpenSearch Dashboards multi-tenancy]({{site.url}}{{site.baseurl}}/security-plugin/access-control/multi-tenancy).
|
||||
|
||||
Like all of the other YAML files, we recommend you use `tenants.yml` to add any tenants you must have in your cluster, and then use OpenSearch Dashboards or the [REST API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#tenants) if you need to further configure or create any other tenants.
|
||||
|
||||
```yml
|
||||
---
|
||||
_meta:
|
||||
@@ -329,12 +325,9 @@ admin_tenant:
|
||||
description: "Demo tenant for admin user"
|
||||
```
|
||||
|
||||
|
||||
## nodes_dn.yml
|
||||
|
||||
`nodes_dn.yml` lets you add certificates' [distinguished names (DNs)]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml) an allow list to enable communication between any number of nodes and/or clusters. For example, a node that has the DN `CN=node1.example.com` in its allow list accepts communication from any other node or certificate that uses that DN.
|
||||
|
||||
The DNs get indexed into a [system index]({{site.url}}{{site.baseurl}}/security-plugin/configuration/system-indices) that only a super admin or an admin with a Transport Layer Security (TLS) certificate can access. If you want to programmatically add DNs to your allow lists, use the [REST API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#distinguished-names).
|
||||
|
||||
```yml
|
||||
---
|
||||
_meta:
|
||||
|
||||
+10
-21
@@ -11,32 +11,16 @@ redirect_from: /troubleshoot/
|
||||
This page contains a list of common issues and workarounds.
|
||||
|
||||
|
||||
## Java error during startup
|
||||
|
||||
You might see `[ERROR][c.a.o.s.s.t.OpenSearchSecuritySSLNettyTransport] [opensearch-node1] SSL Problem Insufficient buffer remaining for AEAD cipher fragment (2). Needs to be more than tag size (16)` when starting OpenSearch. This problem is a [known issue with Java](https://bugs.openjdk.java.net/browse/JDK-8221218) and doesn't affect the operation of the cluster.
|
||||
|
||||
|
||||
## OpenSearch Dashboards fails to start
|
||||
|
||||
If you encounter the error `FATAL Error: Request Timeout after 30000ms` during startup, try running OpenSearch Dashboards on a more powerful machine. We recommend four CPU cores and 8 GB of RAM.
|
||||
|
||||
|
||||
## Multi-tenancy issues in OpenSearch Dashboards
|
||||
|
||||
If you're testing multiple users in OpenSearch Dashboards and encounter unexpected changes in tenant, use Google Chrome in an Incognito window or Firefox in a Private window.
|
||||
|
||||
|
||||
## Expired certificates
|
||||
|
||||
If your certificates have expired, you might receive the following error or something similar:
|
||||
|
||||
```
|
||||
ERROR org.opensearch.security.ssl.transport.SecuritySSLNettyTransport - Exception during establishing a SSL connection: javax.net.ssl.SSLHandshakeException: PKIX path validation failed: java.security.cert.CertPathValidatorException: validity check failed
|
||||
Caused by: java.security.cert.CertificateExpiredException: NotAfter: Thu Sep 16 11:27:55 PDT 2021
|
||||
```
|
||||
|
||||
To check the expiration date for a certificate, run this command:
|
||||
|
||||
```bash
|
||||
openssl x509 -enddate -noout -in <certificate>
|
||||
```
|
||||
|
||||
|
||||
## Encryption at rest
|
||||
|
||||
The operating system for each OpenSearch node handles encryption of data at rest. To enable encryption at rest in most Linux distributions, use the `cryptsetup` command:
|
||||
@@ -101,3 +85,8 @@ The security plugin blocks the update by script operation (`POST <index>/_update
|
||||
## Illegal reflective access operation in logs
|
||||
|
||||
This is a known issue with Performance Analyzer that shouldn't affect functionality.
|
||||
|
||||
|
||||
## Multi-tenancy issues in OpenSearch Dashboards
|
||||
|
||||
If you're testing multiple users in OpenSearch Dashboards and encounter unexpected changes in tenant, use Google Chrome in an Incognito window or Firefox in a Private window.
|
||||
|
||||
@@ -144,12 +144,6 @@ If you are upgrading an Open Distro for Elasticsearch cluster, we recommend firs
|
||||
|
||||
1. Port your settings from `elasticsearch.yml` to `opensearch.yml`. Most settings use the same names. At a minimum, specify `cluster.name`, `node.name`, `discovery.seed_hosts`, and `cluster.initial_master_nodes`.
|
||||
|
||||
1. (Optional) If you're actively connecting to the cluster with legacy clients that check for a particular version number, such as Logstash OSS, add a [compatibility setting]({{site.url}}{{site.baseurl}}/clients/agents-and-ingestion-tools/) to `opensearch.yml`:
|
||||
|
||||
```yml
|
||||
compatibility.override_main_response_version: true
|
||||
```
|
||||
|
||||
1. (Optional) Add your certificates to your `config` directory, add them to `opensearch.yml`, and initialize the security plugin.
|
||||
|
||||
1. Start OpenSearch on the node (rolling) or all nodes (cluster restart).
|
||||
|
||||
Binary file not shown.
Binary file not shown.
@@ -37,7 +37,7 @@ Component | Purpose
|
||||
[Anomaly Detection]({{site.url}}{{site.baseurl}}/monitoring-plugins/ad/) | Identify atypical data and receive automatic notifications
|
||||
[Asynchronous Search]({{site.url}}{{site.baseurl}}/search-plugins/async/) | Run search requests in the background
|
||||
|
||||
Most OpenSearch plugins have corresponding OpenSearch Dashboards plugins that provide a convenient, unified user interface.
|
||||
Most of OpenSearch plugins have a corresponding OpenSearch Dashboards plugin that provide a convenient, unified user interface.
|
||||
|
||||
For specifics around the project, see the [FAQ](https://opensearch.org/faq/).
|
||||
|
||||
|
||||
Reference in New Issue
Block a user