gns3-lab-automation

Overview

GNS3 (Graphical Network Simulator-3) is a network emulation platform for building complex network topologies. This skill provides knowledge for automating GNS3 lab operations through the MCP server.

Key Features (Must Know!)

🗒️ Project Notes/Memory System

Problem: Lab configurations consume conversation context (IPs, credentials, architecture notes) Solution: Store persistent notes in per-project README

When to use:

• ✅ Always read notes when starting work on a project
• ✅ Update notes after configuring new devices
• ✅ Document IP schemes, credentials, topology changes
• ✅ Record troubleshooting findings and solutions

Tools:

• get_project_readme() - Retrieve project documentation
• update_project_readme(content) - Save/update documentation (markdown format)

Resource: projects://{id}/readme (read-only browsing)

Example Workflow:

# 1. Always start by reading existing notes
notes = get_project_readme()

# 2. Do your work (configure router, add nodes, etc.)
# ...

# 3. Update notes with new information
update_project_readme("""
# Lab Configuration

## Network Topology
- Router1: 10.1.0.1/24 (GigabitEthernet0/0)
- Router2: 10.1.0.2/24 (GigabitEthernet0/0)

## Credentials
- Username: admin
- Password: cisco123

## Last Updated
2025-10-26: Added Router2, configured OSPF
""")

📋 Template Usage Notes

Problem: Forgetting default credentials, boot times, device-specific setup steps Solution: Templates include built-in usage notes with device info

What's included:

• Default credentials (username/password)
• Boot timing estimates ("First boot takes 60 seconds...")
• Persistent storage locations ("/root directory persists")
• Console availability and device-specific quirks

How to access:

• For specific node: projects://{id}/nodes/{node_id}/template
• For template: gns3://templates/{template_id}

Example:

# Get usage notes for a MikroTik node you just created
usage = read_resource("projects://{id}/nodes/{node_id}/template")
# Returns: "The login is admin, with no password by default.
#           On first boot, RouterOS is actually being installed..."

Pro Tip: Check template usage before configuring new devices to avoid common mistakes!

Core Concepts

MCP Resources (v0.13.0 - NEW)

MCP resources provide browsable state via standardized URIs, replacing query tools for better IDE integration.

Resource Benefits:

