diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc
index ea6f167f6bce7..d76fa2f2bb310 100644
--- a/docs/reference/index.asciidoc
+++ b/docs/reference/index.asciidoc
@@ -59,9 +59,9 @@ include::monitoring/index.asciidoc[]
 
 include::rollup/index.asciidoc[]
 
-include::{xes-repo-dir}/watcher/index.asciidoc[]
+include::{xes-repo-dir}/security/index.asciidoc[]
 
-include::security/index.asciidoc[]
+include::{xes-repo-dir}/watcher/index.asciidoc[]
 
 include::rest-api/index.asciidoc[]
 
diff --git a/docs/reference/security/index.asciidoc b/docs/reference/security/index.asciidoc
deleted file mode 100644
index bbdad50c4e16e..0000000000000
--- a/docs/reference/security/index.asciidoc
+++ /dev/null
@@ -1,18 +0,0 @@
-[[secure-cluster]]
-= Secure a cluster
-
-[partintro]
---
-The {stack-security-features} enable you to easily secure a cluster. You can
-password-protect your data as well as implement more advanced security
-measures such as encrypting communications, role-based access control,
-IP filtering, and auditing.
-
-* <<elasticsearch-security>>
-* <<configuring-security>>
-
---
-
-include::{xes-repo-dir}/security/overview.asciidoc[]
-
-include::{xes-repo-dir}/security/configuring-es.asciidoc[]
\ No newline at end of file
diff --git a/x-pack/docs/en/security/auditing/event-types.asciidoc b/x-pack/docs/en/security/auditing/event-types.asciidoc
index 0bd6713045889..30c9250a45dcf 100644
--- a/x-pack/docs/en/security/auditing/event-types.asciidoc
+++ b/x-pack/docs/en/security/auditing/event-types.asciidoc
@@ -16,7 +16,7 @@ The following is a list of the events that can be generated:
                                           realm type.
 | `access_denied`                   | | | Logged when an authenticated user attempts to execute
                                           an action they do not have the necessary
-                                          <<security-reference, privilege>> to perform.
+                                          <<security-privileges,privilege>> to perform.
 | `access_granted`                  | | | Logged when an authenticated user attempts to execute
                                           an action they have the necessary privilege to perform.
                                           When the `system_access_granted` event is included, all system
@@ -26,7 +26,7 @@ The following is a list of the events that can be generated:
                                           another user that they have the necessary privileges to do.
 | `run_as_denied`                   | | | Logged when an authenticated user attempts to <<run-as-privilege, run as>>
                                           another user action they do not have the necessary
-                                          <<security-reference, privilege>> to do so.
+                                          <<security-privileges,privilege>> to do so.
 | `tampered_request`                | | | Logged when {security} detects that the request has
                                           been tampered with. Typically relates to `search/scroll`
                                           requests when the scroll ID is believed to have been
diff --git a/x-pack/docs/en/security/auditing/index.asciidoc b/x-pack/docs/en/security/auditing/index.asciidoc
index e82fd4397fb71..bab3c89235c6c 100644
--- a/x-pack/docs/en/security/auditing/index.asciidoc
+++ b/x-pack/docs/en/security/auditing/index.asciidoc
@@ -1,15 +1,6 @@
 
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/overview.asciidoc
 include::overview.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/event-types.asciidoc
 include::event-types.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/output-logfile.asciidoc
 include::output-logfile.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/output-index.asciidoc
 include::output-index.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc
 include::forwarding-logs.asciidoc[]
\ No newline at end of file
diff --git a/x-pack/docs/en/security/authentication/index.asciidoc b/x-pack/docs/en/security/authentication/index.asciidoc
index 120241e990c0e..7e2f1cadc7d1c 100644
--- a/x-pack/docs/en/security/authentication/index.asciidoc
+++ b/x-pack/docs/en/security/authentication/index.asciidoc
@@ -10,11 +10,7 @@ include::native-realm.asciidoc[]
 include::pki-realm.asciidoc[]
 include::saml-realm.asciidoc[]
 include::kerberos-realm.asciidoc[]
-
-include::{xes-repo-dir}/security/authentication/custom-realm.asciidoc[]
-
-include::{xes-repo-dir}/security/authentication/anonymous-access.asciidoc[]
-
-include::{xes-repo-dir}/security/authentication/user-cache.asciidoc[]
-
-include::{xes-repo-dir}/security/authentication/saml-guide.asciidoc[]
+include::custom-realm.asciidoc[]
+include::anonymous-access.asciidoc[]
+include::user-cache.asciidoc[]
+include::saml-guide.asciidoc[]
diff --git a/x-pack/docs/en/security/authorization/index.asciidoc b/x-pack/docs/en/security/authorization/index.asciidoc
index c8216278c6b59..a67582224e410 100644
--- a/x-pack/docs/en/security/authorization/index.asciidoc
+++ b/x-pack/docs/en/security/authorization/index.asciidoc
@@ -1,22 +1,12 @@
 
 include::overview.asciidoc[]
-
 include::built-in-roles.asciidoc[]
-
-include::{xes-repo-dir}/security/authorization/managing-roles.asciidoc[]
-
+include::managing-roles.asciidoc[]
 include::privileges.asciidoc[]
-
 include::document-level-security.asciidoc[]
-
 include::field-level-security.asciidoc[]
-
-include::{xes-repo-dir}/security/authorization/alias-privileges.asciidoc[]
-
-include::{xes-repo-dir}/security/authorization/mapping-roles.asciidoc[]
-
-include::{xes-repo-dir}/security/authorization/field-and-document-access-control.asciidoc[]
-
-include::{xes-repo-dir}/security/authorization/run-as-privilege.asciidoc[]
-
-include::{xes-repo-dir}/security/authorization/custom-roles-provider.asciidoc[]
+include::alias-privileges.asciidoc[]
+include::mapping-roles.asciidoc[]
+include::field-and-document-access-control.asciidoc[]
+include::run-as-privilege.asciidoc[]
+include::custom-roles-provider.asciidoc[]
diff --git a/x-pack/docs/en/security/configuring-es.asciidoc b/x-pack/docs/en/security/configuring-es.asciidoc
index db25f10de1dc4..ee9c24ddc447b 100644
--- a/x-pack/docs/en/security/configuring-es.asciidoc
+++ b/x-pack/docs/en/security/configuring-es.asciidoc
@@ -8,8 +8,7 @@
 {security} enables you to easily secure a cluster. With {security}, you can
 password-protect your data as well as implement more advanced security measures
 such as encrypting communications, role-based access control, IP filtering, and
