[Docs] Misc doc update for RCS 2.0 (#98472)

This PR adds docs for the following items: * Remote indices privileges *
Remote cluster network settings * Remote cluster security settings * New
privileges * New response field for RemoteInfo API

List of preview pages: * [Remote indices in defining
roles](https://elasticsearch_98472.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/defining-roles.html#roles-remote-indices-priv)
* [Remote indices in PutRole
API](https://elasticsearch_98472.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/security-api-put-role.html#security-api-put-role-request-body)
* [Remote cluster server SSL
settings](https://elasticsearch_98472.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/security-settings.html#_remote_cluster_server_api_key_based_model_tlsssl_settings)
* [Remote cluster client SSL
settings](https://elasticsearch_98472.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/security-settings.html#_remote_cluster_client_api_key_based_model_tlsssl_settings)
* [Remote cluster network
settings](https://elasticsearch_98472.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/modules-network.html#remote-cluster-network-settings)
and
[here](https://elasticsearch_98472.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/modules-network.html#common-network-settings)
* [Remote cluster credentials
setting](https://elasticsearch_98472.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/remote-clusters-settings.html)
* [New
privileges](https://elasticsearch_98472.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/security-privileges.html)
* [New response field for RemoteInfo
API](https://elasticsearch_98472.docs-preview.app.elstc.co/guide/en/elasticsearch/reference/master/cluster-remote-info.html#cluster-remote-info-api-response-body)

docs/reference/cluster/remote-info.asciidoc

@@ -67,3 +67,9 @@ Refer to <<skip-unavailable-clusters>>.
 `max_proxy_socket_connections`::
     The maximum number of socket connections to the remote cluster when proxy
     mode is configured.
+
+`cluster_credentials`::
+// TODO: fix the link to new page of API key based remote clusters
+beta:[]
+This field presents and has value of `::es_redacted::` only when the remote cluster
+is configured with the API key based model. Otherwise, the field is not present.

docs/reference/modules/cluster/remote-clusters-settings.asciidoc

@@ -64,6 +64,20 @@ mode are described separately.
   are `deflate` and `lz4`. If unset, the global `transport.compression_scheme`
   is used as the fallback setting.
 
+
+// TODO: fix the link to new page of API key based remote clusters
+
+`cluster.remote.<cluster_alias>.credentials` (<<secure-settings,Secure>>)::
+
+beta:[]
+  Per cluster setting for configuring remote clusters with the API Key based model.
+  This setting takes the encoded value of a
+  <<security-api-create-cross-cluster-api-key,cross-cluster API key>> and must be set
+  in the <<secure-settings,{es} keystore>> on each node in the cluster.
+  The presence (or not) of this setting determines which model a remote cluster uses.
+  If present, the remote cluster uses the API key based model.
+  Otherwise, it uses the certificate based model.
+
 [[remote-cluster-sniff-settings]]
 ==== Sniff mode remote cluster settings
 
@@ -103,4 +117,4 @@ mode are described separately.
   the TLS Server Name Indication extension if
   <<encrypt-internode-communication,TLS is enabled>>. The TLS transport will fail to open
   remote connections if this field is not a valid hostname as defined by the
-  TLS SNI specification.
+  TLS SNI specification.

docs/reference/modules/network.asciidoc

@@ -62,6 +62,13 @@ master-eligible node.
 +
 Defaults to `9300-9400`.
 
+`remote_cluster.port`::
+(<<static-cluster-setting,Static>>, integer)
+beta:[]
+The port to bind for remote cluster client communication. Accepts a single value.
++
+Defaults to `9443`.
+
 [[network-interface-values]]
 ==== Special values for network addresses
 
@@ -257,6 +264,8 @@ include::http.asciidoc[]
 
 include::transport.asciidoc[]
 
+include::remote-cluster-network.asciidoc[]
+
 include::network/tracers.asciidoc[]
 
 include::network/threading.asciidoc[]

docs/reference/modules/remote-cluster-network.asciidoc

@@ -0,0 +1,103 @@
+[[remote-cluster-network-settings]]
+==== Advanced remote cluster (API key based model) settings
+
+beta::[]
+
+Use the following advanced settings to configure the remote cluster interface (API key based model)
+independently of the <<transport-settings,transport interface>>. You can also
+configure both interfaces together using the <<common-network-settings,network settings>>.
+
+`remote_cluster_server.enabled`::
+(<<static-cluster-setting,Static>>, boolean)
+Determines whether the remote cluster server should be enabled. This setting must
+be `true` for `remote_cluster.port` and all following remote cluster settings to
+take effect. Enabling it allows the cluster to serve cross-cluster requests using
+the API key based model. Defaults to `false`.
+
+`remote_cluster.host`::
+(<<static-cluster-setting,Static>>, string)
+Sets the address of this node for remote cluster server traffic. The node will bind to this
+address and will also use it as its remote cluster server publish address. Accepts an IP
+address, a hostname, or a <<network-interface-values,special value>>.
+Use this setting only if you require different configurations for the
+remote cluster server and transport interfaces.
++
+Defaults to the address given by `transport.bind_host`.
+
+`remote_cluster.bind_host`::
+(<<static-cluster-setting,Static>>, string)
+The network address(es) to which the node should bind in order to listen for
+incoming remote cluster connections. Accepts a list of IP addresses, hostnames, and
+<<network-interface-values,special values>>. Defaults to the address given by
+`remote_cluster.host`. Use this setting only if you require
+to bind to multiple addresses or to use different addresses for publishing and
+binding, and you also require different binding configurations for the
+remote cluster server and transport interfaces.
+
+`remote_cluster.publish_host`::
+(<<static-cluster-setting,Static>>, string)
+The network address at which the node can be contacted by other nodes. Accepts
+an IP address, a hostname, or a <<network-interface-values,special value>>.
+Defaults to the address given by `remote_cluster.host`.
+Use this setting only if you require to bind to multiple addresses or to use
+different addresses for publishing and binding, and you also require different
+binding configurations for the remote cluster server and transport interfaces.
+
+`remote_cluster.publish_port`::
+(<<static-cluster-setting,Static>>, integer)
+The port of the <<modules-network-binding-publishing,remote cluster server publish
+address>>. Set this parameter only if you need the publish port to be
+different from `remote_cluster.port`. Defaults to the port assigned via
+`remote_cluster.port`.
+
+`remote_cluster.tcp.keep_alive`::
+(<<static-cluster-setting,Static>>, boolean)
+Configures the `SO_KEEPALIVE` option for remote cluster sockets, which determines
+whether they send TCP keepalive probes. Defaults to `transport.tcp.keep_alive`.
+
+`remote_cluster.tcp.keep_idle`::
+(<<static-cluster-setting,Static>>, integer)
+Configures the `TCP_KEEPIDLE` option for transport sockets, which determines
+the time in seconds that a connection must be idle before starting to send TCP
+keepalive probes. Defaults to `transport.tcp.keep_idle` if set, or the system
+default otherwise. This value cannot exceed `300` seconds. In cases where the
+system default is higher than `300`, the value is automatically lowered to
+`300`. Only applicable on Linux and macOS.
+
+`remote_cluster.tcp.keep_interval`::
+(<<static-cluster-setting,Static>>, integer)
+Configures the `TCP_KEEPINTVL` option for transport sockets, which determines
+the time in seconds between sending TCP keepalive probes. Defaults to
+`transport.tcp.keep_interval` if set, or the system default otherwise. This value
+cannot exceed `300` seconds. In cases where the system default is higher than
+`300`, the value is automatically lowered to `300`. Only applicable on Linux
+and macOS.
+
+`remote_cluster.tcp.keep_count`::
+(<<static-cluster-setting,Static>>, integer)
+Configures the `TCP_KEEPCNT` option for transport sockets, which determines the
+number of unacknowledged TCP keepalive probes that may be sent on a connection
+before it is dropped. Defaults to `transport.tcp.keep_count` if set, or the
+system default otherwise. Only applicable on Linux and macOS.
+
+`remote_cluster.tcp.no_delay`::
+(<<static-cluster-setting,Static>>, boolean)
+Configures the `TCP_NODELAY` option on transport sockets, which determines
+whether {wikipedia}/Nagle%27s_algorithm[TCP no delay] is enabled. Defaults to
+`transport.tcp.no_delay`.
+
+`remote_cluster.tcp.reuse_address`::
+(<<static-cluster-setting,Static>>, boolean)
+Configures the `SO_REUSEADDR` option for network sockets, which determines
+whether the address can be reused or not. Defaults to
+`transport.tcp.reuse_address`.
+
+`remote_cluster.tcp.send_buffer_size`::
+(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
+The size of the TCP send buffer for transport traffic. Defaults to
+`transport.tcp.send_buffer_size`.
+
+`remote_cluster.tcp.receive_buffer_size`::
+(<<static-cluster-setting,Static>>, <<byte-units,byte value>>)
+The size of the TCP receive buffer for transport traffic. Defaults to
+`transport.tcp.receive_buffer_size`.

docs/reference/settings/security-settings.asciidoc

@@ -2563,6 +2563,36 @@ include::ssl-settings.asciidoc[]
 
 include::ssl-settings.asciidoc[]
 
+[[remote-cluster-server-tls-ssl-settings]]
+
+beta::[]
+
+:ssl-prefix:             xpack.security.remote_cluster_server
+:component:              Remote cluster server (API key based model)
+:client-auth-default:    none
+:verifies!:
+:server:
+:secure-pass:
+:ssl-context:            security-remote-cluster-server
+:ssl-layer:              remote cluster server networking layer, which {es} uses to communicate with remote cluster clients
+
+include::ssl-settings.asciidoc[]
+
+[[remote-cluster-client-tls-ssl-settings]]
+
+beta::[]
+
+:ssl-prefix:             xpack.security.remote_cluster_client
+:component:              Remote cluster client (API key based model)
+:client-auth-default:    none
+:verifies:
+:server!:
+:secure-pass:
+:ssl-context:            security-remote-cluster-client
+:ssl-layer:              remote cluster client networking layer, which {es} uses to communicate with remote cluster servers
+
+include::ssl-settings.asciidoc[]
+
 [[ssl-tls-profile-settings]]
 [discrete]
 ===== Transport profile TLS/SSL settings

docs/reference/settings/ssl-settings.asciidoc

@@ -31,9 +31,9 @@ endif::server[]
 ifndef::verifies[]
 The SSL settings in `pass:a[{ssl-prefix}.ssl]` control a _server context_ for TLS, which
 defines the settings for the TLS connection. The use of `verification_mode` in
-a TLS _server_ is discouraged. 
+a TLS _server_ is discouraged.
 endif::verifies[]
-Defines how to verify the certificates presented by another party in the TLS 
+Defines how to verify the certificates presented by another party in the TLS
 connection:
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-verification-mode-values]
 
@@ -62,9 +62,11 @@ When using PEM encoded files, use the following settings:
 (<<static-cluster-setting,Static>>)
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-pem]
 
+ifndef::secure-pass[]
 +{ssl-prefix}.ssl.key_passphrase+::
 (<<static-cluster-setting,Static>>)
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-key-passphrase]
+endif::secure-pass[]
 
 +{ssl-prefix}.ssl.secure_key_passphrase+::
 (<<secure-settings,Secure>>)
@@ -87,17 +89,21 @@ and certificates that should be trusted, use the following settings:
 (<<static-cluster-setting,Static>>)
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]
 
+ifndef::secure-pass[]
 +{ssl-prefix}.ssl.keystore.password+::
 (<<static-cluster-setting,Static>>)
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]
+endif::secure-pass[]
 
 +{ssl-prefix}.ssl.keystore.secure_password+::
 (<<secure-settings,Secure>>)
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]
 
+ifndef::secure-pass[]
 +{ssl-prefix}.ssl.keystore.key_password+::
 (<<static-cluster-setting,Static>>)
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password]
+endif::secure-pass[]
 
 +{ssl-prefix}.ssl.keystore.secure_key_password+::
 (<<secure-settings,Secure>>)
@@ -107,9 +113,11 @@ include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-key
 (<<static-cluster-setting,Static>>)
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]
 
+ifndef::secure-pass[]
 +{ssl-prefix}.ssl.truststore.password+::
 (<<static-cluster-setting,Static>>)
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]
+endif::secure-pass[]
 
 +{ssl-prefix}.ssl.truststore.secure_password+::
 (<<secure-settings,Secure>>)
@@ -131,17 +139,21 @@ include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-path]
 (<<static-cluster-setting,Static>>)
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-type-pkcs12]
 
