Operate GNS3¶

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/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"

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

Add --become when the SSH account has passwordless sudo access. 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. Capture and import retain 64 MiB free on the controller filesystem.

Inspect and stage the result:

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

hyops lab migrate import \
  --env "$ENV" \
  --ref "$REF" \
  --platform gns3 \
  --archive ./gns3-labs.tar.gz

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.

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