Today if the .security index is unavailable then you get errors like this:

[ERROR][o.e.x.s.a.e.ReservedRealm] [REDACTED] failed to retrieve password hash for reserved user [elastic]
org.elasticsearch.action.UnavailableShardsException: at least one primary shard for the index [.security-7] is unavailable
        at org.elasticsearch.xpack.security.support.SecurityIndexManager.getUnavailableReason(SecurityIndexManager.java:138) ~[?:?]
        at org.elasticsearch.xpack.security.authc.esnative.NativeUsersStore.getReservedUserInfo(NativeUsersStore.java:602) ~[?:?]
...

That's certainly true, but it's unclear to users what exactly to do about it. And bear in mind that users with clusters in this state are probably experiencing some level of panic since it's likely that nothing works if the .security index is unavailable.

Please could we:

• add some guidance in the reference manual about how to handle this (i.e. set up a file realm user and then proceed with the usual missing shards troubleshooting
• link to this guidance from the exception message quoted above (using org.elasticsearch.common.ReferenceDocs) so that we can take users directly to the guidance docs.