-auditing. For more information, see
-{xpack-ref}/xpack-security.html[Securing the Elastic Stack].
+auditing.
 
 To use {security} in {es}:
 
@@ -20,12 +19,12 @@ If you want to try all of the {xpack} features, you can start a 30-day trial. At
 the end of the trial period, you can purchase a subscription to keep using the
 full functionality of the {xpack} components. For more information, see
 https://www.elastic.co/subscriptions and
-{xpack-ref}/license-management.html[License Management].
+{stack-ov}/license-management.html[License management].
 --
 
 . Verify that the `xpack.security.enabled` setting is `true` on each node in
 your cluster. If you are using a trial license, the default value is `false`.
-For more information, see {ref}/security-settings.html[Security Settings in {es}].
+For more information, see <<security-settings>>.
 
 . If you plan to run {es} in a Federal Information Processing Standard (FIPS) 
 140-2 enabled JVM, see <<fips-140-compliance>>. 
@@ -37,7 +36,7 @@ NOTE: This requirement applies to clusters with more than one node and to
 clusters with a single node that listens on an external interface. Single-node
 clusters that use a loopback interface do not have this requirement.  For more
 information, see
-{xpack-ref}/encrypting-communications.html[Encrypting Communications].
+<<encrypting-communications>>.
 
 --
 .. <<node-certificates,Generate node certificates for each of your {es} nodes>>.
@@ -50,7 +49,7 @@ information, see
 +
 --
 {security} provides
-{stack-ov}/built-in-users.html[built-in users] to
+<<built-in-users,built-in users>> to
 help you get up and running. The +elasticsearch-setup-passwords+ command is the
 simplest method to set the built-in users' passwords for the first time.
 
@@ -125,7 +124,7 @@ curl -XPOST -u elastic 'localhost:9200/_xpack/security/user/johndoe' -H "Content
 xpack.security.audit.enabled: true
 ----------------------------
 +
-For more information, see {xpack-ref}/auditing.html[Auditing Security Events] 
+For more information, see <<auditing>>
 and <<auditing-settings>>. 
 
 .. Restart {es}.
@@ -135,33 +134,17 @@ By default, events are logged to a dedicated `elasticsearch-access.log` file in
 easier analysis and control what events are logged. 
 --
 
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/docs/reference/security/securing-communications/securing-elasticsearch.asciidoc
-include::{es-repo-dir}/security/securing-communications/securing-elasticsearch.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/docs/reference/security/securing-communications/configuring-tls-docker.asciidoc
-include::{es-repo-dir}/security/securing-communications/configuring-tls-docker.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/docs/reference/security/securing-communications/enabling-cipher-suites.asciidoc
-include::{es-repo-dir}/security/securing-communications/enabling-cipher-suites.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/docs/reference/security/securing-communications/separating-node-client-traffic.asciidoc
-include::{es-repo-dir}/security/securing-communications/separating-node-client-traffic.asciidoc[]
-
-:edit_url:
+include::securing-communications/securing-elasticsearch.asciidoc[]
+include::securing-communications/configuring-tls-docker.asciidoc[]
+include::securing-communications/enabling-cipher-suites.asciidoc[]
+include::securing-communications/separating-node-client-traffic.asciidoc[]
 include::authentication/configuring-active-directory-realm.asciidoc[]
 include::authentication/configuring-file-realm.asciidoc[]
 include::authentication/configuring-ldap-realm.asciidoc[]
 include::authentication/configuring-native-realm.asciidoc[]
 include::authentication/configuring-pki-realm.asciidoc[]
 include::authentication/configuring-saml-realm.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/authentication/configuring-kerberos-realm.asciidoc
 include::authentication/configuring-kerberos-realm.asciidoc[]
-
-:edit_url: 
 include::fips-140-compliance.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/docs/reference/settings/security-settings.asciidoc
 include::{es-repo-dir}/settings/security-settings.asciidoc[]
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/docs/reference/settings/audit-settings.asciidoc
 include::{es-repo-dir}/settings/audit-settings.asciidoc[]
diff --git a/x-pack/docs/en/security/fips-140-compliance.asciidoc b/x-pack/docs/en/security/fips-140-compliance.asciidoc
index 0216e61784cdb..0e46fd8c6f45a 100644
--- a/x-pack/docs/en/security/fips-140-compliance.asciidoc
+++ b/x-pack/docs/en/security/fips-140-compliance.asciidoc
@@ -114,7 +114,7 @@ features are not available while running in fips mode. The list is as follows:
 
 * Azure Classic Discovery Plugin
 * Ingest Attachment Plugin
-* The {ref}/certutil.html[`elasticsearch-certutil`] tool. However,
+* The <<certutil,`elasticsearch-certutil`>> tool. However,
  `elasticsearch-certutil` can very well be used in a non FIPS 140-2
   enabled JVM (pointing `JAVA_HOME` environment variable to a different java
   installation) in order to generate the keys and certificates that
diff --git a/x-pack/docs/en/security/get-started-builtin-users.asciidoc b/x-pack/docs/en/security/get-started-builtin-users.asciidoc
index ad61abd6b9d7b..d380ac6912501 100644
--- a/x-pack/docs/en/security/get-started-builtin-users.asciidoc
+++ b/x-pack/docs/en/security/get-started-builtin-users.asciidoc
@@ -12,7 +12,7 @@ the following command from the {es} directory:
 ./bin/elasticsearch
 ----------------------------------------------------------------------
 
-See {ref}/starting-elasticsearch.html[Starting {es}].
+See <<starting-elasticsearch>>.
 --
 
 . Set the built-in users' passwords. Run the following command from the {es} 
diff --git a/x-pack/docs/en/security/get-started-enable-security.asciidoc b/x-pack/docs/en/security/get-started-enable-security.asciidoc
index 7a09701b18ae1..7eb95698b8a9a 100644
--- a/x-pack/docs/en/security/get-started-enable-security.asciidoc
+++ b/x-pack/docs/en/security/get-started-enable-security.asciidoc
@@ -7,7 +7,7 @@ line. See {kibana-ref}/start-stop.html[Starting and stopping {kib}].
 
 . Stop {es}. For example, if you installed {es} from an archive distribution, 
 enter `Ctrl-C` on the command line. See 
-{ref}/stopping-elasticsearch.html[Stopping {es}].
+<<stopping-elasticsearch>>.
 
 . Add the `xpack.security.enabled` setting to the 
 `ES_PATH_CONF/elasticsearch.yml` file. 
