Enroll examples

Local safe-mode baseline

Harvest the current host, validate the bundle, generate Ansible, install requirements, and run a check-mode playbook.

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

Remote host through SSH config

Use an OpenSSH config alias while still passing --remote-host. The harvested bundle lands locally.

$ enroll harvest \
  --remote-host production-web-1 \
  --remote-ssh-config ~/.ssh/config \
  --out /tmp/enroll-web-1
$ enroll manifest --harvest /tmp/enroll-web-1 --out /tmp/enroll-web-1-ansible --host web-1.example.net

Encrypted SSH key in CI

Provide a key passphrase through an environment variable for non-interactive remote harvesting.

$ export ENROLL_SSH_KEY_PASSPHRASE='correct horse battery staple'
$ enroll single-shot \
  --remote-host host.example.net \
  --remote-user admin \
  --ssh-key-passphrase-env ENROLL_SSH_KEY_PASSPHRASE \
  --harvest /tmp/enroll-harvest \
  --out /tmp/enroll-ansible \
  --host host.example.net

Include and exclude paths

Add targeted files outside the standard scan paths while keeping safe-mode secret checks enabled.

$ enroll harvest --out /tmp/enroll-harvest \
  --include-path '/home/*/.bashrc' \
  --include-path 're:^/home/[^/]+/\.config/myapp/.*$' \
  --exclude-path '/home/*/.config/myapp/cache/**'

Dangerous harvest, encrypted at rest

When you deliberately need aggressive capture, encrypt the harvest bundle immediately.

$ enroll harvest \
  --out /srv/enroll/host-1 \
  --dangerous \
  --sops 54A91143AE0AB4F7743B01FE888ED1B423A3BC99

This writes an encrypted harvest.tar.gz.sops rather than a plaintext bundle directory.

Encrypted manifest bundle

Generate Ansible into a temporary directory, tar it, and encrypt it as one SOPS file.

$ enroll manifest \
  --harvest /srv/enroll/host-1/harvest.tar.gz.sops \
  --out /srv/enroll/host-1-manifest \
  --sops 54A91143AE0AB4F7743B01FE888ED1B423A3BC99

$ cd /srv/enroll/host-1-manifest
$ sops -d manifest.tar.gz.sops | tar -xzvf -
$ cd manifest

One project for multiple hosts

Create the project with the first harvest, then extend it with the second. Host values go in inventory. Identical files remain in shared roles; differing files move into per-host inventory storage. Run these commands outside the output directory.

$ enroll manifest --harvest /tmp/web1.harvest --host web1.example.net --out /tmp/enroll-ansible
$ enroll manifest --harvest /tmp/web2.harvest --host web2.example.net --out /tmp/enroll-ansible --extend
$ cd /tmp/enroll-ansible
$ ansible-galaxy collection install -r requirements.yml
$ ansible-playbook -i inventory/hosts.yml playbook.yml --limit web1.example.net --check

Targeted Ansible role runs

Generated playbooks tag roles as role_<name>, so you can run only a subset. Choose a role present in your generated playbook.

$ ansible-playbook -i "localhost," -c local /tmp/enroll-ansible/playbook.yml --tags role_users

Drift report for cron or CI

Ignore routine version churn while still catching package additions/removals, service changes, user changes, and file drift.

$ enroll diff \
  --old /srv/enroll/baseline \
  --new /srv/enroll/current \
  --format json \
  --ignore-package-versions \
  --exclude-path /var/anacron \
  --exit-code

Webhook notification

Send the diff report when changes are detected. Use --notify-always when a heartbeat is useful.

$ enroll diff \
  --old /srv/enroll/baseline \
  --new /srv/enroll/current \
  --webhook https://example.net/hooks/enroll \
  --webhook-format json \
  --webhook-header 'X-Enroll-Secret: xxxx'

Explain a harvest

Use explain when you want to understand why Enroll included or skipped things.

$ enroll explain /tmp/enroll-harvest
$ enroll explain /tmp/enroll-harvest --format json --max-examples 25

Validate with a pinned schema

CI can validate a harvested bundle against a local schema file and fail on warnings.

$ enroll validate /srv/enroll/current \
  --schema ./state.schema.json \
  --format json \
  --out validate.json \
  --fail-on-warnings