[DOCS] Security link fixes (#48172)

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

@@ -27,7 +27,7 @@ Role mappings define which roles are assigned to each user. Each mapping has
 _rules_ that identify users and a list of _roles_ that are granted to those users.
 
 The role mapping APIs are generally the preferred way to manage role mappings
-rather than using {stack-ov}/mapping-roles.html#mapping-roles-file[role mapping files].
+rather than using <<mapping-roles-file,role mapping files>>.
 The create or update role mappings API cannot update role mappings that are defined
 in role mapping files.
 

x-pack/docs/en/security/auditing/output-logfile.asciidoc

@@ -20,7 +20,7 @@ logger.xpack_security_audit_deprecated_logfile.level = off
 --------------------------------------------------
 
 Alternatively, use the
-{ref}/cluster-update-settings.html[cluster update settings API] to dynamically
+<<cluster-update-settings,cluster update settings API>> to dynamically
 configure the logger:
 
 [source,console]
@@ -72,7 +72,7 @@ The log entries in the `<clustername>_access.log` file have the following format
 `<local_node_info>` ::      Information about the local node that generated
                             the log entry. You can control what node information
                             is included by configuring the
-                            {ref}/auditing-settings.html#node-audit-settings[local node info settings].
+                            <<node-audit-settings,local node info settings>>.
 `<layer>`           ::      The layer from which this event originated:
                             `rest`, `transport` or `ip_filter`.
 `<entry_type>`      ::       The type of event that occurred: `anonymous_access_denied`,
@@ -90,8 +90,8 @@ The log entries in the `<clustername>_access.log` file have the following format
 
 The events and some other information about what gets logged can be
 controlled using settings in the `elasticsearch.yml` file. See
-{ref}/auditing-settings.html#event-audit-settings[Audited Event Settings] and
-{ref}/auditing-settings.html#node-audit-settings[Local Node Info Settings].
+<<event-audit-settings>> and
+<<node-audit-settings>>.
 
 IMPORTANT: No filtering is performed when auditing, so sensitive data may be
 audited in plain text when including the request body in audit events.
@@ -131,7 +131,7 @@ Please take time to review these policies whenever your system architecture chan
 
 A policy is a named set of filter rules. Each filter rule applies to a single event attribute,
 one of the `users`, `realms`, `roles` or `indices` attributes. The filter rule defines
-a list of {ref}/regexp-syntax.html[Lucene regexp], *any* of which has to match the value of the audit
+a list of <<regexp-syntax,Lucene regexp>>, *any* of which has to match the value of the audit
 event attribute for the rule to match.
 A policy matches an event if *all* the rules comprising it match the event.
 An audit event is ignored, therefore not printed, if it matches *any* policy. All other

x-pack/docs/en/security/authentication/active-directory-realm.asciidoc

@@ -7,7 +7,7 @@ Directory to authenticate users. To integrate with Active Directory, you
 configure an `active_directory` realm and map Active Directory users and groups
 to roles in the <<mapping-roles, role mapping file>>.
 
-See {ref}/configuring-ad-realm.html[Configuring an active directory realm].
+See <<configuring-ad-realm>>.
 
 The {security-features} use LDAP to communicate with Active Directory, so
 `active_directory` realms are similar to <<ldap-realm, `ldap` realms>>. Like
@@ -40,18 +40,18 @@ the {security-features} should interact with multiple Active Directory servers.
 Two modes of operation are supported: failover and load balancing.
 
 See
-{ref}/security-settings.html#load-balancing[Load balancing and failover settings].
+<<load-balancing>>.
 
 [[ad-settings]]
 ==== Active Directory realm settings
 
 See
-{ref}/security-settings.html#ref-ad-settings[Active Directory realm settings].
+<<ref-ad-settings>>.
 
 [[mapping-roles-ad]]
 ==== Mapping Active Directory users and groups to roles
 
-See {ref}/configuring-ad-realm.html[Configuring an Active Directory realm]. 
+See <<configuring-ad-realm>>. 
 
 [[ad-user-metadata]]
 ==== User metadata in Active Directory realms
@@ -67,7 +67,7 @@ properties are populated in the user's _metadata_:
 |=======================
 
 This metadata is returned in the 
-{ref}/security-api-authenticate.html[authenticate API] and can be used with
+<<security-api-authenticate,authenticate API>> and can be used with
 <<templating-role-query, templated queries>> in roles.
 
 Additional metadata can be extracted from the Active Directory server by configuring
@@ -77,4 +77,4 @@ the `metadata` setting on the Active Directory realm.
 ==== Setting up SSL between Elasticsearch and Active Directory
 
 See 
-{ref}/configuring-tls.html#tls-active-directory[Encrypting communications between {es} and Active Directory].
+<<tls-active-directory>>.

x-pack/docs/en/security/authentication/built-in-users.asciidoc

@@ -30,7 +30,7 @@ Although they share the same API, the built-in users are separate and distinct
 from users managed by the <<native-realm, native realm>>. Disabling the native
 realm will not have any effect on the built-in users. The built-in users can
 be disabled individually, using the
-{ref}/security-api-disable-user.html[disable users API].
+<<security-api-disable-user,disable users API>>.
 
 [float]
 [[bootstrap-elastic-passwords]]
@@ -45,7 +45,7 @@ setting, which is added to the keystore during installation. You do not need
 to know or change this bootstrap password. If you have defined a
 `bootstrap.password` setting in the keystore, however, that value is used instead.
 For more information about interacting with the keystore, see
-{ref}/secure-settings.html[Secure Settings].
+<<secure-settings>>.
 
 NOTE: After you <<set-built-in-user-passwords,set passwords for the built-in users>>,
 in particular for the `elastic` user, there is no further use for the bootstrap
@@ -70,7 +70,7 @@ bin/elasticsearch-setup-passwords interactive
 --------------------------------------------------
 
 For more information about the command options, see
-{ref}/setup-passwords.html[elasticsearch-setup-passwords].
+<<setup-passwords,elasticsearch-setup-passwords>>.
 
 IMPORTANT: After you set a password for the `elastic` user, the bootstrap
 password is no longer valid; you cannot run the `elasticsearch-setup-passwords`
@@ -78,7 +78,7 @@ command a second time.
 
 Alternatively, you can set the initial passwords for the built-in users by using
 the *Management > Users* page in {kib} or the
-{ref}/security-api-change-password.html[Change Password API]. These methods are
+<<security-api-change-password,change password API>>. These methods are
 more complex. You must supply the `elastic` user and its bootstrap password to
 log into {kib} or run the API. This requirement means that you cannot use the
 default bootstrap password that is derived from the `keystore.seed` setting.
@@ -165,7 +165,7 @@ monitoring data for the {stack}. See <<monitoring-production>>.
 If you have upgraded from an older version of {es}, then you may not have set a
 password for the `beats_system` or `remote_monitoring_user` users. If this is 
 the case, then you should use the *Management > Users* page in {kib} or the
-{ref}/security-api-change-password.html[Change Password API] to set a password
+<<security-api-change-password,change password API>> to set a password
 for these users.
 
 [float]
@@ -189,7 +189,7 @@ See {apm-server-ref}/monitoring.html[Monitoring APM Server].
 If you have upgraded from an older version of {es}, then you may not have set a
 password for the `apm_system` user. If this is the case, 
 then you should use the *Management > Users* page in {kib} or the
-{ref}/security-api-change-password.html[Change Password API] to set a password
+<<security-api-change-password,change password API>> to set a password
 for these users.
 
 [float]

x-pack/docs/en/security/authentication/file-realm.asciidoc

@@ -20,8 +20,8 @@ specify are used for authentication. To use the `file` realm as a fallback, you
 must include it in the realm chain.
 
 To define users, the {security-features} provide the
-{ref}/users-command.html[users] command-line tool. This tool enables you to add
+<<users-command,users>> command-line tool. This tool enables you to add
 and remove users, assign user roles, and manage user passwords.
 
 For more information, see 
-{ref}/configuring-file-realm.html[Configuring a file realm].
+<<configuring-file-realm>>.

x-pack/docs/en/security/authentication/kerberos-realm.asciidoc

@@ -8,10 +8,10 @@ authentication, an industry standard protocol to authenticate users in {es}.
 NOTE: You cannot use the Kerberos realm to authenticate on the transport network layer.
 
 To authenticate users with Kerberos, you need to
-{ref}/configuring-kerberos-realm.html[configure a Kerberos realm] and
+<<configuring-kerberos-realm,configure a Kerberos realm>> and
 <<mapping-roles, map users to roles>>.
 For more information on realm settings, see
-{ref}/security-settings.html#ref-kerberos-settings[Kerberos realm settings].
+<<ref-kerberos-settings>>.
 
 [[kerberos-terms]]
 ==== Key concepts

x-pack/docs/en/security/authentication/ldap-realm.asciidoc

@@ -23,7 +23,7 @@ and a mode with specific templates for user DNs.
 [[ldap-user-search]]
 ==== User search mode and user DN templates mode
 
-See {ref}/configuring-ldap-realm.html[Configuring an LDAP Realm].
+See <<configuring-ldap-realm>>.
 
 [[ldap-load-balancing]]
 ==== Load balancing and failover
@@ -32,12 +32,12 @@ the {security-features} should interact with multiple LDAP servers. The
 {security-features} support both failover and load balancing modes of operation.
 
 See
-{ref}/security-settings.html#load-balancing[Load balancing and failover settings].
+<<load-balancing>>.
 
 [[ldap-settings]]
 ==== LDAP realm settings
 
-See {ref}/security-settings.html#ref-ldap-settings[LDAP realm settings].
+See <<ref-ldap-settings>>.
 
 [[mapping-roles-ldap]]
 ==== Mapping LDAP groups to roles
@@ -53,11 +53,11 @@ systems in the organization.
 
 The `ldap` realm enables you to map LDAP users to roles via their LDAP
 groups, or other metadata. This role mapping can be configured via the
-{ref}/security-api-put-role-mapping.html[add role mapping API] or by using a
+<<security-api-put-role-mapping,add role mapping API>> or by using a
 file stored on each node. When a user authenticates with LDAP, the privileges
 for that user are the union of all privileges defined by the roles to which
 the user is mapped. For more information, see 
-{ref}/configuring-ldap-realm.html[Configuring an LDAP realm].
+<<configuring-ldap-realm>>.
 
 [[ldap-user-metadata]]
 ==== User metadata in LDAP realms
@@ -73,7 +73,7 @@ populated in the user's _metadata_:
 |=======================
 
 This metadata is returned in the
-{ref}/security-api-authenticate.html[authenticate API], and can be used with
+<<security-api-authenticate,authenticate API>>, and can be used with
 <<templating-role-query, templated queries>> in roles.
 
 Additional fields can be included in the user's metadata by  configuring
@@ -85,4 +85,4 @@ with the <<mapping-roles-api, role mapping API>> or in
 ==== Setting up SSL between Elasticsearch and LDAP
 
 See
-{ref}/configuring-tls.html#tls-ldap[Encrypting communications between {es} and LDAP]. 
+<<tls-ldap>>. 

x-pack/docs/en/security/authentication/native-realm.asciidoc

@@ -10,12 +10,12 @@ roles, and manage user passwords.
 [float]
 ==== Configuring a native realm
 
-See {ref}/configuring-native-realm.html[Configuring a native realm]. 
+See <<configuring-native-realm>>. 
 
 [[native-settings]]
 ==== Native realm settings
 
-See {ref}/security-settings.html#ref-native-settings[Native realm settings]. 
+See <<ref-native-settings>>. 
 
 [[managing-native-users]]
 ==== Managing native users
@@ -25,4 +25,4 @@ The {stack} {security-features} enable you to easily manage users in {kib} on th
 
 Alternatively, you can manage users through the `user` API. For more 
 information and examples, see
-{ref}/security-api.html#security-user-apis[user management APIs].
+<<security-user-apis>>.

x-pack/docs/en/security/authentication/oidc-guide.asciidoc

@@ -63,7 +63,7 @@ configure the HTTP interface to use SSL/TLS before you can enable OpenID Connect
 authentication.
 
 For more information, see
-{ref}/configuring-tls.html#tls-http[Encrypting HTTP Client Communications].
+<<tls-http>>.
 
 [[oidc-enable-token]]
 ==== Enable the token service
@@ -84,8 +84,8 @@ OpenID Connect based authentication is enabled by configuring the appropriate re
 the authentication chain for {es}.
 
 This realm has a few mandatory settings, and a number of optional settings.
-The available settings are described in detail in the
-{ref}/security-settings.html#ref-oidc-settings[Security settings in {es}]. This
+The available settings are described in detail in
+<<ref-oidc-settings. This
 guide will explore the most common settings.
 
 Create an OpenID Connect (the realm type is `oidc`) realm in your `elasticsearch.yml` file
@@ -188,7 +188,8 @@ claims.groups:: See <<oidc-claims-mapping>>.
 
 A final piece of configuration of the OpenID Connect realm is to set the `Client Secret` that was assigned
 to the RP during registration in the OP. This is a secure setting and as such is not defined in the realm
-configuration in `elasticsearch.yml` but added to the {ref}/secure-settings.html[elasticsearch keystore].
+configuration in `elasticsearch.yml` but added to the
+<<secure-settings,elasticsearch keystore>>.
 For instance
 
 
@@ -252,7 +253,7 @@ The recommended steps for configuring OpenID Claims mapping are as follows:
   party. This process greatly varies by provider. You can use a static
   configuration while others will support that the RP requests the scopes that
   correspond to the claims to be "released" on authentication time. See
-  {ref}/security-settings.html#ref-oidc-settings[`rp.requested_scopes`] for details about how
+  <<ref-oidc-settings,`rp.requested_scopes`>> for details about how
   to configure the scopes to request. To ensure interoperability and minimize
   the errors, you should only request scopes that the OP supports, and which you
   intend to map to {es} user properties.
@@ -413,7 +414,7 @@ access any data.
 
 Your OpenID Connect users cannot do anything until they are assigned roles. This can be done
 through either the
-{ref}/security-api-put-role-mapping.html[add role mapping API], or with
+<<security-api-put-role-mapping,add role mapping API>> or with
 <<authorization_realms,authorization realms>>.
 
 NOTE: You cannot use <<mapping-roles-file,role mapping files>>
@@ -447,7 +448,7 @@ mapping are derived from the OpenID Connect claims as follows:
 - `metadata`: See <<oidc-user-metadata>>
 
 For more information, see <<mapping-roles>> and
-{ref}/security-api.html#security-role-mapping-apis[role mapping APIs].
+<<security-role-mapping-apis>>.
 
 If your OP has the ability to provide groups or roles to RPs via tha use of
 an OpenID Claim, then you should map this claim to the `claims.groups` setting in
@@ -620,8 +621,9 @@ On a high level, the custom web application would need to perform the following
 authenticate a user with OpenID Connect:
 
 . Make an HTTP POST request to `_security/oidc/prepare`, authenticating as the `facilitator` user, using the name of the
-OpenID Connect realm in the {es} configuration in the request body. See the
-{ref}/security-api-oidc-prepare-authentication.html[OIDC Prepare Authentication API] for more details
+OpenID Connect realm in the {es} configuration in the request body. For more
+details, see 
+<<security-api-oidc-prepare-authentication>>.
 +
 [source,console]
 --------------------------------------------------
@@ -643,8 +645,8 @@ POST /_security/oidc/prepare
   where the user's browser was redirected to, as a parameter, along with the
   values for `nonce` and `state` it had saved in the user's session previously. If more than one
   OpenID Connect realms are configured, the custom web app can specify the name of the realm to be
-  used for handling this, but this parameter is optional.
-  See {ref}/security-api-oidc-authenticate.html[OIDC Authenticate API] for more details
+  used for handling this, but this parameter is optional. For more details, see
+  <<security-api-oidc-authenticate>>.
 +
 [source,console]
 -----------------------------------------------------------------------
@@ -660,9 +662,9 @@ POST /_security/oidc/authenticate
 +
 Elasticsearch will validate this and if all is correct will respond with an access token that can be used
 as a `Bearer` token for subsequent requests and a refresh token that can be later used to refresh the given
-access token as described in {ref}/security-api-get-token.html[get token API].
+access token as described in <<security-api-get-token>>.
 . At some point, if necessary, the custom web application can log the user out by using the
-  {ref}/security-api-oidc-logout.html[OIDC Logout API] passing the access token and refresh token as parameters. For example:
+<<security-api-oidc-logout,OIDC logout API>> passing the access token and refresh token as parameters. For example:
 +
 [source,console]
 --------------------------------------------------

x-pack/docs/en/security/authentication/pki-realm.asciidoc

@@ -11,17 +11,16 @@ You can use PKI certificates to authenticate users in {es} as well as {kib}.
 To use PKI in {es}, you configure a PKI realm, enable client authentication on
 the desired network layers (transport or http), and map the Distinguished Names
 (DNs) from the user certificates to roles. You create the mappings in a <<pki-role-mapping, role
-mapping file>> or use the {ref}/security-api-put-role-mapping.html[create role mappings API]. If you want the same users to also be
+mapping file>> or use the
+<<security-api-put-role-mapping,create role mappings API>>. If you want the same users to also be
 authenticated using certificates when they connect to {kib}, you must configure the {es} PKI
 realm to
-{ref}/configuring-pki-realm.html#pki-realm-for-proxied-clients[allow
-delegation] and to
-{kibana-ref}/kibana-authentication.html#pki-authentication[enable PKI
-authentication in {kib}].
+<<pki-realm-for-proxied-clients,allow delegation>> and to
+{kibana-ref}/kibana-authentication.html#pki-authentication[enable PKI authentication in {kib}].
 