@@ -17,7 +17,7 @@ TIP: The `ES_PATH_CONF` environment variable contains the path for the {es}
 configuration files. If you installed {es} using archive distributions (`zip` or 
 `tar.gz`), it defaults to `ES_HOME/config`. If you used package distributions 
 (Debian or RPM), it defaults to `/etc/elasticsearch`. For more information, see 
-{ref}/settings.html[Configuring {es}].  
+<<settings>>.  
 
 For example, add the following setting:
 
diff --git a/x-pack/docs/en/security/get-started-security.asciidoc b/x-pack/docs/en/security/get-started-security.asciidoc
index a23af294bdf1b..2b816ec18afe2 100644
--- a/x-pack/docs/en/security/get-started-security.asciidoc
+++ b/x-pack/docs/en/security/get-started-security.asciidoc
@@ -328,7 +328,7 @@ using the native realm. You learned how to create user IDs and roles that
 prevent unauthorized access to the {stack}. 
 
 Next, you'll want to try other features that are unlocked by your trial license, 
-such as {ml}. See <<ml-getting-started,Getting started with {ml}>>. 
+such as {ml}. See {stack-ov}/ml-getting-started.html[Getting started with {ml}]. 
 
 Later, when you're ready to increase the number of nodes in your cluster or set 
 up an production environment, you'll want to encrypt communications across the 
@@ -336,7 +336,7 @@ up an production environment, you'll want to encrypt communications across the
 
 For more detailed information about securing the {stack}, see:
 
-* {ref}/configuring-security.html[Configuring security in {es}]. Encrypt 
+* <<configuring-security,Configuring security in {es}>>. Encrypt 
 inter-node communications, set passwords for the built-in users, and manage your 
 users and roles.  
 
diff --git a/x-pack/docs/en/security/get-started-trial.asciidoc b/x-pack/docs/en/security/get-started-trial.asciidoc
index b2b9c9ad2abf7..ec34e04aacb8e 100644
--- a/x-pack/docs/en/security/get-started-trial.asciidoc
+++ b/x-pack/docs/en/security/get-started-trial.asciidoc
@@ -17,5 +17,5 @@ major version, you cannot start a new trial. For example, if you have already
 activated a trial for v6.0, you cannot start a new trial until v7.0.
 
 At the end of the trial period, the platinum features operate in a 
-<<license-expiration,degraded mode>>. You can revert to a basic license, extend 
+{stack-ov}/license-expiration.html[degraded mode]. You can revert to a basic license, extend 
 the trial, or purchase a subscription. 
diff --git a/x-pack/docs/en/security/index.asciidoc b/x-pack/docs/en/security/index.asciidoc
index 6ee1b2c37598e..705950be8cb36 100644
--- a/x-pack/docs/en/security/index.asciidoc
+++ b/x-pack/docs/en/security/index.asciidoc
@@ -1,114 +1,38 @@
-[role="xpack"]
-[[elasticsearch-security]]
-= Securing the {stack}
+[[secure-cluster]]
+= Secure a cluster
 
 [partintro]
 --
-{security} enables you to easily secure a cluster. With {security},
-you can password-protect your data as well as implement more advanced security
+The {stack-security-features} enable you to easily secure a cluster. You can
+password-protect your data as well as implement more advanced security
 measures such as encrypting communications, role-based access control,
-IP filtering, and auditing. This guide describes how to configure the security
-features you need, and interact with your secured cluster.
-
-Security protects Elasticsearch clusters by:
-
-* <<preventing-unauthorized-access, Preventing unauthorized access>>
-  with password protection, role-based access control, and IP filtering.
-* <<preserving-data-integrity, Preserving the integrity of your data>>
-  with message authentication and SSL/TLS encryption.
-* <<maintaining-audit-trail, Maintaining an audit trail>>
-  so you know who's doing what to your cluster and the data it stores.
-
-[float]
-[[preventing-unauthorized-access]]
-=== Preventing Unauthorized Access
-
-To prevent unauthorized access to your Elasticsearch cluster, you must have a
-way to _authenticate_ users. This simply means that you need a way to validate
-that a user is who they claim to be. For example, you have to make sure only
-the person named _Kelsey Andorra_ can sign in as the user `kandorra`. {security} 
-provides a standalone authentication mechanism that enables you to
-quickly password-protect your cluster. If you're already using <<ldap-realm, LDAP>>,
-<<active-directory-realm, Active Directory>>, or <<pki-realm, PKI>> to manage
-users in your organization, {security} is able to integrate with those
-systems to perform user authentication.
-
-In many cases, simply authenticating users isn't enough. You also need a way to
-control what data users have access to and what tasks they can perform. {security}
-enables you to _authorize_ users by assigning access _privileges_ to _roles_,
-and assigning those roles to users. For example, this
-<<authorization,role-based access control>> mechanism (a.k.a RBAC) enables
-you to specify that the user `kandorra` can only perform read operations on the
-`events` index and can't do anything at all with other indices.
-
-{security} also supports <<ip-filtering, IP-based authorization>>. You can
-whitelist and blacklist specific IP addresses or subnets to control network-level
-access to a server.
-
-[float]
-[[preserving-data-integrity]]
-=== Preserving Data Integrity
-
-A critical part of security is keeping confidential data confidential.
-Elasticsearch has built-in protections against accidental data loss and
-corruption. However, there's nothing to stop deliberate tampering or data
-interception. {security} preserves the integrity of your data by
-<<ssl-tls, encrypting communications>> to and from nodes.
-For even greater protection, you can increase the <<ciphers, encryption strength>> and
-<<separating-node-client-traffic, separate client traffic from node-to-node communications>>.
-
-
-[float]
-[[maintaining-audit-trail]]
-=== Maintaining an Audit Trail
-
-Keeping a system secure takes vigilance. By using {security} to maintain
-an audit trail, you can easily see who is accessing your cluster and what they're
-doing. By analyzing access patterns and failed attempts to access your cluster,
-you can gain insights into attempted attacks and data breaches. Keeping an
-auditable log of the activity in your cluster can also help diagnose operational
-issues.
-
-[float]
-=== Where to Go Next
-
-* <<security-getting-started, Getting Started>>
-  steps through how to install and start using Security for basic authentication.
-
-* <<how-security-works, How Security Works>>
-  provides more information about how Security supports user authentication,
-  authorization, and encryption.
-
+IP filtering, and auditing.
+
+* <<elasticsearch-security>>
+* <<configuring-security>>
+* <<security-getting-started>>
+* <<how-security-works>>
+* <<setting-up-authentication>>
+* <<saml-guide>>
+* <<authorization>>
+* <<auditing>>
+* <<encrypting-communications>>
 * <<ccs-tribe-clients-integrations>>
