Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion actions/test.documentation-contract.sh
Original file line number Diff line number Diff line change
Expand Up @@ -92,7 +92,8 @@ done
require_regex "docs/cli/ipmctl/readme.md" '^[[:space:]]+bash -s -- install([[:space:]]|$)'
require_regex "docs/cli/ipmctl/readme.md" '^[[:space:]]+sudo bash -s -- verify([[:space:]]|$)'
require_contains "docs/cli/gpu/readme.md" '/etc/ansible/debian/facts/gpu.yml'
require_contains "docs/cli/ipmctl/readme.md" '/var/lib/devs-guide/ipmctl/receipt.json'
require_contains "docs/cli/ipmctl/readme.md" '/var/lib/ansible/debian/ipmctl/receipt.json'
require_contains "docs/cli/ipmctl/readme.md" '~/.cache/ansible/ipmctl/runs/'
require_contains "docs/cli/llm/host/readme.md" '/etc/ansible/debian/facts/llm-host.yml'
require_contains "docs/cli/llm/host/readme.md" '/etc/ansible/debian/facts/gpu.yml'
require_contains "docs/cli/llm/host/readme.md" '/etc/ansible/debian/facts/nvidia.yml'
Expand Down
10 changes: 9 additions & 1 deletion actions/test.ipmctl-contract.sh
Original file line number Diff line number Diff line change
Expand Up @@ -57,6 +57,7 @@ for marker in \
'readonly EXIT_USAGE=64' \
'readonly IPMCTL_BIN=/usr/local/bin/ipmctl' \
'readonly IPMCTL_VERSION=03.00.00.0538' \
'readonly RUNNER_NAMESPACE=ansible' \
'FEATURE_PLAYBOOKS=("install.packages.yml" "cli/ipmctl.yml")' \
'files/ipmctl/apply-patch.yml' \
'files/ipmctl/patches/0001-edk2-stable202511-host-os-build.patch' \
Expand All @@ -78,7 +79,14 @@ for marker in \
'ipmctl_edk2_tag: edk2-stable202511' \
'ipmctl_edk2_commit: 46548b1adac82211d8d11da12dd914f41e7aa775' \
'ipmctl_install_prefix: /usr/local' \
'ipmctl_receipt_path: /var/lib/devs-guide/ipmctl/receipt.json' \
'ipmctl_receipt_path: /var/lib/ansible/debian/ipmctl/receipt.json' \
'ipmctl_cache_root: "{{ ipmctl_build_home }}/.cache/ansible/ipmctl"' \
'ipmctl_legacy_receipt_path: /var/lib/devs-guide/ipmctl/receipt.json' \
'ipmctl_legacy_cache_root: "{{ ipmctl_build_home }}/.cache/devs-guide/ipmctl"' \
'Require an unambiguous build cache migration' \
'Migrate retained build cache to the neutral namespace' \
'Require an unambiguous managed state migration' \
'Migrate receipt and manifest to the neutral namespace' \
'Refuse an unmanaged local ipmctl binary' \
'Determine whether installation is current' \
'Fetch only reviewed source tags' \
Expand Down
2 changes: 2 additions & 0 deletions actions/test.runner-contract.sh
Original file line number Diff line number Diff line change
Expand Up @@ -21,6 +21,7 @@ for marker in \
'runner.ensure.privileged.session' \
'runner.run.as.root' \
'runner.cleanup.runtime' \
'RUNNER_RUNTIME_NAMESPACE' \
'runner.relative.path.is.safe' \
'runner.fetch.file' \
'runner.copy.file' \
Expand Down Expand Up @@ -91,6 +92,7 @@ direct_fetch_count="$(
require_shell_syntax "${runner}"
for marker in \
'RUNNER_HELPER_URL' \
'RUNNER_NAMESPACE=ansible' \
'source.runner.common' \
'runner.ensure.privileged.session' \
'runner.source.release.common' \
Expand Down
32 changes: 32 additions & 0 deletions actions/test.runner-staging.sh
Original file line number Diff line number Diff line change
Expand Up @@ -74,6 +74,38 @@ run_case() {
fi
}

