Operate EVE-NG

Run this procedure from a workstation where hyops --help succeeds. Complete the Quickstart first when Core is not installed.

Existing-lab migration commands require HybridOps.Core 0.1.5 or newer. Verify the installed version with hyops --version before capture or import.

Use one blueprint reference throughout the lifecycle:

• gcp/eve-ng@v1 for private GCP compute reached through IAP
• onprem/eve-ng@v1 for Proxmox capacity

Both paths provide EVE-NG, declared images, health checks, private access, device automation and protected lab continuity.

1. Prepare the environment

Set an environment name and blueprint reference:

ENV=demo-lab
REF=gcp/eve-ng@v1

Prepare the selected target:

hyops setup gcp
hyops init gcp --env "$ENV" --with-cli-login

For Proxmox, use:

hyops setup proxmox
hyops init proxmox --env "$ENV"

The Proxmox blueprint uses DHCP for the EVE-NG host. Reserve its address in DHCP when the environment requires a stable direct access path.

The Proxmox blueprint builds or reuses its declared VM template through core/onprem/template-image. See Build Proxmox VM Templates when reviewing image inputs, smoke validation or build evidence.

Create the EVE-NG credentials before preflight:

hyops secrets ensure \
  --env "$ENV" \
  EVENG_ROOT_PASSWORD \
  EVENG_ADMIN_PASSWORD

2. Initialise and edit the blueprint

On the first run:

hyops blueprint init \
  --env "$ENV" \
  --ref "$REF" \
  --edit

For an existing environment blueprint:

hyops blueprint edit --env "$ENV" --ref "$REF"

The supported fields and commented examples are maintained in the GCP blueprint and Proxmox blueprint.

The initialized blueprint uses its starter URL list. To import a workstation folder instead, set eveng_images_source to local and set eveng_images_local_path. Local mode recursively discovers supported files in that folder; the URL list is ignored. Keep proprietary sources private and use only images you are authorised to run.

For an authorised IOL image, import its licence file into the environment vault:

hyops secrets set \
  --env "$ENV" \
  --from-file EVENG_IOL_LICENSE=/path/to/iourc

Then enable the commented IOL licence and image entries in the environment blueprint. Do not place licence content in YAML. The vault reapplies it when the host is reconstructed. The local filename is not retained: the target path is /opt/unetlab/addons/iol/bin/iourc, and its licence entry must match the EVE-NG hostname.

Migrate an existing EVE-NG lab

Save intended device configurations. Shut down stateful guests inside their operating systems, then stop the source nodes:

hyops lab migrate capture \
  --platform eve-ng \
  --host <existing-host> \
  --user <ssh-user> \
  --output "$HOME/eve-ng-labs.tar.gz" \
  --include-node-state \
  --guest-quiesced \
  --include-images

OpenSSH uses its configured agent or keys and prompts for the account password in an interactive terminal when required. Core does not store that password. All requested streams are assessed before transfer begins.

For a HybridOps-built source, use --user opsadmin --become; OpenSSH uses the operator key installed during deployment. Add --identity-file <path> only when that key is not available through the agent or default SSH paths.

--guest-quiesced records that each stateful guest was shut down inside the guest before its EVE-NG node was stopped. Stopping the node alone does not establish a clean guest shutdown. The acknowledgement applies only to the current capture and is not a blueprint setting. --become requires passwordless sudo.

For a repeatable shutdown path, replace --guest-quiesced with:

--quiesce-script ./quiesce-lab.sh

The POSIX shell script runs on the EVE-NG host and must shut down the selected guests and stop their EVE nodes. HybridOps waits for all QEMU processes to stop and records the script checksum. The action and QEMU-stop verification share a bounded timeout. Script content and output are not retained. Archive transfer is read-only, does not invoke device exports and refuses to run while QEMU nodes are active. The image companion contains only bases referenced by the captured labs. Licence material is not included. Capture prefers pigz -1 when it is available and otherwise uses gzip -1. Sparse virtual disks remain sparse.