+ifndef::secure-pass[]
 +{ssl-prefix}.ssl.keystore.password+::
 (<<static-cluster-setting,Static>>)
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-password]
+endif::secure-pass[]
 
 +{ssl-prefix}.ssl.keystore.secure_password+::
 (<<secure-settings,Secure>>)
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-secure-password]
 
+ifndef::secure-pass[]
 +{ssl-prefix}.ssl.keystore.key_password+::
 (<<static-cluster-setting,Static>>)
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-keystore-key-password]
+endif::secure-pass[]
 
 +{ssl-prefix}.ssl.keystore.secure_key_password+::
 (<<secure-settings,Secure>>)
@@ -156,9 +168,11 @@ include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-path]
 Set this to `PKCS12` to indicate that the truststore is a PKCS#12 file.
 //TBD:Should this use the ssl-truststore-type definition and default values?
 
+ifndef::secure-pass[]
 +{ssl-prefix}.ssl.truststore.password+::
 (<<static-cluster-setting,Static>>)
 include::{es-repo-dir}/settings/common-defs.asciidoc[tag=ssl-truststore-password]
+endif::secure-pass[]
 
 +{ssl-prefix}.ssl.truststore.secure_password+::
 (<<secure-settings,Secure>>)

x-pack/docs/en/rest-api/security/create-roles.asciidoc

