From 418fc7e4ef41c3b814564a5a3d46fefabe6b7c93 Mon Sep 17 00:00:00 2001 From: Miguel Jacq Date: Sat, 3 Jan 2026 15:16:51 +1100 Subject: [PATCH] Doc updates --- src/docs.html | 43 ++++++++++++++++++++++++++++++++++++++++++- src/index.html | 9 ++++----- 2 files changed, 46 insertions(+), 6 deletions(-) diff --git a/src/docs.html b/src/docs.html index 5d21c77..73276be 100644 --- a/src/docs.html +++ b/src/docs.html @@ -60,6 +60,7 @@
Mental model + How harvesting works Single-site vs multi-site Remote harvesting JinjaTurtle templates @@ -123,6 +124,40 @@
+
+

How harvesting works

+

At a high level, this is what happens when enroll harvest runs on a host:

+ +
    +
  • Detects the OS and its package backend (e.g dpkg vs rpm)
    • +
  • Detects what packages are installed
    • +
  • For each package, it tries to detect files in /etc that have been modified from the default that get shipped with the package.
    • +
  • It detects running/enabled services and timers via systemd. For each of these, it looks for the unit files, any 'drop-in' files, environment variable files, etc, as well as what executable it executes, and tries to map those systemd services to the packages it's already learned about earlier (that way, those 'packages' or future Ansible roles, can also be associated with 'handlers' in Ansible, to handle restart of the services if/when the configs change)
    • +
  • Aside from known packages already learned, it optimistically tries to capture extra system configuration in /etc that is common for config management. This is stuff like the apt or dnf configuration, crons, logrotate configs, networking settings, hosts files, etc.
    • +
  • It also looks for other snowflake stuff in /etc not associated with packages/services or other typical system config, and will put these into an etc_custom role.
    • +
  • Likewise, it looks in /usr/local for stuff, on the assumption that this is an area that custom apps/configs might've been placed in. These go into a usr_local_custom role.
    • +
  • It captures non-system user accounts, their group memberships and their .ssh/authorized_keys
    • +
  • It takes into account anything the user set with --exclude-path or --include-path. For anything extra that is included, it will put these into an 'extra_paths' role. The location could be anywhere e.g something in /opt, /srv, whatever you want.
    • +
  • It writes the state.json and captures the artifacts.
    • +
+
+

Other things to be aware of:

+
    +
  • You can use multiple invocations of --exclude-path to skip the bits you don't want. You also can always comment out from the playbook.yml or delete certain roles it generates once you've run the enroll manifest.
    • +
  • In terms of safety measures: it doesn't traverse symlinks, and it has an 'IgnorePolicy' that makes it ignore most binary files (except GPG binary keys used with apt) - though if you specify certain paths with --include-path and use --dangerous, it will skip some policy statements such as what types of content to ignore.
    • +
  • It will skip files that are too large, and it also currently has a hardcoded cap of the number of files that it will harvest (4000 for /etc, /usr/local/etc and /usr/local/bin, and 500 files per 'role'), to avoid unintentional 'runaway' situations.
    • +
+ +
+
Does Enroll use Ansible community/galaxy roles?
+
No, Enroll doesn't have any knowledge of Ansible Galaxy roles or community plugins. It generates all the roles itself. If you really want to use roles from the community, Enroll may not be the tool for you, other than perhaps to help get you started.
+
+
Keep in mind that a lot of software config files are also good candidates for being Jinja templates with abstracted vars for separate hosts.
+
+
Enroll does use my companion tool JinjaTurtle if it's installed, but JinjaTurtle only recognises certain types of files (.ini style, .json, .xml, .yaml, .toml, but not special ones like Nginx or Apache conf files which have their own special syntax). When Enroll can't turn a config file into a template, it copies the raw file instead and uses it with ansible.builtin.copy in role tasks.
+
+
+

Single-site vs multi-site

Manifest output has two styles. Choose based on how you'll use the result.

@@ -164,7 +199,13 @@

Run Enroll on your workstation, harvest a remote host over SSH. The harvest is pulled locally.

$ enroll harvest --remote-host myhost.example.com --remote-user myuser --out /tmp/enroll-harvest
-$ enroll single-shot --remote-host myhost.example.com --remote-user myuser --out /tmp/enroll-ansible --fqdn myhost.example.com
+$ enroll manifest --harvest /tmp/enroll-harvest --out /tmp/enroll-manifest + +# Alternatively, run both commands combined together with the 'single-shot' mode: + +$ enroll single-shot --remote-host myhost.example.com --remote-user myuser \ + --harvest /tmp/enroll-harvest --out /tmp/enroll-ansible \ + --fqdn myhost.example.com
Tip
diff --git a/src/index.html b/src/index.html index d5323b3..7bb41fd 100644 --- a/src/index.html +++ b/src/index.html @@ -276,8 +276,7 @@ enroll diff \
Harvest
Collect state into a bundle.
-
-
+
@@ -296,7 +295,7 @@ enroll diff \
Single-shot
-
One command → workable output.
+
Harvest → Manifest in one command.
@@ -305,7 +304,7 @@ enroll diff \
Diff
-
Drift report + notifications.
+
Drift report + webhook/email notifications.
@@ -352,7 +351,7 @@ sudo apt install enroll sudo tee /etc/yum.repos.d/mig5.repo > /dev/null << 'EOF' [mig5] name=mig5 Repository -baseurl=https://rpm.mig5.net/rpm/$basearch +baseurl=https://rpm.mig5.net/$releasever/rpm/$basearch enabled=1 gpgcheck=1 repo_gpgcheck=1