Comment out Java for now

Troubleshooting expired certificates, settings, broken link, etc.

_clients/agents-and-ingestion-tools/index.md

@@ -27,12 +27,18 @@ PUT _cluster/settings
 }
 ```
 
+[Just like any other setting]({{site.url}}{{site.baseurl}}/opensearch/configuration/), the alternative is to add the following line to `opensearch.yml` on each node and then restart the node:
+
+```yml
+compatibility.override_main_response_version: true
+```
+
 
 ## Downloads
 
 You can download the OpenSearch output plugin for Logstash from [OpenSearch downloads](https://opensearch.org/downloads.html). The Logstash output plugin is compatible with OpenSearch and Elasticsearch OSS (7.10.2 or lower).
 
-These 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)
@@ -41,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 }
 
 

_clients/index.md

@@ -9,6 +9,20 @@ 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.
+
+{% 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/)
+
+
+## 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 +32,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 %}

_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

_clients/python.md

@@ -0,0 +1,128 @@
+---
+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 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-py
+```
+
+Then import it like any other module:
+
+```python
+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).
+
+
+## Sample code
+
+```python
+from opensearchpy 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-index'
+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)
+```

_monitoring-plugins/pa/dashboards.md

@@ -1,6 +1,6 @@
 ---
 layout: default
-title: Create Dashboards
+title: Create PerfTop Dashboards
 parent: Performance Analyzer
 nav_order: 2
 ---

_monitoring-plugins/pa/index.md

@@ -48,11 +48,11 @@ Otherwise, just specify the OpenSearch endpoint:
 ./opensearch-perf-top-macos --dashboard dashboards/<dashboard>.json --endpoint my-cluster.my-domain.com
 ```
 
-PerfTop has four pre-built dashboards in the `dashboards` directory, but you can also [create your own]({{site.url}}{{site.baseurl}}/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 }
 
 

_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/).

_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:

_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.

_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 use it to check the document count of an index, data stream, or cluster.
+
+
+## Example
+
+To see the number of documents that match a query:
+
+```json
+GET opensearch_dashboards_sample_data_logs/_count
+{
+  "query": {
+    "term": {
+      "response": "200"
+    }
+  }
+}
+```
+
+The following call to the search API produces equivalent results:
+
+```json
+GET opensearch_dashboards_sample_data_logs/_search
+{
+  "query": {
+    "term": {
+      "response": "200"
+    }
+  },
+  "size": 0,
+  "track_total_hits": true
+}
+```
+
+To see the number of documents in an index:
+
+```json
+GET opensearch_dashboards_sample_data_logs/_count
+```
+
+To check for the number of documents in a [data stream]({{site.url}}{{site.baseurl}}/opensearch/data-streams/), replace the index name with the data stream name.
+
+To see the number of documents in your cluster:
+
+```json
+GET _count
+```
+
+Alternatively, you could use the [cat indices]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/cat-indices/) and [cat count]({{site.url}}{{site.baseurl}}/opensearch/rest-api/cat/cat-count/) APIs to see the number of documents per index or data stream.
+{: .note }
+
+
+## Path and HTTP methods
+
+```
+GET <target>/_count/<id>
+POST <target>/_count/<id>
+```
+
+
+## URL parameters
+
+All count parameters are optional.
+
+Parameter | Type | Description
+:--- | :--- | :---
+`allow_no_indices` | Boolean | If false, the request returns an error if any wildcard expression or index alias targets any closed or missing indices. Default is false.
+`analyzer` | String | The analyzer to use in the query string.
+`analyze_wildcard` | Boolean | Specifies whether to analyze wildcard and prefix queries. Default is false.
+`default_operator` | String | Indicates whether the default operator for a string query should be AND or OR. Default is OR.
+`df` | String | The default field in case a field prefix is not provided in the query string.
+`expand_wildcards` | String | Specifies the type of index that wildcard expressions can match. Supports comma-separated values. Valid values are `all` (match any index), `open` (match open, non-hidden indices), `closed` (match closed, non-hidden indices), `hidden` (match hidden indices), and `none` (deny wildcard expressions). Default is `open`.
+`ignore_unavailable` | Boolean | Specifies whether to include missing or closed indices in the response. Default is false.
+`lenient` | Boolean | Specifies whether OpenSearch should accept requests if queries have format errors (for example, querying a text field for an integer). Default is false.
+`min_score` | Float |	Include only documents with a minimum `_score` value in the result.
+`routing` | String | Value used to route the operation to a specific shard.
+`preference` | String | Specifies which shard or node OpenSearch should perform the count operation on.
+`terminate_after` | Integer | The maximum number of documents OpenSearch should process before terminating the request.
+
+## Response
+
+```json
+{
+  "count" : 14074,
+  "_shards" : {
+    "total" : 1,
+    "successful" : 1,
+    "skipped" : 0,
+    "failed" : 0
+  }
+}
+```

_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 rebalancing for all shards), `primaries` (allow rebalancing only for primary shards), `replicas` (allow rebalancing only for replicas), and `none` (do not allow rebalancing). Default is `all`.
-index.routing.rebalance.enable | Enables shard rebalancing for the index. Available options are `all` (allow shard rebalancing for all shards), `primaries`, (allow shard rebalancing only for primary shards), `replicas` (allow shard rebalancing only for replicas), and `none` (do not allow shard rebalancing). Default is `all`.
 index.gc_deletes | Amount of time to retain a deleted document's version number. Default is `60s`.
 index.default_pipeline | The default ingest node pipeline for the index. If the default pipeline is set and the pipeline does not exist, then index requests fail. The pipeline name `_none` specifies that the index does not have an ingest pipeline.
 index.final_pipeline | The final ingest node pipeline for the index. If the final pipeline is set and the pipeline does not exist, then index requests fail. The pipeline name `_none` specifies that the index does not have an ingest pipeline.
 