@@ -74,6 +74,26 @@ that begin with `_` are reserved for system usage.
 For more information, see
 <<run-as-privilege>>.
 
+`remote_indices`:: beta:[] (list) A list of remote indices permissions entries.
++
+--
+// TODO: fix the link to new page of API key based remote clusters
+NOTE: Remote indices are effective for remote clusters configured with the API key based model.
+They have no effect for remote clusters configured with the certificate based model.
+--
+`clusters` (required)::: (list) A list of cluster aliases to which the permissions
+in this entry apply.
+`field_security`::: (object) The document fields that the owners of the role have
+read access to. For more information, see
+<<field-and-document-access-control>>.
+`names` (required)::: (list) A list of indices (or index name patterns) on the remote clusters
+(specified with `clusters`) to which the permissions in this entry apply.
+`privileges`(required)::: (list) The index level privileges that the owners of the role
+have on the specified indices.
+`query`::: A search query that defines the documents the owners of the role have
+read access to. A document within the specified indices must match this query in
+order for it to be accessible by the owners of the role.
+
 For more information, see <<defining-roles>>.
 
 [[security-api-put-role-example]]
@@ -141,3 +161,22 @@ POST /_security/role/cli_or_drivers_minimal
 }
 --------------------------------------------------
 // end::sql-queries-permission[]
