--- title: "Enroll" html_title: "Enroll - Turn existing Linux hosts into Ansible" description: "Enroll harvests real Linux host state and renders Ansible configuration-management output. Documentation for current 0.7 beta behavior." og_title: "Enroll - Turn existing Linux hosts into Ansible" og_description: "Harvest real Linux host state and render reviewable Ansible roles/playbooks." og_type: "website" ---

Current 0.7 beta documentation

Turn a real Linux host into reviewable Ansible.

Enroll inspects Debian-like and RedHat-like machines, writes a harvest bundle (state.json plus artifacts), then renders Ansible roles and playbooks from that snapshot.

Quickstart Read docs Security model

Harvest → Manifest Local or remote over SSH Optional SOPS bundles Ansible output

The core workflow

dry-run before applying

$ enroll harvest --out ./harvest
$ enroll validate ./harvest
$ enroll manifest --harvest ./harvest --out ./ansible
$ cd ./ansible
$ ansible-galaxy collection install -r requirements.yml
$ ansible-playbook -i localhost, -c local playbook.yml --check --diff

Trust boundary: validation proves structure and artifact consistency, not semantic safety. Only apply manifests generated from harvests whose provenance you trust.

What Enroll does today

Enroll is a migration and recovery helper. It gives you a generated Ansible starting point from a machine that already exists; it does not prove that the machine is well designed, compliant, or safe to replicate.

Current output target

The public CLI renders Ansible. The codebase has an internal renderer-neutral model, but the documented user-facing manifest output is Ansible roles, playbooks, inventory, variables, files, templates, handlers, and a generated README.md.

Harvest

Collect package, service, user, file, runtime, Flatpak/Snap, and container-image evidence into a private bundle.

Validate

Check state.json, the vendored JSON schema, referenced artifacts, and orphaned files before rendering or CI use.

Manifest

Freeze the harvest, warn about semantic trust, then render Ansible. Use --fqdn for inventory-driven multi-host output.

Diff, explain, notify

Compare harvests, suppress noisy package-version or path drift, produce text/Markdown/JSON, and optionally send webhooks or email.

Quickstart paths

Choose the shape that matches the job: one host, remote harvest, or a shared multi-host Ansible tree.

More examples

enroll harvest --out ./harvest
enroll manifest --harvest ./harvest --out ./ansible
cd ./ansible
ansible-playbook -i localhost, -c local playbook.yml --check --diff

enroll harvest --remote-host app01.example.net --remote-user mig --out ./harvest
# Use -K / --ask-become-pass when remote sudo needs a password.
enroll manifest --harvest ./harvest --out ./ansible

host=app01.example.net
enroll single-shot --remote-host "$host" --remote-user mig \
  --harvest "./harvest-$host" --out ./ansible-site --fqdn "$host"
cd ./ansible-site
ansible-playbook -i inventory/hosts.ini "playbooks/${host}.yml" --check --diff

enroll diff --old ./harvest-golden --new ./harvest-current \
  --format markdown --ignore-package-versions --exclude-path /var/anacron

Single-site by default

Without --fqdn, Enroll renders self-contained roles where role files live under roles/<role>/files and variables live in defaults/main.yml.

Multi-site with `--fqdn`

With --fqdn, shared role tasks stay reusable while host-specific files and variables live under inventory/host_vars/<fqdn>. --fqdn implies one-role-per-package/unit behavior.

Security-first rendering

Directory harvests are frozen into private temp copies before use, artifact paths are no-follow validated, and harvested Jinja-looking values are emitted as Ansible !unsafe data.