-See also {ref}/configuring-pki-realm.html[Configuring a PKI realm].
+See also <<configuring-pki-realm>>.
 
 [[pki-settings]]
 ==== PKI realm settings
 
-See {ref}/security-settings.html#ref-pki-settings[PKI realm settings].
+See <<ref-pki-settings>>.

x-pack/docs/en/security/authentication/realm-chains.asciidoc

@@ -67,7 +67,7 @@ xpack.security.authc:
 As can be seen above, each realm has a unique name that identifies it. Each type
 of realm dictates its own set of required and optional settings. That said,
 there are 
-{ref}/security-settings.html#ref-realm-settings[settings that are common to all realms]. 
+<<ref-realm-settings,settings that are common to all realms>>. 
 
 [[authorization_realms]]
 ==== Delegating authorization to another realm
@@ -87,7 +87,7 @@ further explanation on which realms support this.
 
 For realms that support this feature, it can be enabled by configuring the
 `authorization_realms` setting on the authenticating realm. Check the list of
-{ref}/security-settings.html#realm-settings[supported settings] for each realm
+<<realm-settings,supported settings>> for each realm
 to see if they support the `authorization_realms` setting. 
 
 If delegated authorization is enabled for a realm, it authenticates the user in 

x-pack/docs/en/security/authentication/realms.asciidoc

