Operate EVE-NG

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

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"

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 and stop the source nodes before capture:

hyops lab migrate capture \
  --platform eve-ng \
  --host <existing-host> \
  --user <ssh-user> \
  --output ./eve-ng-labs.tar.gz \
  --include-node-state \
  --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.

Add --become when the SSH account has passwordless sudo access. Capture 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.

Inspect and stage the result:

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

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

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 before replacing images, lab definitions or node state. Restore the staged bundle with:

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

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. An image is ready only after its installed path is verified. Cached downloads are reused on later runs.

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.

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

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. It stops active QEMU nodes and preserves lab definitions with selected writable overlay state. The candidate must pass verification before it replaces the current archive or managed compute is released. The preceding verified generation remains as a fallback.

Restore the latest verified archive with:

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

Existing lab content is protected. Add --overwrite-labs only when the verified archive should replace it.

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