Linux migration / Engineering resource
Linux migration parity reports explained: promises, coverage and unknowns
A migration parity report asks whether the observed target fulfills a defined set of translated promises. It is not a bitwise clone comparison and not a blanket statement that the application works. Read source coverage, the migration plan, target observations and optional validation lanes together: an equivalent plan can coexist with unresolved source items or unverified application behavior.
01Follow the evidence chain from source to verdict
Start with the source inventory: what was actually discovered and what access or parsing limitations affected it? Virtual Move’s attestation records source and target releases, translated canonicals and target packages, graded confidence, unresolved packages, untranslated canonicals, manual steps and caveats. Those are inputs to review, not background details to ignore once a report exists.
Next inspect the translated migration plan and attestation: what does the rebuild promise to carry, replace or intentionally omit? Finally compare the prepared target with those promises. The relationship is source inventory → translated plan/attestation → observed target → scoped verdict. Package names, paths and service mechanisms may intentionally change across distributions. Literal byte equality of the entire source and target would reject legitimate modernization and still would not establish business correctness.
02Separate plan parity from source completeness
A promise can hold on the target even when a source package never obtained a vetted translation. Review unresolved and untranslated items in the migrate attestation, plus conditionals that could not be evaluated and manual runbook steps. The official attestation documentation says unknown predicates become caveats and unavailable mappings remain untranslated rather than guessed. Review what was discovered as well as what reached the plan.
An EQUIVALENT headline therefore needs a denominator: equivalent to which promises, observed through which mode? It can coexist with source gaps outside those promises. It must not be relabeled “complete migration.” Intentional exclusions need an owner and a reason; overlooked items need investigation. Neither should be silently deleted from the evidence presented to the approver.
03Read a small, clearly partial JSON excerpt
The following illustrative partial verify JSON excerpt uses documented keys and documented optional-lane names only. It is not a full schema, customer result, signed envelope or runnable input. It deliberately omits a fabricated verdict field: the current command page documents the verdict semantics but does not provide a complete top-level verdict JSON schema. Read the real report’s verdict alongside the attestation’s source gaps.
This fragment can accompany otherwise equivalent plan evidence when these optional lanes were not supplied. It does not show that source coverage is complete, that an application was tested, or that a report was signed. The current docs name soak, db_upgrade and response_equivalence under unverified when absent. Container and runtime modes can name additional omissions.
- unverified identifies categories not checked; it is not a list of successful checks.
- soak means no supplied observation-window evidence for that lane; point-in-time parity does not substitute for it.
- db_upgrade means that lane was not supplied. It is not a claim about database consistency or successful upgrade.
- response_equivalence means the recorded-response lane was not supplied. The application owner still needs representative transaction evidence.
{
"unverified": [
"soak",
"db_upgrade",
"response_equivalence"
]
}04Interpret findings without flattening their semantics
The command documentation does not make every missing optional lane force the same verdict. For example, supplied customer roles that were not graded make an otherwise matching result inconclusive; runtime items that cannot be checked also prevent equivalent in that lane. Data and probe differences can change a passing exit to non-zero without changing the parity verdict. Preserve these distinctions in your review and CI rules.
| Finding or state | What it means | Review action |
|---|---|---|
| Missing / different | A promised item is absent or differs in the relevant comparison | Compare with intended changes; resolve or approve the specific gap |
| Inconclusive | Required evidence cannot establish the promised comparison | Supply the missing evidence; do not treat it as equivalent |
| Unverified | A category or observation did not run or could not be read | Assign a test owner or record an explicit scope limitation |
| Equivalent | The graded promises hold under the reported scope | Review source gaps and optional lanes before acceptance |
| Data / probe result differs | These lanes can affect exit status without changing the parity verdict | Read the lane result and exit code, not just the headline |
05Review confidence, intended changes and provenance
Trace a questionable target item back to its canonical mapping, target packages, confidence and caveats. Record why a renamed service or relocated configuration fulfills the intended requirement. A lower-confidence outcome is a review cue, not permission to assume compatibility. Where local policy or application configuration deliberately changes, document the new requirement and its owner instead of manufacturing a source match.
Retain the tooling version, input attestation, target access mode and observation context. A mounted root has no running kernel; an SSH observation can read different runtime facts. Evidence obtained in one mode should not be described as if it came from another. Keep identifiers, paths and detailed findings in your controlled evidence store rather than a public ticket.
06Understand requested signing and signing failure
The documented example below compares an operator-prepared rebuilt target at /mnt/rebuild with the migrate attestation. It does not rebuild the target or execute cutover. Review prerequisites and access for your mode. Optional --sign needs credentials and requests a signature; it does not guarantee that signing succeeds. Verification can also involve seat/account handling described in the command docs, so this is not a promise of a network-free command.
When signing fails, the current docs describe an unsigned report carrying unsigned_because and a reason on the text signature line. With --sign, signing failure normally substitutes exit 6 for verdict exits 0, 3 or 5; exits 1 or 4 retain their code. --allow-unsigned changes the signing failure to a warning. Do not confuse an allowed warning with proof that a signature exists.
To check authenticity and integrity, recompute the report digest and verify the signed envelope with the trusted published key under your key-validation process. That shows provenance and detects alteration. It does not prove business correctness, complete source coverage or regulatory compliance; a valid signature can faithfully protect a report containing gaps.
vrtmv verify --attestation out/vrtmv-attestation.json --root /mnt/rebuild --sign --json07Build a reviewable evidence bundle
Keep the source inventory, migrate attestation, generated plan, verify report, any actual signature and signature-check result, plus optional-lane inputs and results. Link the application/data tests, performance observations, remaining exceptions and change approval. Note which evidence is absent. Optional data, probes, recorded responses, soak and database-upgrade lanes exist in the current docs; do not claim the tool can never check them or that they are configured by default.
Assign review ownership: the migration engineer traces system promises and gaps; application and database owners evaluate workload behavior and consistency; the change approver accepts or rejects remaining risk. Record their decisions in your own change process. The report informs those decisions; it is not an engineer signoff on their behalf.
| Evidence layer | Useful for | Owner’s remaining decision |
|---|---|---|
| Manual system checks | Local boot, service, mount and network observations | Interpret the live operating state |
| Parity evidence | Systematic comparison with translated promises | Review coverage, findings and signing state |
| Application/data/soak validation | Transactions, consistent data and representative operation | Approve workload acceptance and recovery readiness |
Questions engineers ask
- Can equivalent coexist with incomplete source coverage?
- Yes. Plan promises can hold while source items remain unresolved or untranslated, or optional application lanes remain unverified. Read the migrate attestation and optional evidence alongside the scoped verdict.
- Are all parity reports signed?
- No. Verification signing is optional and requested signing can fail. Inspect actual signature evidence and unsigned_because rather than assuming --sign succeeded.
- Does parity replace application and database validation?
- No. Optional lanes can add evidence when supplied, but their coverage and results must be read explicitly. Owners still approve business transactions, data consistency and representative operation.
Sources
Product details checked against the current official documentation. Confirm your installed version, exact conversion and operational prerequisites before use.
Continue reading
Apply this to one workload
Virtual Move helps assess, plan and verify supported Linux workloads. Your team owns the migration and acceptance decision.