-  shows you how to interact with an Elasticsearch cluster protected by
-  {security}.
-
-* <<security-reference, Reference>>
-  provides detailed information about the access privileges you can grant to
-  users, the settings you can configure for Security in `elasticsearch.yml`,
-  and the files where Security configuration information is stored.
+* <<security-troubleshooting>>
+* <<security-limitations>>
 
-[float]
-=== Have Comments, Questions, or Feedback?
-
-Head over to our {security-forum}[Security Discussion Forum]
-to share your experience, questions, and suggestions.
 --
 
+include::overview.asciidoc[]
+include::configuring-es.asciidoc[]
 include::get-started-security.asciidoc[]
-
 include::how-security-works.asciidoc[]
-
 include::authentication/index.asciidoc[]
-
 include::authorization/index.asciidoc[]
-
-include::{xes-repo-dir}/security/auditing/index.asciidoc[]
-
-include::{xes-repo-dir}/security/securing-communications.asciidoc[]
-
-include::{xes-repo-dir}/security/using-ip-filtering.asciidoc[]
-
-include::{xes-repo-dir}/security/tribe-clients-integrations.asciidoc[]
-
-include::{xes-repo-dir}/security/reference.asciidoc[]
+include::auditing/index.asciidoc[]
+include::securing-communications/index.asciidoc[]
+include::using-ip-filtering.asciidoc[]
+include::tribe-clients-integrations/index.asciidoc[]
+include::reference.asciidoc[]
+include::troubleshooting.asciidoc[]
+include::limitations.asciidoc[]
\ No newline at end of file
diff --git a/x-pack/docs/en/security/limitations.asciidoc b/x-pack/docs/en/security/limitations.asciidoc
index 4597969156675..8053fa9172530 100644
--- a/x-pack/docs/en/security/limitations.asciidoc
+++ b/x-pack/docs/en/security/limitations.asciidoc
@@ -1,6 +1,9 @@
 [role="xpack"]
 [[security-limitations]]
 == Security limitations
+++++
+<titleabbrev>Limitations</titleabbrev>
+++++
 
 [float]
 === Plugins
diff --git a/x-pack/docs/en/security/reference.asciidoc b/x-pack/docs/en/security/reference.asciidoc
index 75de1daee6d6b..053acd7404c51 100644
--- a/x-pack/docs/en/security/reference.asciidoc
+++ b/x-pack/docs/en/security/reference.asciidoc
@@ -1,11 +1,10 @@
 [role="xpack"]
 [[security-reference]]
 == Reference
-* <<security-privileges, Security Privileges>>
-* {ref}/security-settings.html[Security Settings]
-* <<security-files, Security Files>>
-* {ref}/security-api.html[Security API]
-* {ref}/xpack-commands.html[Security Commands]
+* <<security-privileges>>
+* <<security-settings>>
+* <<security-files>>
+* <<security-api>>
+* <<xpack-commands>>
 
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/docs/reference/security/reference/files.asciidoc
-include::{es-repo-dir}/security/reference/files.asciidoc[]
+include::reference/files.asciidoc[]
diff --git a/docs/reference/security/reference/files.asciidoc b/x-pack/docs/en/security/reference/files.asciidoc
similarity index 100%
rename from docs/reference/security/reference/files.asciidoc
rename to x-pack/docs/en/security/reference/files.asciidoc
diff --git a/docs/reference/security/securing-communications/configuring-tls-docker.asciidoc b/x-pack/docs/en/security/securing-communications/configuring-tls-docker.asciidoc
similarity index 100%
rename from docs/reference/security/securing-communications/configuring-tls-docker.asciidoc
rename to x-pack/docs/en/security/securing-communications/configuring-tls-docker.asciidoc
diff --git a/docs/reference/security/securing-communications/enabling-cipher-suites.asciidoc b/x-pack/docs/en/security/securing-communications/enabling-cipher-suites.asciidoc
similarity index 96%
rename from docs/reference/security/securing-communications/enabling-cipher-suites.asciidoc
rename to x-pack/docs/en/security/securing-communications/enabling-cipher-suites.asciidoc
index a8e940995a708..c2806d54f672d 100644
--- a/docs/reference/security/securing-communications/enabling-cipher-suites.asciidoc
+++ b/x-pack/docs/en/security/securing-communications/enabling-cipher-suites.asciidoc
@@ -1,6 +1,6 @@
 [role="xpack"]
 [[ciphers]]
-=== Enabling Cipher Suites for Stronger Encryption
+=== Enabling cipher suites for stronger encryption
 
 The TLS and SSL protocols use a cipher suite that determines the strength of
 encryption used to protect the data. You may want to increase the strength of
diff --git a/x-pack/docs/en/security/securing-communications.asciidoc b/x-pack/docs/en/security/securing-communications/index.asciidoc
similarity index 62%
rename from x-pack/docs/en/security/securing-communications.asciidoc
rename to x-pack/docs/en/security/securing-communications/index.asciidoc
index 84f3b0bc27ac6..ee0d922e1cf4a 100644
--- a/x-pack/docs/en/security/securing-communications.asciidoc
+++ b/x-pack/docs/en/security/securing-communications/index.asciidoc
@@ -17,15 +17,4 @@ This section shows how to:
 The authentication of new nodes helps prevent a rogue node from joining the
 cluster and receiving data through replication.
 
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/docs/reference/security/securing-communications/setting-up-ssl.asciidoc
-include::{es-repo-dir}/security/securing-communications/setting-up-ssl.asciidoc[]
-
-[[ciphers]]
-=== Enabling cipher suites for stronger encryption
-
-See {ref}/ciphers.html[Enabling Cipher Suites for Stronger Encryption].
-
-[[separating-node-client-traffic]]
-=== Separating node-to-node and client traffic
-
-See {ref}/separating-node-client-traffic.html[Separating node-to-node and client traffic].
+include::setting-up-ssl.asciidoc[]
\ No newline at end of file
diff --git a/docs/reference/security/securing-communications/node-certificates.asciidoc b/x-pack/docs/en/security/securing-communications/node-certificates.asciidoc
similarity index 99%
rename from docs/reference/security/securing-communications/node-certificates.asciidoc
rename to x-pack/docs/en/security/securing-communications/node-certificates.asciidoc
index eacd9afa2a0af..f48d419b66a81 100644
--- a/docs/reference/security/securing-communications/node-certificates.asciidoc
+++ b/x-pack/docs/en/security/securing-communications/node-certificates.asciidoc
@@ -1,6 +1,6 @@
 [role="xpack"]
 [[node-certificates]]
