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 --fqdn 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 \
  --fqdn 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

Multi-site output

Use --fqdn when enrolling multiple already-running servers. Host-specific data goes to inventory host vars.

$ fqdn="$(hostname -f)"
$ enroll manifest --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible --fqdn "$fqdn"
$ ansible-playbook /tmp/enroll-ansible/playbooks/"$fqdn".yml --check

Targeted Ansible role runs

Generated playbooks tag roles as role_<name>, so you can run only a subset.

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

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