From d14c2d233097fd9161c4deac0a03c84d652f8887 Mon Sep 17 00:00:00 2001 From: James Hodgkinson Date: Wed, 21 Sep 2022 13:05:32 +1000 Subject: [PATCH] Book updates (#1067) * blep * more blep * fixed book build issues, updooted some FAQ and troubleshooting things * more random updoots * dat yak thoe --- examples/server_container.toml | 96 +++++++++++++++++ kanidm_book/src/SUMMARY.md | 3 +- kanidm_book/src/accounts_and_groups.md | 6 +- kanidm_book/src/choosing_a_domain_name.md | 6 +- .../src/developers/designs/rest_interface.md | 3 +- kanidm_book/src/frequently_asked_questions.md | 19 ++++ kanidm_book/src/intro.md | 3 +- kanidm_book/src/server_configuration.md | 102 +----------------- kanidm_book/src/troubleshooting.md | 62 +++++++++++ .../troubleshooting/curl_connection_test.txt | 40 +++++++ 10 files changed, 231 insertions(+), 109 deletions(-) create mode 100644 examples/server_container.toml create mode 100644 kanidm_book/src/frequently_asked_questions.md create mode 100644 kanidm_book/src/troubleshooting.md create mode 100644 kanidm_book/src/troubleshooting/curl_connection_test.txt diff --git a/examples/server_container.toml b/examples/server_container.toml new file mode 100644 index 000000000..3272b3aaa --- /dev/null +++ b/examples/server_container.toml @@ -0,0 +1,96 @@ +# 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. +# 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: +# [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 DNS domain name of the server. This is used in a +# number of security-critical contexts +# such as webauthn, so it *must* match your DNS +# 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 +# including but not limited to webauthn, oauth tokens, and more. +# If you change this value you *must* run +# `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 +# it is non-standard (any port except 443). This must match +# or be a descendent of the +# 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 available features +# and how replication may interact. +# Valid roles are: +# - WriteReplica +# 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. +# - ReadOnlyReplica +# This server will not writes initiated by clients. It +# 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/) +# every day at 22:00 UTC (default) +# schedule = "00 22 * * *" +# four times a day at 3 minutes past the hour, every 6th hours +# schedule = "03 */6 * * *" +# Number of backups to keep (default 7) +# versions = 7 +# \ No newline at end of file diff --git a/kanidm_book/src/SUMMARY.md b/kanidm_book/src/SUMMARY.md index fcaff9caa..804ed2c32 100644 --- a/kanidm_book/src/SUMMARY.md +++ b/kanidm_book/src/SUMMARY.md @@ -16,6 +16,8 @@ - [SSH Key Distribution](ssh_key_dist.md) - [The Recycle Bin](recycle_bin.md) - [Why TLS?](why_tls.md) +- [Frequently Asked Questions](frequently_asked_questions.md) +- [Troubleshooting](troubleshooting.md) # Integrations @@ -42,4 +44,3 @@ - [Packaging](packaging.md) - [Debian/Ubuntu](packaging_debs.md) - diff --git a/kanidm_book/src/accounts_and_groups.md b/kanidm_book/src/accounts_and_groups.md index 36d17f80a..3eb6a97a1 100644 --- a/kanidm_book/src/accounts_and_groups.md +++ b/kanidm_book/src/accounts_and_groups.md @@ -54,7 +54,8 @@ to be "recovered" from the server that is running the kanidmd server. {{#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. + title=Warning! + text=The server must not be running at this point, as it requires exclusive access to the database. }} ```shell @@ -131,7 +132,8 @@ kanidm account person update demo_user --legalname "initial name" --mail "initia {{#template templates/kani-warning.md imagepath=images - text=Warning: Persons may change their own displayname, name, and legal name at any time. You MUST NOT use these values as primary keys in external systems. You MUST use the `uuid` attribute present on all entries as an external primary key. + title=Warning! + text=Persons may change their own displayname, name, and legal name at any time. You MUST NOT use these values as primary keys in external systems. You MUST use the `uuid` attribute present on all entries as an external primary key. }} ## Resetting Person Account Credentials diff --git a/kanidm_book/src/choosing_a_domain_name.md b/kanidm_book/src/choosing_a_domain_name.md index 276f9f06e..a06e8c804 100644 --- a/kanidm_book/src/choosing_a_domain_name.md +++ b/kanidm_book/src/choosing_a_domain_name.md @@ -6,11 +6,9 @@ is not simple as there are a number of considerations you need to be careful of. {{#template templates/kani-warning.md - imagepath=images + imagepath=images/ title=Take note! - text=Incorrect choice of the domain name *may* have security impacts on your Kanidm instance, not - limited to credential phishing, theft, session leaks and more. It is critical you follow this advice - in this chapter! + text=Incorrect choice of the domain name may have security impacts on your Kanidm instance, not limited to credential phishing, theft, session leaks and more. It is critical you follow the advice in this chapter. }} ## Considerations diff --git a/kanidm_book/src/developers/designs/rest_interface.md b/kanidm_book/src/developers/designs/rest_interface.md index dad57108b..542f5bd6d 100644 --- a/kanidm_book/src/developers/designs/rest_interface.md +++ b/kanidm_book/src/developers/designs/rest_interface.md @@ -1,9 +1,8 @@ # REST Interface - {{#template ../../templates/kani-warning.md - imagepath=../../images + 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/frequently_asked_questions.md b/kanidm_book/src/frequently_asked_questions.md new file mode 100644 index 000000000..1d81af46b --- /dev/null +++ b/kanidm_book/src/frequently_asked_questions.md @@ -0,0 +1,19 @@ +# Frequently Asked Questions + +... or ones we think people *might* ask. + +## Why so many crabs? + +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! + +## Why do the crabs have knives? + +Don't [ask](https://www.youtube.com/watch?v=0QaAKi0NFkA). They just [do](https://www.youtube.com/shorts/WizH5ae9ozw). + +## Why won't you take this FAQ thing seriously? + +Look, people just haven't asked many questions yet. \ No newline at end of file diff --git a/kanidm_book/src/intro.md b/kanidm_book/src/intro.md index 6647692c0..c7776718b 100644 --- a/kanidm_book/src/intro.md +++ b/kanidm_book/src/intro.md @@ -9,8 +9,7 @@ The intent of the Kanidm project is to: * Enable integrations to systems and services so they can authenticate accounts. * Make system, network, application and web authentication easy and accessible. - - {{#template +{{#template templates/kani-warning.md imagepath=images title=NOTICE diff --git a/kanidm_book/src/server_configuration.md b/kanidm_book/src/server_configuration.md index b16127c80..06984f8bd 100644 --- a/kanidm_book/src/server_configuration.md +++ b/kanidm_book/src/server_configuration.md @@ -4,105 +4,11 @@ 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. - # 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. - # 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: - # [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 DNS domain name of the server. This is used in a - # number of security-critical contexts - # such as webauthn, so it *must* match your DNS - # 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 - # including but not limited to webauthn, oauth tokens, and more. - # If you change this value you *must* run - # `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 - # it is non-standard (any port except 443). This must match - # or be a descendent of the - # 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 available features - # and how replication may interact. - # Valid roles are: - # - WriteReplica - # 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. - # - ReadOnlyReplica - # This server will not writes initiated by clients. It - # 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/) - # every day at 22:00 UTC (default) - # schedule = "00 22 * * *" - # four times a day at 3 minutes past the hour, every 6th hours - # schedule = "03 */6 * * *" - # Number of backups to keep (default 7) - # versions = 7 - # +``` +{{#rustdoc_include ../../examples/server_container.toml}} +``` - -An example is located in [examples/server.toml](https://github.com/kanidm/kanidm/blob/master/examples/server.toml). +This example is located in [examples/server_container.toml](https://github.com/kanidm/kanidm/blob/master/examples/server_container.toml). {{#template templates/kani-warning.md diff --git a/kanidm_book/src/troubleshooting.md b/kanidm_book/src/troubleshooting.md new file mode 100644 index 000000000..ef83fbbe5 --- /dev/null +++ b/kanidm_book/src/troubleshooting.md @@ -0,0 +1,62 @@ +# Troubleshooting + +Some things to try. + +## Is the server started? + +If you don't see "ready to rock! 🪨" in your logs, it's not started. Scroll back and look for errors!dd + +## Can you connect? + +If the server's running on `idm.example.com:8443` then a simple connectivity test is done using [curl](https://curl.se). + +Run the following command: +```shell +curl -k https://idm.example.com:8443/status +``` + +This is similar to what you *should* see: + +```shell +{{#rustdoc_include troubleshooting/curl_connection_test.txt}} +``` + +This means: + +1. you've successfully connected to a host (10.0.0.14), +2. TLS worked +3. Received the status response "true" + +If you see something like this: + +``` +➜ curl -v https://idm.example.com:8443 +* Trying 10.0.0.1:8443... +* connect to 10.0.0.1 port 8443 failed: Connection refused +* Failed to connect to idm.example.com port 8443 after 5 ms: Connection refused +* Closing connection 0 +curl: (7) Failed to connect to idm.example.com port 8443 after 5 ms: Connection refused +``` + +Then either your DNS is wrong (it's pointing at 10.0.0.1) or you can't connect to the server for some reason. + +If you get errors about certificates, try adding `-k` to skip certificate verification checking and just test connectivity: + +``` +curl -vk https://idm.example.com:8443 +``` + +## Server things to check + +* Has the config file got `bindaddress = "127.0.0.1:8443"` ? Change it to `bindaddress = "[::]:8443"`, so it listens on all interfaces. +* Is there a firewall on the server? +* If you're running in docker, did you expose the port? (`-p 8443:8443`) + +## Client things to check + +Try running commands with `RUST_LOG=debug` to get more information: + +``` +RUST_LOG=debug kanidm login --name anonymous +``` + diff --git a/kanidm_book/src/troubleshooting/curl_connection_test.txt b/kanidm_book/src/troubleshooting/curl_connection_test.txt new file mode 100644 index 000000000..9d725fe5e --- /dev/null +++ b/kanidm_book/src/troubleshooting/curl_connection_test.txt @@ -0,0 +1,40 @@ +➜ curl -vk https://idm.example.com:8443/status +* Trying 10.0.0.14:8443... +* Connected to idm.example.com (10.0.0.14) port 8443 (#0) +* successfully set certificate verify locations: +* CAfile: /etc/ssl/cert.pem +* CApath: none +* (304) (OUT), TLS handshake, Client hello (1): +* (304) (IN), TLS handshake, Server hello (2): +* TLSv1.2 (IN), TLS handshake, Certificate (11): +* TLSv1.2 (IN), TLS handshake, Server key exchange (12): +* TLSv1.2 (IN), TLS handshake, Server finished (14): +* TLSv1.2 (OUT), TLS handshake, Client key exchange (16): +* TLSv1.2 (OUT), TLS change cipher, Change cipher spec (1): +* TLSv1.2 (OUT), TLS handshake, Finished (20): +* TLSv1.2 (IN), TLS change cipher, Change cipher spec (1): +* TLSv1.2 (IN), TLS handshake, Finished (20): +* SSL connection using TLSv1.2 / ECDHE-ECDSA-AES256-GCM-SHA384 +* Server certificate: +* subject: C=AU; ST=Queensland; L=Brisbane; O=INSECURE EXAMPLE; OU=kanidm; CN=idm.example.com +* start date: Sep 20 09:28:18 2022 GMT +* expire date: Oct 21 09:28:18 2022 GMT +* SSL certificate verify result: self signed certificate in certificate chain (19), continuing anyway. +> GET /status HTTP/1.1 +> Host: idm.example.com:8443 +> User-Agent: curl/7.79.1 +> Accept: */* +> +* Mark bundle as not supporting multiuse +< HTTP/1.1 200 OK +< cache-control: no-store, max-age=0 +< content-length: 4 +< content-type: application/json +< date: Tue, 20 Sep 2022 11:52:23 GMT +< pragma: no-cache +< set-cookie: kanidm-session=+LQJKwL0UdAEMoTc0Zrgne2hU+N2nB+Lcf+J1OoI9n4%3DNE7xuL9yCq7B0Ai+IM3gq5T+YZ0ckDuDoWZKzhPMHmSk3oFSscp9vy9n2a5bBFjWKgeNwdLzRbYc4rvMqYi11A%3D%3D; HttpOnly; SameSite=Strict; Secure; Path=/; Expires=Wed, 21 Sep 2022 11:52:23 GMT +< x-content-type-options: nosniff +< x-kanidm-opid: 8b25f050-7f6e-4ce1-befe-90be3c4f8a98 +< +* Connection #0 to host localhost left intact +true \ No newline at end of file