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, the controller will register itself as 127.0.0.1, which breaks remote compute connections
• Symptom: Compute nodes report "No common subnet for compute X (controller) and Y" even when on the same network
• Solution: Always use the actual LAN IP address for the Controller's host field (e.g., host = 192.168.1.104)
• Dynamic IP: If the controller machine uses DHCP, set a static lease on the router or use mDNS (.local domain)

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

If compute nodes report:

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

1. Primary cause: Controller's host is set to 0.0.0.0 - it registers as 127.0.0.1 which is unreachable from compute nodes
2. Check the controller's /v3/version endpoint - if controller_host shows 127.0.0.1, this is the issue
3. Set the Controller's host to its actual LAN IP address (e.g., 192.168.1.104)
4. Verify both machines are on the same network and can ping each other
5. Check firewall rules allow TCP/UDP communication on required ports

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