The output path can be absolute; changing the working directory is not required. When requested, node state and images are written beside the primary archive as eve-ng-labs.node-state.tar.gz and eve-ng-labs.images.tar.gz.

Inspect and stage the result:

hyops lab migrate inspect \
  --platform eve-ng \
  --archive "$HOME/eve-ng-labs.tar.gz" \
  --node-state "$HOME/eve-ng-labs.node-state.tar.gz" \
  --images "$HOME/eve-ng-labs.images.tar.gz"

hyops lab migrate import \
  --env "$ENV" \
  --ref "$REF" \
  --platform eve-ng \
  --archive "$HOME/eve-ng-labs.tar.gz" \
  --node-state "$HOME/eve-ng-labs.node-state.tar.gz" \
  --images "$HOME/eve-ng-labs.images.tar.gz"

Import refuses to replace a different staged bundle. Use --force only after inspecting the replacement and confirming that the active record is no longer required.

Omit --include-images when every referenced base is already declared in the target blueprint. IOL licence material remains an environment secret. Restore checks target capacity and stages image content before promotion. Restore the staged bundle with:

hyops blueprint deploy \
  --env "$ENV" \
  --ref "$REF" \
  --execute \
  --restore-labs

Bundle verification proves archive integrity and path compatibility. Complete the migration only after each restored appliance passes its own boot and service checks. The tested Proxmox-to-GCP path restored IOL, vEOS and Ubuntu state. F5 BIG-IP 11.6 entered filesystem recovery on the GCP target despite a guest-quiesced capture and verified base images. Treat BIG-IP 11.6 writable overlay migration as unsupported; deploy a fresh appliance and restore its configuration through the supported F5 path.

Restore rejects structural QCOW2 corruption. Leak-only validation findings are recorded without rewriting the captured overlay.

3. Validate and deploy

hyops blueprint validate --env "$ENV" --ref "$REF"
hyops blueprint plan --env "$ENV" --ref "$REF"
hyops blueprint preflight --env "$ENV" --ref "$REF"
hyops blueprint deploy --env "$ENV" --ref "$REF" --execute

Deployment completes only after the execution host, guest networking, declared images and EVE-NG health checks are ready. Health includes first-boot completion and the local Tomcat and guacd endpoints required by HTML5 consoles. An image is ready only after its installed path is verified. Cached downloads are reused on later runs. Successful deployment prints the access and credential commands for the selected environment.

4. Access the lab

Open the private web interface:

hyops blueprint access --env "$ENV" --ref "$REF"

Keep the command running while using the printed loopback URL. On macOS, copy the admin password with:

hyops secrets show --env "$ENV" --raw EVENG_ADMIN_PASSWORD |
tr -d '\n' |
pbcopy

Clear the clipboard after use:

pbcopy </dev/null

For native QEMU VNC consoles:

hyops blueprint access \
  --env "$ENV" \
  --ref "$REF" \
  --native-consoles

Keep the session running. HybridOps follows QEMU nodes started during the session and reports each loopback-only forward:

native console available: vnc://127.0.0.1:<port>

The workstation must have a handler registered for vnc:// links. Use the EVE-NG client pack on Windows, a registered VNC client on macOS or Linux, or select the HTML5 console in EVE-NG. Click the node after its forwarded port is reported.

Close an access session with Ctrl-C. Keep the environment running when more access or automation tests remain.

Limit a GCP access session

Set an optional access deadline:

hyops blueprint access \
  --env "$ENV" \
  --ref gcp/eve-ng@v1 \
  --session-minutes 120 \
  --on-expiry protected-release

Keep the command running. At expiry, HybridOps preserves the declared lab state before releasing the environment. A failed preservation or teardown retains the environment.

Manage the session from another terminal:

hyops blueprint session status --env "$ENV" --ref gcp/eve-ng@v1
hyops blueprint session extend --env "$ENV" --ref gcp/eve-ng@v1 --minutes 30
hyops blueprint session cancel --env "$ENV" --ref gcp/eve-ng@v1

cancel removes the expiry action without closing access. Time-bounded access is not available for the Proxmox blueprint.

5. Connect lab networks