@@ -12,7 +12,7 @@ _native_::
 An internal realm where users are stored in a dedicated {es} index.
 This realm supports an authentication token in the form of username and password,
 and is available by default when no realms are explicitly configured. The users
-are managed via the {ref}/security-api.html#security-user-apis[user management APIs].
+are managed via the <<security-user-apis,user management APIs>>.
 See <<native-realm>>.
 
 _ldap_::

x-pack/docs/en/security/authentication/saml-realm.asciidoc

@@ -25,17 +25,17 @@ for SAML realms.
 [[saml-settings]]
 ==== SAML realm settings
 
-See {ref}/security-settings.html#ref-saml-settings[SAML realm settings]. 
+See <<ref-saml-settings>>. 
 
 ==== SAML realm signing settings
 
-See {ref}/security-settings.html#ref-saml-signing-settings[SAML realm signing settings]. 
+See <<ref-saml-signing-settings>>. 
 
 ==== SAML realm encryption settings
 
-See {ref}/security-settings.html#ref-saml-encryption-settings[SAML realm encryption settings]. 
+See <<ref-saml-encryption-settings>>. 
 
 ==== SAML realm SSL settings
 
-See {ref}/security-settings.html#ref-saml-ssl-settings[SAML realm SSL settings]. 
+See <<ref-saml-ssl-settings>>. 
 