+
+The following example configures a role with remote indices privileges on a remote cluster:
+[source,console]
+--------------------------------------------------
+POST /_security/role/role_with_remote_indices
+{
+  "remote_indices": [
+    {
+      "clusters": [ "my_remote" ], <1>
+      "names": ["logs*"], <2>
+      "privileges": ["read", "read_cross_cluster", "view_index_metadata"] <3>
+    }
+  ]
+}
+--------------------------------------------------
+
+<1> The remote indices privileges apply to remote cluster with the alias `my_remote`.
+<2> Privileges are granted for indices matching pattern `logs*` on the remote cluster ( `my_remote`).
+<3> The actual <<privileges-list-indices,index privileges>> granted for `logs*` on `my_remote`.

x-pack/docs/en/security/authorization/managing-roles.asciidoc

@@ -11,8 +11,8 @@ A role is defined by the following JSON structure:
   "cluster": [ ... ], <2>
   "global": { ... }, <3>
   "indices": [ ... ], <4>
-  "applications": [ ... ] <5>
-
+  "applications": [ ... ], <5>
+  "remote_indices": [ ... ] <6>
 }
 -----
 // NOTCONSOLE
@@ -31,6 +31,12 @@ A role is defined by the following JSON structure:
 <4> A list of indices permissions entries. This field is optional (missing `indices`
     privileges effectively mean no index level permissions).
 <5> A list of application privilege entries. This field is optional.
