From 0bf8624824ed4954e2ad3eda2464552c5aab3c5e Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 19 Aug 2021 12:56:53 -0700 Subject: [PATCH 01/60] Getting started content for Python --- _clients/java-rest-high-level.md | 2 +- _clients/python.md | 122 +++++++++++++++++++++++++++++++ 2 files changed, 123 insertions(+), 1 deletion(-) create mode 100644 _clients/python.md diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index 1dcf1563..3f7260cf 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -1,7 +1,7 @@ --- layout: default title: Java high-level REST client -nav_order: 97 +nav_order: 60 --- # Java high-level REST client diff --git a/_clients/python.md b/_clients/python.md new file mode 100644 index 00000000..1a5bf9b0 --- /dev/null +++ b/_clients/python.md @@ -0,0 +1,122 @@ +--- +layout: default +title: Python client +nav_order: 70 +--- + +# Python client + +The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. + + +## Setup + +To add the client to your project, install it using pip: + +```bash +pip install +``` + +Then import it like any other module: + +```python +from opensearch import OpenSearch +``` + + +## Sample code + +```python +from opensearch import OpenSearch + +host = 'localhost' +port = 9200 +auth = ('admin', 'admin') # For testing only. Don't store credentials in code. +ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA + +# Optional client certificates if you don't want to use HTTP basic authentication. +# client_cert_path = '/full/path/to/client.pem' +# client_key_path = '/full/path/to/client-key.pem' + +# Create the client with SSL/TLS enabled, but hostname verification disabled. +client = OpenSearch( + hosts = [{'host': host, 'port': port}], + http_compress=True, # enables gzip compression for request bodies + http_auth = auth, + # client_cert = client_cert_path, + # client_key = client_key_path, + use_ssl = True, + verify_certs = True, + ssl_assert_hostname = False, + ssl_show_warn = False, + ca_certs = ca_certs_path +) + +# Create an index with non-default settings. +index_name = 'python-test-index3' +index_body = { + 'settings': { + 'index': { + 'number_of_shards': 4 + } + } +} + +response = client.indices.create(index_name, body=index_body) +print('\nCreating index:') +print(response) + +# Add a document to the index. +document = { + 'title': 'Moneyball', + 'director': 'Bennett Miller', + 'year': '2011' +} +id = '1' + +response = client.index( + index=index_name, + body=document, + id=id, + refresh=True +) + +print('\nAdding document:') +print(response) + +# Search for the document. +q = 'miller' +query = { + 'size': 5, + 'query': { + 'multi_match': { + 'query': q, + 'fields': ['title^2', 'director'] + } + } +} + +response = client.search( + body=query, + index=index_name +) +print('\nSearch results:') +print(response) + +# Delete the document. +response = client.delete( + index=index_name, + id=id +) + +print('\nDeleting document:') +print(response) + +# Delete the index. +response = client.indices.delete( + index=index_name +) + +print('\nDeleting index:') +print(response) +``` From 9ce5d95786a3baf50be225cdf6c44a3943ff2988 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 19 Aug 2021 13:23:14 -0700 Subject: [PATCH 02/60] Clean up spacing --- _clients/python.md | 22 +++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/_clients/python.md b/_clients/python.md index 1a5bf9b0..0a44cfa9 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -32,7 +32,7 @@ from opensearch import OpenSearch host = 'localhost' port = 9200 auth = ('admin', 'admin') # For testing only. Don't store credentials in code. -ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA +ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA. # Optional client certificates if you don't want to use HTTP basic authentication. # client_cert_path = '/full/path/to/client.pem' @@ -41,7 +41,7 @@ ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use int # Create the client with SSL/TLS enabled, but hostname verification disabled. client = OpenSearch( hosts = [{'host': host, 'port': port}], - http_compress=True, # enables gzip compression for request bodies + http_compress = True, # enables gzip compression for request bodies http_auth = auth, # client_cert = client_cert_path, # client_key = client_key_path, @@ -75,10 +75,10 @@ document = { id = '1' response = client.index( - index=index_name, - body=document, - id=id, - refresh=True + index = index_name, + body = document, + id = id, + refresh = True ) print('\nAdding document:') @@ -97,16 +97,16 @@ query = { } response = client.search( - body=query, - index=index_name + body = query, + index = index_name ) print('\nSearch results:') print(response) # Delete the document. response = client.delete( - index=index_name, - id=id + index = index_name, + id = id ) print('\nDeleting document:') @@ -114,7 +114,7 @@ print(response) # Delete the index. response = client.indices.delete( - index=index_name + index = index_name ) print('\nDeleting index:') From 30facfe628124b75cf17d44c90e946a20b1ce8ca Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 19 Aug 2021 14:38:30 -0700 Subject: [PATCH 03/60] Typo --- _clients/python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/python.md b/_clients/python.md index 0a44cfa9..879513ce 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -6,7 +6,7 @@ nav_order: 70 # Python client -The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. +The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests with raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. ## Setup From 12ce7e5fea5c7c5499da834b36b2617afff79c30 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Wed, 25 Aug 2021 11:05:24 -0700 Subject: [PATCH 04/60] rough draft --- _clients/go.md | 93 ++++++++++++++++++++++++++++++++ _clients/java-rest-high-level.md | 2 +- 2 files changed, 94 insertions(+), 1 deletion(-) create mode 100644 _clients/go.md diff --git a/_clients/go.md b/_clients/go.md new file mode 100644 index 00000000..4273d8b9 --- /dev/null +++ b/_clients/go.md @@ -0,0 +1,93 @@ +--- +layout: default +title: Go client +nav_order: 80 +--- + +# Go client + +<> + +## Setup + +To add the client to your project, import it like any other module: + +```go +go mod init +go get github.com/opensearch-project/opensearch-go +``` + +### Sample response + +```go +go: downloading github.com/opensearch-project/opensearch-go v0.0.0-20210823214927-3567f157dece +go get: added github.com/opensearch-project/opensearch-go v0.0.0-20210823214927-3567f157dece +``` + +## Sample code + +Create a new file called main.go: + + +```go +package main + +import ( + "crypto/tls" + "fmt" + "github.com/opensearch-project/opensearch-go" + "log" + "net/http" +) + +func main () { + // Instantiate a new OpenSearch client object instance + + client, err := opensearch.NewClient(opensearch.Config{ + Transport: &http.Transport{ + TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, + }, + Addresses: []string{"https://localhost:9200"}, + Username: "admin", // For testing only. Don't store credentials in code. + Password: "admin", + }) + +// ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA. Optional client certificates if you don't want to use HTTP basic authentication. +// client_cert_path = '/full/path/to/client.pem' +// client_key_path = '/full/path/to/client-key.pem' + + if err != nil { + fmt.Println("cannot initialize", err) + } + +// Have the client instance return a response + + log.Println(client.Info()) +} +``` + +```go +$ go run main.go + +2021/08/24 23:56:05 [200 OK] { + "name" : "c825aab1d9cc", + "cluster_name" : "docker-cluster", + "cluster_uuid" : "jsIDR0FTR5qXZr4XkZ-GlA", + "version" : { + "distribution" : "opensearch", + "number" : "1.0.0", + "build_type" : "tar", + "build_hash" : "34550c5b17124ddc59458ef774f6b43a086522e3", + "build_date" : "2021-07-02T23:22:21.383695Z", + "build_snapshot" : false, + "lucene_version" : "8.8.2", + "minimum_wire_compatibility_version" : "6.8.0", + "minimum_index_compatibility_version" : "6.0.0-beta1" + }, + "tagline" : "The OpenSearch Project: https://opensearch.org/" +} + +``` + +For all APIs - +https://github.com/opensearch-project/opensearch-go/tree/main/opensearchapi diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index a9ed5945..def97086 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -1,7 +1,7 @@ --- layout: default title: Java high-level REST client -nav_order: 97 +nav_order: 60 --- # Java high-level REST client From ac9acb3c62287e1403fc0ad7c29cf28c1ddaee8e Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 26 Aug 2021 09:15:50 -0700 Subject: [PATCH 05/60] Adds some statements around compatibility Should (hopefully) apply to all clients. --- _clients/index.md | 14 +++++++++++++- _clients/python.md | 2 ++ 2 files changed, 15 insertions(+), 1 deletion(-) diff --git a/_clients/index.md b/_clients/index.md index bdf2bf05..3880a3bb 100644 --- a/_clients/index.md +++ b/_clients/index.md @@ -9,6 +9,18 @@ redirect_from: # OpenSearch client compatibility +OpenSearch provides clients for several popular programming languages, with more coming. In general, clients are compatible with clusters running the same major version of OpenSearch (`major.minor.patch`). + +For example, a 1.0.0 client works with an OpenSearch 1.1.0 cluster, but might not support any non-breaking API changes in OpenSearch 1.1.0. A 1.2.0 client works with the same cluster, but might allow you to pass unsupported options in certain functions. We recommend using the same version for both, but if your tests pass after a cluster upgrade, you don't necessarily need to upgrade your clients immediately. + +* [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/) +* [OpenSearch Python client]({{site.url}}{{site.baseurl}}/clients/python/) +* [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/nodejs/) +* [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/golang/) + + +## Legacy clients + Most clients that work with Elasticsearch OSS 7.10.2 *should* work with OpenSearch, but the latest versions of those clients might include license or version checks that artificially break compatibility. This page includes recommendations around which versions of those clients to use for best compatibility with OpenSearch. Client | Recommended version @@ -18,7 +30,7 @@ Client | Recommended version [Python Elasticsearch client](https://pypi.org/project/elasticsearch/7.13.4/) | 7.13.4 [Elasticsearch Node.js client](https://www.npmjs.com/package/@elastic/elasticsearch/v/7.13.0) | 7.13.0 -Clients exist for a wide variety of languages, so if you test a client and verify that it works, please [submit a PR](https://github.com/opensearch-project/documentation-website/pulls) and add it to this table. +If you test a legacy client and verify that it works, please [submit a PR](https://github.com/opensearch-project/documentation-website/pulls) and add it to this table. {% comment %} diff --git a/_clients/python.md b/_clients/python.md index 879513ce..f2abffe5 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -23,6 +23,8 @@ Then import it like any other module: from opensearch import OpenSearch ``` +If you prefer to add the client manually or just want to examine the source code, see [opensearch-py on GitHub](https://github.com/opensearch-project/opensearch-py). + ## Sample code From 9a2e6ed0284c65bf0ac2620feba7d8dc4d15c3b4 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Thu, 26 Aug 2021 11:33:21 -0700 Subject: [PATCH 06/60] spacing --- _clients/go.md | 132 ++++++++++++++++++++++++++++++------------------- 1 file changed, 82 insertions(+), 50 deletions(-) diff --git a/_clients/go.md b/_clients/go.md index 4273d8b9..d9bc751a 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -6,7 +6,8 @@ nav_order: 80 # Go client -<> +The OpenSearch Go client lets you programmatically interact with data in your OpenSearch cluster as part of your Go application. + ## Setup @@ -17,77 +18,108 @@ go mod init go get github.com/opensearch-project/opensearch-go ``` -### Sample response - -```go -go: downloading github.com/opensearch-project/opensearch-go v0.0.0-20210823214927-3567f157dece -go get: added github.com/opensearch-project/opensearch-go v0.0.0-20210823214927-3567f157dece -``` - ## Sample code -Create a new file called main.go: - - ```go package main import ( + "context" "crypto/tls" "fmt" - "github.com/opensearch-project/opensearch-go" - "log" + opensearch "github.com/opensearch-project/opensearch-go" + opensearchapi "github.com/opensearch-project/opensearch-go/opensearchapi" "net/http" + "strings" ) -func main () { - // Instantiate a new OpenSearch client object instance +const IndexName = "go-test-index1" +func main() { + + // Initialize the client with SSL/TLS enabled. client, err := opensearch.NewClient(opensearch.Config{ Transport: &http.Transport{ TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, }, Addresses: []string{"https://localhost:9200"}, - Username: "admin", // For testing only. Don't store credentials in code. - Password: "admin", + Username: "admin", // For testing only. Don't store credentials in code. + Password: "admin", }) - -// ca_certs_path = '/full/path/to/root-ca.pem' # Provide a CA bundle if you use intermediate CAs with your root CA. Optional client certificates if you don't want to use HTTP basic authentication. -// client_cert_path = '/full/path/to/client.pem' -// client_key_path = '/full/path/to/client-key.pem' - if err != nil { fmt.Println("cannot initialize", err) } -// Have the client instance return a response - + // Print OpenSearch version information. log.Println(client.Info()) + + // Define a mapping. + mapping := strings.NewReader(`{ + 'settings': { + 'index': { + 'number_of_shards': 4 + } + } + }`) + + // Create an index with non-default settings. + res := opensearchapi.CreateRequest{ + Index: IndexName, + Body: mapping, + } + fmt.Println("creating index", res) + + // Add a document to the index. + document := strings.NewReader(`{ + "title": "Moneyball", + "director": "Bennett Miller", + "year": "2011" + }`) + + docId := "1" + req := opensearchapi.IndexRequest{ + Index: IndexName, + DocumentID: docId, + Body: document, + } + insertResponse, err := req.Do(context.Background(), client) + fmt.Println(insertResponse) + + // Search for the document. + content := strings.NewReader(`{ + "size": 5, + "query": { + "multi_match": { + "query": "miller", + "fields": ["title^2", "director"] + } + } + }`) + + search := opensearchapi.SearchRequest{ + Body: content, + } + + searchResponse, err := search.Do(context.Background(), client) + fmt.Println(searchResponse) + + // Delete the document. + delete := opensearchapi.DeleteRequest{ + Index: IndexName, + DocumentID: docId, + } + + deleteResponse, err := delete.Do(context.Background(), client) + fmt.Println("deleting document") + fmt.Println(deleteResponse) + + // Delete the index. + deleteIndex := opensearchapi.IndicesDeleteRequest{ + Index: []string{IndexName}, + } + + deleteIndexResponse, err := deleteIndex.Do(context.Background(), client) + fmt.Println("deleting index") + fmt.Println(deleteIndexResponse) } ``` - -```go -$ go run main.go - -2021/08/24 23:56:05 [200 OK] { - "name" : "c825aab1d9cc", - "cluster_name" : "docker-cluster", - "cluster_uuid" : "jsIDR0FTR5qXZr4XkZ-GlA", - "version" : { - "distribution" : "opensearch", - "number" : "1.0.0", - "build_type" : "tar", - "build_hash" : "34550c5b17124ddc59458ef774f6b43a086522e3", - "build_date" : "2021-07-02T23:22:21.383695Z", - "build_snapshot" : false, - "lucene_version" : "8.8.2", - "minimum_wire_compatibility_version" : "6.8.0", - "minimum_index_compatibility_version" : "6.0.0-beta1" - }, - "tagline" : "The OpenSearch Project: https://opensearch.org/" -} - -``` - -For all APIs - -https://github.com/opensearch-project/opensearch-go/tree/main/opensearchapi From bfc56f2f7fbf9cf97910483bddb9ca0286b640bc Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Thu, 26 Aug 2021 11:39:32 -0700 Subject: [PATCH 07/60] incorporated feedback --- _clients/go.md | 7 ++++++- 1 file changed, 6 insertions(+), 1 deletion(-) diff --git a/_clients/go.md b/_clients/go.md index d9bc751a..37c89e94 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -11,10 +11,15 @@ The OpenSearch Go client lets you programmatically interact with data in your Op ## Setup -To add the client to your project, import it like any other module: +If you're creating a new project: ```go go mod init +``` + +To add the client to your project, import it like any other module: + +```go go get github.com/opensearch-project/opensearch-go ``` From 1c4f81eb53185387b27afdd961b32739475a9478 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Thu, 26 Aug 2021 11:41:09 -0700 Subject: [PATCH 08/60] minor fix --- _clients/go.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_clients/go.md b/_clients/go.md index 37c89e94..e77fc0dd 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -55,8 +55,8 @@ func main() { fmt.Println("cannot initialize", err) } - // Print OpenSearch version information. - log.Println(client.Info()) + // Print OpenSearch version information on console. + fmt.Println(client.Info()) // Define a mapping. mapping := strings.NewReader(`{ From c9728698934f57a36278d85314ab647407c06f90 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 26 Aug 2021 11:50:46 -0700 Subject: [PATCH 09/60] Link to pip, because why not --- _clients/python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/python.md b/_clients/python.md index f2abffe5..cdc7dc29 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -11,7 +11,7 @@ The OpenSearch Python client provides a more natural syntax for interacting with ## Setup -To add the client to your project, install it using pip: +To add the client to your project, install it using [pip](https://pip.pypa.io/): ```bash pip install From cea3ba7ce9450617dac23521bd1f2277931d89dd Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Thu, 26 Aug 2021 12:44:58 -0700 Subject: [PATCH 10/60] Getting started docs for javascript --- _clients/javascript.md | 141 +++++++++++++++++++++++++++++++++++++++++ 1 file changed, 141 insertions(+) create mode 100644 _clients/javascript.md diff --git a/_clients/javascript.md b/_clients/javascript.md new file mode 100644 index 00000000..60c1cba1 --- /dev/null +++ b/_clients/javascript.md @@ -0,0 +1,141 @@ +--- +layout: default +title: Javascript client +nav_order: 80 +--- + +# Javascript client + +The OpenSearch Javascript client provides a safer and easier way to interact with your OpenSearch cluster. Rather than using OpenSearch from the browser and potentially exposing your data to the public, you can build an OpenSearch client that takes care of sending requests to your cluster. + +The client contains a library of APIs that let you perform different operations on your cluster and return a standard response body. The example here demonstrates some basic operations like creating an index, adding documents, and searching your data. + + +## Setup + +To add the client to your project, install it from npm: + +```bash +npm install @opensearch/opensearch +``` + +If you prefer to add the client manually or just want to examine the source code, see [opensearch-js](https://github.com/opensearch-project/opensearch-js) on GitHub. + +Then require the client: + +```javascript +const { Client } = require('@opensearch/opensearch') +``` + + +## Sample code + +```javascript +'use strict'; + +var host = 'localhost'; +var protocol = 'https'; +var port = 9200; +var auth = 'admin:admin'; // For testing only. Don't store credentials in code. +var ca_certs_path = '/full/path/to/root-ca.pem'; + +// Optional client certificates if you don't want to use HTTP basic authentication. +// var client_cert_path = '/full/path/to/client.pem' +// var client_key_path = '/full/path/to/client-key.pem' + +// Create a client with SSL/TLS enabled. +var { Client } = require('@opensearch/opensearch'); +var fs = require('fs'); +var client = new Client({ + node: protocol + '://' + auth + '@' + host + ':' + port, + ssl: { + ca: fs.readFileSync(ca_certs_path), + // cert: fs.readFileSync(client_cert_path), + // key: fs.readFileSync(client_key_path) + } +}) + +async function search() { + + // Create an index with non-default settings. + var index_name = 'books' + var settings = { + 'settings': { + 'index': { + 'number_of_shards': 4, + 'number_of_replicas': 3 + } + } + } + + var response = await client.indices.create({ + index: index_name, + body: settings + }) + + console.log('Creating index:') + console.log(response.body) + + // Add a document to the index. + var document = { + 'title': 'The Outsider', + 'author': 'Stephen King', + 'year': '2018', + 'genre': 'Crime fiction' + } + + var id = '1' + + var response = await client.index({ + id: id, + index: index_name, + body: document + }) + + console.log('Adding document:') + console.log(response.body) + + // Force an index refresh so the subsequent search returns results. + client.indices.refresh({ + index: index_name + }) + + // Search for the document. + var query = { + 'query': { + 'match': { + 'title': { + 'query': 'The Outsider' + } + } + } + } + + var response = await client.search({ + index: index_name, + body: query + }) + + console.log('Search results:') + console.log(response.body.hits) + + // Delete the document. + var response = await client.delete({ + index: index_name, + id: id + }) + + console.log('Deleting document:') + console.log(response.body) + + // Delete the index. + var response = await client.indices.delete({ + index: index_name + }) + + console.log('Deleting index:') + console.log(response.body) +} + +search().catch(console.log) +``` From 4d39000cd3daa41336c031fbdf26566b2b8c25d1 Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Thu, 26 Aug 2021 12:51:04 -0700 Subject: [PATCH 11/60] Add command to install specific version --- _clients/javascript.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/_clients/javascript.md b/_clients/javascript.md index 60c1cba1..42a00f67 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -19,6 +19,12 @@ To add the client to your project, install it from npm: npm install @opensearch/opensearch ``` +To install a specific major version of the client, run the following command: + +```bash +npm install @opensearch/opensearch@ +``` + If you prefer to add the client manually or just want to examine the source code, see [opensearch-js](https://github.com/opensearch-project/opensearch-js) on GitHub. Then require the client: From 51d359ec4075a41e2bdb14567ea6fb1113f621fa Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Thu, 26 Aug 2021 13:34:19 -0700 Subject: [PATCH 12/60] Remove index refresh --- _clients/javascript.md | 8 ++------ 1 file changed, 2 insertions(+), 6 deletions(-) diff --git a/_clients/javascript.md b/_clients/javascript.md index 42a00f67..f6490863 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -95,17 +95,13 @@ async function search() { var response = await client.index({ id: id, index: index_name, - body: document + body: document, + refresh: true }) console.log('Adding document:') console.log(response.body) - // Force an index refresh so the subsequent search returns results. - client.indices.refresh({ - index: index_name - }) - // Search for the document. var query = { 'query': { From e210d7d217586d64f3421e80d9c4af892237b74c Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Thu, 26 Aug 2021 13:36:12 -0700 Subject: [PATCH 13/60] Fix nav order to not conflict with Go --- _clients/javascript.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/javascript.md b/_clients/javascript.md index f6490863..2c4946f4 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -1,7 +1,7 @@ --- layout: default title: Javascript client -nav_order: 80 +nav_order: 90 --- # Javascript client From 18d389187943d1a3002ac916a5f6741b7573c148 Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Thu, 26 Aug 2021 15:23:06 -0700 Subject: [PATCH 14/60] Specify how to turn off cert verification --- _clients/javascript.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_clients/javascript.md b/_clients/javascript.md index 2c4946f4..55134c00 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -56,6 +56,7 @@ var client = new Client({ node: protocol + '://' + auth + '@' + host + ':' + port, ssl: { ca: fs.readFileSync(ca_certs_path), + // You can turn off certificate verification (rejectUnauthorized: false) if you're using self-signed certificates with a hostname mismatch. // cert: fs.readFileSync(client_cert_path), // key: fs.readFileSync(client_key_path) } From fbc0447bcdad8e2a83caa74153d3a46d3a5b280d Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Fri, 27 Aug 2021 13:20:59 -0700 Subject: [PATCH 15/60] added more context --- _clients/go.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_clients/go.md b/_clients/go.md index e77fc0dd..06b6e533 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -25,6 +25,8 @@ go get github.com/opensearch-project/opensearch-go ## Sample code +This sample code creates a client, adds an index with non-default settings, inserts a document, searches for the document, deletes the document, and finally deletes the index: + ```go package main From 7aed3bfbf1a1af94a0c21795bbc2165d9df14c09 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Fri, 27 Aug 2021 14:00:26 -0700 Subject: [PATCH 16/60] updated code to check error message --- _clients/go.md | 173 ++++++++++++++++++++++++++----------------------- 1 file changed, 93 insertions(+), 80 deletions(-) diff --git a/_clients/go.md b/_clients/go.md index 06b6e533..6db260ac 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -29,104 +29,117 @@ This sample code creates a client, adds an index with non-default settings, inse ```go package main - import ( - "context" - "crypto/tls" - "fmt" - opensearch "github.com/opensearch-project/opensearch-go" - opensearchapi "github.com/opensearch-project/opensearch-go/opensearchapi" - "net/http" - "strings" + "os" + "context" + "crypto/tls" + "fmt" + opensearch "github.com/opensearch-project/opensearch-go" + opensearchapi "github.com/opensearch-project/opensearch-go/opensearchapi" + "net/http" + "strings" ) - const IndexName = "go-test-index1" - func main() { + // Initialize the client with SSL/TLS enabled. + client, err := opensearch.NewClient(opensearch.Config{ + Transport: &http.Transport{ + TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, + }, + Addresses: []string{"https://localhost:9200"}, + Username: "admin", // For testing only. Don't store credentials in code. + Password: "admin", + }) + if err != nil { + fmt.Println("cannot initialize", err) + os.Exit(1) + } - // Initialize the client with SSL/TLS enabled. - client, err := opensearch.NewClient(opensearch.Config{ - Transport: &http.Transport{ - TLSClientConfig: &tls.Config{InsecureSkipVerify: true}, - }, - Addresses: []string{"https://localhost:9200"}, - Username: "admin", // For testing only. Don't store credentials in code. - Password: "admin", - }) - if err != nil { - fmt.Println("cannot initialize", err) - } + // Print OpenSearch version information on console. + fmt.Println(client.Info()) - // Print OpenSearch version information on console. - fmt.Println(client.Info()) - - // Define a mapping. - mapping := strings.NewReader(`{ - 'settings': { - 'index': { + // Define index mapping. + mapping := strings.NewReader(`{ + 'settings': { + 'index': { 'number_of_shards': 4 } } - }`) + }`) - // Create an index with non-default settings. - res := opensearchapi.CreateRequest{ - Index: IndexName, - Body: mapping, - } - fmt.Println("creating index", res) + // Create an index with non-default settings. + res := opensearchapi.CreateRequest{ + Index: IndexName, + Body: mapping, + } + fmt.Println("creating index", res) - // Add a document to the index. - document := strings.NewReader(`{ - "title": "Moneyball", - "director": "Bennett Miller", - "year": "2011" - }`) + // Add a document to the index. + document := strings.NewReader(`{ + "title": "Moneyball", + "director": "Bennett Miller", + "year": "2011" + }`) - docId := "1" - req := opensearchapi.IndexRequest{ - Index: IndexName, - DocumentID: docId, - Body: document, - } - insertResponse, err := req.Do(context.Background(), client) - fmt.Println(insertResponse) + docId := "1" + req := opensearchapi.IndexRequest{ + Index: IndexName, + DocumentID: docId, + Body: document, + } + insertResponse, err := req.Do(context.Background(), client) + if err != nil { + fmt.Println("failed to insert document ", err) + os.Exit(1) + } + fmt.Println(insertResponse) - // Search for the document. - content := strings.NewReader(`{ - "size": 5, - "query": { - "multi_match": { - "query": "miller", - "fields": ["title^2", "director"] - } - } - }`) + // Search for the document. + content := strings.NewReader(`{ + "size": 5, + "query": { + "multi_match": { + "query": "miller", + "fields": ["title^2", "director"] + } + } + }`) - search := opensearchapi.SearchRequest{ - Body: content, - } + search := opensearchapi.SearchRequest{ + Body: content, + } - searchResponse, err := search.Do(context.Background(), client) - fmt.Println(searchResponse) + searchResponse, err := search.Do(context.Background(), client) + if err != nil { + fmt.Println("failed to search document ", err) + os.Exit(1) + } + fmt.Println(searchResponse) - // Delete the document. - delete := opensearchapi.DeleteRequest{ - Index: IndexName, - DocumentID: docId, - } + // Delete the document. + delete := opensearchapi.DeleteRequest{ + Index: IndexName, + DocumentID: docId, + } - deleteResponse, err := delete.Do(context.Background(), client) - fmt.Println("deleting document") - fmt.Println(deleteResponse) + deleteResponse, err := delete.Do(context.Background(), client) + if err != nil { + fmt.Println("failed to delete document ", err) + os.Exit(1) + } + fmt.Println("deleting document") + fmt.Println(deleteResponse) - // Delete the index. - deleteIndex := opensearchapi.IndicesDeleteRequest{ - Index: []string{IndexName}, - } + // Delete previously created index. + deleteIndex := opensearchapi.IndicesDeleteRequest{ + Index: []string{IndexName}, + } - deleteIndexResponse, err := deleteIndex.Do(context.Background(), client) - fmt.Println("deleting index") - fmt.Println(deleteIndexResponse) + deleteIndexResponse, err := deleteIndex.Do(context.Background(), client) + if err != nil { + fmt.Println("failed to delete index ", err) + os.Exit(1) + } + fmt.Println("deleting index", deleteIndexResponse) } ``` From dc48c6ced5d1a35867e1d3a9f7e9304bbde51ff2 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 30 Aug 2021 12:58:30 -0700 Subject: [PATCH 17/60] added count API --- _opensearch/rest-api/count.md | 103 ++++++++++++++++++++++++++++++++++ 1 file changed, 103 insertions(+) create mode 100644 _opensearch/rest-api/count.md diff --git a/_opensearch/rest-api/count.md b/_opensearch/rest-api/count.md new file mode 100644 index 00000000..7a1a8568 --- /dev/null +++ b/_opensearch/rest-api/count.md @@ -0,0 +1,103 @@ +--- +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 the use the count API to see the total number of documents in an index, a data stream, or an entire cluster. + + +## Example + +To see the number of documents that match a query: + +```json +GET opensearch_dashboards_sample_data_logs/_count +{ + "query": { + "term": { + "response": "200" + } + } +} +``` + +You can also use the search API for the same result: + +```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 /_count/ +POST /_count/ +``` + + +## 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 + } +} +``` From baa5622f9d4a4910b57bcb05dffbe4ce3ac52cef Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Tue, 31 Aug 2021 10:29:20 -0700 Subject: [PATCH 18/60] minor changes --- _opensearch/rest-api/count.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_opensearch/rest-api/count.md b/_opensearch/rest-api/count.md index 7a1a8568..b7b6b12d 100644 --- a/_opensearch/rest-api/count.md +++ b/_opensearch/rest-api/count.md @@ -10,7 +10,7 @@ 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 the use the count API to see the total number of documents in an index, a data stream, or an entire cluster. +You can also use it to check the document count of an index, data stream, or cluster. ## Example From 34068f01bd7e31856519c4dda0b1e9bd3153c647 Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 1 Sep 2021 16:29:19 -0700 Subject: [PATCH 19/60] Add note about enabling compatibility setting during upgrade --- _clients/agents-and-ingestion-tools/index.md | 6 ++++++ _upgrade-to/upgrade-to.md | 6 ++++++ 2 files changed, 12 insertions(+) diff --git a/_clients/agents-and-ingestion-tools/index.md b/_clients/agents-and-ingestion-tools/index.md index 7b9ca7fb..ed326279 100644 --- a/_clients/agents-and-ingestion-tools/index.md +++ b/_clients/agents-and-ingestion-tools/index.md @@ -27,6 +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 diff --git a/_upgrade-to/upgrade-to.md b/_upgrade-to/upgrade-to.md index 1fed63f3..a415b621 100644 --- a/_upgrade-to/upgrade-to.md +++ b/_upgrade-to/upgrade-to.md @@ -144,6 +144,12 @@ 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). From eaba608cfd2898cbf2554886568c6e2dc0ebc6d3 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 7 Sep 2021 15:28:29 -0700 Subject: [PATCH 20/60] Update some Dashboards settings paths --- .../access-control/multi-tenancy.md | 20 +++++++++---------- .../access-control/users-roles.md | 2 +- 2 files changed, 11 insertions(+), 11 deletions(-) diff --git a/_security-plugin/access-control/multi-tenancy.md b/_security-plugin/access-control/multi-tenancy.md index 537841c2..5b7ed3f5 100644 --- a/_security-plugin/access-control/multi-tenancy.md +++ b/_security-plugin/access-control/multi-tenancy.md @@ -47,21 +47,21 @@ Setting | Description opensearch.username: kibanaserver opensearch.password: kibanaserver opensearch.requestHeadersWhitelist: ["securitytenant","Authorization"] -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 +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 ``` 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. -`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. +`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. ## Add tenants diff --git a/_security-plugin/access-control/users-roles.md b/_security-plugin/access-control/users-roles.md index 445e1e63..b4e58c7a 100644 --- a/_security-plugin/access-control/users-roles.md +++ b/_security-plugin/access-control/users-roles.md @@ -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 `plugins.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 `opensearch_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. From 243c7315e439bc4d08218c105e0d08424ee4a77f Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 8 Sep 2021 08:34:57 -0700 Subject: [PATCH 21/60] Update generate-certificates.md --- _security-plugin/configuration/generate-certificates.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_security-plugin/configuration/generate-certificates.md b/_security-plugin/configuration/generate-certificates.md index 69945d7e..da73f7ec 100755 --- a/_security-plugin/configuration/generate-certificates.md +++ b/_security-plugin/configuration/generate-certificates.md @@ -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 30 +openssl req -new -x509 -sha256 -key root-ca-key.pem -out root-ca.pem -days 730 ``` -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 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. - 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 30 +openssl x509 -req -in admin.csr -CA root-ca.pem -CAkey root-ca-key.pem -CAcreateserial -sha256 -out admin.pem -days 730 ``` Just like the root certificate, use the `-days` option to specify an expiration date of longer than 30 days. From 2c713e43adf9ee0ac39679eb0c6b5c4067dcd085 Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 8 Sep 2021 10:08:33 -0700 Subject: [PATCH 22/60] Update index.md --- _opensearch/query-dsl/index.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/_opensearch/query-dsl/index.md b/_opensearch/query-dsl/index.md index 3d1b7de8..ac55e7ea 100644 --- a/_opensearch/query-dsl/index.md +++ b/_opensearch/query-dsl/index.md @@ -5,8 +5,11 @@ 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. From c507de5b9fb5ccc437cc815fd94f214e49855b00 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 9 Sep 2021 11:22:13 -0700 Subject: [PATCH 23/60] Minor wording changes for Beats OSS --- _clients/agents-and-ingestion-tools/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_clients/agents-and-ingestion-tools/index.md b/_clients/agents-and-ingestion-tools/index.md index ed326279..04adfb1e 100644 --- a/_clients/agents-and-ingestion-tools/index.md +++ b/_clients/agents-and-ingestion-tools/index.md @@ -38,7 +38,7 @@ compatibility.override_main_response_version: true 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 versions of Beats offer the best compatibility with OpenSearch. For more information, see the [compatibility matrices](#compatibility-matrices). +These are the latest versions of Beats OSS with OpenSearch compatibility. 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 +47,7 @@ These versions of Beats offer the best compatibility with OpenSearch. For more i - [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 OSS 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 instead. {: .note } From b0301949812f929eb0d0dfc7d2a0933b8aea0e01 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Fri, 10 Sep 2021 14:25:00 -0700 Subject: [PATCH 24/60] incorporated feedback --- _opensearch/rest-api/count.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_opensearch/rest-api/count.md b/_opensearch/rest-api/count.md index b7b6b12d..c3463a08 100644 --- a/_opensearch/rest-api/count.md +++ b/_opensearch/rest-api/count.md @@ -28,7 +28,7 @@ GET opensearch_dashboards_sample_data_logs/_count } ``` -You can also use the search API for the same result: +The following call to the search API produces equivalent results: ```json GET opensearch_dashboards_sample_data_logs/_search From 50f3fa51d84c99f38580da1bb91523f63874a798 Mon Sep 17 00:00:00 2001 From: aetter Date: Fri, 10 Sep 2021 15:01:43 -0700 Subject: [PATCH 25/60] Update python.md --- _clients/python.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/python.md b/_clients/python.md index cdc7dc29..bcb1ff93 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -14,7 +14,7 @@ The OpenSearch Python client provides a more natural syntax for interacting with To add the client to your project, install it using [pip](https://pip.pypa.io/): ```bash -pip install +pip install opensearch ``` Then import it like any other module: From ed8230cb02fafacfd531c8e15e422ecae79157a4 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 14 Sep 2021 09:08:45 -0700 Subject: [PATCH 26/60] Update delay to milliseconds, page_size to integer --- _im-plugin/index-rollups/rollup-api.md | 60 +++++++++++++------------- 1 file changed, 30 insertions(+), 30 deletions(-) diff --git a/_im-plugin/index-rollups/rollup-api.md b/_im-plugin/index-rollups/rollup-api.md index 06df2e7a..07a06a41 100644 --- a/_im-plugin/index-rollups/rollup-api.md +++ b/_im-plugin/index-rollups/rollup-api.md @@ -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` | 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 +`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. | Integer | 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 #### Sample response From 125585f04e5207092b2ab19e0cf4368d813aedf9 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 14 Sep 2021 09:10:35 -0700 Subject: [PATCH 27/60] OK fine we can call it a number --- _im-plugin/index-rollups/rollup-api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_im-plugin/index-rollups/rollup-api.md b/_im-plugin/index-rollups/rollup-api.md index 07a06a41..7aa878d3 100644 --- a/_im-plugin/index-rollups/rollup-api.md +++ b/_im-plugin/index-rollups/rollup-api.md @@ -104,7 +104,7 @@ Options | Description | Type | Required `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. | Integer | Yes +`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 From 2a0cf500cc8de02f9f46a611707e789f88945e62 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Tue, 14 Sep 2021 11:10:11 -0700 Subject: [PATCH 28/60] updated helm project path --- _opensearch/install/helm.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_opensearch/install/helm.md b/_opensearch/install/helm.md index a5bc7d50..55458626 100644 --- a/_opensearch/install/helm.md +++ b/_opensearch/install/helm.md @@ -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 [opensearch-devops](https://github.com/opensearch-project/opensearch-devops/) repository: +1. Clone the [helm-charts](https://github.com/opensearch-project/helm-charts) repository: ```bash - git clone https://github.com/opensearch-project/opensearch-devops.git + git clone https://github.com/opensearch-project/helm-charts ``` 1. Change to the `opensearch` directory: ```bash - cd Helm/opensearch + cd charts/opensearch ``` 1. Package the Helm chart: From 35a7b186fc0e1d955e28ca1e8ae9d69e306cee76 Mon Sep 17 00:00:00 2001 From: Keith Chan <12404772+keithhc2@users.noreply.github.com> Date: Tue, 14 Sep 2021 14:03:29 -0700 Subject: [PATCH 29/60] Fixed broken link --- _opensearch/rest-api/document-apis/update-by-query.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_opensearch/rest-api/document-apis/update-by-query.md b/_opensearch/rest-api/document-apis/update-by-query.md index 0e66d1ae..bb7ebe2b 100644 --- a/_opensearch/rest-api/document-apis/update-by-query.md +++ b/_opensearch/rest-api/document-apis/update-by-query.md @@ -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.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. +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. ```json { From ba9f43262276530ada4eb08e1de7e6199d0a0426 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 16 Sep 2021 14:38:01 -0700 Subject: [PATCH 30/60] Fix table --- _opensearch/rest-api/create-index.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_opensearch/rest-api/create-index.md b/_opensearch/rest-api/create-index.md index 9ff027f0..87dc7591 100644 --- a/_opensearch/rest-api/create-index.md +++ b/_opensearch/rest-api/create-index.md @@ -96,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 | 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_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_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. @@ -109,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 - 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.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.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. From 21ae64aac987263d5700b843ee6502f22939b7b9 Mon Sep 17 00:00:00 2001 From: aetter Date: Fri, 17 Sep 2021 14:17:21 -0700 Subject: [PATCH 31/60] Move to h2 --- _security-plugin/configuration/generate-certificates.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security-plugin/configuration/generate-certificates.md b/_security-plugin/configuration/generate-certificates.md index da73f7ec..8206e2fa 100755 --- a/_security-plugin/configuration/generate-certificates.md +++ b/_security-plugin/configuration/generate-certificates.md @@ -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): From 05ba9198f60666f343e420d96b020ecf1a359588 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 20 Sep 2021 13:22:18 -0700 Subject: [PATCH 32/60] modified description --- _clients/go.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/go.md b/_clients/go.md index 6db260ac..46b359aa 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -6,7 +6,7 @@ nav_order: 80 # Go client -The OpenSearch Go client lets you programmatically interact with data in your OpenSearch cluster as part of your Go application. +The OpenSearch Go client lets you build a Go application that interacts with the data in your OpenSearch cluster. ## Setup From 6bf8a7d51aa1a745685d82fc7ab03d20f3b8c828 Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 20 Sep 2021 13:27:13 -0700 Subject: [PATCH 33/60] minor change --- _clients/go.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/go.md b/_clients/go.md index 46b359aa..ac09a0c8 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -6,7 +6,7 @@ nav_order: 80 # Go client -The OpenSearch Go client lets you build a Go application that interacts with the data in your OpenSearch cluster. +The OpenSearch Go client lets you easily connect your Go application with the data in your OpenSearch cluster. ## Setup From 54a0b8e755b2f4873f99163949fd60fd0780f96d Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 20 Sep 2021 13:29:58 -0700 Subject: [PATCH 34/60] minor change --- _clients/go.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/go.md b/_clients/go.md index ac09a0c8..75ee300e 100644 --- a/_clients/go.md +++ b/_clients/go.md @@ -6,7 +6,7 @@ nav_order: 80 # Go client -The OpenSearch Go client lets you easily connect your Go application with the data in your OpenSearch cluster. +The OpenSearch Go client lets you connect your Go application with the data in your OpenSearch cluster. ## Setup From 4ffdce637741c9b0bd8d5c3ea1a98277343d30a4 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 21 Sep 2021 11:34:44 -0700 Subject: [PATCH 35/60] Minor improvements Troubleshooting expired certificates, settings, broken link, etc. --- _monitoring-plugins/pa/dashboards.md | 2 +- _monitoring-plugins/pa/index.md | 4 ++-- _opensearch/configuration.md | 8 +++++++ _troubleshoot/index.md | 31 +++++++++++++++++++--------- 4 files changed, 32 insertions(+), 13 deletions(-) diff --git a/_monitoring-plugins/pa/dashboards.md b/_monitoring-plugins/pa/dashboards.md index 2d8c9ec9..561f6fa3 100644 --- a/_monitoring-plugins/pa/dashboards.md +++ b/_monitoring-plugins/pa/dashboards.md @@ -1,6 +1,6 @@ --- layout: default -title: Create Dashboards +title: Create PerfTop Dashboards parent: Performance Analyzer nav_order: 2 --- diff --git a/_monitoring-plugins/pa/index.md b/_monitoring-plugins/pa/index.md index c83df772..006af045 100644 --- a/_monitoring-plugins/pa/index.md +++ b/_monitoring-plugins/pa/index.md @@ -48,11 +48,11 @@ Otherwise, just specify the OpenSearch endpoint: ./opensearch-perf-top-macos --dashboard dashboards/.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}}/dashboards/). +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/). 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 } diff --git a/_opensearch/configuration.md b/_opensearch/configuration.md index a6a0f995..d28767bf 100755 --- a/_opensearch/configuration.md +++ b/_opensearch/configuration.md @@ -65,4 +65,12 @@ 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/). diff --git a/_troubleshoot/index.md b/_troubleshoot/index.md index 76a03551..fc11a6b6 100644 --- a/_troubleshoot/index.md +++ b/_troubleshoot/index.md @@ -11,16 +11,32 @@ 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 +``` + + ## 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: @@ -85,8 +101,3 @@ The security plugin blocks the update by script operation (`POST /_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. From 30378f0076a0a09859233a28f5fe2085165b5ded Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 21 Sep 2021 12:34:59 -0700 Subject: [PATCH 36/60] Sentence case access control page names --- _security-plugin/access-control/api.md | 2 +- _security-plugin/access-control/cross-cluster-search.md | 4 ++-- _security-plugin/access-control/default-action-groups.md | 4 ++-- _security-plugin/access-control/document-level-security.md | 4 ++-- _security-plugin/access-control/field-level-security.md | 4 ++-- _security-plugin/access-control/field-masking.md | 4 ++-- _security-plugin/access-control/impersonation.md | 4 ++-- _security-plugin/access-control/index.md | 2 +- _security-plugin/access-control/multi-tenancy.md | 4 ++-- _security-plugin/access-control/permissions.md | 2 +- _security-plugin/access-control/users-roles.md | 4 ++-- 11 files changed, 19 insertions(+), 19 deletions(-) diff --git a/_security-plugin/access-control/api.md b/_security-plugin/access-control/api.md index f3c0c685..19dd46ec 100644 --- a/_security-plugin/access-control/api.md +++ b/_security-plugin/access-control/api.md @@ -1,7 +1,7 @@ --- layout: default title: API -parent: Access Control +parent: Access control nav_order: 90 --- diff --git a/_security-plugin/access-control/cross-cluster-search.md b/_security-plugin/access-control/cross-cluster-search.md index 288c82ff..060ad624 100644 --- a/_security-plugin/access-control/cross-cluster-search.md +++ b/_security-plugin/access-control/cross-cluster-search.md @@ -1,7 +1,7 @@ --- layout: default -title: Cross-Cluster Search -parent: Access Control +title: Cross-cluster search +parent: Access control nav_order: 40 --- diff --git a/_security-plugin/access-control/default-action-groups.md b/_security-plugin/access-control/default-action-groups.md index a8793aff..025791b6 100644 --- a/_security-plugin/access-control/default-action-groups.md +++ b/_security-plugin/access-control/default-action-groups.md @@ -1,7 +1,7 @@ --- layout: default -title: Default Action Groups -parent: Access Control +title: Default action groups +parent: Access control nav_order: 51 --- diff --git a/_security-plugin/access-control/document-level-security.md b/_security-plugin/access-control/document-level-security.md index 04db5fa2..a6d9390f 100644 --- a/_security-plugin/access-control/document-level-security.md +++ b/_security-plugin/access-control/document-level-security.md @@ -1,7 +1,7 @@ --- layout: default -title: Document-Level Security -parent: Access Control +title: Document-level security +parent: Access control nav_order: 10 --- diff --git a/_security-plugin/access-control/field-level-security.md b/_security-plugin/access-control/field-level-security.md index b79dc7ec..e306c951 100644 --- a/_security-plugin/access-control/field-level-security.md +++ b/_security-plugin/access-control/field-level-security.md @@ -1,7 +1,7 @@ --- layout: default -title: Field-Level Security -parent: Access Control +title: Field-level security +parent: Access control nav_order: 11 --- diff --git a/_security-plugin/access-control/field-masking.md b/_security-plugin/access-control/field-masking.md index 991edfc9..e00233dd 100644 --- a/_security-plugin/access-control/field-masking.md +++ b/_security-plugin/access-control/field-masking.md @@ -1,7 +1,7 @@ --- layout: default -title: Field Masking -parent: Access Control +title: Field masking +parent: Access control nav_order: 12 --- diff --git a/_security-plugin/access-control/impersonation.md b/_security-plugin/access-control/impersonation.md index cc995785..82966389 100644 --- a/_security-plugin/access-control/impersonation.md +++ b/_security-plugin/access-control/impersonation.md @@ -1,7 +1,7 @@ --- layout: default -title: User Impersonation -parent: Access Control +title: User impersonation +parent: Access control nav_order: 20 --- diff --git a/_security-plugin/access-control/index.md b/_security-plugin/access-control/index.md index 99c081e6..6275487f 100644 --- a/_security-plugin/access-control/index.md +++ b/_security-plugin/access-control/index.md @@ -1,6 +1,6 @@ --- layout: default -title: Access Control +title: Access control nav_order: 10 has_children: true has_toc: false diff --git a/_security-plugin/access-control/multi-tenancy.md b/_security-plugin/access-control/multi-tenancy.md index 5b7ed3f5..bb092851 100644 --- a/_security-plugin/access-control/multi-tenancy.md +++ b/_security-plugin/access-control/multi-tenancy.md @@ -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 --- diff --git a/_security-plugin/access-control/permissions.md b/_security-plugin/access-control/permissions.md index 192e8a7b..6e222fbe 100644 --- a/_security-plugin/access-control/permissions.md +++ b/_security-plugin/access-control/permissions.md @@ -1,7 +1,7 @@ --- layout: default title: Permissions -parent: Access Control +parent: Access control nav_order: 50 --- diff --git a/_security-plugin/access-control/users-roles.md b/_security-plugin/access-control/users-roles.md index b4e58c7a..d7bb9b8a 100644 --- a/_security-plugin/access-control/users-roles.md +++ b/_security-plugin/access-control/users-roles.md @@ -1,7 +1,7 @@ --- layout: default -title: Users and Roles -parent: Access Control +title: Users and roles +parent: Access control nav_order: 1 --- From 65f333d038325af731ff13dcae6e45f400d5398b Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 21 Sep 2021 13:40:38 -0700 Subject: [PATCH 37/60] Update python.md --- _clients/python.md | 12 ++++++++---- 1 file changed, 8 insertions(+), 4 deletions(-) diff --git a/_clients/python.md b/_clients/python.md index bcb1ff93..9ce68bca 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -8,19 +8,23 @@ nav_order: 70 The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests with raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. +{% comment %} +`opensearch-py` is the lower-level of the two Python clients. If you want a general client for assorted operations, it's a great choice. If you want a higher-level client strictly for indexing and search operations, consider [opensearch-dsl-py]({{site.url}}{{site.baseurl}}/clients/python-dsl/). +{% endcomment %} + ## Setup To add the client to your project, install it using [pip](https://pip.pypa.io/): ```bash -pip install opensearch +pip install opensearch-py ``` Then import it like any other module: ```python -from opensearch import OpenSearch +from opensearchpy import OpenSearch ``` If you prefer to add the client manually or just want to examine the source code, see [opensearch-py on GitHub](https://github.com/opensearch-project/opensearch-py). @@ -29,7 +33,7 @@ If you prefer to add the client manually or just want to examine the source code ## Sample code ```python -from opensearch import OpenSearch +from opensearchpy import OpenSearch host = 'localhost' port = 9200 @@ -55,7 +59,7 @@ client = OpenSearch( ) # Create an index with non-default settings. -index_name = 'python-test-index3' +index_name = 'python-test-index' index_body = { 'settings': { 'index': { From 66ca05e7145c266b792938b461c686a964156566 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 21 Sep 2021 13:56:25 -0700 Subject: [PATCH 38/60] Update links --- _clients/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_clients/index.md b/_clients/index.md index 3880a3bb..d920e16a 100644 --- a/_clients/index.md +++ b/_clients/index.md @@ -15,8 +15,8 @@ For example, a 1.0.0 client works with an OpenSearch 1.1.0 cluster, but might no * [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/) * [OpenSearch Python client]({{site.url}}{{site.baseurl}}/clients/python/) -* [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/nodejs/) -* [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/golang/) +* [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/javascript/) +* [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/go/) ## Legacy clients From 75efdfeae8352e6b26bb3faf6854cf6bb8f503fa Mon Sep 17 00:00:00 2001 From: piellick <18485789+piellick@users.noreply.github.com> Date: Wed, 22 Sep 2021 10:57:09 +0200 Subject: [PATCH 39/60] change ES_HOME env variable to OPENSEARCH_HOME env variable looks wrong on "Launch the agent CLI" --- _opensearch/install/tar.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_opensearch/install/tar.md b/_opensearch/install/tar.md index 2d0f9310..af45a3af 100644 --- a/_opensearch/install/tar.md +++ b/_opensearch/install/tar.md @@ -111,7 +111,7 @@ In a tarball installation, Performance Analyzer collects data when it is enabled 1. Launch the agent CLI: ```bash - ES_HOME="$PWD" ./bin/performance-analyzer-agent-cli + OPENSEARCH_HOME="$PWD" ./bin/performance-analyzer-agent-cli ``` 1. In a separate window, enable the Performance Analyzer plugin: From 2d228a86ca7b46fdba8bccfe39aada53728ef62a Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Wed, 22 Sep 2021 12:26:41 -0700 Subject: [PATCH 40/60] Update client name --- _clients/javascript.md | 163 ++++++++++++++++++++--------------------- 1 file changed, 80 insertions(+), 83 deletions(-) diff --git a/_clients/javascript.md b/_clients/javascript.md index 55134c00..5d429a08 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -10,19 +10,18 @@ The OpenSearch Javascript client provides a safer and easier way to interact wit The client contains a library of APIs that let you perform different operations on your cluster and return a standard response body. The example here demonstrates some basic operations like creating an index, adding documents, and searching your data. - ## Setup To add the client to your project, install it from npm: ```bash -npm install @opensearch/opensearch +npm install @opensearch-project/opensearch ``` To install a specific major version of the client, run the following command: ```bash -npm install @opensearch/opensearch@ +npm install @opensearch-project/opensearch@ ``` If you prefer to add the client manually or just want to examine the source code, see [opensearch-js](https://github.com/opensearch-project/opensearch-js) on GitHub. @@ -30,115 +29,113 @@ If you prefer to add the client manually or just want to examine the source code Then require the client: ```javascript -const { Client } = require('@opensearch/opensearch') +const { Client } = require("@opensearch-project/opensearch"); ``` - ## Sample code ```javascript -'use strict'; +"use strict"; -var host = 'localhost'; -var protocol = 'https'; +var host = "localhost"; +var protocol = "https"; var port = 9200; -var auth = 'admin:admin'; // For testing only. Don't store credentials in code. -var ca_certs_path = '/full/path/to/root-ca.pem'; +var auth = "admin:admin"; // For testing only. Don't store credentials in code. +var ca_certs_path = "/full/path/to/root-ca.pem"; // Optional client certificates if you don't want to use HTTP basic authentication. // var client_cert_path = '/full/path/to/client.pem' // var client_key_path = '/full/path/to/client-key.pem' // Create a client with SSL/TLS enabled. -var { Client } = require('@opensearch/opensearch'); -var fs = require('fs'); +var { Client } = require("@opensearch/opensearch"); +var fs = require("fs"); var client = new Client({ - node: protocol + '://' + auth + '@' + host + ':' + port, - ssl: { - ca: fs.readFileSync(ca_certs_path), - // You can turn off certificate verification (rejectUnauthorized: false) if you're using self-signed certificates with a hostname mismatch. - // cert: fs.readFileSync(client_cert_path), - // key: fs.readFileSync(client_key_path) - } -}) + node: protocol + "://" + auth + "@" + host + ":" + port, + ssl: { + ca: fs.readFileSync(ca_certs_path), + // You can turn off certificate verification (rejectUnauthorized: false) if you're using self-signed certificates with a hostname mismatch. + // cert: fs.readFileSync(client_cert_path), + // key: fs.readFileSync(client_key_path) + }, +}); async function search() { + // Create an index with non-default settings. + var index_name = "books"; + var settings = { + settings: { + index: { + number_of_shards: 4, + number_of_replicas: 3, + }, + }, + }; - // Create an index with non-default settings. - var index_name = 'books' - var settings = { - 'settings': { - 'index': { - 'number_of_shards': 4, - 'number_of_replicas': 3 - } - } - } + var response = await client.indices.create({ + index: index_name, + body: settings, + }); - var response = await client.indices.create({ - index: index_name, - body: settings - }) + console.log("Creating index:"); + console.log(response.body); - console.log('Creating index:') - console.log(response.body) + // Add a document to the index. + var document = { + title: "The Outsider", + author: "Stephen King", + year: "2018", + genre: "Crime fiction", + }; - // Add a document to the index. - var document = { - 'title': 'The Outsider', - 'author': 'Stephen King', - 'year': '2018', - 'genre': 'Crime fiction' - } + var id = "1"; - var id = '1' + var response = await client.index({ + id: id, + index: index_name, + body: document, + refresh: true, + }); - var response = await client.index({ - id: id, - index: index_name, - body: document, - refresh: true - }) + console.log("Adding document:"); + console.log(response.body); - console.log('Adding document:') - console.log(response.body) + // Search for the document. + var query = { + query: { + match: { + title: { + query: "The Outsider", + }, + }, + }, + }; - // Search for the document. - var query = { - 'query': { - 'match': { - 'title': { - 'query': 'The Outsider' - } - } - } - } + var response = await client.search({ + index: index_name, + body: query, + }); - var response = await client.search({ - index: index_name, - body: query - }) + console.log("Search results:"); + console.log(response.body.hits); - console.log('Search results:') - console.log(response.body.hits) + // Delete the document. + var response = await client.delete({ + index: index_name, + id: id, + }); - // Delete the document. - var response = await client.delete({ - index: index_name, - id: id - }) + console.log("Deleting document:"); + console.log(response.body); - console.log('Deleting document:') - console.log(response.body) + // Delete the index. + var response = await client.indices.delete({ + index: index_name, + }); - // Delete the index. - var response = await client.indices.delete({ - index: index_name - }) - - console.log('Deleting index:') - console.log(response.body) + console.log("Deleting index:"); + console.log(response.body); } -search().catch(console.log) +search().catch(console.log); ``` From 293743e15b249fb45d8a985b481058bd20be84cf Mon Sep 17 00:00:00 2001 From: Liz Snyder Date: Wed, 22 Sep 2021 12:27:39 -0700 Subject: [PATCH 41/60] Missed one --- _clients/javascript.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_clients/javascript.md b/_clients/javascript.md index 5d429a08..cb308a29 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -48,7 +48,7 @@ var ca_certs_path = "/full/path/to/root-ca.pem"; // var client_key_path = '/full/path/to/client-key.pem' // Create a client with SSL/TLS enabled. -var { Client } = require("@opensearch/opensearch"); +var { Client } = require("@opensearch-project/opensearch"); var fs = require("fs"); var client = new Client({ node: protocol + "://" + auth + "@" + host + ":" + port, From 07b0650128bc31b5dbdbb09b00609a0b179a66ca Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 22 Sep 2021 12:59:25 -0700 Subject: [PATCH 42/60] Add remote cluster information operation --- _opensearch/rest-api/remote-info.md | 40 +++++++++++++++++++++++++++++ 1 file changed, 40 insertions(+) create mode 100644 _opensearch/rest-api/remote-info.md diff --git a/_opensearch/rest-api/remote-info.md b/_opensearch/rest-api/remote-info.md new file mode 100644 index 00000000..e9d88402 --- /dev/null +++ b/_opensearch/rest-api/remote-info.md @@ -0,0 +1,40 @@ +--- +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 + } +} +``` From a9144167d8db4ff67143a7a5bd58f5eb38b03043 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 23 Sep 2021 10:29:51 -0700 Subject: [PATCH 43/60] Note that ISM doesn't run jobs on red clusters --- _im-plugin/ism/index.md | 1 + 1 file changed, 1 insertion(+) diff --git a/_im-plugin/ism/index.md b/_im-plugin/ism/index.md index 7a2a3da3..5e983e45 100644 --- a/_im-plugin/ism/index.md +++ b/_im-plugin/ism/index.md @@ -89,6 +89,7 @@ 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 From d2ba96967b8b350d076b43e8aff4a66a3098e0eb Mon Sep 17 00:00:00 2001 From: aetter Date: Fri, 24 Sep 2021 13:49:48 -0700 Subject: [PATCH 44/60] Give CCS Compose file unique node names Avoid weird conflicts if you use our main Compose file and then try to use this one. --- .../access-control/cross-cluster-search.md | 34 +++++++++---------- 1 file changed, 17 insertions(+), 17 deletions(-) diff --git a/_security-plugin/access-control/cross-cluster-search.md b/_security-plugin/access-control/cross-cluster-search.md index 060ad624..3c37f3c6 100644 --- a/_security-plugin/access-control/cross-cluster-search.md +++ b/_security-plugin/access-control/cross-cluster-search.md @@ -65,11 +65,11 @@ Save this file as `docker-compose.yml` and run `docker-compose up` to start two ```yml version: '3' services: - opensearch-node1: + opensearch-ccs-node1: image: opensearchproject/opensearch:{{site.opensearch_version}} - container_name: opensearch-node1 + container_name: opensearch-ccs-node1 environment: - - cluster.name=opensearch-cluster1 + - cluster.name=opensearch-ccs-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-node2: + opensearch-ccs-node2: image: opensearchproject/opensearch:{{site.opensearch_version}} - container_name: opensearch-node2 + container_name: opensearch-ccs-node2 environment: - - cluster.name=opensearch-cluster2 + - cluster.name=opensearch-ccs-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-cluster1", + "cluster_name" : "opensearch-ccs-cluster1", ... } curl -XGET -u 'admin:admin' -k 'https://localhost:9250' { - "cluster_name" : "opensearch-cluster2", + "cluster_name" : "opensearch-ccs-cluster2", ... } ``` -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. +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. 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-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 +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 ``` 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-cluster1": { + "opensearch-ccs-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-cluster1:books/_search?pretty' +curl -XGET -k -u 'admin:admin' 'https://localhost:9250/opensearch-ccs-cluster1:books/_search?pretty' { ... "hits": [{ - "_index": "opensearch-cluster1:books", + "_index": "opensearch-ccs-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-cluster1:books/_search?pretty' +curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-ccs-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-cluster1:books/_search?pretty' +curl -XGET -k -u booksuser:password 'https://localhost:9250/opensearch-ccs-cluster1:books/_search?pretty' { ... "hits": [{ - "_index": "opensearch-cluster1:books", + "_index": "opensearch-ccs-cluster1:books", "_type": "_doc", "_id": "1", "_score": 1.0, From b12dab67054b7e615e5c73d018b8d76615633095 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Fri, 24 Sep 2021 14:13:26 -0700 Subject: [PATCH 45/60] Add descriptions to config yaml files and added some security APIs --- _security-plugin/access-control/api.md | 214 +++++++++++++++---------- _security-plugin/configuration/yaml.md | 9 +- 2 files changed, 139 insertions(+), 84 deletions(-) diff --git a/_security-plugin/access-control/api.md b/_security-plugin/access-control/api.md index 19dd46ec..b5b3e9d3 100644 --- a/_security-plugin/access-control/api.md +++ b/_security-plugin/access-control/api.md @@ -1179,6 +1179,117 @@ PATCH _plugins/_security/api/securityconfig } ``` +--- + +## Distinguished names + +These REST APIs let a super admin allow list distinguished names to enable communication between clusters and/or nodes. + +Before you can use the REST API to add, retrieve, update, or delete any distinguished names, you must first add the following line to `opensearch.yml`: + +```yml +plugins.security.nodes_dn_dynamic_config_enabled: true +``` + + +### Get distinguished names + +Retrieves all allow listed distinguished names. + +#### 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 or node, include its name in the request's URL. + +#### Request + +``` +GET _plugins/_security/api/nodesdn/ +``` + +#### Sample response + +```json +{ + "cluster3": { + "nodes_dn": [ + "CN=cluster3.example.com" + ] + } +} +``` + + +### Add distinguished names + +Adds the specified distinguished names to the cluster's or node's allow list. + +#### Request + +```json +PUT _plugins/_security/api/nodesdn/ +{ + "nodes_dn": [ + "CN=cluster3.example.com" + ] +} +``` + +#### Sample response + +```json +{ + "status": "CREATED", + "message": "'cluster3' created." +} +``` + +If the specified cluster or node already has an allow list of distinguished names, the PUT request updates the list instead. + +#### Sample response + +```json +{ + "status": "OK", + "message": "'cluster7' updated." +} +``` + + +### Delete distinguished names + +Deletes the cluster's allow listed distinguished names. + +#### Request + +``` +DELETE _plugins/_security/api/nodesdn/ +``` + +#### Sample response + +```json +{ + "status": "OK", + "message": "'cluster3' deleted." +} +``` + --- @@ -1188,101 +1299,38 @@ PATCH _plugins/_security/api/securityconfig Introduced 1.0 {: .label .label-purple } -Retrieves the current security plugin configuration in JSON format. +Retrieves the cluster's certificates. #### 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 - } -} +GET _opendistro/_security/api/ssl/certs ``` #### Sample response ```json { - "status": "OK", - "message": "'config' updated." + "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" + } + ] } ``` - - -### 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 -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." -} -``` - --- ## Cache diff --git a/_security-plugin/configuration/yaml.md b/_security-plugin/configuration/yaml.md index 6d6bcdd9..f9383b45 100644 --- a/_security-plugin/configuration/yaml.md +++ b/_security-plugin/configuration/yaml.md @@ -315,6 +315,10 @@ _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: @@ -325,9 +329,12 @@ admin_tenant: description: "Demo tenant for admin user" ``` - ## nodes_dn.yml +`nodes_dn.yml` lets you allow list certificates' [distinguished names (DNs)]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml) to enable communication between any number of nodes and/or clusters. For example, a node that allow lists the DN `CN=node1.example.com` 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 allow list DNs, use the [REST API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#distinguished-names). + ```yml --- _meta: From e8a863e943611f81c171e8a0f07694d87a2a1024 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Fri, 24 Sep 2021 14:23:17 -0700 Subject: [PATCH 46/60] Minor language tweak --- _security-plugin/access-control/api.md | 15 ++------------- 1 file changed, 2 insertions(+), 13 deletions(-) diff --git a/_security-plugin/access-control/api.md b/_security-plugin/access-control/api.md index b5b3e9d3..7634111b 100644 --- a/_security-plugin/access-control/api.md +++ b/_security-plugin/access-control/api.md @@ -1235,9 +1235,9 @@ GET _plugins/_security/api/nodesdn/ ``` -### Add distinguished names +### Update distinguished names -Adds the specified distinguished names to the cluster's or node's allow list. +Adds or updates the specified distinguished names in the cluster's or node's allow list. #### Request @@ -1259,17 +1259,6 @@ PUT _plugins/_security/api/nodesdn/ } ``` -If the specified cluster or node already has an allow list of distinguished names, the PUT request updates the list instead. - -#### Sample response - -```json -{ - "status": "OK", - "message": "'cluster7' updated." -} -``` - ### Delete distinguished names From 430b9fed507e5ca9289f21869ec620a595a859d7 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Fri, 24 Sep 2021 14:53:33 -0700 Subject: [PATCH 47/60] Added "security" --- _security-plugin/access-control/api.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/_security-plugin/access-control/api.md b/_security-plugin/access-control/api.md index 7634111b..8c2b8088 100644 --- a/_security-plugin/access-control/api.md +++ b/_security-plugin/access-control/api.md @@ -1288,7 +1288,7 @@ DELETE _plugins/_security/api/nodesdn/ Introduced 1.0 {: .label .label-purple } -Retrieves the cluster's certificates. +Retrieves the cluster's security certificates. #### Request From c85fd21b4feae12a6fa70fc65a19495ad939cf7b Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 27 Sep 2021 10:07:37 -0700 Subject: [PATCH 48/60] Addressed comments --- _security-plugin/access-control/api.md | 10 +++++----- _security-plugin/configuration/yaml.md | 8 ++++---- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/_security-plugin/access-control/api.md b/_security-plugin/access-control/api.md index 8c2b8088..dd5604a3 100644 --- a/_security-plugin/access-control/api.md +++ b/_security-plugin/access-control/api.md @@ -1183,9 +1183,9 @@ PATCH _plugins/_security/api/securityconfig ## Distinguished names -These REST APIs let a super admin allow list distinguished names to enable communication between clusters and/or nodes. +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 add, retrieve, update, or delete any distinguished names, you must first add the following line to `opensearch.yml`: +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 @@ -1194,7 +1194,7 @@ plugins.security.nodes_dn_dynamic_config_enabled: true ### Get distinguished names -Retrieves all allow listed distinguished names. +Retrieves all distinguished names in the allow list. #### Request @@ -1214,7 +1214,7 @@ GET _plugins/_security/api/nodesdn } ``` -To get the distinguished names from a specific cluster or node, include its name in the request's URL. +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 @@ -1262,7 +1262,7 @@ PUT _plugins/_security/api/nodesdn/ ### Delete distinguished names -Deletes the cluster's allow listed distinguished names. +Deletes all distinguished names in the specified cluster's or node's allow list. #### Request diff --git a/_security-plugin/configuration/yaml.md b/_security-plugin/configuration/yaml.md index f9383b45..114f080d 100644 --- a/_security-plugin/configuration/yaml.md +++ b/_security-plugin/configuration/yaml.md @@ -126,7 +126,7 @@ plugins.security.restapi.password_validation_error_message: "Password must be mi ## whitelist.yml -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. +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. 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 allow list custom indices. `whitelist.yml` doesn't support wildcards, so you must manually specify all of the indices you want to allow list. +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. ```yml requests: # Only allow GET requests to /sample-index1/_doc/1 and /sample-index2/_doc/1 @@ -331,9 +331,9 @@ admin_tenant: ## nodes_dn.yml -`nodes_dn.yml` lets you allow list certificates' [distinguished names (DNs)]({{site.url}}{{site.baseurl}}/security-plugin/configuration/generate-certificates/#add-distinguished-names-to-opensearchyml) to enable communication between any number of nodes and/or clusters. For example, a node that allow lists the DN `CN=node1.example.com` accepts communication from any other node or certificate that uses that DN. +`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 allow list DNs, use the [REST API]({{site.url}}{{site.baseurl}}/security-plugin/access-control/api/#distinguished-names). +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 --- From 7c425f102d3703edbda9d4e8fc6747f221128f3f Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 27 Sep 2021 12:52:36 -0700 Subject: [PATCH 49/60] Added reindex API --- _opensearch/reindex-data.md | 23 ---- _opensearch/rest-api/document-apis/reindex.md | 121 ++++++++++++++++++ 2 files changed, 121 insertions(+), 23 deletions(-) create mode 100644 _opensearch/rest-api/document-apis/reindex.md diff --git a/_opensearch/reindex-data.md b/_opensearch/reindex-data.md index f1e7164b..6d51a748 100644 --- a/_opensearch/reindex-data.md +++ b/_opensearch/reindex-data.md @@ -156,28 +156,6 @@ 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. @@ -272,7 +250,6 @@ 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 diff --git a/_opensearch/rest-api/document-apis/reindex.md b/_opensearch/rest-api/document-apis/reindex.md new file mode 100644 index 00000000..5ad961a8 --- /dev/null +++ b/_opensearch/rest-api/document-apis/reindex.md @@ -0,0 +1,121 @@ +--- +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. From eda842a36dbcab88079d40dea535e64fb42dbd0e Mon Sep 17 00:00:00 2001 From: ashwinkumar12345 Date: Mon, 27 Sep 2021 13:08:27 -0700 Subject: [PATCH 50/60] added info about the priority value --- _im-plugin/ism/index.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/_im-plugin/ism/index.md b/_im-plugin/ism/index.md index 5e983e45..f27e2636 100644 --- a/_im-plugin/ism/index.md +++ b/_im-plugin/ism/index.md @@ -55,6 +55,8 @@ 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: From dc69f8010b03c6081233c0434fbdcbdcb42231b0 Mon Sep 17 00:00:00 2001 From: keithhc2 Date: Mon, 27 Sep 2021 17:07:38 -0700 Subject: [PATCH 51/60] Added a setting to enable patch configuration --- _security-plugin/access-control/api.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/_security-plugin/access-control/api.md b/_security-plugin/access-control/api.md index dd5604a3..2f4a6652 100644 --- a/_security-plugin/access-control/api.md +++ b/_security-plugin/access-control/api.md @@ -1159,6 +1159,12 @@ 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`: + +```yml +plugins.security.unsupported.restapi.allow_securityconfig_modification: true +``` + #### Request ```json From cbdefc2463a7ad7d79444c2d979175201678b724 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 28 Sep 2021 10:54:04 -0700 Subject: [PATCH 52/60] Improve permissions introduction Also corrects some permissions names that still use `opendistro`, adds missing permissions, adds some short () description to unclear permissions. --- .../access-control/permissions.md | 179 +++++++++++++----- 1 file changed, 129 insertions(+), 50 deletions(-) diff --git a/_security-plugin/access-control/permissions.md b/_security-plugin/access-control/permissions.md index 6e222fbe..486745e9 100644 --- a/_security-plugin/access-control/permissions.md +++ b/_security-plugin/access-control/permissions.md @@ -7,58 +7,125 @@ nav_order: 50 # Permissions -This page is a complete list of available permissions in the security plugin. Each permission controls access to a data type or API. +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. -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/). +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. {: .tip } -## Cluster +## 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: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/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/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/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/reindex/rethrottle - cluster:admin/repository/delete - cluster:admin/repository/get @@ -94,7 +161,9 @@ Rather than creating new action groups from individual permissions, you can ofte - cluster:monitor/tasks/list -## Indices +## 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:admin/aliases - indices:admin/aliases/exists @@ -102,13 +171,22 @@ Rather than creating new action groups from individual permissions, you can ofte - indices:admin/analyze - indices:admin/cache/clear - indices:admin/close -- indices:admin/create -- indices:admin/delete +- 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/exists - indices:admin/flush - indices:admin/flush* - indices:admin/forcemerge -- indices:admin/get +- 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/mapping/put - indices:admin/mappings/fields/get - indices:admin/mappings/fields/get* @@ -137,22 +215,23 @@ Rather than creating new action groups from individual permissions, you can ofte - indices:data/read/mget* - indices:data/read/msearch - indices:data/read/msearch/template -- indices:data/read/mtv +- indices:data/read/mtv (multi-term vectors) - 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 +- indices:data/read/tv (term vectors) - indices:data/write/bulk - indices:data/write/bulk* -- indices:data/write/delete +- indices:data/write/delete (delete documents) - indices:data/write/delete/byquery -- indices:data/write/index +- indices:data/write/index (add documents to existing indices) - 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 From 01a9fb6d6d087f5727438280bb8346536381cbad Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 28 Sep 2021 11:10:36 -0700 Subject: [PATCH 53/60] Adding async back in, just in case --- _security-plugin/access-control/permissions.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/_security-plugin/access-control/permissions.md b/_security-plugin/access-control/permissions.md index 486745e9..4a203e52 100644 --- a/_security-plugin/access-control/permissions.md +++ b/_security-plugin/access-control/permissions.md @@ -101,6 +101,10 @@ These permissions are for the cluster and can't be applied granularly. For examp - 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 From 9a5c8cd6ae639d8bc7fec68b4d35beeb0e258bc7 Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 28 Sep 2021 13:53:49 -0700 Subject: [PATCH 54/60] Wording change --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index 602a8883..87301cf4 100755 --- a/index.md +++ b/index.md @@ -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 of OpenSearch plugins have a corresponding OpenSearch Dashboards plugin that provide a convenient, unified user interface. +Most OpenSearch plugins have corresponding OpenSearch Dashboards plugins that provide a convenient, unified user interface. For specifics around the project, see the [FAQ](https://opensearch.org/faq/). From d4c20f040250ab3e5fef6d43fe5f06af9ada504a Mon Sep 17 00:00:00 2001 From: aetter Date: Tue, 28 Sep 2021 15:33:48 -0700 Subject: [PATCH 55/60] Re-add LDAP Docker example Update Docker Compose file --- _security-plugin/configuration/ldap.md | 6 ++---- assets/examples/ldap-example.zip | Bin 4169 -> 5923 bytes 2 files changed, 2 insertions(+), 4 deletions(-) diff --git a/_security-plugin/configuration/ldap.md b/_security-plugin/configuration/ldap.md index 8a69ba2a..ff8da4eb 100755 --- a/_security-plugin/configuration/ldap.md +++ b/_security-plugin/configuration/ldap.md @@ -11,7 +11,6 @@ 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 @@ -38,7 +37,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. @@ -46,14 +45,13 @@ 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 /bin/bash`. -{% endcomment %} ## Connection settings diff --git a/assets/examples/ldap-example.zip b/assets/examples/ldap-example.zip index 29a2ee81eb2abae937945bedee0b8ae9c57be31f..acecc3e5c22266fc304efc68f20a275c6ac8f468 100644 GIT binary patch literal 5923 zcmdT|c{tR4_nyW!_E839DUq_Tr6LB|#x}OH&)D~EY^B85vNx2hWgEMceR)t6Le`S9 z)@ZROMd6{}e7&zH`B|>#&-b{-muu!a=X0NPpEKwFAk|1n89{)NdrRwX{PEvkw4h@k zCo6L|LF+5#&TdZD!uoo&Ad1vzU31_?h}SjuxvmUG_84nRPgl%UAtx()n+?a9>|V2b|8>62ap#>e%^(rRmM^P}+<%dkO|nyl zx18V^jk3EQ5W`VIof@Vn(j%B2}<~L9&9ltiRtW9b9P7loISLh~*Ud?zt~|YT{;P!yiYAI6&C)EP9%*cS|(P z(iUxjp4U*nG*5pi3>g5%v5=gEvL5&3ni5 zIW?^?!2pT7U2xeT+2Bs%<+!8-DxGf}1h5?LI^qV#+acEM##J*128E0UEH)&gA}J%k zL@}Z!qrzX#K|8aeEHbMmDdTooaY|X??c(sll#t@=nw0$F!mQY`tc>jJvhYaWAZ&bg z_6Z0HF%J}w_-?`@JP|p7{&!wZUZ>I8q%tWB2*k9V%0d@)QMyDbTW_$KZ&KUz{=HGN zN5h_|Z7iNml%i`AfnKzYrdE>>;vI1Vxu6x>D62tam(zdrat<<-GU^~t1YV6>ycFSY z&!z=>GhdAgpgGnUEiM!HhAFuCOc!S`R6fklveTXs&+ zzamNrD>UdQ4E_S7`~KLI0Ftwz!K89YFcH%U;7k+{>aZtgPZLi8oaFZzKUlW^GlYhS zd_TIqa`rBs))*IaCzO|mHO52es2~>agCZmaA@ck>1NVvAv$)aF zBv!}+WF$WXEmLz;x6gblV)`OI=Cc+*&_ppHg3~vl5r2C3h7EyW^+~hxt!W~&3mZpj ziaw*%0v94}CZN-{b@rR*k4Nnb*5gjcGnfkJO}r}WH8T%z=HK*scD<)GTSi4x3WvUC zn1Cn8k$r-&4@T+nT+LEu6~`BZes%tv@1+Qxv?6v~X&Hs#u)3OF->th4C}5DMXe48% z`+0=tp}C13W&UdIlCm}!s5SY&tbSzbWSh>r_fG=ryZH+ibk8;IosGdIK^7H*v+DF zMtAIHX9#vKHWMF;ra#S0;T;K6HW`lgb2bIjQ+6L_?Ck6(od_1~|KX?*OVn~G5g&l@ zH~MA2x_>x|1A{;u+c}DHb+YzAIh(t=*}K^OL(#jkJ-bmfKDOTFsR&K5&jqrKl7NJm zQLyK%I3!9@D$p8%vpVUwI@Kx{@rtZZt=#!1Pa?8r6fsMWKM+yJzWR;FV+O1c^odV600N22J4mw~W&w!lnoNb^E zynAqM@5KKPQY~rAIQ&Qf0x@r=nx(6Yjs0(qVRj#bv$_{theV(wYy1!`K_rR&U*%wF zQV5Pt@Exa=`|<8G=2LkKn)dfHf7Rm~1m0@adQu`ao{fxutE^vIF7j@+j%49Yt< zidQC@NRkZ4qPgbUU8b9A^qhy>sq`a(BV!@r!Tw9>WQ}!=xsvrcJ0ixjCtl63$<|nlom0PnwMozKpi&aM3w^ZJxvarY=9ZlqT4d z@>777Fa@3ON@x`lB{{n$o-=ZvqiHnvp-)xHz_dyw`n)U6=gH|e4mSSl&&&C7!Qr11 zL}n_!3iVE@KMqunBvdNb(+k*3;<^PKoDmo9i<{&lxvY7cTeZ?`AN0lcpIJMvFdc>_ zSss^ieEsuK!Jwr~XmyHdK6Y8TT`qP+<8}LJNwCP%4}Q-Jk$F8uk}NCQ!s?xpES$;s zRgL4{ra%1{qK3aNlH;x|Wq5&S9t0Y2^*y4$O0|q(P&Y0fY@FDmwva{R+a%Rc6^T( z+l6rdgT0mO`&&A#5cBc>Rt+mxOGj&rprxy`o2!TQKXcrexGkFyU%+$Qw)jAANOK4d z_3OSIWu#w+PJxC+oZu)5yvTq%HM!VkG^1K)Ej%}O9@@}Q)}oqouOUwW$FyHwHr61hbQC-h~0)^pBo-Nb@$vD$}Y7(t5b*6 zg?j`PA`^2%D!UqDOPd;DKB?h)V!x7B(yMe_E4*JHz7%>e`%H)4#LV2QB&zpZA{qT` zb2a==U=YUl_2}Mn#h;j5v?o^mZY7RTm7~8H8phe0u06H8enb3%77t3Ouj7MqTujSY zPHv;H{jJrT2PZx@KE9rA7WbqB0oFaIvV?q$DkTd78&cktCCIS6DCeeHfRP4%DX~8* z^OMw<+*_3*K}5CK5fc9{PU^4YMU9VFNFVurvVg2ODm1E(ik-SJ4)z(p+1eVEp*)xocFia9S=8XJ+?hD?VWw5Sh1N$t>s=UW#_3=dL`)SvMgc@^hTu`Jy&)X}v-(UlqhrMdGp1~K&| zp2MovguD}T0$+}qINsHa2}*j#C($u^_vNBT`EmK!Z-xU<@-!`rl?RV+2ANAcSq;_5 zKJ1EfPfj)UuUBnt^IY+eI49LfmGfzW%BAWl&*!$c6Q8DhR{VTr@|j=puNPx9r{|~{ zm4=ifvlizwZNy?>MK8E)CYJ`4rh0w7lw|nZ?I;`%dqqw9htV2nl6v+UGiB4~tv%FX zbCUOl9N}Q6wOFZt@%*R7Oz!eC)e8fWy>~7x-Mv04qvhB#GMzu*$oy9G*0o>6u|feE z<)l+3B>{new)#D0wl>@&;+WZMYuu;z{?)i~XD12~R+cbu3@4`?l1HT#e2fXM+Y|;( zKy-EYs|lQXuG-(BDj>uwsHvf1D%%;s^)wa9dL*WCLKig*2CWg&G zTa`3$kFaU8*!2UTUAOx^V(w6*tuXaG!P^(NmP+dgsk z0STy|t(!Wael`t{^(1!uA0YQ$$@jqs#M+7x*!?#Rk0n5M$GCUceINq+(AG@}*t$0j zj~%1j262~_Xdi4qkgeE&rEAmhSVfxMvF#FXA5g&b-8z^5B&QVZHc7azkIGWKCG(b%$tgc7pvTQnXfBE*Cu=7|`Z7(+wJ_*sWYnIe10mWnJT zl_j*$$dVPf}4u1I*Ma?TH&B8dQ z0{2}pR7`rdYg$g$9`uSJPz@IM4G6@!1-c~_*12O(1iD=&)lq7ab7?dhP?4KV%Bdhz za!D0HDVbDpr=*k|n|!CShD4Di#)>#{bFqUQZJ}I*_&Prt(=nEF|9dePhzoR%`C{h6 zk1+vEa~vQb<0xJ~<(J0=rS=^ss>2hOB9nwiRIjz(rRd3YKTwpz=DyCQ^~#nLGwVo= z^$5ocVb&M6HVmh?(Oscs2QZoyg@y^zA>NMMXyeioZ1M?{W)m0_FEh;H@_2kfF3sV!Gr+G+ND+9uRDrh58 zxvihc=eS777==QNu z{jwz7`%AfIGabqX!#BTH)c6`H&U;Jt3tS7V=EtG;I`*~@(nRLiCa>t5BpxyMQ2dnL z*O^kCss8x-X+L+-1scv8J~-jBb~;Q-#LqYGjnle`e{FB_qo_xnY7MVEC(;MS=kQ8I z5dE6&R!O~6uGg$5yk+bg;`^O72rCBVI~{y_Y#`7CQ~rrT?5-FT1IbWjf(bJQrc7bY zzr-Me(i;2>C1AD`-H~)g?sU|uD!Ouqv-Z$AB!u0kdVmqbrhuDkLPwe2xv5=qen88l zm@M=VjEaE-8e3c-E5KSCjIoU?71~5M#Rtn3ByH(lH0aRE^7x@Z7xS2y*;kn8jRksu^jFj1 zt*$vk586b9Q3ag)A|q$Gbc7cw*&gq}2Sv~0HfIJ5Q?{xmXQQok;|!fE+eepZN0<2P zbzF#WIt$GxyXQ&}CX&VA-DrC3LUR@h0wF*s;EISO0nEhmr~HEHf|LD?0d;|v4OfhQ ztQifWCQy=?kvaxK^W*FHuh&)&i9_G`7A9{lz564uKRk;kE93bKYNXVYjc?eR_hn(% z!5ubAI!7?Yb=|`q=pe@}kyt6nr|5?DH$5K`=yykw%Q+yHo z>vFM$qujmn*#x{CUMJ+Orq(0Um!^OV1?mgys{(umF*{++_{J1po-ZqRL-HTzmt)tb zZ}c>St+Ov(=6mLeToNk(w0huqtzt0Yt+SVPb8IyB#961g<+RThBu*t;rB8&-2LFtd zvWK(7;vXzHkk9wgF*O|pj@nWyhuWWw+pzZ-qWO~MgC7uFl)Hr5z`%xdrAeVl^QgC& zg}&xtx>vk^+M+ADr!tpbc@T86hLbYW?V=8N+J9wWdYq8Nt{k2$CEh-L#>&+;^-V&t zXL#`!fyWWo7dche&O)CKrKsH(ZBS-6dpYZ(5yAGnHP0+Mr7&popiGnE4H-8a-Tl7_ z7s<;_c`)mOlER_w(rlGx$DvTfWHMrVJqIDEvk840ui~F5j}%&ivT_Q(6p+Nu%qLdn z{8OQ$yK?G1faX0wSYc+m4GAYDs8N{-w) z<(ocwGDuL?`B*{q7oN3y2oc%+IsQ{(uKqq9a)q8w>8RgqgKN`@N2o%#xXFrTrox*s zJ0Bi)KkkU6viGKZG(`ssx0u!JQSp&D`#~2k(Zby$5|Ky7XnYsP_ad9IZhBu~FWJfH zTxXTAZ|@@R8g0Vt{OhhLENX;^gQXuKRCK!r+uC5H%eotp4|0rn2!Shkrx}`7h5S3KSEHqWz>}OW<;Nwc+~nFHokL#HoXq_&9}COL}Ja zYta^d@9zzYVbg~;->$LAhAqDAC5@%&H3!&aY-{GQ4QxNvcvc6oDM9}l zuBTrRnn6>Zgk9%fB9!u6P9`-T@hi9RrDj4BeBdb>A@9_}EJRy7?hSXOj2_KkV>Hju!Q|Zg}SWn?d(g?bb?>QDWq%Z_d)Ygkw1oC z_pgXXQLJDL)rQtuc)J+yj@4bEc($8o*3i6Q(xP>4*Mx`sG&YKyK81I(b!YUPY*?!! z9`DuFX*^bhv*~WLZONI59xUsWo3a&72p%^n3(o=ENLVG03r&O+tSJg@VCa(cdbspz z{z63MKyp+DA@~O0i{{T>d-)SK=u+d$Ub;JnsjzM9&bMHX&IN<>IDN4csYOP+;oV^X zr_u7+&|t2C<_?`|wo|2p=B0|Zc@aN>ms4rbTcWlfzEAc#o8ezqUh z{KFXQU)hb)zkST+0s$Ca`M-f;0rtZf>zD@U^7tvHi7KWj|H~K$3}_WS^!KSB@G?XZ Qd@Q=>&JF^-gRwmO6GpYbl>h($ From 65d2ef48600268d16372a15485f39e53e87eb04e Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 29 Sep 2021 09:29:41 -0700 Subject: [PATCH 56/60] Re-add SAML example --- _security-plugin/configuration/saml.md | 8 +++----- assets/examples/saml-example.zip | Bin 3388 -> 4580 bytes 2 files changed, 3 insertions(+), 5 deletions(-) diff --git a/_security-plugin/configuration/saml.md b/_security-plugin/configuration/saml.md index e2d71f0f..a2a789e7 100755 --- a/_security-plugin/configuration/saml.md +++ b/_security-plugin/configuration/saml.md @@ -11,7 +11,6 @@ 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 @@ -35,7 +34,6 @@ 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 @@ -300,13 +298,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: -``` -plugins.security.auth.type: "saml" +```yml +opensearch_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"] ``` diff --git a/assets/examples/saml-example.zip b/assets/examples/saml-example.zip index fb0e026509185bfe051b240cfe89cca9fdee6c05..32c53c525b99791e634f2fc0d07ab84a322efe5b 100644 GIT binary patch literal 4580 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 I%*A;659D54xX6c= z8RXTqu2j6s-Qa%x4fW$YV2js*XL1(>&+k-wq((f3`|n6DfXU^Y5pUvXHDd?3dSgXc z!=MU1c3Wd(;~Q|gP2pXM+`8h|C-CA%Dlx`!HwlhUn(uX4HU+8OJ>J1OP|@8-lRv9o z^r*qK8s3`Gv7d~DYPCjGNZmZGakJV=`m)7AW!JeX?uKE-6P-`)UDK9uTk2O zlIkdLu?x+aiQM6;=VHu9w_Z!+OijNF&Gt$=6f`JPU%9WM$LE1Vu66-}YC_)&ZIe;p z&cD^!BhGb09Z4c8oD*AXyL_Qz($ zu2L75irjgP`UBdw6p*(L1bS#CLo@oo1Br*z_R^*%D(UGgE1R7d;+5{V16igW#wm>m z9_EzRn10OO4@zB#f{NE;{fKnFM-ekV`F(zl9khDeHKrCUMKIMN{?k2(fn0#H_V^-R z5Bpp??bvxevU`o@1n=9451~JLE(Ob=d4MAeW`-}$sFL>2xhh)1y;41p_cK=>jvg2H z$JUhh?w-suPoA;uh?8!Ck!%)Xn&i0Jmfe+&Y!~_i3@?4OJM?6w#1EV?*0$r+gWhfh zl3RFq$M9ZSndLi`ECxHZ|F+?C>2H8I3>3EK#lmO|2mlb_`;U=dDI}7S5cytSSaVB9 z{2{$h*rer!NaD_#B3ZZQQMW$l27Ou2dX}?9MUn>`8u+ z_C4rJ%MbQ;M46wK?`Uo%xY>J<3})WEZ&xLkpUSvA9TR;aFed#Ar-^*2 zLg`-)B-%PFo=?m%DB5~?%v!fY-o8*i*n1{`zvx$$t9`XsHssQNeCFLtb2)i!)y76o zsWI_PP9c9-=HBM;NsViB3bV{q<#)**?-Hbl*X8S|M}yi7r|-w4boQyQd;|_ky8gy9 zAOIkO$8W&7zQz@LB>(``^}z9E_#B~zqI?*1CL@gcD}XKwePDI115g)XkkO|PKQ-$W zQjq;K2uw5gRR33}{FSmk*1^3qsGX0^%O6Ghnc#lzZg+S)4C$FD4(v;*n&p`c4jdiV zx4lw2WR{zEDGzZjY)j$1Bfu(+sFo4ZH?;k3bruk3<2NBj8FgneQjl3yL)o~roi9&s zcImQ~urMoeW+o8%x52anx$<^}L5J&jKGhrsQ_!}FHq~z-bJg3xwl+xnfx2CMXCTy* z3o|y!z&Y&EaDR}r&qiTEVXv&(%}&lJHo?A$dhX0p6_?6lN~+67L8PwYJCJPiLny?v z?D>mq2|sVAnu}-A36js)qqR?i?sP*a;mT1`1;Z0+(|dWly68uhF0^G1JZn{HRd0}l zoYrb+!q@UO!azvQR=Ma$#s|L=-({sfRfg>`)C3L)pm016lW7_k!t^3}`kr&D5ZtVI zNm2!#yAY_lWhQl-#?BBh(LNx-HHzE6Z?-qd&1s&E#q~|mBkpD+E=aly0%=whcP7HV zMnE4mBp0YzT6Q((3^i;}<#3&GS!eBBkU1&k}9rz~+HB|v8 ziWf`51;p#q0JHYw&1219SWAvrIM*)-aul`Fxbtk{!I=kds=g0=8`*1jg5a%yw>q<5 zQriG2WoQv_N@>`@q5)kUMM{;it%uKt#0YF^O+MuDRac&vq{WQ$H?I`>FV$=Pkgiqm zx?SrfeI^H<B1hYj9( zSE%|8>Br}vNsioV5l~xdFl`y0#N6e`D=HUj?mvEFOLOxhjmmb9A7OlW>?qP;emi&S zh0tb1g!yACiPTy9FKp&BtorATCCZH`FI6xrsH3rIALU`Q&UOItS6=~w9Ol!~Yn@ay60AlM%UTTZ zj|~WGPa$&cwX!U7?bRq^A%sHx$-njazdd|y5s|{L1*}NnSEGnUfvhX?8Dxqy|1bWl rsMuO0i8!ztMXYimU;b?H`b^zFU<3{$E<8K{01;lrLN>-qir)SUDuy(d From 973d967514c325f6a27a5da6599433ebea86057a Mon Sep 17 00:00:00 2001 From: aetter Date: Wed, 29 Sep 2021 14:57:46 -0700 Subject: [PATCH 57/60] Update impersonation.md --- _security-plugin/access-control/impersonation.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/_security-plugin/access-control/impersonation.md b/_security-plugin/access-control/impersonation.md index 82966389..100d1104 100644 --- a/_security-plugin/access-control/impersonation.md +++ b/_security-plugin/access-control/impersonation.md @@ -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 `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: +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: ```bash -curl -XGET -u 'admin:admin' -k -H "opensearch_security_impersonate_as: user_1" https://localhost:9200/_plugins/_security/authinfo?pretty +curl -XGET -u 'admin:admin' -k -H "opendistro_security_impersonate_as: user_1" https://localhost:9200/_plugins/_security/authinfo?pretty ``` From ab00a055490e09d13d5b45c5a5e682e8465f1002 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 30 Sep 2021 13:48:32 -0700 Subject: [PATCH 58/60] Comment out Java for now --- _clients/index.md | 2 ++ _clients/python.md | 2 +- 2 files changed, 3 insertions(+), 1 deletion(-) diff --git a/_clients/index.md b/_clients/index.md index d920e16a..2f3513dd 100644 --- a/_clients/index.md +++ b/_clients/index.md @@ -13,7 +13,9 @@ OpenSearch provides clients for several popular programming languages, with more For example, a 1.0.0 client works with an OpenSearch 1.1.0 cluster, but might not support any non-breaking API changes in OpenSearch 1.1.0. A 1.2.0 client works with the same cluster, but might allow you to pass unsupported options in certain functions. We recommend using the same version for both, but if your tests pass after a cluster upgrade, you don't necessarily need to upgrade your clients immediately. +{% comment %} * [OpenSearch Java client]({{site.url}}{{site.baseurl}}/clients/java/) +{% endcomment %} * [OpenSearch Python client]({{site.url}}{{site.baseurl}}/clients/python/) * [OpenSearch JavaScript (Node.js) client]({{site.url}}{{site.baseurl}}/clients/javascript/) * [OpenSearch Go client]({{site.url}}{{site.baseurl}}/clients/go/) diff --git a/_clients/python.md b/_clients/python.md index 9ce68bca..10a856a2 100644 --- a/_clients/python.md +++ b/_clients/python.md @@ -6,7 +6,7 @@ nav_order: 70 # Python client -The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests with raw JSON bodies to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. +The OpenSearch Python client provides a more natural syntax for interacting with your cluster. Rather than sending HTTP requests to a given URL, you can create an OpenSearch client for your cluster and call the client's built-in functions. {% comment %} `opensearch-py` is the lower-level of the two Python clients. If you want a general client for assorted operations, it's a great choice. If you want a higher-level client strictly for indexing and search operations, consider [opensearch-dsl-py]({{site.url}}{{site.baseurl}}/clients/python-dsl/). From 7cb714894fba8d1401dbab84824384b226cea616 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 30 Sep 2021 13:52:34 -0700 Subject: [PATCH 59/60] Nitpicks --- _clients/javascript.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/_clients/javascript.md b/_clients/javascript.md index cb308a29..c670e4b8 100644 --- a/_clients/javascript.md +++ b/_clients/javascript.md @@ -1,18 +1,18 @@ --- layout: default -title: Javascript client +title: JavaScript client nav_order: 90 --- -# Javascript client +# JavaScript client -The OpenSearch Javascript client provides a safer and easier way to interact with your OpenSearch cluster. Rather than using OpenSearch from the browser and potentially exposing your data to the public, you can build an OpenSearch client that takes care of sending requests to your cluster. +The OpenSearch JavaScript client provides a safer and easier way to interact with your OpenSearch cluster. Rather than using OpenSearch from the browser and potentially exposing your data to the public, you can build an OpenSearch client that takes care of sending requests to your cluster. The client contains a library of APIs that let you perform different operations on your cluster and return a standard response body. The example here demonstrates some basic operations like creating an index, adding documents, and searching your data. ## Setup -To add the client to your project, install it from npm: +To add the client to your project, install it from [npm](https://www.npmjs.com): ```bash npm install @opensearch-project/opensearch From c378da8799fa3c10e85dc42905c859cf902e28f7 Mon Sep 17 00:00:00 2001 From: aetter Date: Thu, 30 Sep 2021 14:01:14 -0700 Subject: [PATCH 60/60] Make name more explicit --- _clients/java-rest-high-level.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/_clients/java-rest-high-level.md b/_clients/java-rest-high-level.md index def97086..892f7341 100644 --- a/_clients/java-rest-high-level.md +++ b/_clients/java-rest-high-level.md @@ -1,10 +1,10 @@ --- layout: default -title: Java high-level REST client +title: Elasticsearch OSS Java high-level REST client nav_order: 60 --- -# Java high-level REST client +# Elasticsearch OSS Java high-level REST client The Elasticsearch OSS Java high-level REST client allows you to interact with your OpenSearch clusters and indices through Java methods and data structures rather than HTTP methods and JSON. @@ -22,7 +22,7 @@ To start using the Elasticsearch OSS Java high-level REST client, ensure that yo ``` -You can now start your OpenSearch cluster. The 7.10.2 high-level REST client works with the 1.x versions of OpenSearch. +You can now start your OpenSearch cluster. The 7.10.2 Elasticsearch OSS high-level REST client works with the 1.x versions of OpenSearch. ## Sample code