gns3-server/docs/features/compute-controller-setup.md

This documentation is organized by AI with reference to actual code. AI can make mistakes — please verify against the source code when in doubt.

Controller + Compute Setup

This document describes the minimum configuration required to set up a GNS3 Controller with remote Compute nodes.

Architecture Overview

• Compute: Runs individual nodes (QEMU, Docker, etc.) and provides resource monitoring
• Controller: Manages multiple computes, projects, and provides the REST API
• Database: Controller uses SQLite to store projects, nodes, and compute registration

Minimum Configuration

1. Compute Node Configuration

Create the configuration file at ~/.config/GNS3/3.1/gns3_server.conf:

[Server]
host = 0.0.0.0
port = 3080
compute_username = gns3
compute_password = gns3

Start the Compute:

gns3server

2. Controller Node Configuration

Create the configuration file at ~/.config/GNS3/3.1/gns3_server.conf:

[Server]
host = 192.168.1.140
port = 3080
compute_username = gns3
compute_password = gns3

Start the Controller:

gns3server

3. Register Compute with Controller

Use the API to register a remote compute:

POST /v3/computes
{
  "protocol": "http",
  "host": "192.168.1.x",
  "port": 3080,
  "user": "gns3",
  "password": "gns3"
}

Important Notes

Host Configuration

• Controller host: If set to 0.0.0.0, it will be changed to 127.0.0.1, which breaks cross-subnet link creation
• Solution: Always use the actual IP address for Controller's host field

Password Configuration

• If compute_password is not set, a random 16-character password is auto-generated on startup
• The Controller must use the same credentials as the Compute's configuration

Network Requirements

• Controller and Compute must be on the same LAN for cross-compute links to work
• UDP tunnel is used for cross-compute links, requiring network connectivity on UDP ports

Configuration File Location

• Default location: ~/.config/GNS3/3.1/gns3_server.conf
• Version 3.0 uses ~/.config/GNS3/3.0/

Troubleshooting

401 Unauthorized on Compute Connect

1. Check that Compute's compute_username and compute_password match what was passed to the API
2. Verify the Compute's configuration file is correctly loaded
3. Ensure the [Server] section is used (not [Controller])

No Common Subnet Error

1. Verify Controller's host is set to its actual IP, not 0.0.0.0
2. Ensure both machines are on the same network
3. Check firewall rules allow UDP communication

Controller Hostname Unreachable

If the controller machine uses a hostname defined in /etc/hosts (e.g., guobin.localhost), and the compute node reports:

Cannot get an IP address on same subnet: No common subnet for compute X (controller) and Y

1. Symptom: The controller's hostname resolves to an IP that is unreachable from the compute node
2. Root Cause: The /etc/hosts entry for the controller's hostname points to a stale or unreachable IP address
3. Solution:
   • Ensure the controller's hostname in /etc/hosts resolves to the correct, reachable IP address
   • Example (correct):

     192.168.1.104  guobin.localhost
     

   • If the machine's IP is dynamic (DHCP), consider:
     • Setting a DHCP static lease on the router for a fixed IP
     • Using mDNS (.local domain) if supported by the compute node