Skip to main content

​
Common log locations

journalctl -u himmelblaud --no-pager
journalctl -u himmelblaud-tasks --no-pager

​
Enable verbose logging

Add debug = true to /etc/himmelblau/himmelblau.conf and restart both daemons: 
[global]
debug = true

sudo systemctl restart himmelblaud himmelblaud-tasks

​
Issues

Check that both daemons are running:
sudo systemctl status himmelblaud himmelblaud-tasks
Check that a domain is configured:
cat /etc/himmelblau/himmelblau.conf
The domain option must be set. Without it, no users can authenticate.Check pam_allow_groups:If pam_allow_groups is configured, the user must be a member of one of the listed groups. Verify the user’s group membership in Entra ID matches the configured group GUIDs.Inspect the PAM configuration:Run without --really to perform a dry run and see what changes would be applied:
sudo aad-tool configure-pam
Apply the changes:
sudo aad-tool configure-pam --really
Check that NSS is configured to use Himmelblau:
grep himmelblau /etc/nsswitch.conf
The passwd, group, and shadow lines should include himmelblau, for example:
passwd:     compat systemd himmelblau
group:      compat systemd himmelblau
shadow:     compat systemd himmelblau
Verify nscd is disabled:nscd caches NSS results and will interfere with Himmelblau’s own cache. It must be disabled and masked:
sudo systemctl status nscd
If it is running:
sudo systemctl stop nscd
sudo systemctl disable nscd
sudo systemctl mask nscd
Test daemon connectivity:
sudo aad-tool status
Check network connectivity:Himmelblau must reach login.microsoftonline.com to complete MFA. Verify DNS resolution and outbound HTTPS are working from the host.Check daemon logs for errors:
journalctl -u himmelblaud --no-pager
Look for connection errors or timeout messages.Run an interactive authentication test:
sudo aad-tool auth-test --name user@domain.com
This tests the full authentication path through himmelblaud and shows the MFA challenge interactively. It does not test your PAM configuration — only that the daemon can process authentications correctly.
Check that Hello is enabled in the configuration:
grep -E 'enable_hello|hello_pin' /etc/himmelblau/himmelblau.conf
enable_hello must be true (it is the default). If it was explicitly disabled, re-enable it and restart the daemons.Check the minimum PIN length:The PIN the user set must meet or exceed hello_pin_min_length (default: 6 characters). If the policy was tightened after the PIN was created, the user needs to re-enroll their PIN.Force a full re-authentication:The user can re-authenticate with their password or MFA to re-establish their Hello credentials:
sudo aad-tool auth-test --name user@domain.com --force-reauth
--force-reauth bypasses the cached Hello key and requires a full MFA/password challenge, after which a new Hello key is enrolled.
Mark all cached entries as stale (soft refresh on next use):
sudo aad-tool cache-clear
Clear only the NSS resolution cache:
sudo aad-tool cache-clear --nss
Clear only the mapped name cache:
sudo aad-tool cache-clear --mapped
The following command performs a full cache wipe and unjoins the device from Entra ID. Only use it if you intend to re-enroll the machine.
sudo aad-tool cache-clear --full
Himmelblau ships a SELinux policy module. If you are seeing AVC denials, first check that the policy module is installed:
semodule -l | grep himmelblaud
To diagnose specific denials:
sudo audit2why -a
If the policy module is missing, reinstall the himmelblau package for your distribution. If you encounter denials that are not covered by the shipped policy, please report them upstream so the policy can be updated.

Build docs developers (and LLMs) love

Get started for freeTalk to us