x-pack/docs/en/security/authentication/token-authentication-services.asciidoc

@@ -13,7 +13,7 @@ The {security-features} provide the following built-in token-based authenticatio
 services, which are listed in the order they are consulted:
 
 _token-service_::
-The token service uses the {ref}/security-api-get-token.html[get token API] to
+The token service uses the <<security-api-get-token,get token API>> to
 generate access tokens and refresh tokens based on the OAuth2 specification.
 The access token is a short-lived token. By default, it expires after 20 minutes
 but it can be configured to last a maximum of 1 hour. It can be refreshed by
@@ -32,7 +32,7 @@ curl -H "Authorization: Bearer dGhpcyBpcyBub3QgYSByZWFsIHRva2VuIGJ1dCBpdCBpcyBvb
 
 _api-key-service_::
 The API key service uses the
-{ref}/security-api-create-api-key.html[create API key API] to generate API keys.
+<<security-api-create-api-key,create API key API>> to generate API keys.
 By default, the API keys do not expire. When you make a request to create API
 keys, you can specify an expiration and permissions for the API key. The
 permissions are limited by the authenticated user's permissions. You can use the
@@ -54,5 +54,5 @@ service to use to generate and manage the tokens. Non-expiring API keys may seem
 like the easy option but you must consider the security implications that come
 with non-expiring keys. Both the _token-service_ and _api-key-service_ permit
 you to invalidate the tokens. See
-{ref}/security-api-invalidate-token.html[invalidate token API] and
-{ref}/security-api-invalidate-api-key.html[invalidate API key API].
+<<security-api-invalidate-token,invalidate token API>> and
+<<security-api-invalidate-api-key,invalidate API key API>>.

x-pack/docs/en/security/authentication/user-cache.asciidoc

@@ -13,12 +13,12 @@ object to avoid unnecessarily needing to perform role mapping on each request.
 The cached user credentials are hashed in memory. By default, the {es}
 {security-features} use a salted `sha-256` hash algorithm. You can use a
 different hashing algorithm by setting the `cache.hash_algo` realm settings. See 
-{ref}/security-settings.html#hashing-settings[User cache and password hash algorithms].
+<<hashing-settings>>.
 
 [[cache-eviction-api]]
 ==== Evicting users from the cache
 
-You can use the {ref}/security-api-clear-cache.html[clear cache API] to force
+You can use the <<security-api-clear-cache,clear cache API>> to force
 the eviction of cached users . For example, the following request evicts all
 users from the `ad1` realm:
 

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

@@ -2,7 +2,8 @@
 [[securing-aliases]]
 === Granting privileges for indices and aliases
 
-Elasticsearch allows to execute operations against {ref}/indices-aliases.html[index aliases],
+Elasticsearch allows to execute operations against
+<<indices-aliases,index aliases>>,
 which are effectively virtual indices. An alias points to one or more indices,
 holds metadata and potentially a filter. The {es} {security-features} treat
 aliases and indices
@@ -97,4 +98,4 @@ alias need the `manage` permission.
 Aliases can hold a filter, which allows to select a subset of documents that can
 be accessed out of all the documents that the physical index contains. These
 filters are not always applied and should not be used in place of
-<<document-level-security, document level security>>.
+<<document-level-security,document level security>>.

x-pack/docs/en/security/authorization/document-level-security.asciidoc

@@ -32,7 +32,7 @@ NOTE: Omitting the `query` entry entirely disables document level security for
       the respective indices permission entry.
 
 The specified `query` expects the same format as if it was defined in the
-search request and supports the full {es} {ref}/query-dsl.html[Query DSL].
+search request and supports the full {es} <<query-dsl,query DSL>>.
 
 For example, the following role grants read access only to the documents whose
 `department_id` equals `12`:

x-pack/docs/en/security/authorization/field-and-document-access-control.asciidoc

@@ -26,7 +26,7 @@ document level permissions per index. See <<multiple-roles-dls-fls>>.
 =====================================================================
 
 NOTE: Document- and field-level security disables the
-{ref}/shard-request-cache.html[shard request cache].
+<<shard-request-cache,shard request cache>>.
 
 [[multiple-roles-dls-fls]]
 ==== Multiple roles with document and field level security

x-pack/docs/en/security/authorization/field-level-security.asciidoc

@@ -217,7 +217,8 @@ The resulting permission is equal to:
 --------------------------------------------------
 // NOTCONSOLE
 
-NOTE: Field-level security should not be set on {ref}/alias.html[`alias`] fields. To secure a
+NOTE: Field-level security should not be set on <<alias,`alias`>> fields.
+To secure a
 concrete field, its field name must be used directly.
 
 For more information, see <<field-and-document-access-control>>.

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

@@ -133,13 +133,13 @@ The following describes the structure of an application privileges entry:
     have any special meaning to the {es} {security-features}.
 
 For details about the validation rules for these fields, see the
-{ref}/security-api-put-privileges.html[add application privileges API].
+<<security-api-put-privileges,add application privileges API>>.
 
 A role may refer to application privileges that do not exist - that is, they
 have not yet been defined through the add application privileges API (or they
 were defined, but have since been deleted). In this case, the privilege has
 no effect, and will not grant any actions in the
-{ref}/security-api-has-privileges.html[has privileges API].
+<<security-api-has-privileges,has privileges API>>.
 
 ==== Example
 
@@ -179,7 +179,7 @@ There are two available mechanisms to define roles: using the _Role Management A
 or in local files on the {es} nodes. You can also implement
 custom roles providers.  If you need to integrate with another system to retrieve
 user roles, you can build a custom roles provider plugin. For more information,
-see <<custom-roles-authorization, Customizing Roles and Authorization>>.
+see <<custom-roles-authorization>>.
 
 [float]
 [[roles-management-ui]]
