diff --git a/docs/reference/index.asciidoc b/docs/reference/index.asciidoc
index 49ba010683686..910217879bb57 100644
--- a/docs/reference/index.asciidoc
+++ b/docs/reference/index.asciidoc
@@ -63,7 +63,7 @@ include::rollup/index.asciidoc[]
 
 include::frozen-indices.asciidoc[]
 
-include::security/index.asciidoc[]
+include::{xes-repo-dir}/security/index.asciidoc[]
 
 include::{xes-repo-dir}/watcher/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 bd0a5a026296c..685c3c6b8365e 100644
--- a/x-pack/docs/en/security/auditing/event-types.asciidoc
+++ b/x-pack/docs/en/security/auditing/event-types.asciidoc
@@ -18,7 +18,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
@@ -28,7 +28,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 the {security-features} detect 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 027482df75fd3..d0c0a75b61733 100644
--- a/x-pack/docs/en/security/auditing/index.asciidoc
+++ b/x-pack/docs/en/security/auditing/index.asciidoc
@@ -1,18 +1,7 @@
 
-: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/auditing-search-queries.asciidoc
 include::auditing-search-queries.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/x-pack/docs/en/security/auditing/forwarding-logs.asciidoc
 include::forwarding-logs.asciidoc[]
diff --git a/x-pack/docs/en/security/authentication/index.asciidoc b/x-pack/docs/en/security/authentication/index.asciidoc
index 1af179a5c269c..92e033d3521e4 100644
--- a/x-pack/docs/en/security/authentication/index.asciidoc
+++ b/x-pack/docs/en/security/authentication/index.asciidoc
@@ -11,11 +11,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 17060860a4540..dab36c636117d 100644
--- a/x-pack/docs/en/security/configuring-es.asciidoc
+++ b/x-pack/docs/en/security/configuring-es.asciidoc
@@ -8,8 +8,7 @@
 The {es} {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. For more information, see
-{stack-ov}/elasticsearch-security.html[Securing the {stack}].
+auditing.
 
 To use {es} {security-features}:
 
@@ -25,7 +24,7 @@ https://www.elastic.co/subscriptions and
 
 . 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
-{stack-ov}/encrypting-communications.html[Encrypting Communications].
+<<encrypting-communications>>.
 
 --
 .. <<node-certificates,Generate node certificates for each of your {es} nodes>>.
@@ -50,7 +49,7 @@ information, see
 +
 --
 The {es} {security-features} provide
-{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 {stack-ov}/auditing.html[Auditing Security Events] 
+For more information, see <<auditing>> 
 and <<auditing-settings>>. 
 
 .. Restart {es}.
@@ -135,37 +134,18 @@ 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/security/reference/files.asciidoc
-include::{es-repo-dir}/security/reference/files.asciidoc[]
-
-:edit_url: https://github.com/elastic/elasticsearch/edit/{branch}/docs/reference/settings/audit-settings.asciidoc
+include::reference/files.asciidoc[]
 include::{es-repo-dir}/settings/audit-settings.asciidoc[]
diff --git a/x-pack/docs/en/security/get-started-security.asciidoc b/x-pack/docs/en/security/get-started-security.asciidoc
index 846cf9ab375fb..3ae5f5115ec47 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>>. 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 0e4ada78e8fce..013758188b876 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 320342dec13be..7d591c558ede6 100644
--- a/x-pack/docs/en/security/index.asciidoc
+++ b/x-pack/docs/en/security/index.asciidoc
@@ -1,109 +1,39 @@
-[role="xpack"]
-[[elasticsearch-security]]
-= Securing the {stack}
+[[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. 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`. The
-{es-security-features} provide 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, the {security-features}
-are 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. The
-{es-security-features} enable 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.
-
-The {security-features} also support <<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. The {stack-security-features} preserve 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 {stack-security-features} 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>>
+* <<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 the 
-  {stack-security-features}.
+* <<security-getting-started>>
+* <<encrypting-internode-communications>>
+* <<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::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::auditing/index.asciidoc[]
+include::securing-communications/index.asciidoc[]
+include::using-ip-filtering.asciidoc[]
+include::tribe-clients-integrations/index.asciidoc[]
 include::get-started-security.asciidoc[]
-
 include::securing-communications/tutorial-tls-intro.asciidoc[]
+include::troubleshooting.asciidoc[]
+include::limitations.asciidoc[]
diff --git a/x-pack/docs/en/security/limitations.asciidoc b/x-pack/docs/en/security/limitations.asciidoc
index 0d075847ca89d..5c0ada645aee3 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/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 b727b55aadcfa..80d899c350e8e 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 63fded729eb8c..52a9a2868e4ab 100644
--- a/x-pack/docs/en/security/securing-communications.asciidoc
+++ b/x-pack/docs/en/security/securing-communications/index.asciidoc
@@ -18,15 +18,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[]
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 d0d4d108abada..da4bab060da9e 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 598c3318fd52d..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>>
-
-
-The {es} {security-features} enable you to secure your {es} cluster. But
-{es} itself is only one product within the {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/cross-cluster-kibana.asciidoc b/x-pack/docs/en/security/tribe-clients-integrations/cross-cluster-kibana.asciidoc
new file mode 100644
index 0000000000000..95e5d188f0084
--- /dev/null
+++ b/x-pack/docs/en/security/tribe-clients-integrations/cross-cluster-kibana.asciidoc
@@ -0,0 +1,39 @@
+[[cross-cluster-kibana]]
+==== {ccs-cap} and {kib}
+
+When {kib} 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 {kib} is connected to.)
+* If they are, the remote cluster then determines if the user has access
+to the specified indices.
+
+To grant {kib} 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 {kib} is connected to the cluster where you're actively
+indexing {ls} 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 {kib} 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 {kib} 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 b20aabd323f1b..b89aef2fdb242 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
 
-{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 the {es} {security-features}
 enabled.
@@ -25,7 +25,7 @@ To use cross cluster search with secured clusters:
 
 * Enable the {es} {security-features} 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.
@@ -37,10 +37,10 @@ For more 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-remote-clusters.html#configuring-remote-clusters[Configuring Remote Clusters].
+  in <<configuring-remote-clusters>>.
   For example, the following configuration adds two remote clusters
   to the local cluster:
 +
@@ -70,7 +70,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`.
@@ -145,7 +145,7 @@ cluster `two` as follows:
 
 [source,js]
 -----------------------------------------------------------
-GET two:logs-2017.04/_search <1>
+GET two:logs-2017.04/_search 
 {
   "query": {
     "match_all": {}
@@ -154,7 +154,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/index.asciidoc b/x-pack/docs/en/security/tribe-clients-integrations/index.asciidoc
new file mode 100644
index 0000000000000..d2b8c4713a6d1
--- /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>>
+
+
+The {es} {security-features} enable you to secure your {es} cluster. But
+{es} itself is only one product within the {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]
+
+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/monitoring.asciidoc b/x-pack/docs/en/security/tribe-clients-integrations/monitoring.asciidoc
index 1a18fdc167893..344fde687ad8f 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
 
-The <<xpack-monitoring,{stack} {monitor-features}>> consist of two components:
+The {stack} {monitor-features} consist of two components:
 an agent that you install on 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}/monitor-elasticsearch-cluster.html[Monitor a cluster]
+* <<monitor-elasticsearch-cluster>>
 * {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/troubleshooting.asciidoc b/x-pack/docs/en/security/troubleshooting.asciidoc
index a321dcc48db6e..8c9c761cca0ae 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