packaging: Add kanidmd deb package, update documentation (#3506)

* packaging: Use cargo-deb multiarch support

This allows building all platforms from one definition,
assuming the --multiarch=foreign flag is used.

* packaging: Use correct path naming for unixd service files

While cargo-deb works around the mistake, better to name them as per the
rules: https://github.com/kornelski/cargo-deb/blob/main/systemd.md#systemd-unit-file-naming

* docs: Update book chapter on Debian packaging

* packaging: Shift Debian builds to a separate build profile

* packaging: Add deb for kanidmd

book/src/packaging/debian_ubuntu_packaging.md

@@ -5,57 +5,45 @@
 - Debian packaging is complex enough that it lives in a separate repository:
 [kanidm/kanidm_ppa_automation](https://github.com/kanidm/kanidm_ppa_automation).
 - While official packages are available at https://kanidm.github.io/kanidm_ppa/ these instructions will guide you
-through replicating the same process locally, using [cross](https://github.com/cross-rs/cross) & Docker to isolate the build process
+through replicating the same process locally, using Docker to isolate the build process from your normal computer.
-from your normal computer and allow building packages for multiple architectures.
+- Due to the complexity of crosscompilation, we no longer support it and recommend building natively,
+i.e. on the platform you're targeting.
 - While the examples below will use `aarch64-unknown-linux-gnu` aka `arm64`,
 the same process works for `x86_64-unknown-linux-gnu` aka `amd64` as well.
 
 1. Start in the root directory of the main [kanidm/kanidm](https://github.com/kanidm/kanidm) repository.
-1. Install cross:
-   ```shell
-   cargo install cross
-   ```
 1. Pull in the separate deb packaging submodule:
    ```shell
    git submodule update platform/debian/kanidm_ppa_automation
    ```
-1. Launch your desired crossbuild target. Do note the script assumes you use rustup!
-   ```shell
-   # See valid targets:
-   platform/debian/kanidm_ppa_automation/scripts/crossbuild.sh
-   # Launch a target:
-   platform/debian/kanidm_ppa_automation/scripts/crossbuild.sh debian-12-aarch64-unknown-linux-gnu
-   # You can also specify multiple targets within the same distribution:
-   platform/debian/kanidm_ppa_automation/scripts/crossbuild.sh debian-12-{aarch64,x86_64}-unknown-linux-gnu
-   ```
-1. Go get a drink of your choice while the build completes.
 1. Create a sacrificial deb builder container to avoid changing your own system:
    ```shell
-   docker run --rm -it -e CI=true \
+   docker run --rm -it -e VERBOSE=true -e CI=true \
        --mount "type=bind,src=$PWD,target=/src" \
        --workdir /src \
        rust:bookworm
    ```
 1. In the container install dependencies with:
    ```shell
-   # The parameter given is which additional target debian architecture to enable (amd64, arm64, etc.)
+   platform/debian/kanidm_ppa_automation/scripts/install_ci_build_dependencies.sh
-   # If your native platform is amd64, running with arm64 is enough to cover both archs.
-   platform/debian/kanidm_ppa_automation/scripts/install_ci_build_dependencies.sh arm64
    ```
-1. In the container launch the deb build:
+1. Launch your desired target build:
+   ```shell
+   platform/debian/kanidm_ppa_automation/scripts/build_native.sh aarch64-unknown-linux-gnu
+   ```
+1. Go get a drink of your choice while the build completes.
+1. Launch the deb build:
    ```shell
    platform/debian/kanidm_ppa_automation/scripts/build_debs.sh aarch64-unknown-linux-gnu
-   # Again, multiple targets also work:
-   platform/debian/kanidm_ppa_automation/scripts/build_debs.sh {aarch64,x86_64}-unknown-linux-gnu
    ```
 1. You can now exit the container, the package paths displayed at the end under `target` will
    persist.
 
 ## Adding or amending a deb package
-The rough overview of steps is:
+The rough overview of steps is as follows, see further down for details.
 1. Add cargo-deb specific metadata to the rust package and any static assets. Submit your changes as
    a PR.
-2. Add build instructions to the separate packaging repo. Submit your changes as a PR.
+2. Add build steps to the separate packaging repo. Submit your changes as a PR.
 3. Go back to the main repo to update the packaging submodule reference to aid running manual dev
    builds of the new package.
 
@@ -72,8 +60,8 @@ an example, see `unix_integration/resolver/Cargo.toml`
 ### Configuration in the kanidm_ppa_automation repo
 - The repo is: [kanidm/kanidm_ppa_automation](https://github.com/kanidm/kanidm_ppa_automation)
 - Changes are needed if a new binary and/or package is added, or if build time dependencies change.
-- Amend `scripts/crossbuild.sh` build rules to include new binaries or packages with shared
+- Amend `scripts/build_native.sh` build rules to include new binaries or packages with shared
-libraries. Search for the lines starting with `cross build`.
+libraries.
 - Add any new build time system dependencies to `scripts/install_ci_build_dependencies.sh`, be aware
   of any difference in package names between Debian & Ubuntu.
 - Add any new packages to `scripts/build_debs.sh`, search for the line starting with `for package in`.

libs/profiles/release_debian.toml

@@ -0,0 +1,14 @@
+# The main difference from the release_linux profile is using
+# per-package shared directories for a clearer separation and 
+# thus more consistent install & sysadmin experience.
+
+# Don't set the value for autodetect
+# cpu_flags = "none"
+server_admin_bind_path = "/var/run/kanidmd/sock"
+server_ui_pkg_path = "/usr/share/kanidmd/static"
+server_config_path = "/etc/kanidmd/server.toml"
+client_config_path = "/etc/kanidm/config"
+# TODO: unixd should migrate to it's own config dir as part of the sparkled migration.
+# No point in doing two back to back migrations.
+resolver_config_path = "/etc/kanidm/unixd"
+resolver_unix_shell_path = "/bin/bash"

server/daemon/Cargo.toml

@@ -57,6 +57,31 @@ clap = { workspace = true, features = ["derive"] }
 clap_complete = { workspace = true }
 kanidm_build_profiles = { workspace = true }
 
+## Debian packaging
+[package.metadata.deb]
+name = "kanidmd"
+maintainer = "James Hodgkinson <james@terminaloutcomes.com>"
+# Can't use $auto depends because the name of libssl3 varies by distro and version
+depends = [
+	"libc6",
+	"tpm-udev",
+	"libssl3 | libssl3t64",
+]
+section = "network"
+priority = "optional"
+changelog = "../../target/debian/changelog"  # Generated by platform/debian/build_debs.sh
+assets = [
+    [ "target/release/kanidmd", "usr/bin/", "755" ],
+  	[ "debian/group.conf", "usr/lib/sysusers.d/kandimd.conf", "644" ],
+    [ "debian/server.toml", "etc/kanidmd/server.toml", "640" ],
+    [ "../../examples/server.toml", "usr/share/kanidmd/", "444" ],
+    [ "../core/static/**/*", "usr/share/kanidmd/static", "444" ],
+]
+maintainer-scripts = "debian/"
+systemd-units = [
+	{ unit-name = "kanidmd", enable = false},  # Cannot start without manual config
+]
+
 
 [package.metadata.cargo-machete]
 ignored = ["clap_complete", "kanidm_build_profiles"]

server/daemon/debian/group.conf

@@ -0,0 +1,2 @@
+# This is a sysusers.d format config, please refer to man sysusers.d(5)
+g kanidmd -

server/daemon/debian/kanidmd.service

@@ -10,13 +10,15 @@ Before=radiusd.service
 [Service]
 Type=notify
 DynamicUser=yes
-StateDirectory=kanidm
+User=kanidmd_dyn
+Group=kanidmd
+StateDirectory=kanidmd
 StateDirectoryMode=0750
 CacheDirectory=kanidmd
 CacheDirectoryMode=0750
 RuntimeDirectory=kanidmd
 RuntimeDirectoryMode=0755
-ExecStart=/usr/sbin/kanidmd server -c /etc/kanidm/server.toml
+ExecStart=/usr/bin/kanidmd server
 
 AmbientCapabilities=CAP_NET_BIND_SERVICE
 CapabilityBoundingSet=CAP_NET_BIND_SERVICE

server/daemon/debian/postinst

@@ -0,0 +1,38 @@
+#!/bin/sh
+# postinst script for kanidmd
+#
+# see: dh_installdeb(1)
+
+set -e
+
+
+case "$1" in
+    configure)
+        echo "Creating the kanidmd group for config & cert ownership..."
+        systemd-sysusers
+        echo "Fixing ownership of server configuration ..."
+        chown :kanidmd /etc/kanidmd/server.toml*
+
+        echo "============================="
+        echo "Thanks for installing Kanidm!"
+        echo "============================="
+        echo "Please ensure you modify the configuration file at /etc/kanidmd/server.toml"
+        echo "Only then: systemctl enable kanidmd.service"
+        echo "Full examples are in /usr/share/kanidmd/"
+    ;;
+
+    abort-upgrade|abort-remove|abort-deconfigure)
+    ;;
+
+    *)
+        echo "postinst called with unknown argument \`$1'" >&2
+        exit 1
+    ;;
+esac
+
+# dh_installdeb will replace this with shell code automatically
+# generated by other debhelper scripts.
+
+#DEBHELPER#
+
+exit 0

server/daemon/debian/server.toml

@@ -0,0 +1,51 @@
+# Kanidm server minimal configuration - /etc/kanidm/server.toml
+# For a full example and documentation, see /usr/share/kanidmd/server.toml
+# or `example/server.toml` in the source repository
+
+# NOTE: You must configure at least domain & origin below to allow the server to start!
+
+#   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 = "127.0.0.1:8443"
+
+#   The path to the kanidm database.
+#   The provided example uses systemd dynamic user pathing for security
+db_path = "/var/lib/private/kanidmd/kanidm.db"
+
+#   TLS chain and key in pem format. Both must be present.
+#   If the server receives a SIGHUP, these files will be
+#   re-read and reloaded if their content is valid.
+#   These should be owned by root:kanidmd to give the service access.
+tls_chain = "/etc/kanidmd/chain.pem"
+tls_key = "/etc/kanidmd/key.pem"
+
+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
+#
+#   ⚠️  WARNING ⚠️
+#
+#   Changing this value after first use 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.
+# NOTE: You must set this value!
+#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"
+# NOTE: You must set this value!
+#origin = "https://idm.example.com:8443"
+
+[online_backup]
+path = "/var/lib/private/kanidmd/backups/"
+schedule = "00 22 * * *"

unix_integration/nss_kanidm/Cargo.toml

@@ -27,8 +27,6 @@ lazy_static = { workspace = true }
 cc = "^1.2.10"
 
 ## Debian packaging
-# The base metadata does **not** work to build a functioning package!
-# A target specific variant must be used to get the right multiarch path.
 [package.metadata.deb]
 name = "libnss-kanidm"
 maintainer = "James Hodgkinson <james@terminaloutcomes.com>"
@@ -36,27 +34,13 @@ depends = ""
 section = "network"
 priority = "optional"
 assets = [
-    # Empty on purpose
-]
-
-[package.metadata.deb.variants.aarch64-unknown-linux-gnu]
-merge-assets.append = [
     [
         "target/release/libnss_kanidm.so",
-        "usr/lib/aarch64-linux-gnu/libnss_kanidm.so.2",
+        # This is not the final path as cargo-deb needs to be run with --multiarch=foreign
+        "usr/lib/libnss_kanidm.so.2",
         "644",
     ],
 ]
 
-[package.metadata.deb.variants.x86_64-unknown-linux-gnu]
-merge-assets.append = [
-    [
-        "target/release/libnss_kanidm.so",
-        "usr/lib/x86_64-linux-gnu/libnss_kanidm.so.2",
-        "644",
-    ],
-]
-
-
 [package.metadata.cargo-machete]
 ignored = ["cc", "lazy_static"]

unix_integration/pam_kanidm/Cargo.toml

@@ -27,8 +27,6 @@ time = { workspace = true }
 pkg-config = { workspace = true }
 
 ## Debian packaging
-# The base metadata does **not** work to build a functioning package!
-# A target specific variant must be used to get the right multiarch path.
 [package.metadata.deb]
 name = "libpam-kanidm"
 maintainer = "James Hodgkinson <james@terminaloutcomes.com>"
@@ -37,28 +35,10 @@ section = "network"
 priority = "optional"
 maintainer-scripts = "debian/"
 assets = [
-    # Empty on purpose
-]
-
-[package.metadata.deb.variants.aarch64-unknown-linux-gnu]
-merge-assets.append = [
     [
         "target/release/libpam_kanidm.so",
-        "usr/lib/aarch64-linux-gnu/security/pam_kanidm.so",
+        # This is not the final path as cargo-deb needs to be run with --multiarch=foreign
-        "644",
+        "usr/lib/security/pam_kanidm.so",
-    ],
-    [
-        "debian/kanidm.pam",
-        "usr/share/pam-configs/kanidm",
-        "644",
-    ],
-]
-
-[package.metadata.deb.variants.x86_64-unknown-linux-gnu]
-merge-assets.append = [
-    [
-        "target/release/libpam_kanidm.so",
-        "usr/lib/x86_64-linux-gnu/security/pam_kanidm.so",
         "644",
     ],
     [