@@ -195,7 +195,7 @@ manage roles, log in to {kib} and go to *Management / Security / Roles*.
 The _Role Management APIs_ enable you to add, update, remove and retrieve roles
 dynamically. When you use the APIs to manage roles in the `native` realm, the
 roles are stored in an internal {es} index. For more information and examples, 
-see {ref}/security-api.html#security-role-apis[role management APIs]. 
+see <<security-role-apis>>. 
 
 [float]
 [[roles-management-file]]

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

@@ -3,8 +3,8 @@
 === Mapping users and groups to roles
 
 If you authenticate users with the `native` or `file` realms, you can manage
-role assignment by using the <<managing-native-users, User Management APIs>> or
-the {ref}/users-command.html[users] command-line tool respectively.
+role assignment by using the <<managing-native-users,user management APIs>> or
+the <<users-command,users>> command-line tool respectively.
 
 For other types of realms, you must create _role-mappings_ that define which
 roles should be assigned to each user based on their username, groups, or
@@ -19,16 +19,16 @@ the API, and other roles that are mapped through files.
 
 When you use role-mappings, you assign existing roles to users.
 The available roles should either be added using the
-{ref}/security-api.html#security-role-apis[role management APIs] or defined in the
-<<roles-management-file, roles file>>. Either role-mapping method can use
+<<security-role-apis,role management APIs>> or defined in the
+<<roles-management-file,roles file>>. Either role-mapping method can use
 either role management method. For example, when you use the role mapping API,
 you are able to map users to both API-managed roles and file-managed roles
 (and likewise for file-based role-mappings).
 
 NOTE: The PKI, LDAP, Kerberos and SAML realms support using
-<<authorization_realms, authorization realms>> as an alternative to role mapping.
+<<authorization_realms,authorization realms>> as an alternative to role mapping.
 
-NOTE: When <<anonymous-access, anonymous access>> is enabled, the roles
+NOTE: When <<anonymous-access,anonymous access>> is enabled, the roles
 of the anonymous user are assigned to all the other users as well.
 
 NOTE: Users with no roles assigned will be unauthorized for any action.
@@ -37,7 +37,7 @@ NOTE: Users with no roles assigned will be unauthorized for any action.
 ==== Using the role mapping API
 
 You can define role-mappings through the
-{ref}/security-api-put-role-mapping.html[add role mapping API].
+<<security-api-put-role-mapping,add role mapping API>>.
 
 [[mapping-roles-file]]
 ==== Using role mapping files
@@ -50,9 +50,9 @@ By default, role mappings are stored in `ES_PATH_CONF/role_mapping.yml`,
 where `ES_PATH_CONF` is `ES_HOME/config` (zip/tar installations) or
 `/etc/elasticsearch` (package installations). To specify a different location,
 you configure the `files.role_mapping` setting in the 
-{ref}/security-settings.html#ref-ad-settings[Active Directory], 
-{ref}/security-settings.html#ref-ldap-settings[LDAP], and 
-{ref}/security-settings.html#ref-pki-settings[PKI] realm settings in 
+<<ref-ad-settings,Active Directory>>, 
+<<ref-ldap-settings,LDAP>>, and 
+<<ref-pki-settings,PKI>> realm settings in 
 `elasticsearch.yml`.
 
 Within the role mapping file, the security roles are keys and groups and users

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

@@ -24,9 +24,9 @@ ability to manage security.
 
 `manage_api_key`::
 All security-related operations on {es} API keys including 
-{ref}/security-api-create-api-key.html[creating new API keys],
-{ref}/security-api-get-api-key.html[retrieving information about API keys], and
-{ref}/security-api-invalidate-api-key.html[invalidating API keys].
+<<security-api-create-api-key,creating new API keys>>,
+<<security-api-get-api-key,retrieving information about API keys>>, and
+<<security-api-invalidate-api-key,invalidating API keys>>.
 +
 --
 [NOTE]
@@ -73,17 +73,17 @@ roles of the user who created or updated them.
 
 `manage_oidc`::
 Enables the use of {es} APIs
-({ref}/security-api-oidc-prepare-authentication.html[OpenID Connect Prepare Authentication],
-{ref}/security-api-oidc-authenticate.html[OpenID Connect Authenticate], and
-{ref}/security-api-oidc-logout.html[OpenID Connect Logout])
+(<<security-api-oidc-prepare-authentication,OpenID connect prepare authentication>>,
+<<security-api-oidc-authenticate,OpenID connect authenticate>>, and
+<<security-api-oidc-logout,OpenID connect logout>>)
 to initiate and manage OpenID Connect authentication on behalf of other users.
 
 `manage_own_api_key`::
 All security-related operations on {es} API keys that are owned by the current
 authenticated user. The operations include 
-{ref}/security-api-create-api-key.html[creating new API keys],
-{ref}/security-api-get-api-key.html[retrieving information about API keys], and
-{ref}/security-api-invalidate-api-key.html[invalidating API keys].
+<<security-api-create-api-key,creating new API keys>>,
+<<security-api-get-api-key,retrieving information about API keys>>, and
+<<security-api-invalidate-api-key,invalidating API keys>>.
 
 `manage_pipeline`::
 All operations on ingest pipelines.
@@ -145,7 +145,7 @@ status of {Ilm}
 
 `transport_client`::
 All privileges necessary for a transport client to connect.  Required by the remote
-cluster to enable <<cross-cluster-configuring,Cross Cluster Search>>.
+cluster to enable <<cross-cluster-configuring,{ccs}>>.
 
 [[privileges-list-indices]]
 ==== Indices privileges
@@ -210,7 +210,7 @@ from an index.
 
 `manage_leader_index`::
 All actions that are required to manage the lifecycle of a leader index, which
-includes {ref}/ccr-post-forget-follower.html[forgetting a follower]. This
+includes <<ccr-post-forget-follower,forgetting a follower>>. This
 privilege is necessary only on clusters that contain leader indices.
 
 `monitor`::
@@ -242,19 +242,19 @@ The `run_as` permission enables an authenticated user to submit requests on
 behalf of another user. The value can be a user name or a comma-separated list
 of user names. (You can also specify users as an array of strings or a YAML
 sequence.) For more information, see
-<<run-as-privilege, Submitting Requests on Behalf of Other Users>>.
+<<run-as-privilege>>.
 
 [[application-privileges]]
 ==== Application privileges
 
 Application privileges are managed within {es} and can be retrieved with the 
