hc023307c/gns3-netbox-manager repository overview

⁠GNS3 NetBox Manager Repository Overview

Last updated: 2026-08-30

⁠Overview

GNS3 NetBox Manager is a lightweight web service for synchronizing lab data between GNS3 and NetBox. It is designed for practical network-lab workflows where users need to build, import, deploy, and update topologies without manually re-entering the same information in multiple systems.

The service sits between GNS3 and NetBox and connects to both platforms through their APIs. It does not bundle either platform, and it does not permanently store infrastructure credentials on the server.

⁠What this project does

This project provides a browser-based operational layer for three common workflow models:

• GNS3-first: build in GNS3, then import into NetBox
• NetBox-first: model in NetBox, then deploy to GNS3
• YAML-first: define a lab in YAML, then apply it to NetBox or deploy it to GNS3

In day-to-day use, the service helps with:

• importing GNS3 projects into NetBox
• deploying NetBox lab definitions into GNS3
• updating device configuration from NetBox into an existing GNS3 lab
• pulling selected GNS3 project data back into NetBox
• validating topology YAML before execution
• generating AI-ready topology context for YAML authoring
• preparing NetBox integration metadata such as custom fields, choice sets, template mappings, and device-type support

⁠Architecture

The application is intentionally small in scope. It packages only the integration service itself.

User Browser
    |
    |  request-scoped settings
    v
GNS3 NetBox Manager
    | \
    |  \__ NetBox API
    |
    \____ GNS3 API

⁠Design principles

• GNS3 and NetBox remain external systems
• credentials are provided by the browser at runtime
• the backend uses those credentials only for the active request
• the backend does not act as a long-term credential store
• the container image packages only the web service and its runtime dependencies

⁠Deployment scope

This repository builds a standalone application image for GNS3 NetBox Manager.

It does not include:

• a GNS3 server
• a NetBox instance
• lab images or appliances
• customer data
• preconfigured credentials

⁠Example Docker Compose deployment

services:
  gns3-netbox-manager:
    image: <dockerhub-user>/gns3-netbox-manager:latest
    container_name: gns3-netbox-manager
    restart: unless-stopped
    ports:
      - "8088:8080"
    volumes:
      - ./data:/app/data

After the container starts, open:

http://<docker-host>:8088/settings

⁠First-time setup

For a new environment, the recommended setup order is:

1. Start the container.
2. Open the Settings page.
3. Enter the GNS3 connection details.
4. Enter the NetBox connection details.
5. Test both connections.
6. Run Initialize / Sync Integration.
7. Confirm that custom fields, choice sets, template mappings, and device types were synchronized successfully.

This initialization step is important because YAML validation, template-aware workflows, and several deployment features depend on the metadata created here.

⁠Main application areas

The web interface is organized around operational tasks rather than platform internals.

⁠Settings

The Settings page is where users provide GNS3 and NetBox connection details.

Supported behavior:

• store settings for the current browser session only
• optionally keep settings in local browser storage on the user's own machine

The server does not permanently store these credentials.

⁠System Integration

The System Integration page prepares NetBox for use with the service and keeps metadata aligned with live GNS3 templates.

It synchronizes:

• required NetBox custom fields
• the GNS3 template choice set
• template mappings used by YAML and deployment workflows
• device-type metadata needed by supported import and deployment paths

This action is safe to run again after template changes or when moving to a different NetBox environment.

⁠GNS3 Projects

The GNS3 Projects area supports GNS3-first workflows.

Typical tasks include:

• refreshing the project list
• checking project sync state
• comparing a GNS3 Project with NetBox
• importing a GNS3 project into NetBox
• closing an opened project
• deleting a project from GNS3

Typical flow:

1. Build or modify the topology in GNS3.
2. Open GNS3 Projects.
3. Refresh the list.
4. Import the target project into NetBox.
5. Review or continue with later synchronization tasks if needed.

