From c6e5e426d04d4062000d7f755ff87cae7b66e562 Mon Sep 17 00:00:00 2001 From: James Hodgkinson Date: Mon, 8 Aug 2022 09:55:03 +1000 Subject: [PATCH] Fixing broken images and probably making it worse, because that's how I roll. (#973) --- Makefile | 1 + kanidm_book/src/accounts_and_groups.md | 1 + kanidm_book/src/administrivia.md | 11 ++++-- .../src/developers/designs/rest_interface.md | 1 + kanidm_book/src/integrations/ldap.md | 38 +++++++++++++------ kanidm_book/src/intro.md | 1 + kanidm_book/src/recycle_bin.md | 9 +++-- kanidm_book/src/server_configuration.md | 12 ++++-- kanidm_book/src/templates/kani-warning.md | 2 +- 9 files changed, 53 insertions(+), 23 deletions(-) diff --git a/Makefile b/Makefile index 2f2479a50..e772cacd6 100644 --- a/Makefile +++ b/Makefile @@ -116,6 +116,7 @@ doc: ## Build the rust documentation locally doc: cargo doc --document-private-items +book: ## Build the Kanidm book book: cargo doc --no-deps mdbook build kanidm_book diff --git a/kanidm_book/src/accounts_and_groups.md b/kanidm_book/src/accounts_and_groups.md index 5b4cfa5e1..e6ca86e28 100644 --- a/kanidm_book/src/accounts_and_groups.md +++ b/kanidm_book/src/accounts_and_groups.md @@ -31,6 +31,7 @@ admin (system admin) account. {{#template templates/kani-warning.md + imagepath=images text=Warning: The server must not be running at this point, as it requires exclusive access to the database. }} diff --git a/kanidm_book/src/administrivia.md b/kanidm_book/src/administrivia.md index 97a8b4b20..65042a655 100644 --- a/kanidm_book/src/administrivia.md +++ b/kanidm_book/src/administrivia.md @@ -55,11 +55,14 @@ the number of backup versions to keep. An example is located in # Configuration Test -You can test your configuration will correctly start with the server. +{{#template + templates/kani-warning.md + imagepath=images + title=Take note! + text=While this is a configuration file test, it still needs to open the database so that it can check a number of internal values are consistent with the configuration. As a result, this requires the instance under config test to be stopped! +}} -> **WARNING:** While this is a configuration test, it still needs to open the database so that -> it can check a number of internal values are consistent with the configuration. As a result, -> this requires the instance under config test to be stopped! +You can test that your configuration is correct, and the server should correctly start. docker stop docker run --rm -i -t -v kanidmd:/data \ diff --git a/kanidm_book/src/developers/designs/rest_interface.md b/kanidm_book/src/developers/designs/rest_interface.md index 1f764502d..dad57108b 100644 --- a/kanidm_book/src/developers/designs/rest_interface.md +++ b/kanidm_book/src/developers/designs/rest_interface.md @@ -3,6 +3,7 @@ {{#template ../../templates/kani-warning.md + imagepath=../../images text=Here begins some early notes on the REST interface - much better ones are in the repository's designs directory. }} diff --git a/kanidm_book/src/integrations/ldap.md b/kanidm_book/src/integrations/ldap.md index 4d68a371a..c6a088e1f 100644 --- a/kanidm_book/src/integrations/ldap.md +++ b/kanidm_book/src/integrations/ldap.md @@ -7,9 +7,13 @@ authentication for many years, with almost every application in the world being able to search and bind to LDAP. As many organization still rely on LDAP, Kanidm can host a read-only LDAP interface. -> **WARNING** The LDAP server in Kanidm is not RFC compliant. This -> is intentional, as Kanidm wants to cover the common use case, -> simple bind and search. +{{#template + ../templates/kani-warning.md + imagepath=../images + title=Warning! + text=The LDAP server in Kanidm is not RFC compliant. This is intentional, as Kanidm wants to cover the common use case, simple bind and search. +}} + ## What is LDAP @@ -105,10 +109,22 @@ Kanidm native attributes. ## Example Given a default install with domain "example.com" the configured LDAP DN will be "dc=example,dc=com". + +Run your server: + + cargo run -- server \ + -D kanidm.db \ + -C ca.pem -c cert.pem \ + -k key.pem \ + -b 127.0.0.1:8443 \ + -l 127.0.0.1:3636 + This can be queried with: - cargo run -- server -D kanidm.db -C ca.pem -c cert.pem -k key.pem -b 127.0.0.1:8443 -l 127.0.0.1:3636 - > LDAPTLS_CACERT=ca.pem ldapsearch -H ldaps://127.0.0.1:3636 -b 'dc=example,dc=com' -x '(name=test1)' + LDAPTLS_CACERT=ca.pem ldapsearch \ + -H ldaps://127.0.0.1:3636 \ + -b 'dc=example,dc=com' \ + -x '(name=test1)' # test1@example.com, example.com dn: spn=test1@example.com,dc=example,dc=com @@ -122,10 +138,10 @@ This can be queried with: spn: test1@example.com entryuuid: 22a65b6c-80c8-4e1a-9b76-3f3afdff8400 -It is recommended that client applications filter accounts that can login with '(class=account)' -and groups with '(class=group)'. If possible, group membership is defined in RFC2307bis or -Active Directory style. This means groups are determined from the "memberof" attribute which contains -a DN to a group. +It is recommended that client applications filter accounts that can login with `(class=account)` +and groups with `(class=group)`. If possible, group membership is defined in RFC2307bis or +Active Directory style. This means groups are determined from the "memberof" attribute which +contains a DN to a group. LDAP binds can use any unique identifier of the account. The following are all valid bind DNs for the object listed above (if it was a POSIX account, that is). @@ -138,8 +154,8 @@ the object listed above (if it was a POSIX account, that is). ldapwhoami ... -x -D 'spn=test1@example.com,dc=example,dc=com' ldapwhoami ... -x -D 'name=test1,dc=example,dc=com' -Most LDAP clients are very picky about TLS, and can be very hard to debug or display errors. For example -these commands: +Most LDAP clients are very picky about TLS, and can be very hard to debug or display errors. +For example these commands: ldapsearch -H ldaps://127.0.0.1:3636 -b 'dc=example,dc=com' -x '(name=test1)' ldapsearch -H ldap://127.0.0.1:3636 -b 'dc=example,dc=com' -x '(name=test1)' diff --git a/kanidm_book/src/intro.md b/kanidm_book/src/intro.md index e502a1f05..f8cee37b4 100644 --- a/kanidm_book/src/intro.md +++ b/kanidm_book/src/intro.md @@ -12,6 +12,7 @@ The intent of the Kanidm project is to: {{#template templates/kani-warning.md + imagepath=images title=NOTICE text=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. }} diff --git a/kanidm_book/src/recycle_bin.md b/kanidm_book/src/recycle_bin.md index 7bff61a0e..8db4a0251 100644 --- a/kanidm_book/src/recycle_bin.md +++ b/kanidm_book/src/recycle_bin.md @@ -3,9 +3,12 @@ The recycle bin is a storage of deleted entries from the server. This allows recovery from mistakes for a period of time. -> **WARNING:** The recycle bin is a best effort - when recovering in some cases -> not everything can be "put back" the way it was. Be sure to check your entries -> are valid once they have been revived. +{{#template + templates/kani-warning.md + imagepath=images + title=Warning! + text=The recycle bin is a best effort - when recovering in some cases not everything can be "put back" the way it was. Be sure to check your entries are valid once they have been revived. +}} ## Where is the Recycle Bin? diff --git a/kanidm_book/src/server_configuration.md b/kanidm_book/src/server_configuration.md index ef84f67fe..8cf6298fd 100644 --- a/kanidm_book/src/server_configuration.md +++ b/kanidm_book/src/server_configuration.md @@ -2,7 +2,7 @@ ### Configuring server.toml -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: +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. @@ -102,10 +102,14 @@ You need a configuration file in the volume named `server.toml`. (Within the con # -An example is located in [examples/server.toml](../../examples/server.toml). +An example is located in [examples/server.toml](https://github.com/kanidm/kanidm/blob/master/examples/server.toml). -> **WARNING** You MUST set the `domain` name correctly, aligned with your `origin`, else the server -> may refuse to start, or some features (e.g. webauthn, oauth) may not work correctly! +{{#template + templates/kani-warning.md + imagepath=images + title=Warning! + text=You MUST set the `domain` name correctly, aligned with your `origin`, else the server may refuse to start or some features (e.g. webauthn, oauth) may not work correctly! +}} ### Check the configuration is valid. diff --git a/kanidm_book/src/templates/kani-warning.md b/kanidm_book/src/templates/kani-warning.md index 91b6325fa..9a27ff043 100644 --- a/kanidm_book/src/templates/kani-warning.md +++ b/kanidm_book/src/templates/kani-warning.md @@ -1,6 +1,6 @@ - +
Kani WarningKani Warning [[#title]]