-{ref}/security-api-has-privileges.html[has privileges API] and the 
-{ref}/security-api-get-privileges.html[get application privileges API]. They do 
+<<security-api-has-privileges,has privileges API>> and the 
+<<security-api-get-privileges,get application privileges API>>. They do 
 not, however, grant access to any actions or resources within {es}. Their 
 purpose is to enable applications to represent and store their own privilege 
 models within {es} roles. 
 
 To create application privileges, use the 
-{ref}/security-api-put-privileges.html[add application privileges API]. You can 
+<<security-api-put-privileges,add application privileges API>>. You can 
 then associate these application privileges with roles, as described in 
 <<defining-roles>>. 

x-pack/docs/en/security/authorization/set-security-user.asciidoc

@@ -9,18 +9,19 @@ To guarantee that a user reads only their own documents, it makes sense to set u
 document level security. In this scenario, each document must have the username
 or role name associated with it, so that this information can be used by the
 role query for document level security. This is a situation where the
-{ref}/ingest-node-set-security-user-processor.html[Set Security User Processor] ingest processor can help.
+<<ingest-node-set-security-user-processor,set security user processor>> ingest processor can help.
 
 NOTE: Document level security doesn't apply to write APIs. You must use unique
 ids for each user that uses the same index, otherwise they might overwrite other
 users' documents. The ingest processor just adds properties for the current
 authenticated user to the documents that are being indexed.
 
