Auto-publishing the book and rustdoc. (#534)

.github/workflows/kanidm_book.yml

@@ -0,0 +1,47 @@
+name: GitHub Pages
+
+on:
+  push:
+    branches:
+      - master
+  pull_request:
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    concurrency:
+      group: ${{ github.workflow }}-${{ github.ref }}
+    steps:
+      - uses: actions/checkout@v2
+
+      - name: Install deps
+        run: sudo apt-get update && sudo apt-get install -y clang build-essential librust-openssl-dev libssl-dev libsqlite3-dev libudev-dev libpam0g-dev
+
+      - name: Setup mdBook
+        uses: peaceiris/actions-mdbook@v1
+        with:
+          mdbook-version: 'latest'
+
+      - uses: actions-rs/toolchain@v1
+        with:
+          toolchain: stable
+
+      - uses: actions-rs/cargo@v1
+        with:
+          command: doc
+          args: --no-deps
+      - name: Copy developer readme into book
+        run: cp DEVELOPER_README.md ./kanidm_book/src/ && echo '- [Developer Guide](DEVELOPER_README.md)' >> ./kanidm_book/src/SUMMARY.md
+
+      - name: Run mdbook
+        run: mdbook build kanidm_book
+
+      - name: Move files around
+        run: mv ./kanidm_book/book/ ./docs/ && mkdir -p ./docs/rustdoc/ &&  mv ./target/doc/* ./docs/rustdoc/
+
+      - name: Deploy
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs
+          destination_dir: ./docs

README.md

@@ -18,7 +18,7 @@ treated as such.
 
 ## Documentation / Getting Started / Install
 
-If you want to deploy kanidm to see what it can do, you should read the [kanidm book]
+If you want to deploy Kanidm to see what it can do, you should read the [kanidm book]
 
 We also publish limited [support guidelines].
 

kanidm_book/src/SUMMARY.md

@@ -1,26 +1,21 @@
 # Summary
 
-[Introduction to Kanidm](./intro.md)
+- [Introduction to Kanidm](./intro.md)
-
-Getting started with Kanidm
-
 - [Installing the Server](./installing_the_server.md)
-- [Administrative Tasks](./administrivia.md)
+  - [Server Configuration](./installing_the_server.md)
-- [Interacting with the Server](./client_tools.md)
+  - [Security Hardening](./security_hardening.md)
+
+
+- [Client Tools](./client_tools.md)
+  - [Installing client tools](./installing_client_tools.md)
 - [Accounts and Groups](./accounts_and_groups.md)
-
+- [Administrative Tasks](./administrivia.md)
-Additional information
-
-- [Legacy Applications - LDAP](./ldap.md)
   - [Monitoring the platform](./monitoring.md)
-- [PAM and nsswitch](./pam_and_nsswitch.md)
   - [Password Quality and Badlisting](./password_quality.md)
   - [POSIX Accounts and Groups](./posix_accounts.md)
-- [RADIUS](./radius.md)
-- [Recycle Bin](./recycle_bin.md)
-- [Security Hardening](./security_hardening.md)
   - [SSH Key Distribution](./ssh_key_dist.md)
-
+  - [The Recycle Bin](./recycle_bin.md)
------------
+- [LDAP](./ldap.md)
-[Why TLS?](./why_tls.md)
+- [PAM and nsswitch](./pam_and_nsswitch.md)
-
+- [RADIUS](./radius.md)
+- [Why TLS?](./why_tls.md)

kanidm_book/src/accounts_and_groups.md

@@ -124,7 +124,7 @@ accounts". This is to help prevent elevation attacks, where say a member of a
 service desk could attempt to reset the password of idm_admin or admin, or even a member of
 HR or System Admin teams to move laterally.
 
-Generally, membership of a "privilege" group that ships with kanidm, such as:
+Generally, membership of a "privilege" group that ships with Kanidm, such as:
 
 * idm_account_manage_priv
 * idm_people_read_priv

kanidm_book/src/client_tools.md

@@ -1,70 +1,10 @@
-# Interacting with the Server
+# Client tools
 
-To interact with Kanidm as an administrator, you'll need to use our command line tools.
+To interact with Kanidm as an administrator, you'll need to use our command line tools. If you haven't installed them yet, [install them now](installing_client_tools.mdc).
-
-## From packages
-
-Kanidm currently supports:
-
- * OpenSUSE Tumbleweed
- * OpenSUSE Leap 15.3
- * Fedora 33/34
-
-### OpenSUSE Tumbleweed
-
-Kanidm is part of OpenSUSE Tumbleweed since October 2020. This means you can install
-the clients with:
-
-    zypper ref
-    zypper in kanidm-clients
-
-### OpenSUSE Leap 15.3
-
-Leap 15.3 is still not fully supported with Kanidm. For an experimental client, you can
-try the development repository. Using zypper you can add the repository with:
-
-    zypper ar -f obs://network:idm network_idm
-
-Then you need to refresh your metadata and install the clients.
-
-    zypper ref
-    zypper in kanidm-clients
-
-### Fedora
-
-Fedora is still experimentally supported through the development repository. You need to add the repository metadata into the correct directory.
-
-    cd /etc/yum.repos.d
-    # 33
-    wget https://download.opensuse.org/repositories/network:/idm/Fedora_33/network:idm.repo
-    # 34
-    wget https://download.opensuse.org/repositories/network:/idm/Fedora_34/network:idm.repo
-
-You can then install with:
-
-    dnf install kanidm-clients
-
-## From source (CLI only, not recommended)
-
-After you check out the source (see [GitHub](https://github.com/kanidm/kanidm)), navigate to:
-
-    cd kanidm_tools
-    cargo install --path .
-
-## Checking that the tools work
-
-Now you can check your instance is working. You may need to provide a CA certificate for verification
-with the -C parameter:
-
-    kanidm login --name anonymous
-    kanidm self whoami -C ../path/to/ca.pem -H https://localhost:8443 --name anonymous
-    kanidm self whoami -H https://localhost:8443 --name anonymous
-
-Now you can take some time to look at what commands are available - please [ask for help at any time](https://github.com/kanidm/kanidm#getting-in-contact--questions).
 
 ## Kanidm configuration
 
-You can configure kanidm to help make commands simpler by modifying ~/.config/kanidm OR /etc/kanidm/config
+You can configure `kanidm` to help make commands simpler by modifying `~/.config/kanidm` or `/etc/kanidm/config`.
 
     uri = "https://idm.example.com"
     verify_ca = true|false
@@ -83,7 +23,7 @@ to establish a session token.
     kanidm login --name USERNAME
     kanidm login --name admin
 
-Once complete, you can use kanidm without reauthenticating for a period of time for administration.
+Once complete, you can use `kanidm` without reauthenticating for a period of time for administration.
 
 You can list active sessions with:
 

kanidm_book/src/installing_client_tools.md

@@ -0,0 +1,63 @@
+# Installing Client Tools
+
+> **NOTE** As this project is in a rapid development phase, running different release versions will likely present incompatibilities. Ensure you're running the same release version of client/server binaries (eg. 1.1.0-alpha5, released 2021-07-07)
+
+## From packages
+
+Kanidm currently supports:
+
+ * OpenSUSE Tumbleweed
+ * OpenSUSE Leap 15.3
+ * Fedora 33/34
+
+### OpenSUSE Tumbleweed
+
+Kanidm is part of OpenSUSE Tumbleweed since October 2020. This means you can install
+the clients with:
+
+    zypper ref
+    zypper in kanidm-clients
+
+### OpenSUSE Leap 15.3
+
+Leap 15.3 is still not fully supported with Kanidm. For an experimental client, you can
+try the development repository. Using zypper you can add the repository with:
+
+    zypper ar -f obs://network:idm network_idm
+
+Then you need to refresh your metadata and install the clients.
+
+    zypper ref
+    zypper in kanidm-clients
+
+### Fedora
+
+Fedora is still experimentally supported through the development repository. You need to add the repository metadata into the correct directory.
+
+    cd /etc/yum.repos.d
+    # 33
+    sudo wget https://download.opensuse.org/repositories/network:/idm/Fedora_33/network:idm.repo
+    # 34
+    sudo wget https://download.opensuse.org/repositories/network:/idm/Fedora_34/network:idm.repo
+
+You can then install with:
+
+    sudo dnf install kanidm-clients
+
+## From source (CLI only, not recommended)
+
+After you check out the source (see [GitHub](https://github.com/kanidm/kanidm)), navigate to:
+
+    cd kanidm_tools
+    cargo install --path .
+
+## Checking that the tools work
+
+Now you can check your instance is working. You may need to provide a CA certificate for verification
+with the -C parameter:
+
+    kanidm login --name anonymous
+    kanidm self whoami -C ../path/to/ca.pem -H https://localhost:8443 --name anonymous
+    kanidm self whoami -H https://localhost:8443 --name anonymous
+
+Now you can take some time to look at what commands are available - please [ask for help at any time](https://github.com/kanidm/kanidm#getting-in-contact--questions).

kanidm_book/src/installing_the_server.md

@@ -1,11 +1,13 @@
 # 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.
+
 Currently we have docker images for the server components. They can be found at:
 
-    https://hub.docker.com/r/kanidm/server
+ - <https://hub.docker.com/r/kanidm/server>
-    https://hub.docker.com/r/kanidm/radius
+ - <https://hub.docker.com/r/kanidm/radius>
 
-You can fetch these with:
+You can fetch these by running the commands:
 
     docker pull kanidm/server:latest
     docker pull kanidm/radius:latest
@@ -16,9 +18,14 @@ If you wish to use an x86\_64 cpu-optimised version (See System Requirements CPU
 
 You may need to adjust your example commands throughout this document to suit.
 
+## Development Version
+
+If you are interested in running the latest code from development, you can do this by changing the
+docker tag to `kanidm/server:devel` or `kanidm/server:x86_64_v3_devel` instead.
+
 ## System Requirements
 
-### CPU
+#### CPU
 
 If you are using the x86\_64 cpu-optimised version, you must have a CPU that is from 2013 or newer
 (Haswell, Ryzen). The following instruction flags are used.
@@ -36,12 +43,12 @@ image. These flags will be:
 
     cmov, cx8, fxsr, mmx, sse, sse2
 
-### Memory
+#### Memory
 
 Kanidm extensively uses memory caching, trading memory consumption to improve parallel throughput.
 You should expect to see 64KB of ram per entry in your database, depending on cache tuning and settings.
 
-### Disk
+#### Disk
 
 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.
@@ -113,109 +120,9 @@ OR for a shell into the volume:
 
     docker run --rm -i -t -v kanidmd:/data opensuse/leap:latest /bin/sh
 
-## Configuration
+
-
+
-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:
+# Continue on to [Configuring the Server](server_configuration.md)
-
+
-    #   The webserver bind address. Will use HTTPS if tls_* is provided.
-    #   Defaults to "127.0.0.1:8443"
-    bindaddress = "127.0.0.1:8443"
-    #
-    #   The read-only ldap server bind address. The server will use LDAPS if tls_* is provided.
-    #   Defaults to "" (disabled)
-    # ldapbindaddress = "127.0.0.1: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:
-    #   [zfs, other]
-    #   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.
-    #   - other:
-    #     * 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
-    #   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 = "/data/chain.pem"
-    # tls_key = "/data/key.pem"
-    #
-    #   The log level of the server. May be default, verbose, perfbasic, perffull
-    #   Defaults to "default"
-    # log_level = "default"
-    #
-    #   The origin for webauthn. This is the url to the server, with the port included if
-    #   it is non-standard (any port except 443)
-    # 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.
-    #   Valid roles are:
-    #   - write_replica
-    #     This server provides all functionality of Kanidm. It allows authentication, writes, and
-    #     the web user interface to be served.
-    #   - write_replica_no_ui
-    #     This server is the same as a write_replica, but does NOT offer the web user interface.
-    #   - read_only_replica
-    #     This server will not writes initiated by clients. It supports authentication and reads,
-    #     and must have a replication agreement as a source of it's data.
-    #   Defaults to "write_replica".
-    # role = "write_replica"
-
-An example is located in [examples/server.toml](../../examples/server.toml).
-
-Then you can setup the initial admin account and initialise the database into your volume.
-
-    docker run --rm -i -t -v kanidmd:/data kanidm/server:latest /sbin/kanidmd recover_account -c /data/server.toml -n admin
-
-You then want to set your domain name so that security principal names (spn's) are generated correctly.
-This domain name *must* match the url/origin of the server that you plan to use to interact with
-so that other features work correctly. It is possible to change this domain name later.
-
-    docker run --rm -i -t -v kanidmd:/data kanidm/server:latest /sbin/kanidmd domain_name_change -c /data/server.toml -n idm.example.com
-
-Now we can run the server so that it can accept connections. This defaults to using `-c /data/server.toml`
-
-    docker run -p 8443:8443 -v kanidmd:/data kanidm/server:latest
-
-# Development Version
-
-If you are interested to run our latest code from development, you can do this by changing the
-docker tag to `kanidm/server:devel` or `kanidm/server:x86_64_v3_devel` instead.
-
-# Running as non-root in docker
-
-By default the above commands will run kanidmd as "root" in the container to make the onboarding
-smoother. However, this is not recommended in production for security reasons.
-
-You should allocate a uidnumber/gidnumber for the service to run as that is unique on your host
-system. In this example we use `1000:1000`
-
-You will need to adjust the permissions on the /data volume to ensure that the process
-can manage the files. Kanidm requires the ability to write to the /data directory to create
-the sqlite files. This uid/gidnumber should match the above. You could consider the following
-changes to help isolate these changes:
-
-    docker run --rm -i -t -v kanidmd:/data opensuse/leap:latest /bin/sh
-    # mkdir /data/db/
-    # chown 1000:1000 /data/db/
-    # chmod 750 /data/db/
-    # sed -i -e "s/db_path.*/db_path = \"\/data\/db\/kanidm.db\"/g" /data/server.toml
-    # chown root:root /data/server.toml
-    # chmod 644 /data/server.toml
-
-You can then use this with run the kanidm server in docker with a user.
-
-    docker run --rm -i -t -u 1000:1000 -v kanidmd:/data kanidm/server:latest /sbin/kanidmd ...
-
-> **HINT**
-> You need to use the uidnumber/gidnumber to the `-u` argument, as the container can't resolve
-> usernames from the host system.
 
 

kanidm_book/src/intro.md

@@ -13,6 +13,10 @@ The intent of the Kanidm project is to:
 > This is a pre-release project. While all effort has been made to ensure no data loss
 > or security flaws, you should still be careful when using this in your environment.
 
+## Library documentation
+
+Looking for the `rustdoc` documentation for the libraries themselves? [Click here!](./rustdoc/kanidm/)
+
 ## Why do I want Kanidm?
 
 Whether you work in a business, a volunteer organisation, or are an enthusiast who manages 
@@ -32,7 +36,7 @@ many devices and credentials with different privileges. An example of how this l
                                 ┌──────────────────┐
                                ┌┴─────────────────┐│
                                │                  ││
-           ┌───────────────────┬───▶│      Kanidm      │◀──────┬─────────────────────────┐
+          ┌───────────────┬───▶│      Kanidm      │◀─────┬─────────────────────────┐
           │               │    │                  ├┘     │                         │
           │               │    └──────────────────┘      │                       Verify
      Account Data         │              ▲               │                       Radius
@@ -45,7 +49,7 @@ many devices and credentials with different privileges. An example of how this l
     │            │        │         Public Keys      Password               └────────────┘
     │  Database  │        │              │               │                        ▲
     │            │        │              │               │                        │
-     └────────────┘            │              │                │               ┌─────────┴──────────┐
+    └────────────┘        │              │               │               ┌────────┴──────┐
            ▲              │              │               │               │               │
            │              │              │               │               │               │
     ┌────────────┐        │       ┌────────────┐  ┌────────────┐  ┌────────────┐  ┌────────────┐
@@ -64,7 +68,7 @@ many devices and credentials with different privileges. An example of how this l
            │              │              │               │               │               │
            │              │        ┌──────────┐          │               │               │
            │              │        │          │          │               │               │
-            └──────────────────┴────────│  Laptop  │───────────┴───────────────┴────────────────────┘
+           └──────────────┴────────│  Laptop  │──────────┴───────────────┴───────────────┘
                                    │          │
                                    └──────────┘
                                          ▲

kanidm_book/src/ldap.md

@@ -1,4 +1,4 @@
-# Legacy Applications -- LDAP
+# LDAP
 
 While many applications can support systems like SAML or OAuth, many do not. LDAP
 has been the "lingua franca" of authentication for many years, with almost
@@ -43,7 +43,7 @@ For this reason, when you search the LDAP interface, Kanidm will make some mappi
 * The '\*' and '+' operators can not be used in conjuction with attribute lists in searches.
 
 These decisions were made to make the path as simple and effective as possible,
-relying more on the kanidm query and filter system than attempting to generate a tree-like
+relying more on the Kanidm query and filter system than attempting to generate a tree-like
 representation of data. As almost all clients can use filters for entry selection
 we don't believe this is a limitation for consuming applications.
 
@@ -81,7 +81,7 @@ By default Kanidm is limited in what attributes are generated or remaped into LD
 the server internally contains a map of extended attribute mappings for application specific requests
 that must be satisfied.
 
-An example is that some applications expect and require a 'CN' value, even though kanidm does not
+An example is that some applications expect and require a 'CN' value, even though Kanidm does not
 provide it. If the application is unable to be configured to accept "name" it may be necessary
 to use Kanidm's mapping feature. Today these are compiled into the server so you may need to open
 an issue with your requirements.

kanidm_book/src/pam_and_nsswitch.md

@@ -1,22 +1,12 @@
 # PAM and nsswitch
 
-PAM and nsswitch are the core mechanisms used by Linux and BSD clients
+[PAM](http://linux-pam.org) and [nsswitch](https://en.wikipedia.org/wiki/Name_Service_Switch) are the core mechanisms used by Linux and BSD clients to resolve identities from an IDM service like Kanidm into accounts that can be used on the machine for various interactive tasks.
-to resolve identities from an IDM service like kanidm into accounts that
-can be used on the machine for various interactive tasks.
 
-## The unix daemon
+## The UNIX daemon
 
-Kanidm provide a unix daemon that runs on any client that wants to use pam
+Kanidm provides a UNIX daemon that runs on any client that wants to use PAM and nsswitch integration. This is provided as the daemon can cache the accounts for users who have unreliable networks or leave the site where Kanidm is. The cache is also able to cache missing-entry responses to reduce network traffic and main server load.
-and nsswitch integration. This is provided as the daemon can cache the accounts
-for users who have unreliable networks or leave the site where kanidm is. The
-cache is also able to cache missing-entry responses to reduce network traffic
-and main server load.
 
-Additionally, the daemon means that the pam and nsswitch integration libraries
+Additionally, the daemon means that the PAM and nsswitch integration libraries can be small, helping to reduce the attack surface of the machine. Similarly, a tasks daemon is available that can create home directories on first login and supports several features related to aliases and links to these home directories.
-can be small, helping to reduce the attack surface of the machine.
-Similarly, a tasks daemon is available that can create home directories on first
-login and supports several features related to aliases and links to these
-home directories.
 
 We recommend you install the client daemon from your system package manager.
 
@@ -33,10 +23,9 @@ You can check the privileged tasks daemon is running with
 
     systemctl status kanidm-unixd-tasks
 
-
+> **NOTE** The `kanidm_unixd_tasks` daemon is not required for PAM and nsswitch functionality.
-> **NOTE** The `kanidm_unixd_tasks` daemon is not required for pam and nsswitch functionality.
 > If disabled, your system will function as usual. It is however recommended due to the features
-> it provides supporting kanidm's capabilities.
+> it provides supporting Kanidm's capabilities.
 
 Both unixd daemons use the connection configuration from /etc/kanidm/config. This is the covered in
 [client_tools](./client_tools.md#kandim-configuration). 
@@ -52,8 +41,8 @@ You can also configure some unixd specific options with the file /etc/kanidm/uni
     gid_attr_map = "spn"
 
 The `pam_allowed_login_groups` defines a set of posix groups where membership of any of these
-groups will be allowed to login via pam. All posix users and groups can be resolved by nss
+groups will be allowed to login via PAM. All posix users and groups can be resolved by nss
-regardless of pam login status. This may be a group name, spn or uuid.
+regardless of PAM login status. This may be a group name, spn or uuid.
 
 `default_shell` is the default shell for users with none defined. Defaults to `/bin/sh`.
 
@@ -69,7 +58,7 @@ to nss calls. It is recommended you choose a "human friendly" attribute here.
 Valid choices are `none`, `uuid`, `name`, `spn`. Defaults to `spn`.
 
 > **NOTICE:**
-> All users in kanidm can change their name (and their spn) at any time. If you change
+> All users in Kanidm can change their name (and their spn) at any time. If you change
 > `home_attr` from `uuid` you *must* have a plan on how to manage these directory renames
 > in your system. We recommend that you have a stable id (like the uuid) and symlinks
 > from the name to the uuid folder. Automatic support is provided for this via the unixd
@@ -122,7 +111,7 @@ You can also do the same for groups.
  
 ## PAM
 
-> **WARNING:** Modifications to pam configuration *may* leave your system in a state
+> **WARNING:** Modifications to PAM configuration *may* leave your system in a state
 > where you are unable to login or authenticate. You should always have a recovery
 > shell open while making changes (ie root), or have access to single-user mode
 > at the machine's console.
@@ -135,7 +124,7 @@ where each module may request or reuse authentication token information.
 ### Before you start
 
 You *should* backup your /etc/pam.d directory from its original state as you *may* change the
-pam config in a way that will cause you to be unable to authenticate to your machine.
+PAM config in a way that will cause you to be unable to authenticate to your machine.
 
     cp -a /etc/pam.d /root/pam.d.backup
 
@@ -148,7 +137,7 @@ To configure PAM on suse you must module four files:
     /etc/pam.d/common-password
     /etc/pam.d/common-session
 
-Each of these controls one of the four stages of pam. The content should look like:
+Each of these controls one of the four stages of PAM. The content should look like:
 
     # /etc/pam.d/common-account-pc
     account    [default=1 ignore=ignore success=ok] pam_localuser.so
@@ -182,7 +171,7 @@ Each of these controls one of the four stages of pam. The content should look li
 
 ### Fedora 33
 
-> **WARNING:** kanidm currently has no support for SELinux policy - this may mean you need to
+> **WARNING:** Kanidm currently has no support for SELinux policy - this may mean you need to
 > run the daemon with permissive mode for the unconfined_service_t daemon type. To do this run:
 > `semanage permissive -a unconfined_service_t`. To undo this run `semanage permissive -d unconfined_service_t`.
 >
@@ -319,7 +308,7 @@ You can clear (wipe) the cache with:
     $ kanidm_cache_clear
 
 There is an important distinction between these two - invalidated cache items may still
-be yielded to a client request if the communication to the main kanidm server is not
+be yielded to a client request if the communication to the main Kanidm server is not
 possible. For example, you may have your laptop in a park without wifi.
 
 Clearing the cache, however, completely wipes all local data about all accounts and groups.

kanidm_book/src/password_quality.md

@@ -1,39 +1,28 @@
 # Password Quality and Badlisting
 
-Kanidm embeds a set of tools to help your users use and create strong passwords. This is important
+Kanidm embeds a set of tools to help your users use and create strong passwords. This is important as not all user types will require MFA for their roles, but compromised accounts still pose a risk. There may also be deployment or other barriers to a site rolling out site wide MFA.
-as not all user types will require MFA for their roles, but compromised accounts still pose a risk.
-There may also be deployment or other barriers to a site rolling out site wide MFA.
 
 ## Quality Checking
 
-Kanidm enforces that all passwords are checked by the library "zxcvbn". This has a large number of
+Kanidm enforces that all passwords are checked by the library "[zxcvbn](https://github.com/dropbox/zxcvbn)". This has a large number of checks for password quality. It also provides constructive feedback to users on how to improve their passwords if it was rejected.
-checks for password quality. It also provides constructive feedback to users on how to improve their
-passwords if it was rejected.
 
-Some things that zxcvbn looks for is use of the account name or email in the password, common passwords,
+Some things that zxcvbn looks for is use of the account name or email in the password, common passwords, low entropy passwords, dates, reverse words and more.
-low entropy passwords, dates, reverse words and more.
 
 This library can not be disabled - all passwords in Kanidm must pass this check.
 
 ## Password Badlisting
 
-This is the process of configuring a list of passwords to exclude from being able to be used. This
+This is the process of configuring a list of passwords to exclude from being able to be used. This is especially useful if a specific business has been notified of a compromised account, allowing you to maintain a list of customised excluded passwords.
-is especially useful if a specific business has been notified of a compromised account, allowing
-you to maintain a list of customised excluded passwords.
 
-The other value to this feature is being able to badlist common passwords that zxcvbn does not
+The other value to this feature is being able to badlist common passwords that zxcvbn does not detect, or from other large scale password compromises.
-detect, or from other large scale password compromises.
 
-By default we ship with a preconfigured badlist that is updated overtime as new password breach
+By default we ship with a preconfigured badlist that is updated overtime as new password breach lists are made available.
-lists are made available.
 
 ## Updating your own badlist.
 
-You can update your own badlist by using the proided `kanidm_badlist_preprocess` tool which helps
+You can update your own badlist by using the proided `kanidm_badlist_preprocess` tool which helps to automate this process.
-to automate this process.
 
-Given a list of passwords in a text file, it will generate a modification set which can be
+Given a list of passwords in a text file, it will generate a modification set which can be applied. The tool also provides the command you need to run to apply this.
-applied. The tool also provides the command you need to run to apply this.
 
     kanidm_badlist_preprocess -m -o /tmp/modlist.json <password file> [<password file> <password file> ...]
 

kanidm_book/src/security_hardening.md

@@ -15,9 +15,11 @@ The unixd resolver is also a high value target as it can be accessed to allow un
 access to a server, to intercept communications to the server, or more. This also must be protected
 carfully.
 
-For this reason the kanidm's components must be protected carefully. Kanidm avoids many classic
+For this reason, Kanidm's components must be protected carefully. Kanidm avoids many classic
 attacks by being developed in a memory safe language, but risks still exist.
 
+## Startup Warnings
+
 At startup Kanidm will warn you if the environment it is running in is suspicious or
 has risks. For example:
 
@@ -114,4 +116,31 @@ This file should be everyone-readable which is why the bits are defined as such.
 > but it affects the check. We don't believe this is a significant issue though because
 > setting these to 440 and 444 helps to prevent accidental changes by an administrator anyway
 
+## Running as non-root in docker
 
+The commands provided in this book will run kanidmd as "root" in the container to make the onboarding
+smoother. However, this is not recommended in production for security reasons.
+
+You should allocate a uidnumber/gidnumber for the service to run as that is unique on your host
+system. In this example we use `1000:1000`
+
+You will need to adjust the permissions on the `/data` volume to ensure that the process
+can manage the files. Kanidm requires the ability to write to the `/data` directory to create
+the sqlite files. This uid/gidnumber should match the above. You could consider the following
+changes to help isolate these changes:
+
+    docker run --rm -i -t -v kanidmd:/data opensuse/leap:latest /bin/sh
+    # mkdir /data/db/
+    # chown 1000:1000 /data/db/
+    # chmod 750 /data/db/
+    # sed -i -e "s/db_path.*/db_path = \"\/data\/db\/kanidm.db\"/g" /data/server.toml
+    # chown root:root /data/server.toml
+    # chmod 644 /data/server.toml
+
+You can then use this with run the kanidm server in docker with a user.
+
+    docker run --rm -i -t -u 1000:1000 -v kanidmd:/data kanidm/server:latest /sbin/kanidmd ...
+
+> **HINT**
+> You need to use the uidnumber/gidnumber to the `-u` argument, as the container can't resolve
+> usernames from the host system.

kanidm_book/src/server_configuration.md

@@ -0,0 +1,70 @@
+## Configuring the Server
+
+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:
+
+    #   The webserver bind address. Will use HTTPS if tls_* is provided.
+    #   Defaults to "127.0.0.1:8443"
+    bindaddress = "127.0.0.1:8443"
+    #
+    #   The read-only ldap server bind address. The server will use LDAPS if tls_* is provided.
+    #   Defaults to "" (disabled)
+    # ldapbindaddress = "127.0.0.1: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:
+    #   [zfs, other]
+    #   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.
+    #   - other:
+    #     * 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
+    #   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 = "/data/chain.pem"
+    # tls_key = "/data/key.pem"
+    #
+    #   The log level of the server. May be default, verbose, perfbasic, perffull
+    #   Defaults to "default"
+    # log_level = "default"
+    #
+    #   The origin for webauthn. This is the url to the server, with the port included if
+    #   it is non-standard (any port except 443)
+    # 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.
+    #   Valid roles are:
+    #   - write_replica
+    #     This server provides all functionality of Kanidm. It allows authentication, writes, and
+    #     the web user interface to be served.
+    #   - write_replica_no_ui
+    #     This server is the same as a write_replica, but does NOT offer the web user interface.
+    #   - read_only_replica
+    #     This server will not writes initiated by clients. It supports authentication and reads,
+    #     and must have a replication agreement as a source of it's data.
+    #   Defaults to "write_replica".
+    # role = "write_replica"
+
+An example is located in [examples/server.toml](../../examples/server.toml).
+
+Then you can setup the initial admin account and initialise the database into your volume.
+
+    docker run --rm -i -t -v kanidmd:/data kanidm/server:latest /sbin/kanidmd recover_account -c /data/server.toml -n admin
+
+You then want to set your domain name so that security principal names (spn's) are generated correctly.
+This domain name *must* match the url/origin of the server that you plan to use to interact with
+so that other features work correctly. It is possible to change this domain name later.
+
+    docker run --rm -i -t -v kanidmd:/data kanidm/server:latest /sbin/kanidmd domain_name_change -c /data/server.toml -n idm.example.com
+
+Now we can run the server so that it can accept connections. This defaults to using `-c /data/server.toml`
+
+    docker run -p 8443:8443 -v kanidmd:/data kanidm/server:latest

kanidm_book/src/ssh_key_dist.md

@@ -37,7 +37,7 @@ can still ssh into your machines, even if your network is down, you move away fr
 some other interruption occurs.
 
 The kanidm_ssh_authorizedkeys command is part of the kanidm-unix-clients package, so should be installed
-on the servers. It communicates to kanidm_unixd, so you should have a configured pam/nsswitch
+on the servers. It communicates to kanidm_unixd, so you should have a configured PAM/nsswitch
 setup as well.
 
 You can test this is configured correctly by running:

kanidm_proto/src/v1.rs

@@ -717,7 +717,7 @@ pub struct TotpSecret {
 }
 
 impl TotpSecret {
-    /// https://github.com/google/google-authenticator/wiki/Key-Uri-Format
+    /// <https://github.com/google/google-authenticator/wiki/Key-Uri-Format>
     pub fn to_uri(&self) -> String {
         // label = accountname / issuer (“:” / “%3A”) *”%20” accountname
         // This is already done server side but paranoia is good!

kanidm_tools/Cargo.toml

@@ -17,6 +17,7 @@ path = "src/cli/lib.rs"
 [[bin]]
 name = "kanidm"
 path = "src/cli/main.rs"
+doc = false
 
 [[bin]]
 name = "kanidm_ssh_authorizedkeys_direct"

kanidm_unix_int/pam_kanidm/src/pam/module.rs

@@ -68,7 +68,7 @@ pub type PamResult<T> = Result<T, PamResultCode>;
 /// Type-level mapping for safely retrieving values with `get_item`.
 ///
 /// See `pam_get_item` in
-/// http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html
+/// <http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html>
 pub trait PamItem {
     /// Maps a Rust type to a pam constant.
     ///
@@ -84,7 +84,7 @@ impl PamHandle {
     /// previously.
     ///
     /// See `pam_get_data` in
-    /// http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html
+    /// <http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html>
     pub unsafe fn get_data<'a, T>(&'a self, key: &str) -> PamResult<&'a T> {
         let c_key = CString::new(key).unwrap();
         let mut ptr: *const PamDataT = ptr::null();
@@ -102,7 +102,7 @@ impl PamHandle {
     /// as long as the current pam cycle.
     ///
     /// See `pam_set_data` in
-    /// http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html
+    /// <http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html>
     pub fn set_data<T>(&self, key: &str, data: Box<T>) -> PamResult<()> {
         let c_key = CString::new(key).unwrap();
         let res = unsafe {
@@ -121,7 +121,7 @@ impl PamHandle {
     /// particularly useful for getting a `PamConv` reference.
     ///
     /// See `pam_get_item` in
-    /// http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html
+    /// <http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html>
     pub fn get_item<'a, T: PamItem>(&self) -> PamResult<&'a T> {
         let mut ptr: *const PamItemT = ptr::null();
         let (res, item) = unsafe {
@@ -143,7 +143,7 @@ impl PamHandle {
     /// Note that all items are strings, except `PAM_CONV` and `PAM_FAIL_DELAY`.
     ///
     /// See `pam_set_item` in
-    /// http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html
+    /// <http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html>
     pub fn set_item_str<T: PamItem>(&mut self, item: &str) -> PamResult<()> {
         let c_item = CString::new(item).unwrap();
 
@@ -168,7 +168,7 @@ impl PamHandle {
     /// This is really a specialization of `get_item`.
     ///
     /// See `pam_get_user` in
-    /// http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html
+    /// <http://www.linux-pam.org/Linux-PAM-html/mwg-expected-by-module-item.html>
     pub fn get_user(&self, prompt: Option<&str>) -> PamResult<String> {
         let ptr: *mut c_char = ptr::null_mut();
         let res = match prompt {

kanidmd/src/lib/core/mod.rs

@@ -6,7 +6,7 @@
 //!
 //! Generally, this is the "entry point" where the server begins to run, and
 //! the entry point for all client traffic which is then directed to the
-//! varius [`actors`].
+//! various `actors`.
 
 mod https;
 mod ldaps;

kanidmd/src/lib/credential/totp.rs

@@ -57,7 +57,7 @@ impl TotpAlgo {
     }
 }
 
-/// https://tools.ietf.org/html/rfc6238 which relies on https://tools.ietf.org/html/rfc4226
+/// <https://tools.ietf.org/html/rfc6238> which relies on <https://tools.ietf.org/html/rfc4226>
 #[derive(Debug, Clone)]
 pub struct Totp {
     secret: Vec<u8>,

kanidmd/src/lib/idm/mod.rs

@@ -1,6 +1,6 @@
-//! The Identity Management components that are layered ontop of the [`QueryServer`]. These allow
+//! The Identity Management components that are layered ontop of the [QueryServer](crate::server::QueryServer). These allow
 //! rich and expressive events and transformations that are lowered into the correct/relevant
-//! actions in the [`QueryServer`]. Generally this is where "Identity Management" policy and code
+//! actions in the [QueryServer](crate::server::QueryServer). Generally this is where "Identity Management" policy and code
 //! is implemented.
 
 pub(crate) mod account;

kanidmd/src/lib/value.rs

@@ -1,7 +1,7 @@
 //! Inside an entry, the key-value pairs are stored in these [`Value`] types. The components of
 //! the [`Value`] module allow storage and transformation of various types of input into strongly
 //! typed values, allows their comparison, filtering and more. It also has the code for serialising
-//! these into a form for the backend that can be persistent into the [`Backend`].
+//! these into a form for the backend that can be persistent into the [`Backend`](crate::be::Backend).
 
 use crate::be::dbvalue::{
     DbCidV1, DbValueCredV1, DbValueEmailAddressV1, DbValueTaggedStringV1, DbValueV1,

project_docs/RELEASE_AND_SUPPORT.md

@@ -1,6 +1,6 @@
 ## Release Schedule
 
-In the alpha phase, kanidm will be released on a 3 month (quarterly) basis,
+In the alpha phase, Kanidm will be released on a 3 month (quarterly) basis,
 starting on July 1st 2020.
 
 * January 1st