142 lines
7.6 KiB
HTML
142 lines
7.6 KiB
HTML
---
|
|
title: "Examples"
|
|
html_title: "Enroll Examples"
|
|
description: "Copy/paste recipes for Enroll: one host, fleets, drift detection, and safe storage."
|
|
---
|
|
<header class="py-5 hero">
|
|
<div class="container py-3">
|
|
<div class="kicker mb-3"><i class="bi bi-terminal"></i> Examples</div>
|
|
<h1 class="display-6 fw-bold mb-2">Copy/paste recipes</h1>
|
|
<p class="lead mb-0">Practical flows you can adapt to your environment.</p>
|
|
</div>
|
|
</header>
|
|
|
|
<main class="py-5">
|
|
<div class="container">
|
|
|
|
<div class="row g-4">
|
|
<div class="col-lg-6">
|
|
<div class="feature-card p-4 h-100">
|
|
<div class="fw-semibold mb-2">Enroll a single host (local)</div>
|
|
<div class="codeblock terminal">
|
|
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#ex-single-local"><i class="bi bi-clipboard"></i> Copy</button>
|
|
<pre class="mb-0"><code id="ex-single-local"><span class="prompt">$</span> enroll harvest --out /tmp/enroll-harvest
|
|
<span class="prompt">$</span> enroll manifest --harvest /tmp/enroll-harvest \
|
|
--out /tmp/enroll-ansible
|
|
<span class="prompt">$</span> ansible-playbook -i "localhost," -c local \
|
|
/tmp/enroll-ansible/playbook.yml --diff --check</code></pre>
|
|
</div>
|
|
<p class="small text-secondary mt-2 mb-0">Great for "make this box reproducible" or building a golden role set.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="col-lg-6">
|
|
<div class="feature-card p-4 h-100">
|
|
<div class="fw-semibold mb-2">Enroll a remote host (over SSH)</div>
|
|
<div class="codeblock terminal">
|
|
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#ex-remote"><i class="bi bi-clipboard"></i> Copy</button>
|
|
<pre class="mb-0"><code id="ex-remote"><span class="prompt">$</span> enroll harvest \
|
|
--remote-host myhost.example.com \
|
|
--remote-user myuser \
|
|
--out /tmp/enroll-harvest
|
|
<span class="prompt">$</span> enroll manifest \
|
|
--harvest /tmp/enroll-harvest \
|
|
--out /tmp/enroll-ansible</code></pre>
|
|
</div>
|
|
<p class="small text-secondary mt-2 mb-0">No need to manually run commands on the server - your bundle lands locally. If your remote user needs a password for sudo, pass in <code>--ask-become-pass</code> or <code>-K</code>, just like in Ansible. If you don't want to use sudo, pass <code>--no-sudo</code>, but your harvest may contain less data.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="col-lg-6">
|
|
<div class="feature-card p-4 h-100">
|
|
<div class="fw-semibold mb-2">Fleets: multi-site output</div>
|
|
<div class="codeblock terminal">
|
|
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#ex-multisite"><i class="bi bi-clipboard"></i> Copy</button>
|
|
<pre class="mb-0"><code id="ex-multisite"><span class="prompt">$</span> fqdn="$(hostname -f)"
|
|
<span class="prompt">$</span> enroll single-shot --remote-host "$fqdn" \
|
|
--remote-user myuser \
|
|
--out /tmp/enroll-ansible \
|
|
--fqdn "$fqdn"
|
|
<span class="prompt">$</span> ansible-playbook "/tmp/enroll-ansible/playbooks/${fqdn}.yml"</code></pre>
|
|
</div>
|
|
<p class="small text-secondary mt-2 mb-0">Shared roles + host inventory keeps one host's differences from breaking another.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="col-lg-6">
|
|
<div class="feature-card p-4 h-100">
|
|
<div class="fw-semibold mb-2">Drift detection with <code>enroll diff</code></div>
|
|
<div class="codeblock terminal">
|
|
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#ex-diff"><i class="bi bi-clipboard"></i> Copy</button>
|
|
<pre class="mb-0"><code id="ex-diff"><span class="prompt">$</span> enroll diff --old /path/to/harvestA --new /path/to/harvestB --format markdown --exclude-path /var/anacron --ignore-package-versions
|
|
<span class="prompt">$</span> enroll diff --old /path/to/golden --new /path/to/current \
|
|
--webhook https://example.net/webhook \
|
|
--webhook-format json \
|
|
--webhook-header 'X-Enroll-Secret: ...' \
|
|
--ignore-package-versions --exit-code
|
|
</code></pre>
|
|
</div>
|
|
<p class="small text-secondary mt-2 mb-0">Use it in cron or CI to alert on change.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="col-lg-6">
|
|
<div class="feature-card p-4 h-100">
|
|
<div class="fw-semibold mb-2">Explain a harvest with <code>enroll explain</code></div>
|
|
<div class="codeblock terminal">
|
|
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#ex-explain"><i class="bi bi-clipboard"></i> Copy</button>
|
|
<pre class="mb-0"><code id="ex-explain"><span class="prompt">$</span> enroll explain /tmp/enroll-harvest
|
|
|
|
# machine-readable (reasons, examples, inventory breakdown)
|
|
<span class="prompt">$</span> enroll explain /tmp/enroll-harvest --format json | jq .
|
|
|
|
# encrypted bundle
|
|
<span class="prompt">$</span> enroll explain /var/lib/enroll/harvest.tar.gz.sops --sops</code></pre>
|
|
</div>
|
|
<p class="small text-secondary mt-2 mb-0">Great for answering "why did it include/exclude that file?" before you generate a manifest.</p>
|
|
</div>
|
|
</div>
|
|
|
|
<div class="col-lg-6">
|
|
<div class="feature-card p-4 h-100">
|
|
<div class="fw-semibold mb-2">Enforce the previous state with <code>enroll diff --enforce</code></div>
|
|
<div class="codeblock terminal">
|
|
<button class="btn btn-sm btn-outline-secondary copy-btn" data-copy-target="#ex-diff"><i class="bi bi-clipboard"></i> Copy</button>
|
|
<pre class="mb-0"><code id="ex-diff"><span class="prompt">$</span> enroll diff \
|
|
--old /path/to/harvestA \
|
|
--new /path/to/harvestB \
|
|
--enforce \
|
|
--format json
|
|
</code></pre>
|
|
</div>
|
|
<p class="small text-secondary mt-2 mb-0">Enforcing the old harvest will restore its files/perms, missing packages, changed services or users, if <code>ansible-playbook</code> is on the PATH.</p>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
<hr class="my-5">
|
|
|
|
<div class="row g-4">
|
|
<div class="col-lg-6">
|
|
<div class="callout p-4 h-100">
|
|
<div class="fw-semibold mb-2"><i class="bi bi-shield-check"></i> Safe harvesting (default)</div>
|
|
<p class="small text-secondary mb-3">Enroll tries to avoid harvesting files that might contain secrets. If you need to capture "everything", pass <code>--dangerous</code> and treat the output as sensitive.</p>
|
|
<p class="small text-secondary mb-3">You can still control what gets collected and what doesn't by using <code>--include</code> and <code>--exclude</code> flags.</p>
|
|
<div class="terminal"><pre class="mb-0"><code><span class="prompt">$</span> enroll harvest --dangerous --out /tmp/enroll-harvest</code></pre></div>
|
|
</div>
|
|
</div>
|
|
<div class="col-lg-6">
|
|
<div class="callout p-4 h-100">
|
|
<div class="fw-semibold mb-2"><i class="bi bi-lock"></i> Encrypt bundles at rest (SOPS)</div>
|
|
<p class="small text-secondary mb-3">Produce a single encrypted file for harvest and/or manifest output (requires SOPS to be installed).</p>
|
|
<p class="small text-secondary mb-3">This is especially a good idea if you are using <code>--dangerous</code>, which might sweep up secrets (see above).</p>
|
|
<div class="terminal"><pre class="mb-0"><code><span class="prompt">$</span> enroll harvest --dangerous --out /tmp/harvest \
|
|
--sops <FINGERPRINT>
|
|
<span class="prompt">$</span> enroll manifest --harvest /tmp/harvest/harvest.tar.gz.sops \
|
|
--out /tmp/enroll-ansible --sops <FINGERPRINT></code></pre></div>
|
|
</div>
|
|
</div>
|
|
</div>
|
|
|
|
</div>
|
|
</main>
|