-The {ref}/ingest-node-set-security-user-processor.html[set security user processor] attaches user-related details (such as
+The <<ingest-node-set-security-user-processor,set security user processor>> attaches user-related details (such as
 `username`,  `roles`, `email`, `full_name` and `metadata` ) from the current
 authenticated user to the current document by pre-processing the ingest. When
 you index data with an ingest pipeline, user details are automatically attached
 to the document.
 
-For more information see {ref}/ingest.html[Ingest node] and {ref}/ingest-node-set-security-user-processor.html[Set security user processor].
+For more information see <<ingest>> and
+<<ingest-node-set-security-user-processor>>
 

x-pack/docs/en/security/ccs-clients-integrations/cross-cluster.asciidoc

@@ -1,7 +1,7 @@
 [[cross-cluster-configuring]]
-=== Cross cluster search and security
+=== {ccs-cap} and security
 
-{ref}/modules-cross-cluster-search.html[Cross cluster search] enables
+<<modules-cross-cluster-search,{ccs-cap}>> 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:
 +
@@ -69,7 +69,8 @@ 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
+[[cross-cluster-configuring-example]]
+==== 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`.
@@ -140,7 +141,7 @@ cluster `two` as follows:
 
 [source,console]
 -----------------------------------------------------------
-GET two:logs-2017.04/_search <1>
+GET two:logs-2017.04/_search
 {
   "query": {
     "match_all": {}
@@ -148,6 +149,5 @@ GET two:logs-2017.04/_search <1>
 }
 -----------------------------------------------------------
 // TEST[skip:todo]
-//TBD: Is there a missing description of the <1> callout above?
 
 include::cross-cluster-kibana.asciidoc[]

x-pack/docs/en/security/ccs-clients-integrations/index.asciidoc

@@ -1,17 +1,17 @@
 [role="xpack"]
 [[ccs-clients-integrations]]
-== Cross cluster search, clients, and integrations
+== {ccs-cap}, clients, and integrations
 
-When using {ref}/modules-cross-cluster-search.html[Cross Cluster Search]
+When using <<modules-cross-cluster-search,{ccs}>>
 you need to take extra steps to secure communications with the connected
 clusters.
 
-* <<cross-cluster-configuring, Cross Cluster Search and Security>>
+* <<cross-cluster-configuring>>
 
 You will need to update the configuration for several clients to work with a
 secured cluster:
 
-* <<http-clients, HTTP Clients>>
+* <<http-clients>>
 
 
 The {es} {security-features} enable you to secure your {es} cluster. But
@@ -26,7 +26,7 @@ be secured as well, or at least communicate with the cluster in a secured way:
 * {kibana-ref}/using-kibana-with-security.html[{kib}]
 * {logstash-ref}/ls-security.html[Logstash]
 * {metricbeat-ref}/securing-beats.html[Metricbeat]
-* <<secure-monitoring, Monitoring>>
+* <<secure-monitoring>>
 * {packetbeat-ref}/securing-beats.html[Packetbeat]
 * {kibana-ref}/secure-reporting.html[Reporting]
 * {winlogbeat-ref}/securing-beats.html[Winlogbeat]

x-pack/docs/en/security/ccs-clients-integrations/monitoring.asciidoc

@@ -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]
 

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

x-pack/docs/en/security/get-started-builtin-users.asciidoc

@@ -16,7 +16,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.

x-pack/docs/en/security/get-started-enable-security.asciidoc

@@ -8,7 +8,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. 
@@ -18,7 +18,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:
 

x-pack/docs/en/security/get-started-security.asciidoc

@@ -56,7 +56,7 @@ discovery.type: single-node
 ----
 
 For more information, see
-{ref}/bootstrap-checks.html#single-node-discovery[Single-node discovery].
+<<single-node-discovery>>.
 --
 
 When you enable {es} {security-features}, basic authentication is enabled by
@@ -357,7 +357,7 @@ want to encrypt communications across the {stack}. To learn how, read
 
 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.  
 

x-pack/docs/en/security/securing-communications/enabling-cipher-suites.asciidoc

@@ -18,8 +18,7 @@ encryption with key lengths greater than 128 bits, such as 256-bit AES encryptio
 After installation, all cipher suites in the JCE are available for use but requires
 configuration in order to use them. To enable the use of stronger cipher suites
 with {es} {security-features}, configure the `cipher_suites` parameter. See the
-{ref}/security-settings.html#ssl-tls-settings[Configuration Parameters for TLS/SSL]
-section of this document for specific parameter information.
+<<ssl-tls-settings>> section of this document for specific parameter information.
 
 NOTE: The _JCE Unlimited Strength Jurisdiction Policy Files_ must be installed
       on all nodes in the cluster to establish an improved level of encryption

x-pack/docs/en/security/securing-communications/node-certificates.asciidoc

@@ -12,7 +12,7 @@ Additionally, it is recommended that the certificates contain subject alternativ
 names (SAN) that correspond to the node's IP address and DNS name so that
 hostname verification can be performed.
 
-The {ref}/certutil.html[`elasticsearch-certutil`] command simplifies the process
+The <<certutil,`elasticsearch-certutil`>> command simplifies the process
 of generating certificates for the {stack}. It takes care of generating a CA and
 signing certificates with the CA. It can be used interactively or in a silent
 mode through the use of an input file. It also supports generation of

x-pack/docs/en/security/securing-communications/setting-up-ssl.asciidoc

@@ -13,13 +13,13 @@ components of the {stack}. You must perform each of the steps that are
 applicable to your cluster.
 
 . Generate a private key and X.509 certificate for each of your {es} nodes. See
-{ref}/configuring-tls.html#node-certificates[Generating Node Certificates].
+<<node-certificates>>.
 
 . Configure each node in the cluster to identify itself using its signed
 certificate and enable TLS on the transport layer. You can also optionally
 enable TLS on the HTTP layer. See
-{ref}/configuring-tls.html#tls-transport[Encrypting Communications Between Nodes in a Cluster] and
-{ref}/configuring-tls.html#tls-http[Encrypting HTTP Client Communications]. 
+<<tls-transport>> and
+<<tls-http>>. 
 
 . Configure the {monitor-features} to use encrypted connections. See <<secure-monitoring>>.
 

x-pack/docs/en/security/securing-communications/tls-http.asciidoc

@@ -81,7 +81,7 @@ bin/elasticsearch-keystore add xpack.security.http.ssl.secure_key_passphrase
 ===============================
 * All TLS-related node settings are considered to be highly sensitive and
 therefore are not exposed via the
-{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API] For more
+<<cluster-nodes-info,nodes info API>> For more
 information about any of these settings, see <<security-settings>>.
 
 * {es} monitors all files such as certificates, keys, keystores, or truststores 

x-pack/docs/en/security/securing-communications/tls-transport.asciidoc

@@ -36,7 +36,7 @@ also be used as a truststore. In this case, the path value should match
 the `keystore.path` value.
 Note, however, that this is not the general rule. There are keystores that cannot be
 used as truststores, only 
-{ref}/security-settings.html#pkcs12-truststore-note[specifically crafted ones can]
+<<pkcs12-truststore-note,specifically crafted ones can>>.
 --
 
 ** If the certificate is in PEM format, add the following information to the
@@ -99,7 +99,7 @@ communication across the cluster.
 ===============================
 * All TLS-related node settings are considered to be highly sensitive and
 therefore are not exposed via the
-{ref}/cluster-nodes-info.html#cluster-nodes-info[nodes info API] For more
+<<cluster-nodes-info,nodes info API>> For more
 information about any of these settings, see <<security-settings>>.
 
 * {es} monitors all files such as certificates, keys, keystores, or truststores 

x-pack/docs/en/security/securing-communications/tutorial-tls-addnodes.asciidoc

@@ -6,7 +6,7 @@
 You can add more nodes to your cluster and optionally designate specific
 purposes for each node. For example, you can allocate master nodes, data nodes,
 ingest nodes, machine learning nodes, and dedicated coordinating nodes. For
-details about each node type, see {ref}/modules-node.html[Nodes].
+details about each node type, see <<modules-node>>.
 
 Let's add two nodes to our cluster!
 
@@ -111,7 +111,7 @@ The default value for this setting is `127.0.0.1, [::1]`, therefore it isn't
 actually required in this tutorial. When you want to form a cluster with nodes
 on other hosts, however, you must use this setting to provide a list of
 master-eligible nodes to seed the discovery process. For more information, see
-{ref}/modules-discovery-hosts-providers.html[Discovery].
+<<modules-discovery-hosts-providers>>.
 --
 
 . On each node, enable TLS for transport communications. You must also configure
@@ -140,7 +140,7 @@ package, run the following command from each {es} directory:
 ./bin/elasticsearch
 ----------------------------------------------------------------------
 
-See {ref}/starting-elasticsearch.html[Starting {es}].
+See <<starting-elasticsearch>>.
 
 If you encounter errors, you can see some common problems and solutions in
 <<trb-security-ssl>>.
@@ -150,7 +150,7 @@ If you encounter errors, you can see some common problems and solutions in
 +
 --
 For example, log into {kib} with the `elastic` built-in user. Go to
-*Dev Tools > Console* and run the {ref}/cluster-health.html[cluster health API]:
+*Dev Tools > Console* and run the <<cluster-health,cluster health API>>:
 
 [source,console]
 ----------------------------------
@@ -159,7 +159,7 @@ GET _cluster/health
 
 Confirm the `number_of_nodes` in the response from this API.
 
-You can also use the {ref}/cat-nodes.html[cat nodes API] to identify the master
+You can also use the <<cat-nodes,cat nodes API>> to identify the master
 node:
 
 [source,console]
@@ -174,7 +174,7 @@ node.
 Now that you have multiple nodes, your data can be distributed across the
 cluster in multiple primary and replica shards. For more information about the
 concepts of clusters, nodes, and shards, see
-{ref}/getting-started.html[Getting started with {es}].
+<<getting-started>>.
 
 [float]
 [[encrypting-internode-nextsteps]]
@@ -182,7 +182,7 @@ concepts of clusters, nodes, and shards, see
 
 Congratulations! You've encrypted communications between the nodes in your
 cluster and can pass the 
-{ref}/bootstrap-checks-xpack.html#bootstrap-checks-tls[TLS bootstrap check].
+<<bootstrap-checks-tls,TLS bootstrap check>>.
 
 If you want to encrypt communications between other products in the {stack}, see
 <<encrypting-communications>>.

x-pack/docs/en/security/securing-communications/tutorial-tls-certificates.asciidoc

@@ -33,7 +33,7 @@ remember its location and password. Ideally you should store the file securely,
 since it holds the key to your cluster.
 
 For more information about this command, see
-{ref}/certutil.html[elasticsearch-certutil].
+<<certutil>>.
 --
 
 . Create a folder to contain certificates in the configuration directory of your
@@ -69,7 +69,7 @@ The output file is a PKCS#12 keystore that includes a node certificate, node key
 and CA certificate.
 --
 
-TIP: The {ref}/certutil.html[elasticsearch-certutil] command has a lot more
+TIP: The <<certutil,elasticsearch-certutil>> command has a lot more
 options. For example, it can generate Privacy Enhanced Mail (PEM) formatted
 certificates and keys. It can also generate certificate signing requests (CSRs)
 that you can use to obtain signed certificates from a commercial or

x-pack/docs/en/security/securing-communications/tutorial-tls-internode.asciidoc

@@ -10,12 +10,12 @@ IMPORTANT: When you enable {es} {security-features}, unless you have a trial
 license, you must use Transport Layer Security (TLS) to encrypt internode
 communication. By following the steps in this tutorial tutorial, you learn how
 to meet the minimum requirements to pass the 
-{ref}/bootstrap-checks-xpack.html#bootstrap-checks-tls[TLS bootstrap check].
+<<bootstrap-checks-tls,TLS bootstrap check>>.
 
 . (Optional) Name the cluster.
 +
 --
-For example, add the {ref}/cluster.name.html[cluster.name] setting in the
+For example, add the <<cluster.name,cluster.name>> setting in the
 `ES_PATH_CONF/elasticsearch.yml` file:
 
 [source,yaml]
@@ -27,7 +27,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>>.
 
 The default cluster name is `elasticsearch`. You should choose a unique name,
 however, to ensure that your nodes join the right cluster.
@@ -36,7 +36,7 @@ however, to ensure that your nodes join the right cluster.
 . (Optional) Name the {es} node.
 +
 --
-For example, add the {ref}/node.name.html[node.name] setting in the
+For example, add the <<node.name,node.name>> setting in the
 `ES_PATH_CONF/elasticsearch.yml` file:
 
 [source,yaml]
@@ -80,8 +80,8 @@ TIP: If you are starting a cluster with multiple master-eligible nodes for the
 first time, add all of those node names to the `cluster.initial_master_nodes`
 setting.
  
-See {ref}/modules-discovery-bootstrap-cluster.html[Bootstrapping a cluster] and
-{ref}/discovery-settings.html[Important discovery and cluster formation settings].
+See <<modules-discovery-bootstrap-cluster>> and
+<<discovery-settings>>.
 --
 
 . Enable Transport Layer Security (TLS/SSL) for transport (internode)
@@ -109,7 +109,7 @@ generate your certificates, you might have different values for these settings,
 but that scenario is not covered in this tutorial.
 
 For more information, see <<get-started-enable-security>> and 
-{ref}/security-settings.html#transport-tls-ssl-settings[Transport TLS settings].
+<<transport-tls-ssl-settings>>.
 --
 
 . Store the password for the PKCS#12 file in the {es} keystore.
@@ -134,7 +134,7 @@ file. We are using this file for both the transport TLS keystore and truststore,
 therefore supply the same password for both of these settings.
 --
 
-. {ref}/starting-elasticsearch.html[Start {es}].
+. <<starting-elasticsearch,Start {es}>>.
 +
 --
 For example, if you installed {es} with a `.tar.gz` package, run the following

x-pack/docs/en/security/securing-communications/tutorial-tls-intro.asciidoc

@@ -4,12 +4,12 @@
 == Tutorial: Encrypting communications
 
 In the {stack-gs}/get-started-elastic-stack.html[Getting started with the {stack}]
-and <<security-getting-started,Getting started with security>> tutorials, we
+and <<security-getting-started>> tutorials, we
 used a cluster with a single {es} node to get up and running with the {stack}.
 
 You can add as many nodes as you want in a cluster but they must be able to
 communicate with each other. The communication between nodes in a cluster is
-handled by the {ref}/modules-transport.html[transport module]. To secure your
+handled by the <<modules-transport,transport module>>. To secure your
 cluster, you must ensure that the internode communications are encrypted.
 
 NOTE: In this tutorial, we add more nodes by installing more copies of {es} on
@@ -20,8 +20,8 @@ When you are deploying a production environment, however, you are generally
 adding nodes on different machines so that your cluster is resilient to outages
 and avoids data loss. In a production scenario, there are additional
 requirements that are not covered in this tutorial. See
-{ref}/bootstrap-checks.html#dev-vs-prod-mode[Development vs production mode] and
-{ref}/add-elasticsearch-nodes.html[Adding nodes to your cluster].
+<<dev-vs-prod-mode>> and
+<<add-elasticsearch-nodes>>.
 
 [float]
 [[encrypting-internode-prerequisites]]
@@ -29,7 +29,7 @@ requirements that are not covered in this tutorial. See
 
 Ideally, you should do this tutorial after you complete the 
 {stack-gs}/get-started-elastic-stack.html[Getting started with the {stack}] and
-<<security-getting-started,Getting started with security>> tutorials.
+<<security-getting-started>> tutorials.
 
 At a minimum, you must install and configure {es} and {kib} in a cluster with a
 single {es} node. In particular, this tutorial provides instructions for adding

x-pack/docs/en/security/troubleshooting.asciidoc

@@ -33,7 +33,7 @@ Or post in the https://discuss.elastic.co/[Elastic forum].
 
 *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:*
@@ -80,7 +80,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
@@ -92,14 +92,14 @@ this error.
 
 Groups are located by either an LDAP search or by the "memberOf" attribute on
 the user.  Also, If subtree search is turned off, it will search only one
-level deep.  See the <<ldap-settings, LDAP Settings>> for all the options.
+level deep. For all the options, see <<ldap-settings>>.
 There are many options here and sticking to the defaults will not work for all
 scenarios.
 
 | _group to role mapping_|
 
 Either the `role_mapping.yml` file or the location for this file could be
-misconfigured. For more information, see {ref}/security-files.html[Security files].
+misconfigured. For more information, see <<security-files>>.
 
 |_role definition_|
 
@@ -139,7 +139,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
@@ -287,7 +287,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`::
@@ -299,7 +299,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`::
@@ -315,7 +315,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`::
@@ -418,7 +418,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 
@@ -428,7 +428,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
@@ -584,7 +584,7 @@ and the most commonly encountered ones are:
 . `urn:oasis:names:tc:SAML:2.0:status:InvalidNameIDPolicy`: The SAML Identity Provider cannot support
   releasing a NameID with the requested format. When creating SAML Authentication Requests, {es} sets
   the NameIDPolicy element of the Authentication request with the appropriate value. This is controlled
-  by the {ref}/security-settings.html#ref-saml-settings[`nameid_format`] configuration parameter in
+  by the <<ref-saml-settings,`nameid_format`>> configuration parameter in
   `elasticsearch.yml`, which if not set defaults to `urn:oasis:names:tc:SAML:2.0:nameid-format:transient`.
    This instructs the Identity Provider to return a NameID with that specific format in the SAML Response. If
   the SAML Identity Provider cannot grant that request, for example because it is configured to release a
@@ -687,7 +687,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,
@@ -764,7 +764,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
@@ -780,7 +780,7 @@ log that indicate a config file is in a deprecated location.
 By default, in 6.2 and earlier releases, the 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 
@@ -794,5 +794,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>>. 
 

x-pack/docs/en/security/using-ip-filtering.asciidoc

@@ -78,7 +78,7 @@ xpack.security.http.filter.enabled: true
 [float]
 === Specifying TCP transport profiles
 
-{ref}/modules-transport.html[TCP transport profiles]
+<<modules-transport,TCP transport profiles>>
 enable Elasticsearch to bind on multiple hosts. The {es} {security-features} enable you to apply
 different IP filtering on different profiles.