Skip to content

Load EVE-NG Images (HyOps)

Execution context: Run this procedure from a terminal where hyops --help succeeds. If HybridOps.Core is not installed, complete the Quickstart. For deployment support, use GitHub Discussions.

  • Purpose: Stage and install EVE-NG images from URL, local, or remote sources onto an existing EVE-NG host.
  • Trigger: Initial topology content load, curriculum refresh, or controlled image catalog update.
  • Impact: Writes under /opt/unetlab/addons on the target EVE-NG host.
  • Severity: P2

  • Pre-reqs: Base EVE-NG service is already ready, SSH access works, and source paths or URLs are approved.

  • Rollback strategy: Run hyops destroy with explicit eveng_images_destroy_paths, or rebuild the host from a clean baseline if broad image cleanup is required.

Context

This runbook covers platform/linux/eve-ng-images, the content-layer module used after platform/linux/eve-ng is ready.

Supported source modes:

  • url
  • local
  • remote

The module is intentionally separate from the base EVE-NG blueprint so shared, academy, and instructor lanes can reuse the same foundation with different image catalogs.

Preconditions and safety checks

  • Correct environment selected (--env <env>).
  • Base EVE-NG module state is ok.
  • Source images are approved for the target lane.
  • Any required IOL licence was obtained legitimately for this EVE-NG host.
  • URL downloads are reachable, or local/remote sources are accessible from the execution runner.
  • For destructive cleanup, eveng_images_destroy_paths only contains paths under /opt/unetlab/addons/.

Steps

For an authorised IOL image on EVE-NG Community Edition, store its host-bound licence before validation:

hyops secrets set --env <env> \
  --from-file EVENG_IOL_LICENSE=/path/to/iourc

The local filename is not retained. The role installs the material as /opt/unetlab/addons/iol/bin/iourc and requires a licence entry for the observed EVE-NG hostname.

Set load_vault_env: true, include EVENG_IOL_LICENSE in required_env, and set eveng_images_iol_license_required: true in the module inputs. Do not add the licence file to the image archive.

  1. Validate inputs

    hyops validate --env <env> \
  --module platform/linux/eve-ng-images \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/linux/eve-ng-images/examples/inputs.min.yml"

  2. Preflight

    hyops preflight --env <env> --strict \
  --module platform/linux/eve-ng-images \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/linux/eve-ng-images/examples/inputs.min.yml"

  3. Apply

    hyops apply --env <env> \
  --module platform/linux/eve-ng-images \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/linux/eve-ng-images/examples/inputs.min.yml"

  4. Verify state

    cat $HOME/.hybridops/envs/<env>/state/modules/platform__linux__eve-ng-images/latest.json

Check:

  • status is ok
  • outputs.cap.lab.eveng.images is present
  • outputs.eveng_images_requested_count matches the intended batch

  • outputs.eveng_images_iol_license_ready is true when an iourc was supplied

  • Controlled cleanup

    hyops destroy --env <env> \
  --module platform/linux/eve-ng-images \
  --inputs "$HYOPS_CORE_ROOT/modules/platform/linux/eve-ng-images/examples/inputs.min.yml"

Verification

  • Target host contains the expected image directories under /opt/unetlab/addons/.
  • IOL binaries are executable and iourc has the EVE-NG-normalised file mode.
  • An authorised IOL node starts successfully after a host rebuild. This is the definitive check because the licence is bound to the EVE-NG host identity.
  • State file: $HOME/.hybridops/envs/<env>/state/modules/platform__linux__eve-ng-images/latest.json
  • Logs: $HOME/.hybridops/envs/<env>/logs/module/platform__linux__eve-ng-images/<run_id>/

Post-actions and clean-up

  • Remove temporary staging or controller-side source files if they were created for one-off imports.
  • Update curriculum or inventory references if image names changed.
  • Keep image runs separate from topology-content runs so troubleshooting stays clean.

References