Gns3 Lab Automation

GNS3 Lab Automation Skill

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 (prevents partial failures)
• Structured Results: Clear success/failure status per operation
• Timing: Execution time tracking for performance analysis
• Flexibility: Mix different operation types in one batch
• Error Isolation: Failed operations don't stop the batch, all results returned

Coordinate System and Topology Layout

GNS3 uses a specific coordinate system for positioning elements:

Node Positioning:

• Node coordinates (x, y) represent the top-left corner of the node icon
• Icon sizes:
  • PNG images: 78×78 pixels (custom device icons)
  • SVG/internal icons: 58×58 pixels (built-in icons)
• Node center is at (x + icon_size/2, y + icon_size/2)
• Example: Node at (100, 100) with PNG icon has center at (139, 139)

Label Positioning:

• Node labels are stored as offsets from node top-left to label box top-left
• GNS3 API returns: label: {x: -10, y: -25, text: "Router1", rotation: 0, style: "..."}
• The offset (x, y) represents: node_top_left → label_box_top_left
• Label box contains text that is right-aligned and vertically centered within the box
• Text alignment: text-anchor: end; dominant-baseline: central

Link Connections:

• Links connect to the center of nodes, not the top-left corner
• Connection point: (node_x + icon_size/2, node_y + icon_size/2)
• When using set_connection(), specify which adapter and port on each node

Drawing Objects (v0.8.0 - Unified create_drawing):

• Create drawings with create_drawing(drawing_type, x, y, ...) where type is "rectangle", "ellipse", "line", or "text"
• All drawing coordinates (x, y) represent the top-left corner of bounding box
• Rectangle: create_drawing("rectangle", x, y, width=W, height=H, fill_color="#fff", border_color="#000")
• Ellipse: create_drawing("ellipse", x, y, rx=50, ry=30, fill_color="#fff", border_color="#000")
• Line: create_drawing("line", x, y, x2=100, y2=50, border_color="#000", border_width=2) - ends at (x+x2, y+y2)
• Text: create_drawing("text", x, y, text="Label", font_size=10, color="#000", font_weight="normal")
• Z-order: 0 = behind nodes (backgrounds), 1 = in front of nodes (labels)

Topology Export:

• Use export_topology_diagram() to create SVG/PNG screenshots
• Renders nodes with actual icons, links, drawings, and labels
• All positioning respects the coordinate system above
• Output includes:
  • Visual status indicators on nodes (started=green, stopped=red)
  • Port status indicators on links (active=green circles, shutdown=red circles)
  • Preserved fonts and styling from GNS3

Layout Best Practices:

• Minimum spacing to avoid overlaps:
  • Horizontal: 150-200px between node icons
  • Vertical: 100-150px between node icons
  • Site rectangles: 250-350px wide, 200-300px tall
  • Padding around elements: 50px minimum
• Site organization:
  • Place background rectangles at z=0 (behind nodes)
  • Place site labels at z=1 (in front of rectangles)
  • Position site labels 30px above rectangle top edge
  • Center nodes within site rectangles for clean layout
• Node positioning:
  • PNG icons (78×78): Need more spacing than SVG icons (58×58)
  • Account for label width when positioning adjacent nodes
  • Estimated label width: text_length * font_size * 0.6
• Connection planning:
  • Consider link paths when positioning nodes
  • Avoid crossing links where possible for clarity
  • Star topologies: Central node with radial connections
  • Mesh topologies: Triangular or grid layouts work best

Common Workflows

Starting a Lab Environment

1. List projects to find your lab
2. Open the target project
3. List nodes to see topology
4. Start nodes in order (usually: core switches → routers → endpoints)
5. Wait ~30-60s for devices to boot
6. Verify status with list_nodes

Configuring a Router via Console

1. Ensure node is started (use set_node if needed)
2. Send initial newline to wake console: send_console("Router1", "\n")
3. Read output to see prompt: read_console("Router1")
4. Send configuration commands one at a time
5. Always read output after each command to verify
6. Default behavior (v0.8.0): returns only new output since last read
7. Disconnect when done: disconnect_console("Router1")

Example:

send_console("R1", "\n")
read_console("R1")  # See prompt (diff mode default since v0.9.0)
send_console("R1", "show ip interface brief\n")
read_console("R1")  # See command output (only new lines)
disconnect_console("R1")  # Clean up when done

Using send_and_wait_console for Automation

For automated workflows, send_and_wait_console() simplifies command execution by waiting for specific prompts:

Workflow:
1. First, identify the prompt pattern
   - Send \n and read output to see what prompt looks like
   - Note the exact prompt: "Router#", "[admin@MikroTik] >", "switch>", etc.

2. Use the prompt pattern in automated commands
   - send_and_wait_console(node, command, wait_pattern=<prompt>)
   - Tool waits until prompt appears, then returns all output

3. No need to manually wait or read - tool handles timing

Example - Automated configuration:

# Step 1: Identify the prompt
send_console("R1", "\n")
output = read_console("R1")  # Output shows "Router#"

# Step 2: Use prompt pattern for automation
result = send_and_wait_console("R1",
    "show ip interface brief\n",
    wait_pattern="Router#",
    timeout=10)