run_case "runtime namespaces remain explicit and cleanup-safe" '
source "${TEST_HELPER}"
runner.create.runtime staging "${TEST_CASE_ROOT}"
default_runtime="${RUNNER_RUNTIME_DIR}"
[[ "${default_runtime##*/}" == devs-guide-staging.* ]]
[[ "${RUNNER_RUNTIME_NAMESPACE}" == devs-guide ]]
runner.cleanup.runtime
[[ ! -e "${default_runtime}" ]]

runner.create.runtime ipmctl "${TEST_CASE_ROOT}" ansible
neutral_runtime="${RUNNER_RUNTIME_DIR}"
[[ "${neutral_runtime##*/}" == ansible-ipmctl.* ]]
[[ "${RUNNER_RUNTIME_NAMESPACE}" == ansible ]]
runner.cleanup.runtime
[[ ! -e "${neutral_runtime}" ]]
printf "RUNTIME_NAMESPACES_OK\n"
'
expect_status 0 "${CASE_STATUS}" "runtime namespaces"
expect_contains 'RUNTIME_NAMESPACES_OK' "${CASE_OUTPUT}" "runtime namespaces"

run_case "unsupported runtime namespace fails before allocation" '
source "${TEST_HELPER}"
if runner.create.runtime ipmctl "${TEST_CASE_ROOT}" repository-brand; then
exit 90
fi
[[ -z "$(find "${TEST_CASE_ROOT}" -mindepth 1 -print -quit)" ]]
printf "UNSAFE_NAMESPACE_BLOCKED\n"
'
expect_status 0 "${CASE_STATUS}" "unsupported runtime namespace"
expect_contains 'Runner runtime namespace is unsupported: repository-brand' "${CASE_OUTPUT}" "unsupported runtime namespace"
expect_contains 'UNSAFE_NAMESPACE_BLOCKED' "${CASE_OUTPUT}" "unsupported runtime namespace"

run_case "local declarative Ansible manifest" '
source "${TEST_HELPER}"
runner.create.runtime staging "${TEST_CASE_ROOT}"
Expand Down
162 changes: 152 additions & 10 deletions ansible/cli/ipmctl.yml
Original file line number Diff line number Diff line change
Expand Up @@ -20,9 +20,12 @@
ipmctl_edk2_commit: 46548b1adac82211d8d11da12dd914f41e7aa775
ipmctl_install_prefix: /usr/local
ipmctl_binary_path: /usr/local/bin/ipmctl
ipmctl_receipt_root: /var/lib/devs-guide/ipmctl
ipmctl_receipt_path: /var/lib/devs-guide/ipmctl/receipt.json
ipmctl_install_manifest_path: /var/lib/devs-guide/ipmctl/install_manifest.txt
ipmctl_receipt_root: /var/lib/ansible/debian/ipmctl
ipmctl_receipt_path: /var/lib/ansible/debian/ipmctl/receipt.json
ipmctl_install_manifest_path: /var/lib/ansible/debian/ipmctl/install_manifest.txt
ipmctl_legacy_receipt_root: /var/lib/devs-guide/ipmctl
ipmctl_legacy_receipt_path: /var/lib/devs-guide/ipmctl/receipt.json
ipmctl_legacy_install_manifest_path: /var/lib/devs-guide/ipmctl/install_manifest.txt
ipmctl_patch_root: "{{ playbook_dir }}/../files/ipmctl/patches"
ipmctl_patches:
- id: edk2-stable202511-host-os-build
Expand Down Expand Up @@ -83,7 +86,8 @@
- name: Resolve per-run source paths
ansible.builtin.set_fact:
ipmctl_run_id: "{{ lookup('pipe', '/usr/bin/date -u +%Y%m%dT%H%M%S%N') }}"
ipmctl_cache_root: "{{ ipmctl_build_home }}/.cache/devs-guide/ipmctl"
ipmctl_cache_root: "{{ ipmctl_build_home }}/.cache/ansible/ipmctl"
ipmctl_legacy_cache_root: "{{ ipmctl_build_home }}/.cache/devs-guide/ipmctl"

