Operate GNS3¶

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/gns3@v1 for private GCP compute reached through IAP
onprem/gns3@v1 for Proxmox capacity

Both paths provide an authenticated GNS3 server, declared images, a starter project, health checks, private access, device automation and project continuity.

1. Prepare the environment¶

ENV=demo-lab
REF=gcp/gns3@v1

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

For Proxmox, replace the setup and initialisation commands with:

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

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 GNS3 server password before preflight:

hyops secrets ensure --env "$ENV" GNS3_SERVER_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.

GNS3 images are declared individually under gns3_images_items because each entry also defines its registration metadata. Keep proprietary image sources private. Supply a checksum when one is available.

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

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

Then enable the commented IOU licence inputs and add image links under gns3_images_items. The same url, name, type and label declaration used for EVE-NG is accepted. GNS3 maps a single image payload from each raw file or archive and accepts iol as an alias for iou. Do not place licence content in YAML. filename is required; checksum is optional.

Migrate an existing GNS3 lab¶

Stop the source GNS3 server, then capture its projects and controller state:

hyops lab migrate capture \
  --platform gns3 \
  --host <existing-host> \
  --user <ssh-user> \
  --output "$HOME/gns3-labs.tar.gz"

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 data is 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. The output path can be absolute; changing the working directory is not required.

--become requires passwordless sudo. Capture is read-only and refuses to run while the GNS3 server is active. Add --include-images only when the image library must travel with the projects. GNS3 keeps that library in the primary archive; no separate image companion is created. Capture and import retain 64 MiB free on the controller filesystem.

Inspect and stage the result:

hyops lab migrate inspect \
  --platform gns3 \
  --archive "$HOME/gns3-labs.tar.gz"

hyops lab migrate import \
  --env "$ENV" \
  --ref "$REF" \
  --platform gns3 \
  --archive "$HOME/gns3-labs.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.

Keep separately managed images and licence material declared in the environment blueprint. Restore checks target capacity before replacing lab data. 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 after the host, authenticated server, declared images, starter project and health checks are ready.

4. Access GNS3¶

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

Keep the command running. Connect the browser or desktop client to the printed loopback endpoint with username gns3. HybridOps uses port 3080 when it is available and selects another local port when it is already occupied.

For native node consoles in the GNS3 desktop client, use:

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

HybridOps reads each node's console assignment from the authenticated GNS3 API and maintains matching loopback forwards for Telnet, VNC, SPICE and web consoles. Keep the command running while using a native console. New node console ports are forwarded during the same session.

On macOS, copy the password with:

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

Close access with Ctrl-C. HybridOps then offers to keep the environment, archive its projects before teardown, or destroy without an archive. Select keep when more tests remain.

Limit a GCP access session¶

Set an optional access deadline:

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

Keep the command running. At expiry, HybridOps preserves the declared project 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/gns3@v1
hyops blueprint session extend --env "$ENV" --ref gcp/gns3@v1 --minutes 30
hyops blueprint session cancel --env "$ENV" --ref gcp/gns3@v1

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

5. Test device automation¶

Map a GNS3 Cloud node to hyops-mgmt0 and connect a separate management interface on each device. Use DHCP or an address in 172.29.130.0/24 with gateway 172.29.130.1.

Keep this session running in the first terminal:

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

Use a second terminal:

ENV=demo-lab
REF=gcp/gns3@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.

Run a command through the managed automation environment 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.

6. 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

The verified archive contains GNS3 projects, controller metadata and writable node disks. Declared base images and vault-held licence material remain separate. A successful export retains the preceding verified generation as a fallback; a failed export leaves the current archive unchanged.

Restore the latest verified archive with:

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

For a disposable test with no state to retain:

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

References¶

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