+
 ### Mappings
 
 Mappings define how a documents and its fields are stored and indexed. If you're just starting to build out your cluster and data, you may not know exactly how your data should be stored. In those cases, you can use dynamic mappings, which tell OpenSearch to dynamically add data and their fields. However, if you know exactly what types your data fall under and want to enforce that standard, then you can use explicit mappings.

_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
 {

_security-plugin/access-control/api.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: API
-parent: Access Control
+parent: Access control
 nav_order: 90
 ---
 

_security-plugin/access-control/cross-cluster-search.md

@@ -1,7 +1,7 @@
 ---
 layout: default
-title: Cross-Cluster Search
+title: Cross-cluster search
-parent: Access Control
+parent: Access control
 nav_order: 40
 ---
 

_security-plugin/access-control/default-action-groups.md

@@ -1,7 +1,7 @@
 ---
 layout: default
-title: Default Action Groups
+title: Default action groups
-parent: Access Control
+parent: Access control
 nav_order: 51
 ---
 

_security-plugin/access-control/document-level-security.md

@@ -1,7 +1,7 @@
 ---
 layout: default
-title: Document-Level Security
+title: Document-level security
-parent: Access Control
+parent: Access control
 nav_order: 10
 ---
 

_security-plugin/access-control/field-level-security.md

@@ -1,7 +1,7 @@
 ---
 layout: default
-title: Field-Level Security
+title: Field-level security
-parent: Access Control
+parent: Access control
 nav_order: 11
 ---
 

_security-plugin/access-control/field-masking.md

@@ -1,7 +1,7 @@
 ---
 layout: default
-title: Field Masking
+title: Field masking
-parent: Access Control
+parent: Access control
 nav_order: 12
 ---
 

_security-plugin/access-control/impersonation.md

@@ -1,7 +1,7 @@
 ---
 layout: default
-title: User Impersonation
+title: User impersonation
-parent: Access Control
+parent: Access control
 nav_order: 20
 ---
 

_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

_security-plugin/access-control/multi-tenancy.md

@@ -1,7 +1,7 @@
 ---
 layout: default
-title: OpenSearch Dashboards Multi-Tenancy
+title: OpenSearch Dashboards multi-tenancy
-parent: Access Control
+parent: Access control
 nav_order: 30
 ---
 
@@ -47,21 +47,21 @@ Setting | Description
 opensearch.username: kibanaserver
 opensearch.password: kibanaserver
 opensearch.requestHeadersWhitelist: ["securitytenant","Authorization"]
-plugins.security.multitenancy.enabled: true
+opensearch_security.multitenancy.enabled: true
-plugins.security.multitenancy.tenants.enable_global: true
+opensearch_security.multitenancy.tenants.enable_global: true
-plugins.security.multitenancy.tenants.enable_private: true
+opensearch_security.multitenancy.tenants.enable_private: true
-plugins.security.multitenancy.tenants.preferred: ["Private", "Global"]
+opensearch_security.multitenancy.tenants.preferred: ["Private", "Global"]
-plugins.security.multitenancy.enable_filter: false
+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.
+`opensearch_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.
+`opensearch_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.
+`opensearch_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.
+`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.
-`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.enable_filter` | If you have many tenants, you can add a search bar to the top of the list. Default is false.
 
 
 ## Add tenants

_security-plugin/access-control/permissions.md

@@ -1,7 +1,7 @@
 ---
 layout: default
 title: Permissions
-parent: Access Control
+parent: Access control
 nav_order: 50
 ---
 

_security-plugin/access-control/users-roles.md

@@ -1,7 +1,7 @@
 ---
 layout: default
-title: Users and Roles
+title: Users and roles
-parent: Access Control
+parent: Access control
 nav_order: 1
 ---
 
@@ -109,7 +109,7 @@ Role | Description
 `anomaly_full_access` | Grants full permissions to all anomaly detection actions.
 `anomaly_read_access` | Grants permissions to view detectors, but not create, modify, or delete detectors.
 `all_access` | Grants full access to the cluster: all cluster-wide operations, write to all indices, write to all tenants.
-`kibana_read_only` | A special role that prevents users from making changes to visualizations, dashboards, and other OpenSearch Dashboards objects. See `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.

_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.
@@ -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):
 

_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 <certificate>
+```
+
+
 ## Encryption at rest
 
 The operating system for each OpenSearch node handles encryption of data at rest. To enable encryption at rest in most Linux distributions, use the `cryptsetup` command:
@@ -85,8 +101,3 @@ The security plugin blocks the update by script operation (`POST <index>/_update
 ## Illegal reflective access operation in logs
 
 This is a known issue with Performance Analyzer that shouldn't affect functionality.
-
-
-## Multi-tenancy issues in OpenSearch Dashboards
-
-If you're testing multiple users in OpenSearch Dashboards and encounter unexpected changes in tenant, use Google Chrome in an Incognito window or Firefox in a Private window.

_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).