From 1b34b2a8baf6a7203861d2a54ab3722a29c7c002 Mon Sep 17 00:00:00 2001
From: Firstyear
docker run --rm -i -t -v kanidmd:/data opensuse/leap:latest /bin/sh
--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:
- -You can fetch these by running the commands:
-docker pull kanidm/server:latest
-docker pull kanidm/radius:latest
+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 = "[::]: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 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"
+#
+#
+# [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
+#
+#
+# The role of this server. This affects features available 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 it's data.
+# Defaults to "WriteReplica".
+# role = "WriteReplica"
-If you wish to use an x86_64 cpu-optimised version (See System Requirements CPU), you should use:
-docker pull kanidm/server:x86_64_latest
+An example is located in 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 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
-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.
-cmov, cx8, fxsr, mmx, sse, sse2, cx16, sahf, popcnt, sse3, sse4.1, sse4.2, avx, avx2,
-bmi, bmi2, f16c, fma, lzcnt, movbe, xsave
+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
-Older or unsupported CPU's may raise a SIGIL (Illegal Instruction) on hardware that is not supported
-by the project.
-In this case, you should use the standard server:latest image.
-In the future we may apply a baseline of flags as a requirement for x86_64 for the server:latest
-image. These flags will be:
-cmov, cx8, fxsr, mmx, sse, sse2
+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
-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
-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.
-For best performance, you should use NVME or other Flash media.
-TLS
-You'll need a volume where you can place configuration, certificates, and the database:
-docker volume create kanidmd
-
-You should have a chain.pem and key.pem in your kanidmd volume. The reason for requiring
-TLS is explained in 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:
------BEGIN RSA PRIVATE KEY-----
-MII...<base64>
------END RSA PRIVATE KEY-----
-
-The chain.pem is a series of PEM formatted certificates. The leaf certificate, or the certificate
-that matches the private key should be the first certificate in the file. This should be followed
-by the series of intermediates, and the final certificate should be the CA root. For example:
------BEGIN CERTIFICATE-----
-<leaf certificate>
------END CERTIFICATE-----
------BEGIN CERTIFICATE-----
-<intermediate certificate>
------END CERTIFICATE-----
-[ more intermediates if needed ]
------BEGIN CERTIFICATE-----
-<ca/croot certificate>
------END CERTIFICATE-----
-
-
-HINT
-If you are using Let's Encrypt the provided files "fullchain.pem" and "privkey.pem" are already
-correctly formatted as required for Kanidm.
-
-You can validate that the leaf certificate matches the key with the command:
-# openssl rsa -noout -modulus -in key.pem | openssl sha1
-d2188932f520e45f2e76153fbbaf13f81ea6c1ef
-# openssl x509 -noout -modulus -in chain.pem | openssl sha1
-d2188932f520e45f2e76153fbbaf13f81ea6c1ef
-
-If your chain.pem contains the CA certificate, you can validate this file with the command:
-openssl verify -CAfile chain.pem chain.pem
-
-If your chain.pem does not contain the CA certificate (Let's Encrypt chains do not contain the CA
-for example) then you can validate with this command.
-openssl verify -untrusted fullchain.pem fullchain.pem
-
-
-NOTE Here "-untrusted" flag means a list of further certificates in the chain to build up
-to the root is provided, but that the system CA root should be consulted. Verification is NOT bypassed
-or allowed to be invalid.
-
-If these verifications pass you can now use these certificates with Kanidm. To put the certificates
-in place you can use a shell container that mounts the volume such as:
-docker run --rm -i -t -v kanidmd:/data -v /my/host/path/work:/work opensuse/leap:latest /bin/sh -c "cp /work/* /data/"
-
-OR for a shell into the volume:
-docker run --rm -i -t -v kanidmd:/data opensuse/leap:latest /bin/sh
-
-Continue on to Configuring the Server
Security Hardening
Kanidm ships with a secure-by-default configuration, however that is only as strong
as the platform that Kanidm operates in. This could be your container environment
@@ -1158,7 +1137,7 @@ relying more on the Kanidm query and filter system than attempting to generate a
representation of data. As almost all clients can use filters for entry selection
we don't believe this is a limitation for consuming applications.
Security
-TLS
+TLS
StartTLS is not supported due to security risks. LDAPS is the only secure method
of communicating to any LDAP server. Kanidm if configured with certificates will
use them for LDAPS (and will not listen on a plaintext LDAP port). If no certificates exist
diff --git a/docs/radius.html b/docs/radius.html
index 2fa6643b2..8afdbd0d2 100644
--- a/docs/radius.html
+++ b/docs/radius.html
@@ -82,7 +82,7 @@
diff --git a/docs/recycle_bin.html b/docs/recycle_bin.html
index 2a7cc7dd6..d565a58e5 100644
--- a/docs/recycle_bin.html
+++ b/docs/recycle_bin.html
@@ -82,7 +82,7 @@
diff --git a/docs/rustdoc/settings.html b/docs/rustdoc/settings.html
index d0ab44bbb..e80e258ea 100644
--- a/docs/rustdoc/settings.html
+++ b/docs/rustdoc/settings.html
@@ -1,4 +1,4 @@
Rustdoc settings
-Rustdoc settings
Theme preferencesUse system themePreferred dark themePreferred light theme
- Auto-hide item contents for large items.Auto-hide item methods' documentationAuto-hide trait implementation documentationAuto-hide implementors of a traitDirectly go to item in search if there is only one resultShow line numbers on code examplesDisable keyboard shortcuts
\ No newline at end of file
+Rustdoc settings
Theme preferencesUse system themePreferred dark themePreferred light theme
+ Auto-hide item contents for large items.Auto-hide item methods' documentationAuto-hide trait implementation documentationAuto-hide implementors of a traitDirectly go to item in search if there is only one resultShow line numbers on code examplesDisable keyboard shortcuts