+// TODO: fix the link to new page of API key based remote clusters
+<6> beta:[]
+    A list of indices permissions entries for
+    <<remote-clusters,remote clusters configured with the API key based model>>.
+    This field is optional (missing `remote_indices` privileges effectively mean
+    no index level permissions for any API key based remote clusters).
 
 [[valid-role-name]]
 NOTE: Role names must be at least 1 and no more than 507 characters. They can
@@ -39,7 +45,7 @@ NOTE: Role names must be at least 1 and no more than 507 characters. They can
       Leading or trailing whitespace is not allowed.
 
 [[roles-indices-priv]]
-==== Indices Privileges
+==== Indices privileges
 
 The following describes the structure of an indices permissions entry:
 
@@ -49,7 +55,7 @@ The following describes the structure of an indices permissions entry:
   "names": [ ... ], <1>
   "privileges": [ ... ], <2>
   "field_security" : { ... }, <3>
-  "query": "..." <4>
+  "query": "...", <4>
   "allow_restricted_indices": false <5>
 }
 -------
@@ -100,7 +106,7 @@ multiple data streams, indices, and aliases.
 ==============================================================================
 
 [[roles-global-priv]]
-==== Global Privileges
+==== Global privileges
 The following describes the structure of the global privileges entry:
 
 [source,js]
@@ -129,7 +135,7 @@ The following describes the structure of the global privileges entry:
 privilege is restricted to
 
 [[roles-application-priv]]
-==== Application Privileges
+==== Application privileges
 The following describes the structure of an application privileges entry:
 
 [source,js]
@@ -157,6 +163,57 @@ were defined, but have since been deleted). In this case, the privilege has
 no effect, and will not grant any actions in the
 <<security-api-has-privileges,has privileges API>>.
 
