diff --git a/book/src/packaging/debian_ubuntu_packaging.md b/book/src/packaging/debian_ubuntu_packaging.md index b5ef68203..6220d6f42 100644 --- a/book/src/packaging/debian_ubuntu_packaging.md +++ b/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 -from your normal computer and allow building packages for multiple architectures. +through replicating the same process locally, using Docker to isolate the build process from your normal computer. +- 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.) - # 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 + platform/debian/kanidm_ppa_automation/scripts/install_ci_build_dependencies.sh ``` -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 -libraries. Search for the lines starting with `cross build`. +- Amend `scripts/build_native.sh` build rules to include new binaries or packages with shared +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`. diff --git a/libs/profiles/release_debian.toml b/libs/profiles/release_debian.toml new file mode 100644 index 000000000..f951ccb54 --- /dev/null +++ b/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" diff --git a/server/daemon/Cargo.toml b/server/daemon/Cargo.toml index 4f4b385cd..b42692677 100644 --- a/server/daemon/Cargo.toml +++ b/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"] diff --git a/server/daemon/debian/group.conf b/server/daemon/debian/group.conf new file mode 100644 index 000000000..0e9682c15 --- /dev/null +++ b/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 - diff --git a/server/daemon/debian/daemon.kanidmd.service b/server/daemon/debian/kanidmd.service similarity index 89% rename from server/daemon/debian/daemon.kanidmd.service rename to server/daemon/debian/kanidmd.service index 12c512fce..8187e5758 100644 --- a/server/daemon/debian/daemon.kanidmd.service +++ b/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 diff --git a/server/daemon/debian/postinst b/server/daemon/debian/postinst new file mode 100644 index 000000000..157c90df1 --- /dev/null +++ b/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 diff --git a/server/daemon/debian/server.toml b/server/daemon/debian/server.toml new file mode 100644 index 000000000..4869671b8 --- /dev/null +++ b/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 * * *" diff --git a/unix_integration/nss_kanidm/Cargo.toml b/unix_integration/nss_kanidm/Cargo.toml index 4d84cfe1e..a6f979c28 100644 --- a/unix_integration/nss_kanidm/Cargo.toml +++ b/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"] diff --git a/unix_integration/pam_kanidm/Cargo.toml b/unix_integration/pam_kanidm/Cargo.toml index fab00724f..6757c72d3 100644 --- a/unix_integration/pam_kanidm/Cargo.toml +++ b/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", - "644", - ], - [ - "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", + # This is not the final path as cargo-deb needs to be run with --multiarch=foreign + "usr/lib/security/pam_kanidm.so", "644", ], [ diff --git a/unix_integration/resolver/debian/kanidm_unix_int.kanidm-unixd-tasks.service b/unix_integration/resolver/debian/kanidm-unixd-tasks.service similarity index 100% rename from unix_integration/resolver/debian/kanidm_unix_int.kanidm-unixd-tasks.service rename to unix_integration/resolver/debian/kanidm-unixd-tasks.service diff --git a/unix_integration/resolver/debian/kanidm_unix_int.kanidm-unixd.service b/unix_integration/resolver/debian/kanidm-unixd.service similarity index 100% rename from unix_integration/resolver/debian/kanidm_unix_int.kanidm-unixd.service rename to unix_integration/resolver/debian/kanidm-unixd.service