Skip to content

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 baseline means an official EDH release. dev self-baseline means a development build, see the note below.
  • DEVIATIONS: the number of files that differ from the release. unexplained counts the files that are MODIFIED or MISSING, 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 reports NOT_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 MISSING file records that it is expected to be absent. If the file reappears, it is reported as MODIFIED.
  • Acknowledgements are recorded per host.
  • Acknowledgements never lower the DEVIATIONS total: support always sees how many files differ from the release. To see the report as if no acknowledgement existed, add --ignore-acknowledgements to verify.

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.