From ed149e38257adb41719e4467367c311cf449ed58 Mon Sep 17 00:00:00 2001 From: Firstyear Date: Wed, 4 Jan 2023 06:33:52 +1000 Subject: [PATCH] Cleanup references to sqlite, add a FAQ section (#1307) * Cleanup references to sqlite, add a FAQ section * Formatting --- examples/server.toml | 6 +- examples/server_container.toml | 6 +- kanidm_book/src/SUMMARY.md | 8 ++- kanidm_book/src/backup_restore.md | 6 +- kanidm_book/src/database_maint.md | 7 +-- kanidm_book/src/frequently_asked_questions.md | 59 +++++++++++++++++-- kanidm_book/src/prepare_the_server.md | 4 +- kanidm_book/src/security_hardening.md | 6 +- kanidm_book/src/why_tls.md | 29 --------- 9 files changed, 78 insertions(+), 53 deletions(-) delete mode 100644 kanidm_book/src/why_tls.md diff --git a/examples/server.toml b/examples/server.toml index a6e5fab9c..81216a5b3 100644 --- a/examples/server.toml +++ b/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 diff --git a/examples/server_container.toml b/examples/server_container.toml index ce4715d96..2bfd3c8b9 100644 --- a/examples/server_container.toml +++ b/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" # diff --git a/kanidm_book/src/SUMMARY.md b/kanidm_book/src/SUMMARY.md index b04b2e6e7..1b0a3f35c 100644 --- a/kanidm_book/src/SUMMARY.md +++ b/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 diff --git a/kanidm_book/src/backup_restore.md b/kanidm_book/src/backup_restore.md index 19ac3702f..a1aa7d000 100644 --- a/kanidm_book/src/backup_restore.md +++ b/kanidm_book/src/backup_restore.md @@ -41,12 +41,14 @@ docker start ## 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 # Backup your docker's volume folder +# cp -a /path/to/my/volume /path/to/my/backup-volume docker start ``` -Restoration is the reverse process. +Restoration is the reverse process where you copy the entire folder back into place. diff --git a/kanidm_book/src/database_maint.md b/kanidm_book/src/database_maint.md index 1d6179bd3..0597aca29 100644 --- a/kanidm_book/src/database_maint.md +++ b/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: diff --git a/kanidm_book/src/frequently_asked_questions.md b/kanidm_book/src/frequently_asked_questions.md index 5c546797e..9c1893063 100644 --- a/kanidm_book/src/frequently_asked_questions.md +++ b/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? diff --git a/kanidm_book/src/prepare_the_server.md b/kanidm_book/src/prepare_the_server.md index 4e2178a6c..dc18dbf80 100644 --- a/kanidm_book/src/prepare_the_server.md +++ b/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: diff --git a/kanidm_book/src/security_hardening.md b/kanidm_book/src/security_hardening.md index a86de5fd3..f885a7475 100644 --- a/kanidm_book/src/security_hardening.md +++ b/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 diff --git a/kanidm_book/src/why_tls.md b/kanidm_book/src/why_tls.md deleted file mode 100644 index 1221545c2..000000000 --- a/kanidm_book/src/why_tls.md +++ /dev/null @@ -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.