- name: Resolve mutable worktree paths
ansible.builtin.set_fact:
Expand All @@ -92,25 +96,162 @@
ipmctl_edk2_source_dir: "{{ ipmctl_cache_root }}/runs/{{ ipmctl_run_id }}/edk2"
ipmctl_build_dir: "{{ ipmctl_cache_root }}/runs/{{ ipmctl_run_id }}/build"

- name: Inspect neutral and legacy build cache roots
ansible.builtin.stat:
path: "{{ item }}"
follow: false
loop:
- "{{ ipmctl_cache_root }}"
- "{{ ipmctl_legacy_cache_root }}"
register: ipmctl_cache_roots

- name: Require an unambiguous build cache migration
ansible.builtin.assert:
that:
- >-
not (ipmctl_cache_roots.results[0].stat.exists | default(false))
or (ipmctl_cache_roots.results[0].stat.isdir | default(false))
- >-
not (ipmctl_cache_roots.results[1].stat.exists | default(false))
or (ipmctl_cache_roots.results[1].stat.isdir | default(false))
- >-
not (
(ipmctl_cache_roots.results[0].stat.exists | default(false))
and (ipmctl_cache_roots.results[1].stat.exists | default(false))
)
fail_msg: >-
Neutral and legacy ipmctl cache roots conflict or are not directories.
Resolve them manually; the installer will not merge or delete ambiguous data.

- name: Inspect neutral and legacy managed state
ansible.builtin.stat:
path: "{{ item }}"
follow: false
loop:
- "{{ ipmctl_receipt_path }}"
- "{{ ipmctl_install_manifest_path }}"
- "{{ ipmctl_legacy_receipt_path }}"
- "{{ ipmctl_legacy_install_manifest_path }}"
register: ipmctl_managed_state

- name: Require an unambiguous managed state migration
ansible.builtin.assert:
that:
- >-
(ipmctl_managed_state.results[0].stat.exists | default(false))
== (ipmctl_managed_state.results[1].stat.exists | default(false))
- >-
(ipmctl_managed_state.results[2].stat.exists | default(false))
== (ipmctl_managed_state.results[3].stat.exists | default(false))
- >-
not (
(ipmctl_managed_state.results[0].stat.exists | default(false))
and (ipmctl_managed_state.results[2].stat.exists | default(false))
)
- >-
not (ipmctl_managed_state.results[0].stat.exists | default(false))
or (ipmctl_managed_state.results[0].stat.isreg | default(false))
- >-
not (ipmctl_managed_state.results[1].stat.exists | default(false))
or (ipmctl_managed_state.results[1].stat.isreg | default(false))
- >-
not (ipmctl_managed_state.results[2].stat.exists | default(false))
or (ipmctl_managed_state.results[2].stat.isreg | default(false))
- >-
not (ipmctl_managed_state.results[3].stat.exists | default(false))
or (ipmctl_managed_state.results[3].stat.isreg | default(false))
fail_msg: >-
Neutral and legacy ipmctl receipts or manifests conflict, are incomplete,
or are not regular files. Resolve them manually before continuing.

- name: Create neutral cache parent for legacy migration
ansible.builtin.file:
path: "{{ ipmctl_build_home }}/.cache/ansible"
state: directory
owner: "{{ ipmctl_build_user }}"
group: "{{ ipmctl_build_group }}"
mode: "0750"
when:
- ipmctl_cache_roots.results[1].stat.isdir | default(false)
- not (ipmctl_cache_roots.results[0].stat.exists | default(false))
become: true

- name: Migrate retained build cache to the neutral namespace
ansible.builtin.command:
argv:
- /usr/bin/mv
- "{{ ipmctl_legacy_cache_root }}"
- "{{ ipmctl_cache_root }}"
when:
- ipmctl_cache_roots.results[1].stat.isdir | default(false)
- not (ipmctl_cache_roots.results[0].stat.exists | default(false))
become: true
changed_when: true

