Project Atlas AetherDev project hub
Atlas project production

munki_client_configurator

munki-client-configurator is a login-time automation layer that keeps every managed Mac aligned with district policy. It inspects the signed-in users Active Directory OU, maps that context to a Munki ClientIdentifier, patches the local Munki preferences only when necessary, enforces core system/dock defaults, and then refreshes Munki. All actions are logged to /var/log/munki-client-configurator.log so audits are straightforward. It ingests clientid-mapping.json, LaunchDaemon plist, Munki preferences and produces ManagedInstalls ClientIdentifier value, system defaults, log files.

Type
Component
Lifecycle
Active
Last touched
2025-12-12
Visibility
Public

Purpose

munki-client-configurator is a login-time automation layer that keeps every managed Mac aligned with district policy. It inspects the signed-in users Active Directory OU, maps that context to a Munki ClientIdentifier, patches the local Munki preferences only when necessary, enforces core system/dock defaults, and then refreshes Munki. All actions are logged to /var/log/munki-client-configurator.log so audits are straightforward.

Current state

Last touched: 2025-12-12. Functionality and completeness: Full mapping and compliance flow implemented; tests are pending.

Next step

Add baseline automated tests to cover critical flows; Add CI pipeline for build/test/lint; Document deployment/runtime environment (or add Dockerfile); Document interfaces (CLI flags, API endpoints, file formats); Add structured logging and basic health checks.

Interfaces

Inputs
  • clientid-mapping.json, LaunchDaemon plist, Munki preferences
  • Configuration files (TOML/YAML/JSON/INI/CONF)
Outputs
  • ManagedInstalls ClientIdentifier value, system defaults, log files

Reality to Action trace

Reality Ingestion

Contributes in this stage.

Canonical Storage

Not in scope.

Automation Engines

Not in scope.

Human Interfaces

Contributes in this stage.

Operational Adoption

Contributes in this stage.

Core workflow

TBD. Document the 5-10 steps that define the core workflow.

Artifacts

  • Mapping JSON with `ou_map`, `user_map`, `fallback`, `skip_users`, `skip_ous`

Operational notes

Constraints and scars

  • Depends on accurate AD OU mappings and Munki configuration; incorrect mappings can mis-assign ClientIdentifiers.

Reliability posture

Failure modes and safe behavior: Missing mapping files fall back to defaults; Munki failures are logged. Idempotency / retries / batching behavior: Idempotent preference updates; reruns are safe.

Observability

  • Logs: Use UTC timestamps and include the client ID source, previous/new values, and Munki command exit codes. The main log rotates when it exceeds 1 MB (up to three historical copies).
  • Metrics/health checks: None documented; use log files and LaunchDaemon status

Security and privacy

Mapping files and logs include user/OU context; restrict access.

Dependencies

Upstream
  • Active Directory (via dscl), Munki managedsoftwareupdate, optional MDM enrollment checks

Ownership

Owners

Josh Barton

Users

Josh Barton (owner)

munki_client_configurator

Architecture & Major Components

  • High-level diagram (text):

    • Entry/trigger -> core logic -> outputs (details per docs below)

  • Entry points: munki_client_configurator/munki-client-configurator

  • Top-level folders: none (root scripts and JSON/PLIST assets)

  • Key abstractions: ClientIdentifier resolution order, compliance enforcement, Munki refresh orchestration

Setup / Build / Run

  • Build system(s): None (bash script).
  • Install via munki-client-configurator install which deploys the script, mapping JSON, and LaunchDaemon.
  • Requires macOS 11+, Munki installed, and AD binding for OU lookup.