Skip to content
Frostyard docs

Himmelblau

The Himmelblau extension lets a Frostyard machine sign in users with Microsoft Entra ID: console and GDM logins, SSH with MFA, a Hello PIN, a TPM-bound device identity, Intune compliance checks, Kerberos tickets, and browser single sign-on. Use it on a machine that your organization manages in Entra ID. Every image carries the extension’s definition, switched off. The extension itself is not in the image: Updex turns it on and downloads it.

Before you start

Section titled “Before you start”

You need:

  • A Frostyard bootc image. Every image built on Base has systemd-sysext and frostyard-updex.
  • Root access to enable, update, and remove the extension.
  • Network access to https://repository.frostyard.org/ext/himmelblau/.
  • Free space in /var for the image.
  • An Entra ID sign-in domain, such as example.com.
  • This extension works on server and desktop images, so Floe can use it too.

Himmelblau has no published test results on Frostyard images yet. Try it on a machine you can spare first.

Enable Himmelblau

Section titled “Enable Himmelblau”

See what Updex found, then enable the feature and download it now:

Terminal window
updex features list --component=himmelblau
sudo updex features enable himmelblau --now

himmelblau appears as a component, with its feature disabled. The enable command downloads the image, checks its checksum and signature, links it, and refreshes the merge.

Check the merge and the tools that the extension adds:

Terminal window
systemd-sysext status
command -v snosi-himmelblau-setup aad-tool
systemctl status himmelblau-sysext-setup.service

systemd-sysext status lists himmelblau, both names print a path, and himmelblau-sysext-setup.service is active (exited).

himmelblaud.service does not run yet. It starts only after the machine has a configuration, as the next section shows.

If enable --now exits with a refresh error (refresh_error in JSON), the download worked, but the activation did not. If the output says activation did not finish, the extension is merged, but users and groups can be missing: reboot. Otherwise the merge state is unknown: reboot. A sudo systemd-sysext refresh by hand does not create users and groups. Then run the checks above again.

Configure Himmelblau

Section titled “Configure Himmelblau”

Set the domain. Choose --hsm-type now if you want something other than the default, because changing it later forces a reset (see Troubleshooting):

Terminal window
sudo snosi-himmelblau-setup --domain example.com

Run the tool with no arguments on a terminal for prompts instead. It writes /etc/himmelblau/himmelblau.conf.d/50-snosi-setup.conf, restarts himmelblaud and himmelblaud-tasks, and prints aad-tool status.

Check the result:

Terminal window
sudo snosi-himmelblau-setup --show
sudo aad-tool status

--show prints the drop-in, and aad-tool status shows that the daemon is reachable and online.