-==== Generating Node Certificates
+==== Generating node certificates
 
 TLS requires X.509 certificates to perform encryption and authentication of the
 application that is being communicated with. In order for the communication
diff --git a/docs/reference/security/securing-communications/securing-elasticsearch.asciidoc b/x-pack/docs/en/security/securing-communications/securing-elasticsearch.asciidoc
similarity index 100%
rename from docs/reference/security/securing-communications/securing-elasticsearch.asciidoc
rename to x-pack/docs/en/security/securing-communications/securing-elasticsearch.asciidoc
diff --git a/docs/reference/security/securing-communications/separating-node-client-traffic.asciidoc b/x-pack/docs/en/security/securing-communications/separating-node-client-traffic.asciidoc
similarity index 100%
rename from docs/reference/security/securing-communications/separating-node-client-traffic.asciidoc
rename to x-pack/docs/en/security/securing-communications/separating-node-client-traffic.asciidoc
diff --git a/docs/reference/security/securing-communications/setting-up-ssl.asciidoc b/x-pack/docs/en/security/securing-communications/setting-up-ssl.asciidoc
similarity index 100%
rename from docs/reference/security/securing-communications/setting-up-ssl.asciidoc
rename to x-pack/docs/en/security/securing-communications/setting-up-ssl.asciidoc
diff --git a/docs/reference/security/securing-communications/tls-ad.asciidoc b/x-pack/docs/en/security/securing-communications/tls-ad.asciidoc
similarity index 100%
rename from docs/reference/security/securing-communications/tls-ad.asciidoc
rename to x-pack/docs/en/security/securing-communications/tls-ad.asciidoc
diff --git a/docs/reference/security/securing-communications/tls-http.asciidoc b/x-pack/docs/en/security/securing-communications/tls-http.asciidoc
similarity index 100%
rename from docs/reference/security/securing-communications/tls-http.asciidoc
rename to x-pack/docs/en/security/securing-communications/tls-http.asciidoc
diff --git a/docs/reference/security/securing-communications/tls-ldap.asciidoc b/x-pack/docs/en/security/securing-communications/tls-ldap.asciidoc
similarity index 100%
rename from docs/reference/security/securing-communications/tls-ldap.asciidoc
rename to x-pack/docs/en/security/securing-communications/tls-ldap.asciidoc
diff --git a/docs/reference/security/securing-communications/tls-transport.asciidoc b/x-pack/docs/en/security/securing-communications/tls-transport.asciidoc
similarity index 100%
rename from docs/reference/security/securing-communications/tls-transport.asciidoc
rename to x-pack/docs/en/security/securing-communications/tls-transport.asciidoc
diff --git a/x-pack/docs/en/security/tribe-clients-integrations.asciidoc b/x-pack/docs/en/security/tribe-clients-integrations.asciidoc
deleted file mode 100644
index c7d0f8ca73ad8..0000000000000
--- a/x-pack/docs/en/security/tribe-clients-integrations.asciidoc
+++ /dev/null
@@ -1,54 +0,0 @@
-[[ccs-tribe-clients-integrations]]
-== Cross cluster search, tribe, clients, and integrations
-
-When using {ref}/modules-cross-cluster-search.html[Cross Cluster Search] or
-{ref}/modules-tribe.html[Tribe Nodes] you need to take extra steps to secure
-communications with the connected clusters.
-
-* <<cross-cluster-configuring, Cross Cluster Search and Security>>
-* <<tribe-node-configuring, Tribe Nodes and Security>>
-
-You will need to update the configuration for several clients to work with a
-secured cluster:
-
-* <<java-clients, Java Clients>>
-* <<http-clients, HTTP Clients>>
-
-
-{security} enables you to secure your {es} cluster. But {es} itself is only one
-product within the Elastic Stack. It is often the case that other products in
-the stack are connected to the cluster and therefore need to be secured as well,
-or at least communicate with the cluster in a secured way:
-
-* <<hadoop, Apache Hadoop>>
-* {auditbeat-ref}/securing-beats.html[Auditbeat]
-* {filebeat-ref}/securing-beats.html[Filebeat]
-* {heartbeat-ref}/securing-beats.html[Heartbeat]
-* {kibana-ref}/using-kibana-with-security.html[{kib}]
-* {logstash-ref}/ls-security.html[Logstash]
-* {metricbeat-ref}/securing-beats.html[Metricbeat]
-* <<secure-monitoring, Monitoring>>
-* {packetbeat-ref}/securing-beats.html[Packetbeat]
-* {kibana-ref}/secure-reporting.html[Reporting]
-* {winlogbeat-ref}/securing-beats.html[Winlogbeat]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/ribe-clients-integrations/cross-cluster.asciidoc
-include::tribe-clients-integrations/cross-cluster.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/ribe-clients-integrations/tribe.asciidoc
-include::tribe-clients-integrations/tribe.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/ribe-clients-integrations/java.asciidoc
-include::tribe-clients-integrations/java.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/ribe-clients-integrations/http.asciidoc
-include::tribe-clients-integrations/http.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/ribe-clients-integrations/hadoop.asciidoc
-include::tribe-clients-integrations/hadoop.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/ribe-clients-integrations/beats.asciidoc
-include::tribe-clients-integrations/beats.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/ribe-clients-integrations/monitoring.asciidoc
-include::tribe-clients-integrations/monitoring.asciidoc[]
diff --git a/x-pack/docs/en/security/tribe-clients-integrations/beats.asciidoc b/x-pack/docs/en/security/tribe-clients-integrations/beats.asciidoc
index 43c8be5409c28..a12f3cf397a72 100644
--- a/x-pack/docs/en/security/tribe-clients-integrations/beats.asciidoc
+++ b/x-pack/docs/en/security/tribe-clients-integrations/beats.asciidoc
@@ -1,5 +1,5 @@
 [[beats]]
-=== Beats and Security
+=== Beats and security
 
 See:
 
