edhctl support verify
edhctl support verify checks whether the EDH code installed on a host still matches the official EDH release it came from. It tells you, file by file, whether anything was changed, removed or added since installation.
Use it when:
- You open a support case. The report shows support whether your cluster runs standard EDH code or a customized version, and its default output is safe to attach to a ticket.
- You want to confirm that nobody changed EDH files on a host, for example as part of a security review.
- You keep your own customizations and want to track them over time.
Run edhctl support verify --help to display the help message.
How it works¶
Each EDH release ships with an integrity manifest: a list of every file in the release along with its unique fingerprint (a SHA-256 hash). verify computes the fingerprint of every installed file and compares it with the manifest.
Each file falls into one of these categories:
| Category | Meaning |
|---|---|
VERIFIED |
The file is identical to the release. |
MODIFIED |
The file content differs from the release. |
MISSING |
The file is part of the release but is not on the host. |
PATCHED |
The file differs from the release because of a patch supplied by EDH. |
ACKNOWLEDGED |
The file differs from the release, and an administrator recorded it as an expected change (see Acknowledge expected changes). |
UNTRACKED |
The file is not part of the release, for example software installed when the host started, or log files. |
On a cluster running unmodified EDH code, MODIFIED and MISSING are both 0.
Checks also run when the controller starts
EDH runs the same check automatically every time the controller starts, before any EDH code runs. You can decide what happens when that check finds changes, see Choose what happens when changes are found.
Run a check¶
Run the command on any EDH host:
./edhctl support verify
EDH integrity check -- edh-demo
Build: 26.8.0 build_type=release git=4be81c2 build_id=4be81c2-9f3a1d
Manifest: present (release baseline)
Target: code (2814 files tracked)
DEVIATIONS: 1 (1 unexplained)
MODIFIED 1
MISSING 0
PATCHED 0
ACKNOWLEDGED 0
MODIFIED
cluster_manager/web_interface/templates/login.html [post-install]
UNTRACKED: 25341
python/ 19876 runtime-installed
cluster_manager/web_interface/static/node_modules/ 4310 runtime-installed
schedulers/ 1102 runtime-installed
<regenerated> 53 runtime-installed
Result: WARN (on_validation_failure=warn)
Target: installer NOT_APPLICABLE
installer/** never reaches a node, so it cannot be verified here. The installer verifies its own tree at startup, on the workstation where that tree exists.
Overall: WARN (2 target(s) run)
Read the report¶
Build: the EDH version and build the host was installed from.Manifest: what the host is compared against.release baselinemeans an official EDH release.dev self-baselinemeans a development build, see the note below.DEVIATIONS: the number of files that differ from the release.unexplainedcounts the files that areMODIFIEDorMISSING, in other words changes that are neither EDH patches nor acknowledged by an administrator.[build-time]/[post-install]: when the change happened.[build-time]means the file was already different when EDH was installed, usually because the installation package was changed before deployment.[post-install]means the file was changed on the running cluster afterwards.UNTRACKED: files that are not part of the release, grouped by folder. Most of these are expected, such as the Python runtime or the job scheduler installed when the host starts.Result: the overall verdict, described below.
Results¶
| Result | Meaning |
|---|---|
PASS |
Everything matches the release, or every difference is explained by an EDH patch or an acknowledgement. |
REVIEW |
No unexplained changes, but files were found outside the expected folders. Review them (see Review unexpected files). |
WARN |
Unexplained changes were found. |
FAIL |
Unexplained changes were found and your cluster is configured to treat them as an error. The command exits with code 1. |
IGNORED |
Your cluster is configured to ignore integrity results. |
NOT_APPLICABLE |
There is nothing to check on this host for that target. |
When several targets run, Overall shows the most serious result among them.
Development builds
If you installed EDH from a development build rather than an official release, EDH creates its own baseline at installation time. The report shows dev self-baseline -- build-time integrity NOT verifiable. In that case verify still detects files changed after installation, but it cannot tell whether the code was changed before installation.
Choose what to check¶
Use --target to choose what to verify:
all(default): run every target and display one section per target.code: the EDH code installed on the host.installer: the EDH installer. The installer only exists on the computer you deployed EDH from and is never copied to cluster hosts, so from a host this target always reportsNOT_APPLICABLE. The installer checks its own files every time you run it.
./edhctl support verify --target code
Share the report with support¶
The default output is designed to be pasted into a support ticket as is:
- It lists file paths and fingerprints, which are already public in the EDH release. It never includes file content.
- Untracked files are only counted per folder. Their names are not listed, because they belong to you and may be sensitive.
For a machine-readable report, use --output json or --output yaml. These formats contain exactly the same information as the text output, nothing more.
./edhctl support verify --output json > integrity-report.json
Export the changes as a patch¶
Support may ask you to show what was changed in the modified files. Use --export-patch to save the differences to a file:
./edhctl support verify --target code --export-patch
...
Patch: /apps/edh/edh-demo/shared/support/integrity-edh-demo-4be81c2-9f3a1d-20261103T093000Z.patch
WARNING: that file contains source code. Review it before sharing. Diff text is derived from this node's own install artifact, not from a trusted baseline.
By default, the patch is saved under /apps/edh/<cluster_id>/shared/support/ with access restricted to its owner. You can also pass a file path, for example --export-patch /root/my-changes.patch. The changes themselves are never displayed on screen.
Review the patch before you share it
Unlike the default report, the patch file contains source code, including any customizations you made. Read it before sending it to anyone.
Review unexpected files¶
Files found outside the expected folders are counted as <unclassified> and turn the result into REVIEW. They are not counted as changes, but they deserve a look, because an unexpected file in the EDH code folder can be a sign of an unwanted change.
UNTRACKED: 25342
...
<unclassified> 1 REVIEW
(paths withheld; re-run with --show-unclassified)
To see their names on your own host, add --show-unclassified:
./edhctl support verify --show-unclassified
Note
--show-unclassified displays file names that may be sensitive. Do not include that output in a support ticket unless you are comfortable sharing those names.
Acknowledge expected changes¶
If you deliberately customized some EDH files, you can record them as expected with edhctl support ack. Acknowledged files are reported as ACKNOWLEDGED instead of MODIFIED, so new, unexpected changes stand out.
# Acknowledge one file, with the reason for the change
./edhctl support ack add cluster_manager/web_interface/templates/login.html \
--reason "Custom company banner on the login page"
# Acknowledge every current unexplained change at once (asks for confirmation)
./edhctl support ack add --all-pending --reason "Approved customizations"
# List acknowledgements on this host
./edhctl support ack list
# Remove an acknowledgement, or all of them
./edhctl support ack remove cluster_manager/web_interface/templates/login.html
./edhctl support ack remove --all
A few things to know:
- An acknowledgement covers the file exactly as it is now. If the file changes again, it goes back to
MODIFIED. - Acknowledging a
MISSINGfile records that it is expected to be absent. If the file reappears, it is reported asMODIFIED. - Acknowledgements are recorded per host.
- Acknowledgements never lower the
DEVIATIONStotal: support always sees how many files differ from the release. To see the report as if no acknowledgement existed, add--ignore-acknowledgementstoverify.
Choose what happens when changes are found¶
The /configuration/Integrity/on_validation_failure setting controls how EDH reacts when the check finds unexplained changes, both in verify and when the controller starts:
| Value | Behavior |
|---|---|
warn (default) |
Report the changes and continue. The controller starts normally. |
exit |
Treat changes as an error. verify reports FAIL and exits with code 1, and a controller with unexplained changes stops its startup. |
ignore |
Do not treat changes as a problem. verify still lists them but reports IGNORED, and the controller starts normally. |
Update it with edhctl config:
./edhctl config set \
--key "/configuration/Integrity/on_validation_failure" \
--value "exit"
exit can prevent the controller from starting
With exit, a controller with unexplained changes stops during startup, which makes the web interface unavailable. Acknowledge your expected customizations first, and run edhctl support verify to confirm the result is PASS before you switch to exit.