- name: Remove empty legacy user cache parent
ansible.builtin.command:
argv: [/usr/bin/rmdir, "{{ ipmctl_build_home }}/.cache/devs-guide"]
register: ipmctl_legacy_cache_parent_cleanup
become: true
changed_when: ipmctl_legacy_cache_parent_cleanup.rc == 0
failed_when: false

- name: Create neutral managed state directory for legacy migration
ansible.builtin.file:
path: "{{ ipmctl_receipt_root }}"
state: directory
owner: root
group: root
mode: "0755"
when: ipmctl_managed_state.results[2].stat.isreg | default(false)
become: true

- name: Migrate receipt and manifest to the neutral namespace
ansible.builtin.command:
argv: [/usr/bin/mv, "{{ item.source }}", "{{ item.destination }}"]
loop:
- source: "{{ ipmctl_legacy_receipt_path }}"
destination: "{{ ipmctl_receipt_path }}"
- source: "{{ ipmctl_legacy_install_manifest_path }}"
destination: "{{ ipmctl_install_manifest_path }}"
when: ipmctl_managed_state.results[2].stat.isreg | default(false)
become: true
changed_when: true

- name: Remove empty legacy managed state directories
ansible.builtin.command:
argv: [/usr/bin/rmdir, "{{ item }}"]
loop:
- "{{ ipmctl_legacy_receipt_root }}"
- /var/lib/devs-guide
register: ipmctl_legacy_state_cleanup
become: true
changed_when: ipmctl_legacy_state_cleanup.rc == 0
failed_when: false

tasks:
- name: Inspect managed receipt and installed binary
- name: Inspect managed receipt, manifest, and installed binary
ansible.builtin.stat:
path: "{{ item }}"
follow: false
checksum_algorithm: sha256
loop:
- "{{ ipmctl_receipt_path }}"
- "{{ ipmctl_install_manifest_path }}"
- "{{ ipmctl_binary_path }}"
register: ipmctl_initial_stats

- name: Refuse an unmanaged local ipmctl binary
ansible.builtin.assert:
that:
- >-
not (ipmctl_initial_stats.results[1].stat.exists | default(false))
or (ipmctl_initial_stats.results[0].stat.isreg | default(false))
not (ipmctl_initial_stats.results[2].stat.exists | default(false))
or (
(ipmctl_initial_stats.results[0].stat.isreg | default(false))
and (ipmctl_initial_stats.results[1].stat.isreg | default(false))
)
fail_msg: >-
{{ ipmctl_binary_path }} exists without the devs-guide receipt.
{{ ipmctl_binary_path }} exists without the managed Ansible receipt and manifest.
Refusing to overwrite an unmanaged installation.

- name: Decode the optional managed receipt safely
Expand Down Expand Up @@ -145,14 +286,15 @@
register: ipmctl_current_software
changed_when: false
failed_when: false
when: ipmctl_initial_stats.results[1].stat.isreg | default(false)
when: ipmctl_initial_stats.results[2].stat.isreg | default(false)