# Returns when "Router#" appears - command is complete

# Step 3: Continue with more commands
result = send_and_wait_console("R1",
    "configure terminal\n",
    wait_pattern="Router\\(config\\)#",  # Prompt changes in config mode
    timeout=10)

When to use send_and_wait_console:

• Automated scripts where you know the expected prompts
• Long-running commands that need completion confirmation
• Interactive menus where you need to wait for specific text

When to use send_console + read_console:

• Interactive troubleshooting where prompts may vary
• Exploring unknown device states
• When you need fine-grained control over timing

Console Best Practices

• Always read console output after sending commands
• Wait 1-2 seconds between commands for device processing
• Send \n (newline) first to wake up console
• Look for prompts (>, #) in output to confirm device is ready
• Default behavior (v0.9.0): read_console() returns only new output since last read (diff mode)
• Last page mode: Use read_console(node, mode="last_page") for last ~25 lines
• Full buffer: Use read_console(node, mode="all") for entire console history
• Before using send_and_wait_console(): First check what the prompt looks like with read_console()
  • Different devices have different prompts: Router#, [admin@MikroTik] >, switch>, etc.
  • Use the exact prompt pattern in wait_pattern parameter to ensure command completion
  • Example: Send \n, read output to see Router#, then use wait_pattern="Router#" for commands
  • This prevents missing output or waiting for wrong prompt
• No need to manually connect - auto-connects on first send/read
• Disconnect when done to free resources (30min timeout otherwise)
• For RouterOS (MikroTik): default user admin, empty password
• For Arista vEOS: default user admin, no password

Troubleshooting Connectivity

1. Check node status (all started?)
2. Verify console access (can you connect?)
3. Check interfaces: send "show ip interface brief" or equivalent
4. Check routing: send "show ip route"
5. Test ping: send "ping <target_ip>"
6. Read output after each command

Topology Visualization (v0.33.0)

Viewing Diagrams: Use the diagram resource to quickly visualize lab topology:

# Get topology as SVG
diagram = read_resource("diagrams://{project_id}/topology")

Exporting Diagrams: Use export_topology_diagram() tool to save diagrams as files:

# Export as both SVG and PNG
export_topology_diagram(
    output_path="/path/to/topology",
    format="both"  # or "svg", "png"
)

# Export with crop region
export_topology_diagram(
    output_path="/path/to/cropped",
    format="png",
    crop_x=100, crop_y=100,
    crop_width=800, crop_height=600
)

Diagram Features:

• Node positions, status indicators (color-coded by status)
• Network links with connection information
• Drawing objects (labels, shapes, annotations)
• Automatic layout based on node coordinates
• SVG format: scalable, text-based, ideal for AI analysis
• PNG format: rasterized for sharing/presentation

Use Cases:

• Document lab topology
• Visual topology review before making changes
• Share lab configuration with team
• Analyze network layout and connectivity patterns

MCP Prompts - Guided Workflows (v0.17.0)

MCP prompts provide step-by-step guidance for complex multi-step operations.

Available Prompts

ssh_setup - Device-Specific SSH Configuration

• Covers 6 device types: Cisco IOS, NX-OS, MikroTik, Juniper, Arista, Linux
• Step-by-step instructions from console configuration to SSH session establishment
• Device-specific commands with parameter placeholders
• Troubleshooting guidance for common SSH issues

Usage:

Call the ssh_setup prompt with device_type parameter
Example: ssh_setup(device_type="cisco_ios", node_name="R1")

topology_discovery - Network Topology Discovery and Visualization

• Guides through using MCP resources to browse projects/nodes/links
• Instructions for export_topology_diagram tool usage
• Topology pattern analysis (hub-and-spoke, mesh, tiered, etc.)
• Common topology questions to answer during discovery

Usage:

Call the topology_discovery prompt to start guided discovery
The prompt walks through resource browsing and diagram export

troubleshooting - OSI Model-Based Systematic Troubleshooting

• Layer 1-7 troubleshooting methodology
• Common issues and resolutions for each layer
• Console and SSH troubleshooting workflows
• Performance analysis and log collection

Usage:

Call the troubleshooting prompt for systematic diagnosis
Example: troubleshooting(node_name="R1", issue="connectivity")

lab_setup - Automated Topology Creation (v0.18.0)

• Creates complete topologies with single command
• 6 topology types: star, mesh, linear, ring, OSPF, BGP
• Automatic node positioning using layout algorithms
• IP addressing schemes

Topology types:

• star: Hub-and-spoke (parameter: spoke_count)
• mesh: Full mesh (parameter: router_count)
• linear: Chain topology (parameter: router_count)
• ring: Circular topology (parameter: router_count)
• ospf: Multi-area OSPF (parameter: area_count, 3 routers per area)
• bgp: Multiple AS (parameter: AS_count, 2 routers per AS)

Usage:

Call the lab_setup prompt with topology_type and device_count
Example: lab_setup(topology_type="ospf", device_count=3)

node_setup - Complete Node Setup Workflow (v0.23.0)

• End-to-end workflow for adding new node to lab
• Covers: create, boot, configure IP, document, establish SSH
• Device-specific configuration commands (Cisco IOS, Linux, MikroTik)
• Automatic project README documentation updates
• SSH session verification

Workflow steps:

1. Create node from template at specified coordinates
2. Start node and wait for boot completion (device-specific timing)
3. Configure IP address via console (device-specific commands)
4. Document IP/credentials in project README
5. Establish and verify SSH session for automation

Usage:

Call the node_setup prompt to get guided workflow
Example: node_setup(template_name="Cisco IOSv", node_name="R1",
                    x=100, y=100, ip_address="10.1.1.1/24")

SSH Automation (v0.12.0)

SSH automation via Netmiko for advanced device management. Requires SSH proxy container deployed to GNS3 host.

Prerequisites

SSH must be enabled on device first using console tools:

Cisco IOS:

send_console('R1', 'configure terminal\n')
send_console('R1', 'username admin privilege 15 secret cisco123\n')
send_console('R1', 'crypto key generate rsa modulus 2048\n')
send_console('R1', 'ip ssh version 2\n')
send_console('R1', 'line vty 0 4\n')
send_console('R1', 'login local\n')
send_console('R1', 'transport input ssh\n')
send_console('R1', 'end\n')

MikroTik RouterOS:

send_console('MT1', '/user add name=admin password=admin123 group=full\n')
send_console('MT1', '/ip service enable ssh\n')

Basic SSH Workflow

1. Configure SSH Session:

configure_ssh('R1', {
    'device_type': 'cisco_ios',
    'host': '10.10.10.1',
    'username': 'admin',
    'password': 'cisco123'
})

2. Execute Commands:

# Show commands
ssh_send_command('R1', 'show ip interface brief')
ssh_send_command('R1', 'show running-config')

# Configuration commands
ssh_send_config_set('R1', [
    'interface GigabitEthernet0/0',
    'ip address 192.168.1.1 255.255.255.0',
    'no shutdown'
])

3. Review History:

# List recent commands
ssh_get_history('R1', limit=10)

# Search history
ssh_get_history('R1', search='interface')

# Get specific command output
ssh_get_command_output('R1', job_id='...')

Session Management (v0.1.6)

SSH sessions are automatically managed with the following features:

30-Minute Session TTL:

• Sessions automatically expire after 30 minutes of inactivity
• Activity timestamp updated on every operation:
  • SSH command execution (ssh_send_command, ssh_send_config_set)
  • Buffer reads (via resources)
  • Session configuration (reuse of existing session)
• Expired sessions are automatically detected and recreated
• No manual intervention required

Session Health Checks:

• Before reusing existing sessions, health checks verify connection is still alive
• Health check methods:
  1. Netmiko is_alive() if available (Netmiko 4.0+)
  2. Lightweight empty command test (fallback)
• Stale/closed connections automatically recreated
• Ensures reliable session reuse

Auto-Recovery from Stale Sessions (THE KEY FEATURE):

When commands fail with "Socket is closed":

1. Stale session automatically removed from session manager
2. Error response includes error_code="SSH_DISCONNECTED" and suggested_action
3. Just retry configure_ssh() with same parameters - no force needed!
4. Fresh session will be created automatically
5. Retry your ssh_command() - it will work

Recovery Workflow:

# 1. Command fails with "Socket is closed"
result = ssh_send_command('R1', 'show version')
# Returns: error_code="SSH_DISCONNECTED",
#          suggested_action="Session was stale and has been removed. Reconnect..."

# 2. Simply retry configure_ssh() - NO force parameter needed
#    Stale session already cleaned up, new session will be created
configure_ssh('R1', device_dict)

# 3. Retry command - works now
result = ssh_send_command('R1', 'show version')  # ✅ Works

Force Recreation Parameter (rarely needed):

• Use force=True ONLY for: credential changes, manual troubleshooting
• NOT needed for stale session recovery (auto-cleanup handles it)
• Example:

# Force recreation to change credentials (uncommon use case)
configure_ssh('R1', device_dict, force=True)

Error Codes (v0.1.6):

• SSH_DISCONNECTED - Session closed (stale connection) → Just retry configure_ssh()
• TIMEOUT - Command timed out → Increase read_timeout parameter
• COMMAND_FAILED - Generic command failure → Check command syntax

Adaptive Async for Long Commands

For long-running operations (firmware upgrades, backups):

# Start command, return job_id immediately
result = ssh_send_command('R1', 'copy running-config tftp:', wait_timeout=0)
job_id = result['job_id']

# Poll for completion
status = ssh_get_job_status(job_id)
# Returns: {completed, output, execution_time}

# For 15+ minute commands:
ssh_send_command('R1', 'upgrade firmware', read_timeout=900, wait_timeout=0)

Supported Device Types

200+ device types via Netmiko:

• cisco_ios - Cisco IOS/IOS-XE
• cisco_nxos - Cisco Nexus
• juniper - Juniper JunOS
• arista_eos - Arista EOS
• mikrotik_routeros - MikroTik RouterOS
• linux - Linux/

…(truncated)