mart-w/kanidm
1
0
Fork 0
mirror of https://github.com/kanidm/kanidm.git synced 2025-02-23 20:47:01 +01:00
Code Issues Actions Packages Projects Releases Wiki Activity

First review of the Kanidm Administration book (#760)

Browse source
This commit is contained in:
Carla Schroder 2022-05-17 18:22:56 -07:00 committed by GitHub
parent c8a1b7b605
commit 6114d59158
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
3 changed files with 59 additions and 38 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

8
kanidm_book/src/installing_the_server.md
View file

@ -1,6 +1,6 @@
# Installing the Server
> **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.
> **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 if you prefer this option.
Currently we have docker images for the server components. They can be found at:
@ -33,7 +33,7 @@ If you are using the x86\_64 cpu-optimised version, you must have a CPU that is
cmov, cx8, fxsr, mmx, sse, sse2, cx16, sahf, popcnt, sse3, sse4.1, sse4.2, avx, avx2,
bmi, bmi2, f16c, fma, lzcnt, movbe, xsave
Older or unsupported CPU's may raise a SIGIL (Illegal Instruction) on hardware that is not supported
Older or unsupported CPUs 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.
@ -53,7 +53,7 @@ You should expect to see 64KB of ram per entry in your database, depending on ca
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.
For best performance, you should use non-volatile memory express (NVME), or other Flash storage media.
## TLS
@ -62,7 +62,7 @@ You'll need a volume where you can place configuration, certificates, and the da
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](./why_tls.md). In summary, TLS is our root of trust between the
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.
The key.pem should be a single PEM private key, with no encryption. The file content should be

12
kanidm_book/src/intro.md
View file

@ -15,13 +15,13 @@ The intent of the Kanidm project is to:
## Library documentation
Looking for the `rustdoc` documentation for the libraries themselves? [Click here!](./rustdoc/master/kanidm/)
Looking for the `rustdoc` documentation for the libraries themselves? [Click here!](https://kanidm.com/documentation/)
## Why do I want Kanidm?
Whether you work in a business, a volunteer organisation, or are an enthusiast who manages
their personal services, we need methods of authenticating and identifying ourselves
to these systems and subsequently, ways to determine what authorisation and privileges we have
their personal services, you need methods of authenticating and identifying
to your systems, and subsequently, ways to determine what authorisation and privileges you have
while accessing these systems.
We've probably all been in workplaces where you end up with multiple accounts on various
@ -79,8 +79,8 @@ many devices and credentials with different privileges. An example of how this l
└──────────┘
A key design goal is that you authenticate with your device in some manner, and then your device will
continue to authenticate you in the future. Each of these different types of credential from SSH keys,
application passwords, RADIUS passwords and others, are "things your device knows". Each password
continue to authenticate you in the future. Each of these different types of credentials, from SSH keys,
application passwords, to RADIUS passwords and others, are "things your device knows". Each password
has limited capability, and can only access that exact service or resource.
This helps improve security; a compromise of the service or the network transmission does not
@ -90,4 +90,4 @@ specific service is compromised, only the credentials for that service need to b
Due to this model, and the design of Kanidm to centre the device and to have more per-service credentials,
workflows and automation are added or designed to reduce human handling. An example of this
is the use of QR codes with deployment profiles to automatically enrol wireless credentials.
is the use of QR codes with deployment profiles to automatically enroll wireless credentials.

77
kanidm_book/src/server_configuration.md
View file

@ -2,76 +2,97 @@
### Configuring server.toml
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:
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.
# 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.
# 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:
# 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
# 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 sqlite pagesize to 64k. You must set
# recordsize=64k on the zfs filesystem.
# - other:
# * sets sqlite pagesize to 4k, matching most filesystems block sizes.
# * 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
# 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 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
# 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 what 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 spn's throughout the topology.
# 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
# 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.
# 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"
# 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 features available and how replication may interact.
# 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
# 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.
# 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.
# 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/
# 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