• Connect a node interface to Cloud9 for DHCP and outbound access.
• Connect a separate management interface to Cloud8 for private workstation automation.

Cloud9 uses gateway and DNS 172.29.129.1. Cloud8 uses management subnet 172.29.128.0/24 and gateway 172.29.128.1.

6. Test device automation

Keep the automation access session running in the first terminal:

hyops blueprint access \
  --env "$ENV" \
  --ref "$REF" \
  --automation

Use a second terminal:

ENV=demo-lab
REF=gcp/eve-ng@v1

hyops blueprint device list --env "$ENV" --ref "$REF"
hyops blueprint device edit --env "$ENV" --ref "$REF"
hyops blueprint device ping --env "$ENV" --ref "$REF" <device-name-or-address>
hyops blueprint device ssh --env "$ENV" --ref "$REF" <device-name>
hyops blueprint device web --env "$ENV" --ref "$REF" <device-name-or-address> --scheme http --port 80
hyops blueprint device shell --env "$ENV" --ref "$REF"

device ssh uses a target name from device list. The list also shows the detected address and configured SSH user. DHCP discovery uses the blueprint default user. Use device edit to set the user, port, identity file or platform. Do not store passwords in the target file. Restart automation access after an edit before using generated Ansible or Nornir files.

device web maps private interfaces to temporary loopback URLs. Use device edit to declare each target's web service; the generated file documents the available fields. Open named targets together, or every declared service:

hyops blueprint device web --env "$ENV" --ref "$REF" <device-1> <device-2>
hyops blueprint device web --env "$ENV" --ref "$REF" --all

One Ctrl-C closes every tunnel. Add --open-all to open every URL in the workstation browser. Appliance certificates may produce the expected local browser warning.

The device shell exports the generated SSH, Ansible, Nornir and proxy settings. Run one command without entering the shell with:

hyops blueprint device run \
  --env "$ENV" \
  --ref "$REF" \
  -- ansible-playbook site.yml

On macOS, use the managed device commands, generated SSH configuration or SOCKS proxy. Direct workstation ICMP to the private management subnet is not the default access model.

7. Preserve or release the environment

Configure the environment shutdown action once. It must shut down stateful guests and stop their EVE-NG nodes before returning:

hyops blueprint quiescence edit --env "$ENV" --ref "$REF"
hyops blueprint quiescence status --env "$ENV" --ref "$REF"

The action is stored under the selected environment. Protected teardown discovers it automatically, verifies that QEMU processes have stopped and records its checksum with the archive evidence.

Interactive teardown offers keep, archive and destroy, or destroy without an archive:

hyops blueprint destroy --env "$ENV" --ref "$REF" --execute

For a protected non-interactive teardown:

hyops blueprint destroy \
  --env "$ENV" \
  --ref "$REF" \
  --execute \
  --yes \
  --archive-before-destroy

Save intended device changes to startup configuration before teardown. The archive refreshes supported saved configurations through EVE-NG when capture is enabled and preserves lab definitions with selected writable overlay state. Native configuration export has a 300-second default timeout. Set eveng_lab_archive_config_export_timeout_s in the environment blueprint when a different limit is required. During preservation, the terminal reports the active archive phase and the final verified size. The candidate must pass verification before it replaces the current archive or managed compute is released. The preceding verified generation remains as a fallback.

For a manual clean shutdown, use --guest-quiesced for that operation. --quiesce-script is an operation-specific override of the environment action.

Restore the latest verified archive with:

hyops blueprint deploy \
  --env "$ENV" \
  --ref "$REF" \
  --execute \
  --restore-labs

Lab definitions and base images are protected independently. Add --overwrite-labs to replace lab definitions or --overwrite-images to replace referenced base images.

For a disposable test with no state to retain:

hyops blueprint destroy \
  --env "$ENV" \
  --ref "$REF" \
  --execute \
  --yes \
  --skip-archive

References

• GCP EVE-NG blueprint
• Proxmox EVE-NG blueprint
• EVE-NG lifecycle architecture
• EVE-NG image module

License: MIT-0 for code, CC-BY-4.0 for documentation