• Browsable in MCP-aware tools (inspectors, IDEs)
• Automatic discovery and autocomplete
• Consistent URI scheme (gns3:// protocol)
• Better performance with resource subscriptions

Available Resources (v0.29.0 - URI Standardization):

Project-Centric Resources:

• projects:// - List all GNS3 projects
• projects://{project_id} - Get project details by ID
• projects://{project_id}/readme - Get project README/notes (v0.23.0)
• projects://{project_id}/sessions/console/ - Console sessions in project (v0.29.1)
• projects://{project_id}/sessions/ssh/ - SSH sessions in project (v0.29.1)

Object-Centric Resources:

• nodes://{project_id}/ - List nodes in project (NodeSummary, table mode v0.30.0)
• nodes://{project_id}/{node_id} - Get node details (full NodeInfo)
• nodes://{project_id}/{node_id}/template - Get template usage notes for node (v0.23.0)
• links://{project_id}/ - List network links in project (table mode v0.30.0)
• drawings://{project_id}/ - List drawing objects (table mode v0.30.0)

Diagram Resources (v0.33.0):

• diagrams://{project_id}/topology - Get topology diagram as SVG (visualize lab layout)

Template Resources (Static, Not Project-Scoped):

• templates:// - List all available templates (table mode v0.30.0)
• templates://{template_id} - Get template details with usage notes (v0.23.0)

Session Resources (Dual Access Patterns v0.29.1):

Path-based (project-scoped):

• projects://{project_id}/sessions/console/ - Console sessions in project
• projects://{project_id}/sessions/ssh/ - SSH sessions in project

Query-parameter-based (filtered):

• sessions://console/?project_id={id} - Console sessions filtered by project
• sessions://ssh/?project_id={id} - SSH sessions filtered by project

Unfiltered (all sessions):

• sessions://console/ - All console sessions across all projects (table mode v0.30.0)
• sessions://console/{node_name} - Console session for specific node
• sessions://ssh/ - All SSH sessions across all projects (table mode v0.30.0)
• sessions://ssh/{node_name} - SSH session status for node
• sessions://ssh/{node_name}/history - SSH command history (table mode v0.30.0)
• sessions://ssh/{node_name}/buffer - SSH continuous buffer

Proxy Resources:

• proxies:///status - Main proxy status (THREE slashes)
• proxies:// - Proxy registry (host + lab proxies, table mode v0.30.0)
• proxies://sessions - All proxy sessions (table mode v0.30.0)
• proxies://project/{project_id} - Proxies for specific project
• proxies://{proxy_id} - Specific proxy details

Resource vs Tool Usage:

• Resources: Query state (read-only) - use for browsing, monitoring
• Tools: Modify state (actions) - use for changes, commands, configuration

Example Resource Workflow:

# Browse resources (read-only)
1. List all projects: projects://
2. Pick project ID from list
3. View nodes: nodes://{project_id}/
4. Check topology diagram: diagrams://{project_id}/topology
5. Check SSH sessions: sessions://ssh/?project_id={project_id}
6. Check SSH session for specific node: sessions://ssh/R1

# Use tools to modify (actions)
7. Call ssh_configure() to create SSH session
8. Call ssh_command() to execute commands
9. Call set_node() to change node state
10. Call export_topology_diagram() to save diagram as PNG/SVG

Removed in v0.14.0 (use MCP resources instead):

• list_projects() → Use resource projects://
• list_nodes() → Use resource nodes://{project_id}/
• get_node_details() → Use resource nodes://{project_id}/{node_id}
• get_links() → Use resource links://{project_id}/
• list_templates() → Use resource templates://
• list_drawings() → Use resource drawings://{project_id}/
• get_console_status() → Use resource sessions://console/{node_name}
• ssh_get_status() → Use resource sessions://ssh/{node_name}
• ssh_get_history() → Use resource sessions://ssh/{node_name}/history
• ssh_get_command_output() → Use resource with filtering
• ssh_read_buffer() → Use resource sessions://ssh/{node_name}/buffer

Final Architecture (v0.34.0):

• 27 Action Tools: Modify state (create, delete, configure, execute commands)
• 21 MCP Resources: Browse state (projects, nodes, sessions, diagrams, proxies) with table mode
• 5 MCP Prompts: Guided workflows (ssh_setup, topology_discovery, troubleshooting, lab_setup, node_setup)
• Clear separation: Tools change things, Resources view things, Prompts guide workflows
• Table Mode (v0.30.0): All list resources use simple table format for readability

Projects

• Projects are isolated network topologies with their own nodes, links, and configuration
• Projects have status: opened or closed
• Always ensure a project is opened before working with nodes
• Use open_project() to activate a project

Nodes

• Nodes represent network devices (routers, switches, servers, etc.)
• Node types: qemu (VMs), docker (containers), ethernet_switch, nat, etc.
• Node status: started or stopped
• Each node has a unique node_id and human-readable name

Node Deletion & Cleanup (v0.34.0):

• delete_node(node_name) removes node from project
• Automatic SSH session cleanup: When a node is deleted, all SSH sessions are automatically cleaned up:
  • Disconnects SSH sessions on ALL registered proxies (host proxy + lab proxies)
  • Cleans up internal session mappings
  • Best-effort cleanup - won't block deletion if cleanup fails
• Why: Prevents orphaned SSH sessions consuming resources
• Example:

  delete_node("Router1")
  # Automatically:
  # 1. Deletes node from GNS3
  # 2. Disconnects SSH session if active
  # 3. Cleans up proxy mappings
  # No manual cleanup needed!
  

Choosing Between SSH and Console Tools

IMPORTANT: Always prefer SSH tools when available!

Use SSH Tools For:

• Production automation workflows
• Configuration management
• Command execution on network devices
• Better reliability with automatic prompt detection
• Structured output and error handling
• Available SSH tools: ssh_send_command(), ssh_send_config_set(), ssh_read_buffer(), ssh_get_history()

Use Console Tools Only For:

• Initial device configuration (enabling SSH, creating users, generating keys)
• Troubleshooting when SSH is unavailable or broken
• Devices without SSH support (VPCS, simple switches)
• Interactive TUI navigation (vim, menu systems)

Typical Workflow:

1. Start with console tools to configure SSH access
2. Establish SSH session with configure_ssh()
3. Switch to SSH tools for all automation
4. Return to console only if SSH fails

Local Execution on SSH Proxy Container (v0.28.0)

Use node_name="@" to execute commands directly on the SSH proxy container.

Why Use Local Execution:

• Test connectivity before accessing devices (ping, traceroute)
• Run ansible playbooks from /opt/gns3-ssh-proxy mount
• Execute diagnostic tools not available on network devices
• Orchestrate multi-device operations with custom scripts

Available Tools:

• Network diagnostics: ping, traceroute, ip, ss, netstat
• DNS queries: dig, nslookup
• HTTP client: curl
• Automation: ansible-core, python3, bash
• Working directory: /opt/gns3-ssh-proxy (shared with host)

Key Advantages:

• No ssh_configure() needed
• Direct access to diagnostic tools
• Ansible playbooks can orchestrate multiple devices
• Mix local and remote commands in ssh_batch()

Examples:

# Test connectivity before device access
ssh_command("@", "ping -c 3 10.10.10.1")

# Run ansible playbook (mounted from host)
ssh_command("@", "ansible-playbook /opt/gns3-ssh-proxy/backup.yml -i inventory")

# DNS lookup for lab devices
ssh_command("@", "dig router1.lab.local")

# Bash script (list of commands)
ssh_command("@", [
    "cd /opt/gns3-ssh-proxy",
    "python3 backup_configs.py",
    "ls -la backups/"
])

# Batch operations - test connectivity then configure devices
ssh_batch([
    {"type": "send_command", "node_name": "@", "command": "ping -c 2 10.1.1.1"},
    {"type": "send_command", "node_name": "@", "command": "ping -c 2 10.1.1.2"},
    {"type": "send_command", "node_name": "R1", "command": "show ip int brief"},
    {"type": "send_command", "node_name": "R2", "command": "show ip int brief"}
])

File Sharing with Host:

1. Place files in /opt/gns3-ssh-proxy/ on GNS3 host
2. Access same path in container
3. Useful for: ansible playbooks, Python scripts, configuration templates

Note: Local execution returns {success, output, exit_code} instead of SSH job format.

Error Responses

All tools return standardized error responses (v0.20.0) with machine-readable error codes and actionable guidance.

Error Response Structure:

{
  "error": "Human-readable error message",
  "error_code": "MACHINE_READABLE_CODE",
  "details": "Additional error details",
  "suggested_action": "How to fix the error",
  "context": {
    "parameter": "value",
    "debugging_info": "..."
  },
  "server_version": "0.20.0",
  "timestamp": "2025-10-25T14:30:00.000Z"
}

Error Code Categories:

Resource Not Found (404-style):

• PROJECT_NOT_FOUND - No project open or project doesn't exist
• NODE_NOT_FOUND - Node name not found in project
• LINK_NOT_FOUND - Link ID doesn't exist
• TEMPLATE_NOT_FOUND - Template name not available
• DRAWING_NOT_FOUND - Drawing ID not found
• SNAPSHOT_NOT_FOUND - Snapshot name doesn't exist

Validation Errors (400-style):

• INVALID_PARAMETER - Invalid parameter value
• MISSING_PARAMETER - Required parameter not provided
• PORT_IN_USE - Port already connected to another node
• NODE_RUNNING - Operation requires node to be stopped
• NODE_STOPPED - Operation requires node to be running
• INVALID_ADAPTER - Adapter name/number not valid for node
• INVALID_PORT - Port number exceeds adapter capacity

Connection Errors (503-style):

• GNS3_UNREACHABLE - Cannot connect to GNS3 server
• GNS3_API_ERROR - GNS3 server API error
• CONSOLE_DISCONNECTED - Console session lost
• CONSOLE_CONNECTION_FAILED - Failed to connect to console
• SSH_CONNECTION_FAILED - Failed to establish SSH session
• SSH_DISCONNECTED - SSH session lost

Authentication Errors (401-style):

• AUTH_FAILED - Authentication failed
• TOKEN_EXPIRED - JWT token expired
• INVALID_CREDENTIALS - Wrong username/password

Internal Errors (500-style):

• INTERNAL_ERROR - Server internal error
• TIMEOUT - Operation timed out
• OPERATION_FAILED - Generic operation failure

Example Error Handling:

# Attempt to start a node
result = set_node("Router1", action="start")

# Check for errors
if "error" in result:
    error = json.loads(result)
    if error["error_code"] == "NODE_NOT_FOUND":
        # Use suggested_action to fix
        print(error["suggested_action"])  # "Use list_nodes() to see all available nodes"
        # Check available nodes from context
        print(error["context"]["available_nodes"])  # ["Router2", "Router3", "Switch1"]
    elif error["error_code"] == "GNS3_UNREACHABLE":
        # Server connection issue
        print(f"Cannot reach GNS3 at {error['context']['host']}:{error['context']['port']}")

Common Error Scenarios:

1. No project open: Most tools require an open project

   • Error: PROJECT_NOT_FOUND
   • Fix: open_project("ProjectName")

2. Node not found: Typo in node name (case-sensitive)

   • Error: NODE_NOT_FOUND
   • Fix: Check available_nodes in error context or use resource projects://{id}/nodes/

3. Port already in use: Trying to connect already-connected port

   • Error: PORT_IN_USE
   • Fix: Disconnect existing link first with set_connection([{"action": "disconnect", "link_id": "..."}])

4. Node must be stopped: Trying to modify running node properties

   • Error: NODE_RUNNING
   • Fix: set_node("NodeName", action="stop") then retry

Tool Annotations (v0.19.0)

MCP tool annotations provide metadata to IDE/MCP clients for better UX and safety.

destructive (3 tools):

• delete_node, restore_snapshot, delete_drawing
• IDE may show warnings or require confirmation
• These operations delete data or make irreversible changes
• Always create backups before using destructive tools

idempotent (9 tools):

• open_project, create_project, close_project, set_node
• console_disconnect, ssh_configure, ssh_disconnect
• update_drawing, export_topology_diagram
• Safe to retry - same operation produces same result
• Example: Opening already-opened project is safe

read_only (1 tool):

• console_read
• Tool only reads data, makes no state changes
• May be cached by MCP clients

creates_resource (5 tools):

• create_project, create_node, create_snapshot
• export_topology_diagram, create_drawing
• Tool creates new resources (in GNS3 or filesystem)

modifies_topology (3 tools):

• set_connection, create_node, delete_node
• Tool changes network topology structure
• May require project reload in GNS3 GUI

Console Access

• Nodes have console ports for CLI access
• Console types:
  • telnet: CLI access (most routers/switches) - currently supported
  • vnc: Graphical access (desktops/servers) - not yet supported
  • spice+agent: Enhanced graphical - not yet supported
  • none: No console
• Auto-connect workflow (v0.2.0):
  1. Just use console_send(node_name, command) - automatically connects if needed
  2. Read output with console_read(node_name) - returns new output since last read (diff mode, default since v0.9.0)
  3. Or use console_read(node_name, mode="last_page") for last ~25 lines
  4. Or use console_read(node_name, mode="all") for full buffer
  5. Disconnect with console_disconnect(node_name) when done
• Sessions are managed automatically by node name
• Session timeout: 30 minutes of inactivity

Console State Tracking (v0.34.0):

• IMPORTANT: Must read console BEFORE sending commands
• Why: Ensures you understand current terminal state (prompt, login screen, etc.)
• Enforced: All send operations (console_send, console_send_and_wait, console_keystroke) check access state
• Workflow:
  1. First: console_read("R1") - Check terminal state (are you at login? prompt? password?)
  2. Then: console_send("R1", "command\n") - Send appropriate command
  3. Read again: console_read("R1") - Verify command executed
• Error: If you try to send without reading first, you'll get:

  "Cannot send to console - terminal not accessed yet.
   Use console_read() to check current terminal state first."
  

• Best Practice: Always read → send → read pattern for reliable automation

Interactive Console Automation (v0.21.1)

For workflows that need to wait for specific prompts before proceeding:

Tool: console_send_and_wait(node_name, command, wait_pattern, timeout, raw)

Best Practice Workflow:

1. Check the prompt first - See what you're waiting for:

   console_send("R1", "\n")  # Wake console
   output = console_read("R1")  # Check output: "Router#"
   

2. Use that pattern in console_send_and_wait:

   result = console_send_and_wait(
       "R1",
       "show ip interface brief\n",
       wait_pattern="Router#",  # Wait for this exact prompt
       timeout=10
   )
   

3. Check the result:

   {
       "output": "Interface    IP-Address   ...\nGi0/0        192.168.1.1  ...\nRouter#",
       "pattern_found": true,
       "timeout_occurred": false,
       "wait_time": 0.8
   }
   

Use Cases:

• Interactive logins: Wait for "Login:" prompt
• Command completion: Wait for prompt to return before next command
• Configuration mode: Wait for "(config)#" before sending configs
• Reboots: Wait for boot messages to complete

Examples:

# Wait for login prompt
console_send_and_wait("R1", "\n", wait_pattern="Login:", timeout=30)

# Wait for enable prompt
console_send_and_wait("R1", "enable\n", wait_pattern="#", timeout=5)

# Configuration mode
console_send_and_wait("R1", "configure terminal\n", wait_pattern="(config)#", timeout=5)

# No pattern - just wait 2 seconds and return output
console_send_and_wait("R1", "save config\n")

Pattern Matching:

• Supports regex patterns: "Router[>#]" matches "Router>" OR "Router#"
• Pattern search is case-sensitive by default
• If wait_pattern=None, waits 2 seconds and returns output
• Polls console every 0.5 seconds until pattern found or timeout

Error Handling:

• Invalid regex: Returns error with error_code="INVALID_PARAMETER"
• Console disconnected: Returns error with error_code="CONSOLE_DISCONNECTED"
• Timeout without pattern: Sets timeout_occurred=true, still returns accumulated output

When to Use:

• ✅ Interactive console workflows (logins, menus, confirmations)
• ✅ Ensuring command completion before next step
• ✅ Boot sequences with specific prompts
• ❌ Simple command execution - use console_send() + console_read() instead
• ❌ SSH-capable devices - use ssh_command() for better reliability

Batch Console Operations (v0.22.0)

For workflows that need to execute multiple console operations efficiently:

Tool: console_batch(operations) - Execute multiple console operations with two-phase validation

Two-Phase Execution:

1. VALIDATE ALL operations (check nodes exist, required params present)
2. EXECUTE ALL operations (only if all valid, sequential execution)

Supported Operation Types: Each operation in the batch can be any of these types with full parameter support:

1. "send" - Send data to console

   {
       "type": "send",
       "node_name": "R1",
       "data": "show version\n",
       "raw": false  // optional
   }
   

2. "send_and_wait" - Send command and wait for pattern

   {
       "type": "send_and_wait",
       "node_name": "R1",
       "command": "show ip interface brief\n",
       "wait_pattern": "Router#",  // optional
       "timeout": 30,  // optional
       "raw": false  // optional
   }
   

3. "read" - Read console output

   {
       "type": "read",
       "node_name": "R1",
       "mode": "diff",  // optional: diff/last_page/num_pages/all
       "pattern": "error",  // optional grep pattern
       "case_insensitive": true  // optional
   }
   

4. "keystroke" - Send special keystroke

   {
       "type": "keystroke",
       "node_name": "R1",
       "key": "enter"  // up/down/enter/ctrl_c/etc
   }
   

Use Case 1: Multiple Commands on One Node

console_batch([
    {"type": "send_and_wait", "node_name": "R1", "command": "show version\n", "wait_pattern": "Router#"},
    {"type": "send_and_wait", "node_name": "R1", "command": "show ip route\n", "wait_pattern": "Router#"},
    {"type": "send_and_wait", "node_name": "R1", "command": "show running-config\n", "wait_pattern": "Router#"}
])

Use Case 2: Same Command on Multiple Nodes (Parallel Analysis)

console_batch([
    {"type": "send_and_wait", "node_name": "R1", "command": "show ip int brief\n", "wait_pattern": "#"},
    {"type": "send_and_wait", "node_name": "R2", "command": "show ip int brief\n", "wait_pattern": "#"},
    {"type": "send_and_wait", "node_name": "R3", "command": "show ip int brief\n", "wait_pattern": "#"}
])

Use Case 3: Mixed Operations (Interactive Workflow)

console_batch([
    {"type": "send", "node_name": "R1", "data": "\n"},  // Wake console
    {"type": "read", "node_name": "R1", "mode": "last_page"},  // Check prompt
    {"type": "send_and_wait", "node_name": "R1", "command": "show version\n", "wait_pattern": "#"},
    {"type": "keystroke", "node_name": "R1", "key": "ctrl_c"}  // Cancel if needed
])

Return Format:

{
    "completed": [0, 1, 2],  // Indices of successful operations
    "failed": [3],  // Indices of failed operations
    "results": [
        {
            "operation_index": 0,
            "success": true,
            "operation_type": "send_and_wait",
            "node_name": "R1",
            "result": {
                "output": "...",
                "pattern_found": true,
                "timeout_occurred": false,
                "wait_time": 1.2
            }
        },
        {
            "operation_index": 3,
            "success": false,
            "operation_type": "send_and_wait",
            "node_name": "R4",
            "error": {
                "error": "Node not found: R4",
                "error_code": "NODE_NOT_FOUND",
                "suggested_action": "..."
            }
        }
    ],
    "total_operations": 4,
    "execution_time": 5.3
}

When to Use:

• ✅ Running same diagnostic command on multiple routers
• ✅ Executing multi-step workflows on one device
• ✅ Gathering data from multiple nodes for comparison/analysis
• ✅ Interactive sequences with validation checks between steps
• ❌ Single operations - use individual tools for simplicity
• ❌ SSH-capable devices - consider SSH batch operations for better reliability

Advantages:

• Validation: All operations validated before execution (

<!-- Content truncated for initial SEO render. Open the source file tab for the full file. -->