+[[roles-remote-indices-priv]]
+==== Remote indices privileges
+
+beta::[]
+
+// TODO: fix the link to new page of API key based remote clusters
+For remote clusters configured with the API key based model, remote indices privileges
+can be used to specify desired indices privileges for matching remote clusters. The final
+effective index privileges will be an intersection of the remote indices privileges
+and the <<security-api-create-cross-cluster-api-key,cross-cluster API key>>'s indices privileges.
+
+NOTE: Remote indices are effective for remote clusters configured with the API key based model.
+They have no effect for remote clusters configured with the certificate based model.
+
+The remote indices privileges entry has an extra mandatory `clusters` field compared to
+an <<roles-indices-priv,indices privileges entry>>. Otherwise the two have identical structure.
+The following describes the structure of a remote indices permissions entry:
+
+[source,js]
+-------
+{
+  "clusters": [ ... ], <1>
+  "names": [ ... ], <2>
+  "privileges": [ ... ], <3>
+  "field_security" : { ... }, <4>
+  "query": "...", <5>
+  "allow_restricted_indices": false <6>
+}
+-------
+// NOTCONSOLE
+<1> A list of remote cluster aliases. It supports literal strings as well as
+    <<api-multi-index,wildcards>> and <<regexp-syntax,regular expressions>>.
+    This field is required.
+<2> A list of data streams, indices, and aliases to which the permissions
+    in this entry apply. Supports wildcards (`*`).
+<3> The index level privileges the owners of the role have on the associated
+    data streams and indices specified in the `names` argument.
+<4> Specification for document fields the owners of the role have read access to.
+    See <<field-and-document-access-control>> for details.
+<5> A search query that defines the documents the owners of the role have read
+    access to. A document within the associated data streams and indices must match this query
+    in order for it to be accessible by the owners of the role.
+<6> Restricted indices are a special category of indices that are used
+    internally to store configuration data and should not be directly accessed.
+    Only internal system roles should normally grant privileges over the restricted indices.
+    **Toggling this flag is very strongly discouraged because it could effectively grant unrestricted
+    operations on critical data, making the entire system unstable or leaking sensitive information.**
+    If however, for administrative purposes, you need to create a role with privileges covering
+    restricted indices, you must set this field to `true` (default is `false`), and then the
+    `names` field will cover the restricted indices as well.
+
 ==== Example
 
 The following snippet shows an example definition of a `clicks_admin` role:

x-pack/docs/en/security/authorization/privileges.asciidoc

@@ -20,6 +20,28 @@ See <<delete-async-search,delete async search>> API for more informations.
 Privileges to create snapshots for existing repositories. Can also list and view
 details on existing repositories and snapshots.
 
+`cross_cluster_replication`::
+beta:[] Privileges to connect to remote clusters configured with the API key based model
+for cross-cluster replication.
++
+--
+NOTE: This privilege should _not_ be directly granted. It is used internally by
+<<security-api-create-cross-cluster-api-key>> and <<security-api-update-cross-cluster-api-key>>
+to manage cross-cluster API keys.
+
+--
+
+`cross_cluster_search`::
+beta:[] Privileges to connect to remote clusters configured with the API key based model
+for cross-cluster search.
++
+--
+NOTE: This privilege should _not_ be directly granted. It is used internally by
+<<security-api-create-cross-cluster-api-key>> and <<security-api-update-cross-cluster-api-key>>
+to manage cross-cluster API keys.
+
+--
+
 `grant_api_key`::
 Privileges to create {es} API keys on behalf of other users.
 
@@ -30,7 +52,7 @@ obtaining snapshot and restore status. This privilege does not include the
 ability to manage security.
 
 `manage_api_key`::
-All security-related operations on {es} API keys including
+All security-related operations on {es} REST API keys including
 <<security-api-create-api-key,creating new API keys>>,
 <<security-api-get-api-key,retrieving information about API keys>>,
 <<security-api-query-api-key,querying API keys>>,
@@ -278,6 +300,22 @@ aliases to be added to the index once created. In that case the request
 requires the `manage` privilege as well, on both the index and the aliases
 names.
 
+`cross_cluster_replication`::
+beta:[] Privileges to perform cross-cluster replication for indices located on remote clusters
+configured with the API key based model. This privilege should only be used for
+the `privileges` field of <<roles-remote-indices-priv,remote indices privileges>>.
+
+`cross_cluster_replication_internal`::
+beta:[] Privileges to perform supporting actions for cross-cluster replication from remote clusters
+configured with the API key based model.
++
+--
+NOTE: This privilege should _not_ be directly granted. It is used internally by
+<<security-api-create-cross-cluster-api-key>> and <<security-api-update-cross-cluster-api-key>>
+to manage cross-cluster API keys.
+
+--
+
 `delete`::
 Privilege to delete documents.