diff --git a/x-pack/docs/en/security/tribe-clients-integrations/cross-cluster-kibana.asciidoc b/x-pack/docs/en/security/tribe-clients-integrations/cross-cluster-kibana.asciidoc
new file mode 100644
index 0000000000000..68dd7870f934f
--- /dev/null
+++ b/x-pack/docs/en/security/tribe-clients-integrations/cross-cluster-kibana.asciidoc
@@ -0,0 +1,39 @@
+[[cross-cluster-kibana]]
+==== Cross cluster search and Kibana
+
+When Kibana is used to search across multiple clusters, a two-step authorization
+process determines whether or not the user can access indices on a remote
+cluster:
+
+* First, the local cluster determines if the user is authorized to access remote
+clusters. (The local cluster is the cluster Kibana is connected to.)
+* If they are, the remote cluster then determines if the user has access
+to the specified indices.
+
+To grant Kibana users access to remote clusters, assign them a local role
+with read privileges to indices on the remote clusters. You specify remote
+cluster indices as `<remote_cluster_name>:<index_name>`.
+
+To enable users to actually read the remote indices, you must create a matching
+role on the remote clusters that grants the `read_cross_cluster` privilege
+and access to the appropriate indices.
+
+For example, if Kibana is connected to the cluster where you're actively
+indexing Logstash data (your _local cluster_) and you're periodically
+offloading older time-based indices to an archive cluster
+(your _remote cluster_) and you want to enable Kibana users to search both
+clusters:
+
+. On the local cluster, create a `logstash_reader` role that grants
+`read` and `view_index_metadata` privileges on the local `logstash-*` indices.
++
+NOTE: If you configure the local cluster as another remote in {es}, the
+`logstash_reader` role on your local cluster also needs to grant the
+`read_cross_cluster` privilege.
+
+. Assign your Kibana users the `kibana_user` role and your `logstash_reader`
+role.
+
+. On the remote cluster, create a `logstash_reader` role that grants the
+`read_cross_cluster` privilege and `read` and `view_index_metadata` privileges
+for the `logstash-*` indices.
diff --git a/x-pack/docs/en/security/tribe-clients-integrations/cross-cluster.asciidoc b/x-pack/docs/en/security/tribe-clients-integrations/cross-cluster.asciidoc
index e5f43a08e7aee..49094079ac74a 100644
--- a/x-pack/docs/en/security/tribe-clients-integrations/cross-cluster.asciidoc
+++ b/x-pack/docs/en/security/tribe-clients-integrations/cross-cluster.asciidoc
@@ -1,7 +1,7 @@
 [[cross-cluster-configuring]]
-=== Cross Cluster Search and Security
+=== Cross cluster search and security
 
-{ref}/modules-cross-cluster-search.html[Cross Cluster Search] enables
+<<modules-cross-cluster-search,Cross cluster search>> enables
 federated search across multiple clusters. When using cross cluster search
 with secured clusters, all clusters must have {security} enabled.
 
@@ -24,7 +24,7 @@ To use cross cluster search with secured clusters:
 
 * Enable {security} on every node in each connected cluster. For more
 information about the `xpack.security.enabled` setting, see
-{ref}/security-settings.html[Security Settings in {es}].
+<<security-settings>>.
 
 * Enable encryption globally. To encrypt communications, you must enable
   <<ssl-tls,enable SSL/TLS>> on every node.
@@ -36,10 +36,10 @@ information about the `xpack.security.enabled` setting, see
   ** Using the same certificate authority to generate certificates for all
     connected clusters, or
   ** Adding the CA certificate from the local cluster as a trusted CA in
