mirror of
https://github.com/GNS3/gns3-server.git
synced 2026-09-01 15:54:03 +03:00
f9d1ccc701
Add documentation for the "No common subnet" error when the controller's hostname in /etc/hosts resolves to an unreachable or stale IP address. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
125 lines
3.5 KiB
Markdown
125 lines
3.5 KiB
Markdown
<!--
|
|
SPDX-License-Identifier: CC-BY-SA-4.0
|
|
See LICENSE file for licensing information.
|
|
-->
|
|
|
|
> 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`:
|
|
|
|
```ini
|
|
[Server]
|
|
host = 0.0.0.0
|
|
port = 3080
|
|
compute_username = gns3
|
|
compute_password = gns3
|
|
```
|
|
|
|
Start the Compute:
|
|
```bash
|
|
gns3server
|
|
```
|
|
|
|
### 2. Controller Node Configuration
|
|
|
|
Create the configuration file at `~/.config/GNS3/3.1/gns3_server.conf`:
|
|
|
|
```ini
|
|
[Server]
|
|
host = 192.168.1.140
|
|
port = 3080
|
|
compute_username = gns3
|
|
compute_password = gns3
|
|
```
|
|
|
|
Start the Controller:
|
|
```bash
|
|
gns3server
|
|
```
|
|
|
|
### 3. Register Compute with Controller
|
|
|
|
Use the API to register a remote compute:
|
|
|
|
```bash
|
|
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
|