⁠NetBox GNS3 Labs

The NetBox GNS3 Labs area supports NetBox-first workflows.

Typical tasks include:

• refreshing NetBox Locations marked as GNS3 Labs
• previewing the generated lab view
• deploying a NetBox Location into GNS3
• updating configuration for an already deployed lab
• deleting NetBox Lab objects when required

Typical flow:

1. Build the lab model in NetBox.
2. Mark the target Location as a GNS3 Lab.
3. Open NetBox GNS3 Labs.
4. Refresh labs.
5. Preview the deployment.
6. Deploy to GNS3.
7. Use Update Config later if the NetBox-side configuration changes.

⁠YAML Lab

The YAML Lab area supports automation-first workflows.

Typical tasks include:

• validating YAML syntax and topology structure
• applying YAML to NetBox
• deploying YAML directly to GNS3
• copying AI topology context for NetBox-targeted YAML generation
• copying AI topology context for GNS3-targeted YAML generation

Typical flow:

1. Write or generate the YAML.
2. Validate it.
3. Apply it to NetBox or deploy it to GNS3.
4. Continue lifecycle operations in the other service pages as needed.

⁠Supported workflow patterns

⁠GNS3-first workflow

Use this when the source of truth starts in GNS3.

1. Create or update the topology in GNS3.
2. Import the project into NetBox.
3. Continue maintaining metadata, labels, and optional configuration fields in NetBox.

⁠NetBox-first workflow

Use this when the source of truth starts in NetBox.

1. Model the lab in NetBox.
2. Deploy it through NetBox GNS3 Labs.
3. Push later configuration updates from NetBox into GNS3 if needed.

⁠YAML-first workflow

Use this when the topology should be generated, templatized, or produced by automation.

1. Prepare a YAML definition.
2. Validate it.
3. Apply it to NetBox or deploy it to GNS3.
4. Continue operations through the normal UI workflow afterward.

⁠Security model

The service uses a browser-first credential model.

• connection details are sent from the browser with each request
• the backend uses them only during that request
• the backend does not persist them as server-side application secrets
• users may keep them in their own browser storage if they choose

For lab development, HTTP may be acceptable. For any shared, production, or customer-facing environment, HTTPS should be treated as mandatory.

⁠NetBox integration behavior

The NetBox integration layer creates and maintains the metadata needed for reliable synchronization.

This includes:

• custom fields for GNS3-related metadata
• template choice sets
• template-to-device mapping support
• lab-node position metadata such as X/Y coordinates

For the standard naming used by the UI and project documentation, see TERMINOLOGY.md⁠.

The implementation also includes compatibility handling for NetBox environments that reject empty choice sets during initialization.

⁠Special GNS3 nodes

Some GNS3 nodes do not behave like normal routers, switches, or endpoint templates.

Current special handling includes:

• NAT
• Cloud

These node types can still appear in supported workflows, but they are not forced through the same fixed-interface expectations as standard device templates. This reduces false failures during validation and synchronization.

⁠NAT-facing configuration guidance

For links connected to a GNS3 NAT node, YAML generation and configuration logic should not assume a fixed external subnet, gateway, or NAT-side address.

When the selected config driver supports it, DHCP should be preferred on the NAT-facing routed interface. Static addressing should be used only when the platform or lab requirement explicitly requires it.

⁠Running the service inside a GNS3-hosted container

If this application is deployed inside a Docker container that also lives inside a GNS3 topology, the container may not be able to reach the GNS3 VM or GNS3 API by default.

This is a connectivity design issue in the hosting topology, not an application defect.

⁠Recommended workaround

Create a TAP interface on the GNS3 host and connect it into the topology through a Cloud node.

Run on the GNS3 host:

ip tuntap add dev tap-host mode tap
ip link set tap-host up
ip route replace <container-ip>/32 dev tap-host

Important notes:

