ENT-11249: Revised Health and Settings pages

web-ui/health.markdown

@@ -9,10 +9,13 @@ published: true
 
 You can get quick access to the health of hosts, including direct links to reports, from the Health drop down at the top of every Enterprise UI screen. Hosts are listed as unhealthy if:
 
-* the hub was not able to connect to and collect data from the host within a set time interval (unreachable host). The time interval can be set in the Mission Portal settings.
-* the policy did not get executed for the last three runs. This could be caused by `cf-execd` not running on the host (scheduling deviation) or an error in policy that stops its execution. The hub is still able to contact the host, but it will return stale data because of this deviation.
-* two or more hosts use the same key. This is detected by "reporting cookies", randomized tokens generated every report collection. If the client presents a mismatching cookie (compared to last collection) a collision is detected. The number of collisions (per hostkey) that cause the unhealthy status is configurable in [settings][Settings#Preferences].
-* reports have recently been collected, but cf-agent has not recently run. "Recently" is defined by the configured run-interval of their cf-agent.
+* Missing reporting data : Host has connected to hub (to get policy), but reports have never been collected from it.
+* Unreachable hosts : Reports from host has been collected in the past, but not recently (as defined by "Unreachable host threshold").
+* Outdated reporting data : The host is communicating correctly and sending its reports, but the data is outdated (there are no recent reports), indicating that there hasn't been any policy runs recently (performed by the cf-agent binary). There is no data to prove that your policy, describing your desired state, is being successfully enforced.
+* Policy errors : Reports have recently been collected and cf-agent has completed a run with an error.
+* Duplicate IDs : CFEngine hosts are identified by the CFEngine key they use. If two or more hosts use the same key the reports will be very unreliable. This is detected by exchanging randomized cookies(tokens) during report collections. If a client sends a mismatching cookie (compared to last collection), it indicates that multiple hosts are using the same ID.
+* Duplicate hostnames: multiple host identities reporting the same host identifier (by default hostname derived from `default:sys.fqhost` variable but changeable in Settings -> Host identifier)
+
 
 These categories are non-overlapping, meaning a host will only appear in one category at at time even if conditions satisfying multiple categories might be present. This makes reports simpler to read, and makes it easier to detect and fix the root cause of the issue. As one issue is resolved the host might then move to another category.
-In either situation the data from that host will be from old runs and probably not reflect the current state of that host.
+Regardless of the situation, the data from the host will be from the latest report collection, representing the most recent known state of the host.

web-ui/settings.markdown

@@ -29,7 +29,6 @@ administrator to change various options, including:
 * Unreachable host threshold
 * Number of samples used to identify a duplicate identity
 * Log level
-* Customize the user experience with the organization logo
 
 ## User management
 
@@ -56,15 +55,17 @@ if you have the admin role and a role that matches zero hosts, the user will
 not see any hosts in Mission Portal. A shared report will only be accessible
 to a user if the user has all roles that the report was restricted to.
 
-In order to access a shared reports or dashboard the use must have all roles
+In order to access a shared reports or dashboard the user must have all roles
 that the report or dashboard was shared with.
 
 In order to see a host, none of the classes reported by the host can match the
 class exclusions from any role the user has.
 
-Users without a role will not be able to see any hosts in Mission
-Portal.
+Users without a role will not be able to see any hosts in Mission Portal.
 
+Here is a set of example roles, users and the impact on each user will be able to view.
+
+### Example roles
 Role **suse**:
 - Class include: `SUSE`
 - Class exclude: empty
@@ -82,24 +83,24 @@ Role **windows_ubuntu**
 - Class include: `ubuntu`
 - Class exclude: empty
 
+### Example users
 User one has role `SUSE`.
 
 User two has roles `no_windows` and `cfengine_3`.
 
 User three has roles `windows_ubuntu` and `no_windows`.
 
-A report shared with `SUSE` and `no_windows` will not be seen by any of the
-listed users.
+### What reports each user can view
+A report shared with `SUSE` and `no_windows` will not be seen by any of the listed users.
 
-A report shared with `no_windows` and `cfengine_3` will only be seen by user
-two.
+A report shared with `no_windows` and `cfengine_3` will only be seen by user two.
 
 A report shared with `SUSE` will be seen by user one.
 
+### Which hosts each user can view
 User one will only be able to see hosts that report the `SUSE` class.
 
-User two will be able to see all hosts that have **not** reported the `windows`
-class.
+User two will be able to see all hosts that have **not** reported the `windows` class.
 
 User three will only be able to see hosts that have reported the `ubuntu` class.
 
@@ -114,7 +115,7 @@ To set the default role, click Settings -> User management -> Roles. You can the
 
 <img src="roles-list.png" alt="DefaultRoleSelecting" width="700px">
 
-**Behaviour of Default role:**
+**Behaviour of default role:**
 
 Any new users created in Mission Portal's local user database will have this new role assigned.
 
@@ -170,17 +171,13 @@ Configure outbound mail settings:
 
 Mission portal can authenticate against an external directory.
 
-**Special Notes:**
-
-- LDAP API Url refers to the API CFEngine uses internally for authentication.
-  Most likely you will not alter the default value.
-
-- LDAP filter must be supplied.
+**Special notes:**
 
 - LDAP Host refers is the IP or Hostname of your LDAP server.
-
+- LDAP filter must be supplied.
 - LDAP bind username should be the username used to bind and search the LDAP
   directory. It must be provided in distinguished name format.
+  Additionally, you can bind anonymously.
 
 - Default roles for users is configured under [Role management][Settings#Role management].
 
@@ -215,7 +212,7 @@ Mission Portal's configuration can be exported and imported.
 Roles in Mission portal can be restricted to perform only configured actions.
 Configure role-based access controls from settings.
 
-**Special Notes:**
+**Special notes:**
 
 - Admin role has all permissions by default.