Himmelblau runs as two cooperating systemd services. Both must be running for authentication to work.
| Service | Purpose |
|---|
himmelblaud | Main daemon. Handles all authentication requests from the PAM and NSS modules. |
himmelblaud-tasks | Tasks daemon. Handles background operations: home directory creation, Intune policy application, token refresh, Kerberos credential management, and subUID/subGID allocation. |
Starting and stopping
Enable and start both services on boot:
sudo systemctl enable --now himmelblaud himmelblaud-tasks
sudo systemctl restart himmelblaud himmelblaud-tasks
sudo systemctl status himmelblaud himmelblaud-tasks
Viewing logs
Print recent logs from both services:
journalctl -u himmelblaud -u himmelblaud-tasks --no-pager
journalctl -u himmelblaud -f
Debug logging
To enable verbose logging, set debug = true in /etc/himmelblau/himmelblau.conf:
When set to true, debug messages are written to the system journal. Restart both daemons after changing this option.
Alternatively, set the RUST_LOG environment variable before starting the daemon manually:
RUST_LOG=debug himmelblaud
Debug logs may contain sensitive information (tokens, authentication data). Redact them before sharing in bug reports.
Checking daemon health
Use aad-tool status to verify the daemon is reachable and responding:
This checks that himmelblaud is online and able to connect to the Entra ID endpoint.
Cache management
Use aad-tool cache-clear to manage the local authentication cache.
| Flag | Effect |
|---|
| (none) | Marks all cached user and group entries as stale, forcing a refresh on next use. |
--nss | Clears only the NSS resolution cache (/var/cache/nss-himmelblau/cache.db). |
--mapped | Clears only the mapped name cache (/var/cache/nss-himmelblau/mapping.cache.db). |
--full | Completely purges all cache entries and unjoins the host from Entra ID. This is irreversible. |
# Invalidate all cached entries (soft refresh)
sudo aad-tool cache-clear
# Clear the NSS cache only
sudo aad-tool cache-clear --nss
# Clear the mapped name cache only
sudo aad-tool cache-clear --mapped
# Full wipe and unjoin (destructive)
sudo aad-tool cache-clear --full
--full unjoins the device from Entra ID. You will need to re-enroll the machine afterwards.
Socket paths
The daemons communicate with the PAM and NSS modules over Unix domain sockets. Default locations:
| Socket | Path |
|---|
| Main daemon | /var/run/himmelblaud/socket |
| Tasks daemon | /var/run/himmelblaud/task_sock |
| Broker | /var/run/himmelblaud/broker_sock |
himmelblau.conf via the socket_path, task_socket_path, and broker_socket_path options. 