Server Configuration

In this section we will configure your server and create its container instance.

Configuring server.toml

There are two methods for configuration:

Providing a configuration file in the volume named server.toml. (Within the container it should be /data/server.toml)
Using environment variables to specify configuration options (uppercased, prefixed with KANIDM_).

You can use one or both methods, but environment variables take precedence over options specified in files.The full options and explanations are in the kanidmd_core::config::ServerConfig docs page for your particular build.

warning

You MUST set the domain, origin, tls_chain and tls_path options via one method or the other, or the server cannot start!

The following is a commented example configuration.

#   The webserver bind address. Requires TLS certificates.
#   If the port is set to 443 you may require the
#   NET_BIND_SERVICE capability.
#   Defaults to "127.0.0.1:8443"
bindaddress = "[::]:8443"
#
#   The read-only ldap server bind address. Requires
#   TLS certificates. If set to 636 you may require
#   the NET_BIND_SERVICE capability.
#   Defaults to "" (disabled)
# ldapbindaddress = "[::]:3636"
#
#   HTTPS requests can be reverse proxied by a loadbalancer.
#   To preserve the original IP of the caller, these systems
#   will often add a header such as "Forwarded" or
#   "X-Forwarded-For". If set to true, then this header is
#   respected as the "authoritative" source of the IP of the
#   connected client. If you are not using a load balancer
#   then you should leave this value as default.
#   Defaults to false
# trust_x_forward_for = false
#
#   The path to the kanidm database.
db_path = "/data/kanidm.db"
#
#   If you have a known filesystem, kanidm can tune the 
#   database page size 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 database pagesize to 64k. You must set
#       recordsize=64k on the zfs filesystem.
#   - other:
#     * 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
#   an automatic heuristic is used to scale this.
#   You should only adjust this value if you experience
#   memory pressure on your system.
# db_arc_size = 2048
#
#   TLS chain and key in pem format. Both must be present
tls_chain = "/data/chain.pem"
tls_key = "/data/key.pem"
#
#   The log level of the server. May be one of info, debug, trace
#
#   NOTE: this can be overridden by the environment variable
#   `KANIDM_LOG_LEVEL` at runtime
#   Defaults to "info"
# log_level = "info"
#
#   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 Security 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 rename` 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"
#
[online_backup]
#   The path to the output folder for online backups
path = "/data/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 * * *"
#   We also support non standard cron syntax, with the following format:
#   sec  min   hour   day of month   month   day of week   year
#   (it's very similar to the standard cron syntax, it just allows to specify the seconds
#   at the beginning and the year at the end)
#   Number of backups to keep (default 7)
# versions = 7

This example is located in examples/server_container.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, OAuth2) may not work correctly!

Check the configuration is valid

You should test your configuration is valid before you proceed. This defaults to using -c /data/server.toml. The kanidmd volume was created in the evaluation quickstart

docker run --rm -i -t -v kanidmd:/data \
    kanidm/server:latest /sbin/kanidmd configtest

Run the Server

Now we can run the server so that it can accept connections. The container defaults to using a configuration file in /data/server.toml.

docker run -p 443:8443 -v kanidmd:/data kanidm/server:latest

Using the `NET_BIND_SERVICE` capability

If you plan to run without using docker port mapping or some other reverse proxy, and your bindaddress or ldapbindaddress port is less than 1024 you will need the NET_BIND_SERVICE in docker to allow these port binds. You can add this with --cap-add in your docker run command.

docker run --cap-add NET_BIND_SERVICE \
  --network [host OR macvlan OR ipvlan] \
  -v kanidmd:/data \
  kanidm/server:latest

tip

However you choose to run your server, you should document and keep note of the docker run / create command you chose to start the instance. This will be used in the upgrade procedure.

Default Admin Accounts

Now that the server is running, you can initialise the default admin accounts. There are two parallel admin accounts that have separate functions. admin which manages Kanidm's configuration, and idm_admin which manages accounts and groups in Kanidm.

You should consider these as "break-glass" accounts. They exist to allow the server to be bootstrapped and accessed in emergencies. They are not intended for day-to-day use.

These commands will generate a new random password for the admin accounts. You must run the commands as the same user as the kanidmd process or as root. This defaults to using -c /data/server.toml.

docker exec -i -t <container name> \
  kanidmd recover-account admin
#  new_password: "xjgG4..."

docker exec -i -t <container name> \
  kanidmd recover-account idm_admin
#  new_password: "9Eux1..."