Re-running the tool keeps earlier settings unless you override them. You can add a --map later without repeating --domain. The tool rewrites only 50-snosi-setup.conf. Put your own overrides in a separate /etc/himmelblau/himmelblau.conf.d/*.conf file.

Option Effect
--domain DOMAIN Entra ID sign-in domain
--map LOCAL=UPN Make an existing local account sign in through Entra ID under its current username. Repeatable. Writes /etc/himmelblau/user-map
--join-type join|register Device registration mode. The upstream default is join
--hsm-type TYPE tpm_bound_soft_if_possible (default), tpm, or tpm_if_possible
--allow-groups LIST Only these group object IDs or UPNs can sign in. The default is all users
--sudo-groups LIST Group object IDs that get local sudo
--enable-hello, --disable-hello Windows Hello PIN enrollment
--apply-policy, --no-apply-policy Intune enrollment and compliance checks. On by default. Off breaks tenants that require a compliant device
--set KEY=VALUE, --unset KEY Any other [global] option from himmelblau.conf(5)
--no-restart Write the configuration only

Sign in with an Entra ID account:

  • At the GDM login screen, choose Not listed? and enter the UPN, such as user@example.com.
  • Over SSH, run ssh 'user@example.com'@host and complete the MFA prompt.

Check a sign-in:

Terminal window
sudo aad-tool auth-test user@example.com
klist

A mapped local account keeps its username. Its local password no longer applies.

At boot, himmelblau-sysext-setup.service adds himmelblau to /etc/nsswitch.conf, turns on the PAM profile with pam-auth-update, lets GDM’s pam_gnome_keyring reuse the Hello PIN, and makes /etc/krb5.conf include /etc/krb5.conf.d. It only adds lines and never deletes. The tool runs the same step after it writes your configuration. sudo snosi-etc-diff lists nsswitch.conf and pam.d/common-* as modified. That is expected.

On first start, himmelblau-hsm-pin-init.service creates the HSM PIN and seals it with systemd-creds, bound to the TPM when one is available. sudo aad-tool tpm shows whether the PIN is TPM-bound.

For browser single sign-on, log out and back in after the first merge, so your session sees the new broker service. Firefox needs the linux-entra-sso extension. Chromium and Chrome get it through the managed policy in /etc/chromium/policies/managed/himmelblau.json. SSO from a local account needs a --map entry.

The extension also adds Office 365 launchers (/usr/bin/o365 and an Outlook desktop entry) and the Kerberos tools kinit and klist.

Update, roll back, and remove

Section titled “Update, roll back, and remove”

Check for an update, then install it:

Terminal window
updex features check --component=himmelblau
sudo updex features update --component=himmelblau

Updex downloads and verifies the new image, switches the link, deletes older versions, and refreshes the merge. See Manage system extensions for --no-vacuum, --dry-run, and the update timer. The refresh swaps /usr under the running system.

Roll back with sudo updex features rollback himmelblau. It takes effect at the next boot. See Roll back.

Remove Himmelblau:

Terminal window
sudo updex features disable himmelblau --now --force

Updex unmerges all extensions on the host, deletes the image, and merges the rest again. Reboot when the command finishes. Without --force, Updex refuses while the image is merged.

The edits in /etc stay: the himmelblau entries in /etc/nsswitch.conf and the PAM profile. glibc and PAM ignore them when the modules are gone. To clean them up:

Terminal window
sudo snosi-etc-diff --restore /etc/nsswitch.conf
sudo pam-auth-update --remove himmelblau

Your configuration in /etc/himmelblau stays. Device state stays in /var/lib/private/himmelblaud and /var/cache/himmelblaud.

Troubleshooting

Section titled “Troubleshooting”
Symptom Check Fix
himmelblaud.service says condition not met ls /etc/himmelblau/himmelblau.conf.d/ Run sudo snosi-himmelblau-setup --domain example.com. The daemon stays off until a domain is configured.
Logins fail with user unknown getent passwd user@example.com If nothing returns, run sudo /usr/lib/himmelblau/himmelblau-sysext-setup and read its journal.
SSH never asks for MFA sshd -T | grep -i kbdinteractive It must print yes. The setting comes from /etc/ssh/sshd_config.d/30-himmelblau.conf.
Browsers say the device must be registered, and the journal shows AADSTS530003 grep apply_policy /etc/himmelblau/himmelblau.conf.d/50-snosi-setup.conf Keep apply_policy = true. Lock the screen and sign in again, so enrollment runs. Then run aad-tool compliance-check.
Browser SSO loops through PIN prompts, and journalctl --user -u himmelblau-broker repeats Silent PRT SSO cookie unavailable Check whether you use a plain local account Run sudo snosi-himmelblau-setup --map LOCAL=UPN and aad-tool cache-clear. Then sign out and back in through Entra ID.
himmelblaud fails with Unable to load machine root key ... IncorrectKeyType Whether you changed --hsm-type after the first start Stop himmelblaud, delete /var/cache/private/himmelblaud/himmelblau.cache.db, and start it again. The device registers again and a Hello PIN must be enrolled again. Choose the HSM type before the first sign-in.

For more detail, read the journal: journalctl -u himmelblaud -u himmelblaud-tasks -u himmelblau-sysext-setup -b.

What ships

Section titled “What ships”
Item What you get
Package requests himmelblau, nss-himmelblau, pam-himmelblau, himmelblau-sshd-config, himmelblau-broker, himmelblau-sso, himmelblau-sso-policies, o365, krb5-user
Not included himmelblau-qr-greeter and himmelblau-apparmor
Tools aad-tool, snosi-himmelblau-setup, kinit, klist, o365
Settings /etc/himmelblau/himmelblau.conf.d/50-snosi-setup.conf and /etc/himmelblau/user-map, written by the setup tool
Placed in /etc from /usr/share/factory/etc krb5.conf, ssh/sshd_config.d/30-himmelblau.conf, and the Chromium and Chrome native-messaging host and managed policy files
Version The image file name carries the himmelblau package version, plus a +rN snosi revision when one is set
Image file himmelblau_<version>_<os>_<arch>.raw.zst; .raw.xz, .raw.gz, and .raw also work
Download From https://repository.frostyard.org/ext/himmelblau/, signature required (Verify=true), into /var/lib/extensions.d/
Services himmelblau-sysext-setup.service (started at boot), himmelblaud.service (starts once a configuration exists), himmelblaud-tasks.service, himmelblau-hsm-pin-init.service; user units himmelblau-broker.service and himmelblau-compliance-check.timer

The image is built on Base, so it works on server and desktop images. Each build checks the daemons, the NSS and PAM modules, the broker, the SSO host, the launchers, the setup tools, the units, and every factory file that tmpfiles places in /etc. A build that is missing one fails.

himmelblau-qr-greeter is left out because it needs gnome-shell. himmelblau-apparmor is left out because it ships only /etc/apparmor.d.

See also

Section titled “See also”

Sources

Section titled “Sources”

Reviewed 2026-10-27; Updex facts reviewed 2026-10-30. snosi commit b2858ca0222814c395cf8248db98f3e096d57dc9; Updex v2.1.3 commit 2661e987faac986f2594d1d9bbbadf1bf3053f5b.