• do not assign a /24 address to tap-host
• use a /32 host route for the service container IP
• this avoids return-path issues on the management network

Then:

1. Add a Cloud node in GNS3.
2. Bind the Cloud node to tap-host.
3. Connect it to the switch or segment used by the service container.

Example:

GNS3 host
    |
 tap-host
    |
  Cloud
    |
  Switch
    |
Service container

For most users, deploying the service outside the GNS3 topology is still the simpler and more predictable option.

⁠Intended audience

This project is designed for:

• network engineers
• lab administrators
• training environments
• internal automation teams
• users who want a lightweight bridge between GNS3 and NetBox

It is especially useful when teams want repeatable lab workflows without building a larger custom orchestration stack.

⁠Summary

GNS3 NetBox Manager is intended to make GNS3 and NetBox work together in a practical, operator-friendly way. It focuses on deployable lab workflows, repeatable synchronization, YAML-driven automation, and a safer browser-based credential model while staying small enough to package and run as a standalone service.

⁠GNS3 NetBox Manager Terminology Standard

Last updated: 2026-08-30

⁠Purpose

This document defines the standard product terminology used across the GNS3 NetBox Manager web UI, repository documentation, release notes, and future development work.

Its goal is to keep platform names, workflow names, object names, and action labels consistent.

⁠Product name

• Standard name: GNS3 NetBox Manager
• Do not shorten to: GNS3-NetBox, NetBox Manager, or other mixed variants in user-facing text unless space is severely limited

⁠Platform names

• GNS3
• NetBox

Use these exact capitalizations in all user-facing text.

⁠Primary workflow areas

Use these exact names for the main UI areas:

• GNS3 Projects
• NetBox GNS3 Labs
• YAML Lab
• System Integration
• Settings

⁠Source object names

Use the platform-native object names when referring to actual records in each system:

• GNS3 object: Project
• GNS3 device object: Node
• GNS3 template object: Template
• NetBox lab container: Location
• NetBox device object: Device
• NetBox device model object: Device Type
• NetBox interface object: Interface
• NetBox cable object: Cable

⁠Workflow wording rules

When describing a workflow area, use the UI-area name.

Examples:

• Open GNS3 Projects
• Open NetBox GNS3 Labs
• Use YAML Lab

When describing the underlying platform object, use the native object name.

Examples:

• Import the GNS3 Project into NetBox
• Deploy the NetBox Location to GNS3
• Update configuration from the NetBox Location

⁠Standard action labels

Use these exact labels for major actions:

• Refresh Projects
• Check All Project Sync
• Compare with NetBox
• Import to NetBox
• Close Project
• Delete GNS3 Project
• Refresh NetBox Labs
• Preview
• Deploy to GNS3
• Update Config
• Delete NetBox Lab
• Validate YAML
• Apply to NetBox
• Initialize / Sync Integration
• View GNS3 Templates

⁠Standard status and result wording

Preferred result phrases:

• GNS3 Project Deployment Successful
• NetBox Lab Deployment Successful
• Integration synchronization completed successfully.

Preferred object references in messages:

• GNS3 Project
• NetBox Location
• NetBox Lab

Use NetBox Lab for workflow-level success or failure messaging. Use NetBox Location when referring to the actual NetBox object.

⁠Documentation heading standard

Preferred documentation headings:

• GNS3 Project Import to NetBox
• NetBox Lab Deployment to GNS3
• GNS3 Project Configuration Pull to NetBox
• Docker Deployment
• Docker Hub Deployment
• System Integration

⁠Terms to avoid in user-facing text

Avoid these inconsistent or informal variants:

• Netbox
• labnode
• Delete NetBox
• Compare NetBox
• Check All Sync
• Initialize NetBox
• Connections when the intended page is System Integration

⁠Change management rule

If a future feature introduces a new device family, workflow, or page, its user-facing name should be added to this file first, then applied consistently across:

• templates
• README
• repository overview
• release notes
• development notes