Fixes some wordings around system index permission access and usage

_security/access-control/permissions.md

@@ -65,14 +65,16 @@ Rather than individual permissions, you can often achieve your desired security
 {: .tip }
 
 
-## System permissions
+## System Index permissions
 
-System permissions are unique among other permissions in that they extend some traditional admin-only accessibility to non-admin users. These permissions give normal users the ability to modify any system index specified in the role or roles to which they are mapped. The exception to this is the security system index, `.opendistro_security`, which is used to store Security's configuration YAML files and remains accessible only to admins with an admin certificate.
+System index permissions are unique among other permissions in that they extend some traditional admin-only accessibility to non-admin users. These permissions give normal users the ability to modify any system index specified in the role or roles to which they are mapped. The exception to this is the security system index, `.opendistro_security`, which is used to store Security's configuration YAML files and remains accessible only to admins with an admin certificate.
 
-System permissions are specified under `index_permissions` in the `roles.yml` configuration file (See [roles.yml]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#rolesyml).) However, they begin with the prefix `.opendistro` to make them distinguishable from index permissions. For example, the system permission `.opendistro-alerting-config` gives a user permission to modify the system index that stores configurations for the Alerting plugin. The following example shows this system permission specified in a role called `alerting-maint-role`:
+System index permissions are specified under `index_permissions` in the `roles.yml` configuration file (See [roles.yml]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#rolesyml).) and can be granted permission to as any regular index by specifying the action `system:admin/system_index` under `allowed_actions`. Here is an example, the `.opendistro-alerting-config` system index stores configurations for the Alerting plugin. 
+
+The following example shows a way to grant permission system index permission specified in a role called `alerting-main-role`:
 
 ```yml
-alerting-maint-role:
+alerting-main-role:
   reserved: true
   hidden: false
   cluster_permissions:
@@ -81,25 +83,26 @@ alerting-maint-role:
   index_permissions:
   - index_patterns:
     - ".opendistro-alerting-config"
+  - allowed_actions:
+    - "system:admin/system_index"
 ```
 
-The system permission prefix `.opendistro` also works with the wildcard to extend its reach of access. This can be useful, but it should be used with caution to avoid giving unintentional access to system indexes. When specifying system indexes for roles, keep the following considerations in mind:
+The permission prefix `.opendistro` also works with the wildcard to extend its reach of access. This can be useful, but it should be used with caution to avoid giving unintentional access to system indexes. When specifying system indexes for roles, keep the following considerations in mind:
 
 * Specifying the full name of a system index limits access to that index alone: `.opendistro-alerting-config`.
 * Specifying the prefix and a partial name for a system index provides access to all system indexes that begin with the name: `.opendistro-anomaly-detector*`.
-* Specifying the prefix alone gives access to all system indexes: `.opendistro*`.
-* Using `.*` is effectively the same as specifying the prefix with wildcard, as described in the previous point. This gives access to all system indexes.
+* Using `.*` is effectively the same as specifying the prefix with wildcard, as described in the previous point. This gives access to all system indexes that begin with a `.`.
 * Entering the wildcard `*` by itself does not give access to any indexes.
 
 Use extreme caution when using the wildcard to configure access to system indexes. We highly recommend thinking ahead and anticipating the range of access that you will be extending to users before updating your configuration files.
 {: .warning }
 
 
-### Enabling system permissions
+### Enabling system index permissions
 
-Admin users that have the permission [`restapi:admin/roles`]({{site.url}}{{site.baseurl}}/security/access-control/api/#access-control-for-the-api) are able to map system permissions to users in the same way they would for a cluster or index permission in the `roles.yml` file. However, to preserve some control over this permission, the configuration setting `plugins.security.system_indices.additional_control.enabled` allows administrators to disable this feature by setting it to `false`. For more information about this setting, see [Enabling user access to system indexes]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#enabling-user-access-to-system-indexes).
+Users that have the permission [`restapi:admin/roles`]({{site.url}}{{site.baseurl}}/security/access-control/api/#access-control-for-the-api) are able to map system index permissions to all users in the same way they would for a cluster or index permission in the `roles.yml` file. However, to preserve some control over this permission, the system index permission feature is disabled by default and allows administrators to enable this feature by setting the configuration `plugins.security.system_indices.additional_control.enabled` to `true`. For more information about this setting, see [Enabling user access to system indexes]({{site.url}}{{site.baseurl}}/security/configuration/yaml/#enabling-user-access-to-system-indexes).
 
-Keep in mind that an admin user who enables this feature necessarily accepts the risks involved with giving normal users access to system indexes, which may contain sensitive information and configurations essential to a cluster's health. An admin user should also take precautions when assigning `restapi:admin/roles` to users because this permission gives a user not only the ability to assign the system permission to another user but, equally, the ability to self-assign access to any system index.
+Keep in mind that an admin user who enables this feature necessarily accepts the risks involved with giving normal users access to system indexes, which may contain sensitive information and configurations essential to a cluster's health. An admin user should also take precautions when assigning `restapi:admin/roles` to users because this permission gives a user not only the ability to assign the system index permission to another user but, equally, the ability to self-assign access to any system index.
 {: .warning }
 
 

_security/configuration/yaml.md

@@ -136,16 +136,16 @@ plugins.security.cache.ttl_minutes: 60
 
 ### Enabling user access to system indexes
 
-Mapping a system permission `.opendistro-<index-name>` to a user allows that user to modify the system index specified in the permission's name. (The one exception is the Security plugin's [system index]({{site.url}}{{site.baseurl}}/security/configuration/system-indices/)). The `plugins.security.system_indices.additional_control.enabled` setting provides a way for administrators to make this permission available for or hidden from role mapping.
+Mapping a system permission to a user allows that user to modify the system index specified in the permission's name. (The one exception is the Security plugin's [system index]({{site.url}}{{site.baseurl}}/security/configuration/system-indices/)). The `plugins.security.system_indices.additional_control.enabled` setting provides a way for administrators to make this permission available for or hidden from role mapping.
 
-When set to `true`, the feature is enabled and administrators can add the `system:admin/<system_index_name>` permission for a user.
+When set to `true`, the feature is enabled and users with access to modify roles can add the `system:admin/system_index` as an allowed action and an index pattern in the roles that will be used for system index access.
 
 ```yml
 plugins.security.system_indices.additional_control.enabled: true
 ```
 When set to `false`, the permission is disabled and only admins with an admin certificate can make changes to system indexes. By default, the setting is `false` for a new cluster.
 
-To learn more about system permissions, see [System permissions]({{site.url}}{{site.baseurl}}/security/access-control/permissions/#system-permissions) in Permissions documentation.
+To learn more about system index permissions, see [System Index permissions]({{site.url}}{{site.baseurl}}/security/access-control/permissions/#system-index-permissions) in Permissions documentation.
 
 
 ### Password settings