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"

Enable only the image entries required by the project. 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.

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.

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