Cleanup references to sqlite, add a FAQ section (#1307)

* Cleanup references to sqlite, add a FAQ section
* Formatting

examples/server.toml

@@ -9,14 +9,14 @@ bindaddress = "[::]:443"
 #   The path to the kanidm database.
 db_path = "/var/lib/kanidm/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 database operations 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.
+#     * sets database pagesize to 64k. You must set recordsize=64k on the zfs filesystem.
 #   - other:
-#     * sets sqlite pagesize to 4k, matching most filesystems block sizes.
+#     * sets database 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

examples/server_container.toml

@@ -23,17 +23,17 @@ bindaddress = "[::]:8443"
 #   The path to the kanidm database.
 db_path = "/data/kanidm.db"
 #
-#   If you have a known filesystem, kanidm can tune sqlite
+#   If you have a known filesystem, kanidm can tune database
 #   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
+#     * sets database pagesize to 64k. You must set
 #       recordsize=64k on the zfs filesystem.
 #   - other:
-#     * sets sqlite pagesize to 4k, matching most
+#     * sets database pagesize to 4k, matching most
 #       filesystems block sizes.
 # db_fs_type = "zfs"
 #

kanidm_book/src/SUMMARY.md

@@ -1,7 +1,6 @@
 # Kanidm
 
 - [Introduction to Kanidm](intro.md)
-- [Frequently Asked Questions](frequently_asked_questions.md)
 - [Installing the Server](installing_the_server.md)
   - [Choosing a Domain Name](choosing_a_domain_name.md)
   - [Preparing for your Deployment](prepare_the_server.md)
@@ -10,6 +9,9 @@
   - [Platform Security Hardening](security_hardening.md)
 - [Client Tools](client_tools.md)
   - [Installing client tools](installing_client_tools.md)
+
+# Administration
+
 - [Administration](administrivia.md)
   - [Accounts and Groups](accounts_and_groups.md)
   - [Backup and Restore](backup_restore.md)
@@ -20,8 +22,10 @@
   - [POSIX Accounts and Groups](posix_accounts.md)
   - [SSH Key Distribution](ssh_key_dist.md)
   - [The Recycle Bin](recycle_bin.md)
-  - [Why TLS?](why_tls.md)
 - [Troubleshooting](troubleshooting.md)
+
+- [Frequently Asked Questions](frequently_asked_questions.md)
+
 - [Glossary of Technical Terms](glossary.md)
 
 # Services

kanidm_book/src/backup_restore.md

@@ -41,12 +41,14 @@ docker start <container name>
 
 ## Method 3 - Manual Database Copy
 
-This is a simple backup of the data volume.
+This is a simple backup of the data volume containing the database files. Ensure you copy the whole
+folder, rather than individual files in the volume!
 
 ```bash
 docker stop <container name>
 # Backup your docker's volume folder
+# cp -a /path/to/my/volume /path/to/my/backup-volume
 docker start <container name>
 ```
 
-Restoration is the reverse process.
+Restoration is the reverse process where you copy the entire folder back into place.

kanidm_book/src/database_maint.md

@@ -33,10 +33,9 @@ Generally, reindexing is a rare action and should not normally be required.
 
 ## Vacuum
 
-[Vacuuming](https://www.sqlite.org/lang_vacuum.html) is the process of reclaiming un-used pages from
-the sqlite freelists, as well as performing some data reordering tasks that may make some queries
-more efficient . It is recommended that you vacuum after a reindex is performed or when you wish to
-reclaim space in the database file.
+Vacuuming is the process of reclaiming un-used pages from the database freelists, as well as
+performing some data reordering tasks that may make some queries more efficient. It is recommended
+that you vacuum after a reindex is performed or when you wish to reclaim space in the database file.
 
 Vacuum is also able to change the pagesize of the database. After changing `db_fs_type` (which
 affects pagesize) in server.toml, you must run a vacuum for this to take effect:

kanidm_book/src/frequently_asked_questions.md

@@ -2,12 +2,61 @@
 
 ... or ones we think people _might_ ask.
 
-## Why disallow HTTP (without TLS) between my load balancer and Kanidm?
+## Why TLS?
+
+You may have noticed that Kanidm requires you to configure TLS in your container or server install.
+
+We are a secure-by-design rather than secure-by-configuration system, so TLS for all connections is
+considered mandatory and a default rather than an optional feature you add later.
+
+### Why disallow HTTP (without TLS) between my load balancer and Kanidm?
 
 Because Kanidm is one of the keys to a secure network, and insecure connections to them are not best
-practice.
+practice. This can allow account hijacking, privilege escalation, credential disclosures, personal
+information leaks and more.
 
-Please refer to [Why TLS?](why_tls.md) for a longer explanation.
+### What are Secure Cookies?
+
+`secure-cookies` is a flag set in cookies that asks a client to transmit them back to the origin
+site if and only if the client sees HTTPS is present in the URL.
+
+Certificate authority (CA) verification is _not_ checked - you can use invalid, out of date
+certificates, or even certificates where the `subjectAltName` does not match, but the client must
+see https:// as the destination else it _will not_ send the cookies.
+
+### How Does That Affect Kanidm?
+
+Kanidm's authentication system is a stepped challenge response design, where you initially request
+an "intent" to authenticate. Once you establish this intent, the server sets up a session-id into a
+cookie, and informs the client of what authentication methods can proceed.
+
+If you do NOT have a HTTPS URL, the cookie with the session-id is not transmitted. The server
+detects this as an invalid-state request in the authentication design, and immediately breaks the
+connection, because it appears insecure. This prevents credential disclosure since the
+authentication session was not able to be established due to the lost session-id cookie.
+
+Simply put, we are trying to use settings like `secure_cookies` to add constraints to the server so
+that you _must_ perform and adhere to best practices - such as having TLS present on your
+communication channels.
+
+## Can I change the database backend from SQLite to - name of favourite database here -
+
+No, it is not possible swap out the SQLite database for any other type of SQL server.
+
+_ATTEMPTING THIS WILL BREAK YOUR KANIDM INSTANCE IRREPARABLY_
+
+This question is normally asked because people want to setup multiple Kanidm servers connected to a
+single database.
+
+Kanidm does not use SQL as a _database_. Kanidm uses SQL as a durable key-value store and Kanidm
+implements it's own database, caching, querying, optimisation and indexing ontop of that key-value
+store.
+
+As a result, because Kanidm specifically implements it's own cache layer above the key-value store
+(sqlite in this example) then if you were to connect two Kanidm instances to the same key-value
+store, as each server has it's own cache layer and they are not in contact, it is possible for
+writes on one server to never be observed by the second, and if the second were to then write over
+those entries it will cause loss of the changes from the first server.
 
 ## Why so many crabs?
 
@@ -15,8 +64,8 @@ It's [a rust thing](https://rustacean.net).
 
 ## Will you implement -insert protocol here-
 
-Probably, on an infinite time-scale! As long as it's not Kerberos. Or involves SSL or STARTTLS.
-Please log an issue and start the discussion!
+Probably, on an infinite time-scale! As long as it's not STARTTLS. Please log an issue and start the
+discussion!
 
 ## Why do the crabs have knives?
 

kanidm_book/src/prepare_the_server.md

@@ -92,8 +92,8 @@ docker volume create kanidmd
 
 You should have a chain.pem and key.pem in your kanidmd volume. The reason for requiring 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.
+[why tls](./frequently_asked_questions.md#why-tls). 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
 similar to:

kanidm_book/src/security_hardening.md

@@ -134,9 +134,9 @@ You should allocate unique UID and GID numbers for the service to run as on your
 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/GID number should match the above. You could consider the following changes to help isolate
-these changes:
+the files. Kanidm requires the ability to write to the `/data` directory to create the database
+files. This UID/GID number should match the above. You could consider the following changes to help
+isolate these changes:
 
 ```bash
 docker run --rm -i -t -v kanidmd:/data opensuse/leap:latest /bin/sh

kanidm_book/src/why_tls.md

@@ -1,29 +0,0 @@
-# Why TLS?
-
-You may have noticed that Kanidm requires you to configure TLS in your container.
-
-We are a secure-by-design rather than secure-by-installation system, so TLS for all connections is
-considered mandatory.
-
-## What are Secure Cookies?
-
-`secure-cookies` is a flag set in cookies that asks a client to transmit them back to the origin
-site if and only if HTTPS is present in the URL.
-
-Certificate authority (CA) verification is _not_ checked - you can use invalid, out of date
-certificates, or even certificates where the `subjectAltName` does not match, but the client must
-see https:// as the destination else it _will not_ send the cookies.
-
-## How Does That Affect Kanidm?
-
-Kanidm's authentication system is a stepped challenge response design, where you initially request
-an "intent" to authenticate. Once you establish this intent, the server sets up a session-id into a
-cookie, and informs the client of what authentication methods can proceed.
-
-If you do NOT have a HTTPS URL, the cookie with the session-id is not transmitted. The server
-detects this as an invalid-state request in the authentication design, and immediately breaks the
-connection, because it appears insecure.
-
-Simply put, we are trying to use settings like `secure_cookies` to add constraints to the server so
-that you _must_ perform and adhere to best practices - such as having TLS present on your
-communication channels.