First review of the Kanidm Administration book (#760)

kanidm_book/src/installing_the_server.md

@@ -1,6 +1,6 @@
 # Installing the Server
 
-> **NOTE** Our preferred deployment method is in containers, the documentation assumes you're running in docker. Kanidm will run in traditional compute, and server builds are available for multiple platforms or you can build the binaries yourself.
+> **NOTE** Our preferred deployment method is in containers, the documentation assumes you're running in docker. Kanidm will run in traditional compute, and server builds are available for multiple platforms, or you can build the binaries yourself if you prefer this option.
 
 Currently we have docker images for the server components. They can be found at:
 
@@ -33,7 +33,7 @@ If you are using the x86\_64 cpu-optimised version, you must have a CPU that is
     cmov, cx8, fxsr, mmx, sse, sse2, cx16, sahf, popcnt, sse3, sse4.1, sse4.2, avx, avx2,
     bmi, bmi2, f16c, fma, lzcnt, movbe, xsave
 
-Older or unsupported CPU's may raise a SIGIL (Illegal Instruction) on hardware that is not supported
+Older or unsupported CPUs may raise a SIGIL (Illegal Instruction) on hardware that is not supported
 by the project.
 
 In this case, you should use the standard server:latest image.
@@ -53,7 +53,7 @@ You should expect to see 64KB of ram per entry in your database, depending on ca
 You should expect to use up to 8KB of disk per entry you plan to store. At an estimate 10,000 entry
 databases will consume 40MB, 100,000 entry will consume 400MB.
 
-For best performance, you should use NVME or other Flash media.
+For best performance, you should use non-volatile memory express (NVME), or other Flash storage media.
 
 ## TLS
 
@@ -62,7 +62,7 @@ You'll need a volume where you can place configuration, certificates, and the da
     docker volume create kanidmd
 
 You should have a chain.pem and key.pem in your kanidmd volume. The reason for requiring
-TLS is explained in [why tls](./why_tls.md). In summary, TLS is our root of trust between the
+Transport Layer Security (TLS, which replaces the deprecated Secure Sockets Layer, SSL) is explained in [why tls](./why_tls.md). In summary, TLS is our root of trust between the
 server and clients, and a critical element of ensuring a secure system.
 
 The key.pem should be a single PEM private key, with no encryption. The file content should be

kanidm_book/src/intro.md

@@ -15,13 +15,13 @@ The intent of the Kanidm project is to:
 
 ## Library documentation
 
-Looking for the `rustdoc` documentation for the libraries themselves? [Click here!](./rustdoc/master/kanidm/)
+Looking for the `rustdoc` documentation for the libraries themselves? [Click here!](https://kanidm.com/documentation/)
 
 ## Why do I want Kanidm?
 
 Whether you work in a business, a volunteer organisation, or are an enthusiast who manages 
-their personal services, we need methods of authenticating and identifying ourselves
+their personal services, you need methods of authenticating and identifying 
-to these systems and subsequently, ways to determine what authorisation and privileges we have
+to your systems, and subsequently, ways to determine what authorisation and privileges you have
 while accessing these systems.
 
 We've probably all been in workplaces where you end up with multiple accounts on various
@@ -79,8 +79,8 @@ many devices and credentials with different privileges. An example of how this l
                                    └──────────┘
 
 A key design goal is that you authenticate with your device in some manner, and then your device will
-continue to authenticate you in the future. Each of these different types of credential from SSH keys,
+continue to authenticate you in the future. Each of these different types of credentials, from SSH keys,
-application passwords, RADIUS passwords and others, are "things your device knows". Each password
+application passwords, to RADIUS passwords and others, are "things your device knows". Each password
 has limited capability, and can only access that exact service or resource.
 
 This helps improve security; a compromise of the service or the network transmission does not
@@ -90,4 +90,4 @@ specific service is compromised, only the credentials for that service need to b
 
 Due to this model, and the design of Kanidm to centre the device and to have more per-service credentials,
 workflows and automation are added or designed to reduce human handling. An example of this
-is the use of QR codes with deployment profiles to automatically enrol wireless credentials.
+is the use of QR codes with deployment profiles to automatically enroll wireless credentials.

kanidm_book/src/server_configuration.md

@@ -2,76 +2,97 @@
 
 ### Configuring server.toml
 
-You will also need a config file in the volume named `server.toml` (Within the container it should be `/data/server.toml`). Its contents should be as follows:
+You need a configuration file in the volume named `server.toml`. (Within the container it should be `/data/server.toml`.) Its contents should be as follows:
 
-    #   The webserver bind address. Will use HTTPS if tls_* is provided.
+    #   The webserver bind address. Will use HTTPS if tls_* 
+    #   is provided.
     #   Defaults to "127.0.0.1:8443"
     bindaddress = "[::]:8443"
     #
-    #   The read-only ldap server bind address. The server will use LDAPS if tls_* is provided.
+    #   The read-only ldap server bind address. The server 
+    #   will use LDAPS if tls_* is provided.
     #   Defaults to "" (disabled)
     # ldapbindaddress = "[::]:3636"
     #
     #   The path to the kanidm database.
     db_path = "/data/kanidm.db"
     #
-    #   If you have a known filesystem, kanidm can tune sqlite to match. Valid choices are:
+    #   If you have a known filesystem, kanidm can tune sqlite
+    #   to match. Valid choices are:
     #   [zfs, other]
-    #   If you are unsure about this leave it as the default (other). After changing this
+    #   If you are unsure about this leave it as the default 
+    #   (other). After changing this
     #   value you must run a vacuum task.
     #   - zfs:
-    #     * sets sqlite pagesize to 64k. You must set recordsize=64k on the zfs filesystem.
+    #     * sets sqlite pagesize to 64k. You must set 
+    #       recordsize=64k on the zfs filesystem.
     #   - other:
-    #     * sets sqlite pagesize to 4k, matching most filesystems block sizes.
+    #     * sets sqlite pagesize to 4k, matching most 
+    #       filesystems block sizes.
     # db_fs_type = "zfs"
     #
-    #   The number of entries to store in the in-memory cache. Minimum value is 256. If unset
+    #   The number of entries to store in the in-memory cache. 
+    #   Minimum value is 256. If unset
     #   an automatic heuristic is used to scale this.
     # db_arc_size = 2048
     #
-    #   TLS chain and key in pem format. Both must be commented, or both must be present
+    #   TLS chain and key in pem format. Both must be 
+    #   commented, or both must be present
     # tls_chain = "/data/chain.pem"
     # tls_key = "/data/key.pem"
     #
-    #   The log level of the server. May be default, verbose, perfbasic, perffull
+    #   The log level of the server. May be default, verbose,
+    #   perfbasic, perffull
     #   Defaults to "default"
     # log_level = "default"
     #
-    #   The DNS domain name of the server. This is used in a number of security-critical contexts
+    #   The DNS domain name of the server. This is used in a 
-    #   such as webauthn, so it *must* match your DNS hostname. It is what is used to create
+    #   number of security-critical contexts
-    #   security principal names such as `william@idm.example.com` so that in a (future)
+    #   such as webauthn, so it *must* match your DNS 
-    #   trust configuration it is possible to have unique spn's throughout the topology.
+    #   hostname. It is used to create
+    #   security principal names such as `william@idm.example.com`
+    #   so that in a (future)
+    #   trust configuration it is possible to have unique Service
+    #   Principal Names (spns) throughout the topology.
     #   ⚠️  WARNING ⚠️
-    #   Changing this value WILL break many types of registered credentials for accounts
+    #   Changing this value WILL break many types of registered 
+    #   credentials for accounts
     #   including but not limited to webauthn, oauth tokens, and more.
-    #   If you change this value you *must* run `kanidmd domain_name_change` immediately
+    #   If you change this value you *must* run 
-    #   after.
+    #   `kanidmd domain_name_change` immediately after.
     domain = "idm.example.com"
     #
-    #   The origin for webauthn. This is the url to the server, with the port included if
+    #   The origin for webauthn. This is the url to the server, 
-    #   it is non-standard (any port except 443). This must match or be a descendent of the
+    #   with the port included if
-    #   domain name you configure above. If these two items are not consistent, the server
+    #   it is non-standard (any port except 443). This must match 
-    #   WILL refuse to start!
+    #   or be a descendent of the
-    # origin = "https://idm.example.com"
+    #   domain name you configure above. If these two items are 
+    #   not consistent, the server WILL refuse to start!
+    #   origin = "https://idm.example.com"
     origin = "https://idm.example.com:8443"
     #
-    #   The role of this server. This affects features available and how replication may interact.
+    #   The role of this server. This affects available features  
+    #   and how replication may interact.
     #   Valid roles are:
     #   - WriteReplica
-    #     This server provides all functionality of Kanidm. It allows authentication, writes, and
+    #     This server provides all functionality of Kanidm. It 
+    #     allows authentication, writes, and
     #     the web user interface to be served.
     #   - WriteReplicaNoUI
-    #     This server is the same as a WriteReplica, but does NOT offer the web user interface.
+    #     This server is the same as a WriteReplica, but does NOT 
+    #     offer the web user interface.
     #   - ReadOnlyReplica
-    #     This server will not writes initiated by clients. It supports authentication and reads,
+    #     This server will not writes initiated by clients. It 
-    #     and must have a replication agreement as a source of it's data.
+    #     supports authentication and reads,
+    #     and must have a replication agreement as a source of 
+    #     its data.
     #   Defaults to "WriteReplica".
     # role = "WriteReplica"
     #
     # [online_backup]
     #   The path to the output folder for online backups
     # path = "/var/lib/kanidm/backups/"
-    #   The schedule to run online backups - see https://crontab.guru/
+    #   The schedule to run online backups (see https://crontab.guru/)
     #   every day at 22:00 UTC (default)
     # schedule = "00 22 * * *"
     #    four times a day at 3 minutes past the hour, every 6th hours