- name: Determine whether installation is current
ansible.builtin.set_fact:
ipmctl_install_is_current: >-
{{
(ipmctl_initial_stats.results[0].stat.isreg | default(false))
and (ipmctl_initial_stats.results[1].stat.isreg | default(false))
and (ipmctl_initial_stats.results[2].stat.isreg | default(false))
and (ipmctl_previous_receipt.schema_version | default(0) | int == 1)
and (ipmctl_previous_receipt.platform.debian | default('') == '13')
and (ipmctl_previous_receipt.platform.architecture | default('') == 'amd64')
Expand All @@ -166,7 +308,7 @@
and (ipmctl_previous_receipt.install.binary | default('') == ipmctl_binary_path)
and
(
ipmctl_initial_stats.results[1].stat.checksum | default('')
ipmctl_initial_stats.results[2].stat.checksum | default('')
== ipmctl_previous_receipt.install.binary_sha256 | default('')
)
and (ipmctl_current_software.results[0].rc | default(1) | int == 0)
Expand Down
42 changes: 28 additions & 14 deletions docs/cli/ipmctl/readme.md
Original file line number Diff line number Diff line change
Expand Up @@ -68,25 +68,32 @@ For an audit-friendly remote run, download and review the exact published
entrypoint first:

```bash
wget -qO /tmp/devs-guide-ipmctl.sh \
wget -qO /tmp/ansible-ipmctl.sh \
https://devs-guide.github.io/debian/setup/cli/ipmctl.sh
less /tmp/devs-guide-ipmctl.sh
bash /tmp/devs-guide-ipmctl.sh install
less /tmp/ansible-ipmctl.sh
bash /tmp/ansible-ipmctl.sh install
```

The exact Git tags and commits are verified before patches are applied. CMake
uses a Release build with two parallel jobs. A successful install records its
commits, patch checksums, toolchain, binary checksum, and install manifest at:

```text
/var/lib/devs-guide/ipmctl/receipt.json
/var/lib/ansible/debian/ipmctl/receipt.json
```

A repeat install skips source fetching and compilation only when the receipt,
binary checksum, exact version, and complete runtime linkage still match.
The installer refuses to overwrite an unmanaged `/usr/local/bin/ipmctl`.
Failed build workspaces remain under the invoking user's
`~/.cache/devs-guide/ipmctl/runs/` for inspection.
`~/.cache/ansible/ipmctl/runs/` for inspection. Temporary runner files use
`/tmp/ansible-ipmctl.*` and are removed by the path-constrained cleanup trap.

Installations created before the neutral Ansible namespace was introduced are
migrated without rebuilding. The installer moves the complete legacy cache,
receipt, and manifest only when the new destinations do not already exist. If
both namespaces contain state, it stops for human review instead of merging or
deleting ambiguous data.

## Verify

Expand Down Expand Up @@ -122,16 +129,24 @@ failure is a warning distinct from a broken software installation.
Only `install`, `verify`, and `--help` are accepted. PMem allocation changes
remain a manual maintenance operation outside this runner.

## Remote acceptance
## Validated target and remote acceptance

The pinned source tuple was built successfully from the published runner on a
Debian 13 amd64 Intel Ice Lake host with four Intel Optane PMem 200 modules.
Version, linkage, DIMM discovery, topology, memory resources, and the current
or pending goal query passed. The accepted host was using Memory Mode with no
App Direct allocation and no pending goal. Hardware identifiers and serial
numbers are deliberately excluded from this documentation.

Before merge, fetch the candidate commit into the intended Debian 13 amd64
PMem-200 server and run from that checked-out repository. Do not substitute an
unpublished Pages URL for the reviewed candidate files.
Before merging a future runtime change, fetch its exact candidate commit from
`raw.githubusercontent.com` and set `PAGES_BASE_URL` to that same immutable
commit so the runner and every staged dependency come from one revision. A Git
clone is not required.

1. Capture `/etc/os-release`, architecture, kernel, GCC/G++, CMake, Python, and
the installed build-dependency versions for the pull-request evidence.
2. Run `bash setup/cli/ipmctl.sh install` once and retain the complete output.
3. Run `bash setup/cli/ipmctl.sh install` again and confirm it reports the
2. Run the candidate `install` once and retain the complete output.
3. Run the candidate `install` again and confirm it reports the
matching installation rather than rebuilding.
4. Run `bash setup/cli/ipmctl.sh verify` and retain all four labeled probe
sections.
Expand All @@ -141,9 +156,8 @@ unpublished Pages URL for the reviewed candidate files.
6. Only then run the LLM host validator with `--require-ipmctl` and, when
appropriate, `--require-memory-mode`.

After review, merge, and `www` publication, fetch the published runner and run
`verify` again. Reinstall from the public URL only if the published content
differs from the accepted candidate or a reinstall is intentional.
After review, merge, and `www` publication, run the published `install` once
to prove the managed receipt still skips rebuilding, then run `verify` again.

GitHub Actions checks the static runner, playbook, patch checksums, YAML, and
publication contract. It deliberately does not rebuild archived Intel source
Expand Down
Loading
Loading