-    each remote cluster (see {ref}/security-settings.html#transport-tls-ssl-settings[Transport TLS settings]).
+    each remote cluster (see <<transport-tls-ssl-settings>>).
 
 * Configure the local cluster to connect to remote clusters as described
-  in {ref}/modules-cross-cluster-search.html#_configuring_cross_cluster_search[Configuring Cross Cluster Search].
+  in <<modules-cross-cluster-search>>.
   For example, the following configuration adds two remote clusters
   to the local cluster:
 +
@@ -69,7 +69,7 @@ PUT _cluster/settings
   that exists on the remote clusters.  On the remote clusters, use that role
   to define which indices the user may access.  (See <<authorization>>).
 
-==== Example Configuration of Cross Cluster Search
+==== Example configuration of cross cluster search
 
 In the following example, we will configure the user `alice` to have permissions
 to search any index starting with `logs-` in cluster `two` from cluster `one`.
@@ -144,7 +144,7 @@ cluster `two` as follows:
 
 [source,js]
 -----------------------------------------------------------
-GET two:logs-2017.04/_search <1>
+GET two:logs-2017.04/_search
 {
   "query": {
     "match_all": {}
@@ -153,7 +153,5 @@ GET two:logs-2017.04/_search <1>
 -----------------------------------------------------------
 // CONSOLE
 // TEST[skip:todo]
-//TBD: Is there a missing description of the <1> callout above?
 
-:edit_url: https://github.com/elastic/kibana/edit/{branch}/docs/security/cross-cluster-kibana.asciidoc
-include::{kib-repo-dir}/security/cross-cluster-kibana.asciidoc[]
+include::cross-cluster-kibana.asciidoc[]
diff --git a/x-pack/docs/en/security/tribe-clients-integrations/hadoop.asciidoc b/x-pack/docs/en/security/tribe-clients-integrations/hadoop.asciidoc
index 0613f1ef77131..2c028b6e47d7c 100644
--- a/x-pack/docs/en/security/tribe-clients-integrations/hadoop.asciidoc
+++ b/x-pack/docs/en/security/tribe-clients-integrations/hadoop.asciidoc
@@ -1,5 +1,5 @@
 [[hadoop]]
-=== ES-Hadoop and Security
+=== ES-Hadoop and security
 
 Elasticsearch for Apache Hadoop ("ES-Hadoop") is capable of using HTTP basic and
 PKI authentication and/or TLS/SSL when accessing an Elasticsearch cluster. For
diff --git a/x-pack/docs/en/security/tribe-clients-integrations/http.asciidoc b/x-pack/docs/en/security/tribe-clients-integrations/http.asciidoc
index d56bcc919151d..a81bf8b6b3579 100644
--- a/x-pack/docs/en/security/tribe-clients-integrations/http.asciidoc
+++ b/x-pack/docs/en/security/tribe-clients-integrations/http.asciidoc
@@ -1,5 +1,5 @@
 [[http-clients]]
-=== HTTP/REST Clients and Security
+=== HTTP/REST clients and security
 
 {security} works with standard HTTP {wikipedia}/Basic_access_authentication[basic authentication]
 headers to authenticate users. Since Elasticsearch is stateless, this header must
diff --git a/x-pack/docs/en/security/tribe-clients-integrations/index.asciidoc b/x-pack/docs/en/security/tribe-clients-integrations/index.asciidoc
new file mode 100644
index 0000000000000..58f3bdefd9019
--- /dev/null
+++ b/x-pack/docs/en/security/tribe-clients-integrations/index.asciidoc
@@ -0,0 +1,41 @@
+[[ccs-tribe-clients-integrations]]
+== Cross cluster search, tribe, clients, and integrations
+
+When using <<modules-cross-cluster-search,cross cluster search>> or
+<<modules-tribe,tribe nodes>> you need to take extra steps to secure
+communications with the connected clusters.
+
+* <<cross-cluster-configuring>>
+* <<tribe-node-configuring>>
+
+You will need to update the configuration for several clients to work with a
+secured cluster:
+
+* <<java-clients>>
+* <<http-clients>>
+
+
+{security} enables you to secure your {es} cluster. But {es} itself is only one
+product within the Elastic Stack. It is often the case that other products in
+the stack are connected to the cluster and therefore need to be secured as well,
+or at least communicate with the cluster in a secured way:
+
+* <<hadoop, Apache Hadoop>>
+* {auditbeat-ref}/securing-beats.html[Auditbeat]
+* {filebeat-ref}/securing-beats.html[Filebeat]
+* {heartbeat-ref}/securing-beats.html[Heartbeat]
+* {kibana-ref}/using-kibana-with-security.html[{kib}]
+* {logstash-ref}/ls-security.html[Logstash]
+* {metricbeat-ref}/securing-beats.html[Metricbeat]
+* <<secure-monitoring>>
+* {packetbeat-ref}/securing-beats.html[Packetbeat]
+* {kibana-ref}/secure-reporting.html[Reporting]
+* {winlogbeat-ref}/securing-beats.html[Winlogbeat]
+
+include::cross-cluster.asciidoc[]
+include::tribe.asciidoc[]
+include::java.asciidoc[]
+include::http.asciidoc[]
+include::hadoop.asciidoc[]
+include::beats.asciidoc[]
+include::monitoring.asciidoc[]
diff --git a/x-pack/docs/en/security/tribe-clients-integrations/java.asciidoc b/x-pack/docs/en/security/tribe-clients-integrations/java.asciidoc
index 88985328c0011..c31e665661a92 100644
--- a/x-pack/docs/en/security/tribe-clients-integrations/java.asciidoc
+++ b/x-pack/docs/en/security/tribe-clients-integrations/java.asciidoc
@@ -1,5 +1,5 @@
 [[java-clients]]
-=== Java Client and Security
+=== Java client and security
 
 {security} supports the Java http://www.elastic.co/guide/en/elasticsearch/client/java-api/current/transport-client.html[transport client] for Elasticsearch.
 The transport client uses the same transport protocol that the cluster nodes use
@@ -11,7 +11,7 @@ NOTE: Using the Java Node Client with secured clusters is not recommended or
 
 [float]
 [[transport-client]]
-==== Configuring the Transport Client to work with a Secured Cluster
+==== Configuring the transport client to work with a secured cluster
 
 [WARNING]
 ===================================
@@ -39,7 +39,7 @@ level Java REST Client] with JSON request and response bodies.
 To use the transport client with a secured cluster, you need to:
 
 [[java-transport-client-role]]
-. {ref}/setup-xpack-client.html[Configure the {xpack} transport client].
+. <<setup-xpack-client,Configure the {xpack} transport client>>.
 
 . Configure a user with the privileges required to start the transport client.
 A default `transport_client` role is built-in to {xpack} that grants the
@@ -115,7 +115,7 @@ Client authentication requires every client to have a certification signed by a
 +
 --
 NOTE: Client authentication is enabled by default. For information about
-      disabling client authentication, see <<disabling-client-auth, Disabling Client Authentication>>.
+      disabling client authentication, see <<disabling-client-auth>>.
 
 [source,java]
 --------------------------------------------------------------------------------------------------
@@ -158,10 +158,11 @@ TransportClient client = new PreBuiltXPackTransportClient(Settings.builder()
 
 [float]
 [[disabling-client-auth]]
-===== Disabling Client Authentication
+===== Disabling client authentication
 
 If you want to disable client authentication, you can use a client-specific
-transport protocol. For more information see <<separating-node-client-traffic, Separating Node to Node and Client Traffic>>.
+transport protocol. For more information see
+<<separating-node-client-traffic>>.
 
 If you are not using client authentication and sign the Elasticsearch node
 certificates with your own CA, you need to provide the path to the CA
@@ -188,12 +189,12 @@ NOTE: If you are using a public CA that is already trusted by the Java runtime,
 
 [float]
 [[connecting-anonymously]]
-===== Connecting Anonymously
+===== Connecting anonymously
 
 To enable the transport client to connect anonymously, you must assign the
 anonymous user the privileges defined in the <<java-transport-client-role,transport_client>>
 role. Anonymous access must also be enabled, of course. For more information,
-see <<anonymous-access,Enabling Anonymous Access>>.
+see <<anonymous-access>>.
 
 [float]
 [[security-client]]
diff --git a/x-pack/docs/en/security/tribe-clients-integrations/monitoring.asciidoc b/x-pack/docs/en/security/tribe-clients-integrations/monitoring.asciidoc
index aad11ebe707e0..57c52343ec62d 100644
--- a/x-pack/docs/en/security/tribe-clients-integrations/monitoring.asciidoc
+++ b/x-pack/docs/en/security/tribe-clients-integrations/monitoring.asciidoc
@@ -1,7 +1,7 @@
 [[secure-monitoring]]
 === Monitoring and Security
 
-<<xpack-monitoring, {monitoring}>> consists of two components: an agent
+{monitoring} consists of two components: an agent
 that you install on each {es} and Logstash node, and a Monitoring UI
 in {kib}. The monitoring agent collects and indexes metrics from the nodes
 and you visualize the data through the Monitoring dashboards in {kib}. The agent
@@ -17,7 +17,7 @@ with the monitoring cluster.
 
 For more information, see:
 
-* {ref}/configuring-monitoring.html[Configuring monitoring in {es}]
+* <<configuring-monitoring>>
 * {kibana-ref}/monitoring-xpack-kibana.html[Configuring monitoring in {kib}]
 * {logstash-ref}/configuring-logstash.html[Configuring monitoring for Logstash nodes]
 
diff --git a/x-pack/docs/en/security/tribe-clients-integrations/tribe.asciidoc b/x-pack/docs/en/security/tribe-clients-integrations/tribe.asciidoc
index 2402d0a5f75f5..42062b9075252 100644
--- a/x-pack/docs/en/security/tribe-clients-integrations/tribe.asciidoc
+++ b/x-pack/docs/en/security/tribe-clients-integrations/tribe.asciidoc
@@ -1,7 +1,7 @@
 [[tribe-node-configuring]]
-=== Tribe Nodes and Security
+=== Tribe nodes and security
 
-{ref}/modules-tribe.html[Tribe nodes] act as a federated client across multiple
+<<modules-tribe,Tribe nodes>> act as a federated client across multiple
 clusters. When using tribe nodes with secured clusters, all clusters must have
 {security} enabled and share the same security configuration (users, roles,
 user-role mappings, SSL/TLS CA). The tribe node itself also must be configured
diff --git a/x-pack/docs/en/security/troubleshooting.asciidoc b/x-pack/docs/en/security/troubleshooting.asciidoc
index 1ed44c3067e5e..13646171cec04 100644
--- a/x-pack/docs/en/security/troubleshooting.asciidoc
+++ b/x-pack/docs/en/security/troubleshooting.asciidoc
@@ -2,7 +2,7 @@
 [[security-troubleshooting]]
 == Troubleshooting security
 ++++
-<titleabbrev>Security</titleabbrev>
+<titleabbrev>Troubleshooting</titleabbrev>
 ++++
 
 Use the information in this section to troubleshoot common problems and find
@@ -53,7 +53,7 @@ index in the old format to a 6.0 cluster.
 
 *Symptoms:*
 
-* When you use the {ref}/cluster-nodes-info.html[nodes info API] to retrieve
+* When you use the <<cluster-nodes-info,nodes info API>> to retrieve
 settings for a node, some information is missing.
 
 *Resolution:*
@@ -100,7 +100,7 @@ jacknich       : monitoring,unknown_role* <1>
 <1> `unknown_role` was not found in `roles.yml`
 
 For more information about this command, see the 
-{ref}/users-command.html[`elasticsearch-users` command].
+<<users-command,`elasticsearch-users` command>>.
 --
 
 . If you are authenticating to LDAP, a number of configuration options can cause
@@ -159,7 +159,7 @@ recognizes `role1` as an expected parameter. The solution here is to quote the
 parameter: `-r "role1,role2"`.
 
 For more information about this command, see
-{ref}/users-command.html[`elasticsearch-users` command].
+<<users-command,`elasticsearch-users` command>>.
 
 [[trouble-shoot-active-directory]]
 === Users are frequently locked out of Active Directory
@@ -299,7 +299,7 @@ verify that all nodes are using the same setting for
 `xpack.security.transport.ssl.enabled`.
 
 For more information about this setting, see
-{ref}/security-settings.html[Security Settings in {es}].
+<<security-settings>>.
 --
 
 `java.io.StreamCorruptedException: invalid internal transport message format, got`::
@@ -311,7 +311,7 @@ connects to a node that has encrypted communication disabled. Please verify that
 all nodes are using the same setting for `xpack.security.transport.ssl.enabled`.
 
 For more information about this setting, see
-{ref}/security-settings.html[Security Settings in {es}].
+<<security-settings>>.
 --
 
 `java.lang.IllegalArgumentException: empty text`::
@@ -327,7 +327,7 @@ xpack.security.http.ssl.enabled: true
 ----------------
 
 For more information about this setting, see
-{ref}/security-settings.html[Security Settings in {es}].
+<<security-settings>>.
 --
 
 `ERROR: unsupported ciphers [...] were requested but cannot be used in this JVM`::
@@ -405,7 +405,7 @@ module use following Kerberos realm setting:
 xpack.security.authc.realms.<realm-name>.krb.debug: true
 ----------------
 
-For detailed information, see {ref}/security-settings.html#ref-kerberos-settings[Kerberos realm settings].
+For detailed information, see <<ref-kerberos-settings>>.
 
 Sometimes you may need to go deeper to understand the problem during SPNEGO 
 GSS context negotiation or look at the Kerberos message exchange. To enable 
@@ -415,7 +415,7 @@ Kerberos/SPNEGO debug logging on JVM, add following JVM system properties:
 
 `-Dsun.security.spnego.debug=true`
 
-For more information about JVM system properties, see {ref}/jvm-options.html[configuring JVM options].
+For more information about JVM system properties, see <<jvm-options>>.
 
 [[trb-security-saml]]
 === Common SAML issues
@@ -679,7 +679,7 @@ Otherwise, {kib} cannot connect to {es}.
 [[trb-security-setup]]
 === Setup-passwords command fails due to connection failure
 
-The {ref}/setup-passwords.html[elasticsearch-setup-passwords command] sets
+The <<setup-passwords,elasticsearch-setup-passwords command>> sets
 passwords for the built-in users by sending user management API requests. If
 your cluster uses SSL/TLS for the HTTP (REST) interface, the command attempts to
 establish a connection with the HTTPS protocol. If the connection attempt fails,
@@ -756,7 +756,7 @@ Alternatively, set the `xpack.security.http.ssl.enabled` setting to `true`.
 `xpack.security.http.ssl.verification_mode` to `certificate`.
 
 For more information about these settings, see
-{ref}/security-settings.html[Security Settings in {es}].
+<<security-settings>>.
 
 [[trb-security-path]]
 === Failures due to relocation of the configuration files
@@ -773,7 +773,7 @@ By default, in 6.2 and earlier releases, the
 <<security-files,security configuration files>> are located in the 
 `ES_PATH_CONF/x-pack` directory, where `ES_PATH_CONF` is an environment 
 variable that defines the location of the 
-{ref}/settings.html#config-files-location[config directory]. 
+<<config-files-location,config directory>>. 
 
 In 6.3 and later releases, the config directory no longer contains an `x-pack` 
 directory. The files that were stored in this folder, such as the 
@@ -787,5 +787,5 @@ deprecated, however, and you should move your files out of that folder.
 In 6.3 and later releases, settings such as `files.role_mapping` default to 
 `ES_PATH_CONF/role_mapping.yml`. If you do not want to use the default locations, 
 you must update the settings appropriately. See 
-{ref}/security-settings.html[Security settings in {es}]. 
+<<security-settings>>.