GNS3 2.2.61 配置参数详解

目标：把 gns3_server.conf 的每个关键参数讲清楚——默认值是什么、改了到底影响哪段逻辑、哪些参数在 2.2.61 里已经失效。本文所有回显与取值均来自 gns3-server 2.2.61 实机验证（Ubuntu 22.04.5 + Python 3.10.12），并对照 2.2.61 源码逐项确认读取点；安装步骤见 《Ubuntu 22.04 安装 GNS3 2.2.61 服务端指南》，集群编排与接口调用可参考专栏内后续篇目。

一、配置文件位置与加载顺序

1.1 默认查找路径

不显式传 --config 时，2.2.61 按下面的顺序读取配置文件（源码 gns3server/config.py）：

1. ./gns3_server.conf                     （当前工作目录）
2. ~/.config/GNS3/2.2/gns3_server.conf
3. ~/.config/GNS3.conf
4. /etc/gns3/gns3_server.conf
5. /etc/xdg/GNS3/gns3_server.conf
6. /etc/xdg/GNS3.conf

后加载的文件覆盖先加载的同名键，所以 /etc/xdg/GNS3.conf 的优先级最高。生产环境建议显式指定配置文件，避免工作目录不同导致读到的配置不一致：

/opt/gns3/venv/bin/gns3server --config /etc/gns3/gns3_server.conf \
    --log /var/log/gns3/gns3_server.log

systemd 托管时把这两个参数写进 ExecStart，文件改动后 systemctl restart gns3-server 生效。

1.2 配置文件骨架

[Server]
host = 0.0.0.0
port = 3080
config_path = /etc/gns3
projects_path = /var/lib/gns3/projects
images_path = /var/lib/gns3/images
appliances_path = /var/lib/gns3/appliances
symbols_path = /var/lib/gns3/symbols
report_errors = true
local = false

[Qemu]
enable_kvm = false
qemu_path = /usr/bin/qemu-system-x86_64

[Dynamips]
dynamips_path = /usr/bin/dynamips

[VPCS]
vpcs_path = /usr/bin/vpcs

1.3 读到的生效值（实测）

用服务端自带的配置对象打印实际解析结果，避免"写了但没生效"：

/opt/gns3/venv/bin/python -c "
from gns3server.config import Config
c = Config.instance(files=['/etc/gns3/gns3_server.conf'])
for sec in ('Server','Qemu','Dynamips','VPCS'):
    cfg = c.get_section_config(sec)
    print('['+sec+']')
    for k in cfg.keys():
        print('  '+k+' = '+str(cfg.get(k)))
"

[Server]
  host = 0.0.0.0
  port = 3080
  config_path = /etc/gns3
  projects_path = /var/lib/gns3/projects
  images_path = /var/lib/gns3/images
  appliances_path = /var/lib/gns3/appliances
  symbols_path = /var/lib/gns3/symbols
  report_errors = true
  local = false
[Qemu]
  enable_kvm = false
  qemu_path = /usr/bin/qemu-system-x86_64
[Dynamips]
  dynamips_path = /usr/bin/dynamips
[VPCS]
  vpcs_path = /usr/bin/vpcs

这里能看到的只有"显式写进文件"的键；没写的键用源码默认值，下面每节都会标注默认值来源。

1.4 一个高频坑：键写错了节

INI 格式里，键属于它上面最近的那个节标题。实测把鉴权参数追加到文件末尾（当时最后一行属于 [VPCS] 节），重启后鉴权并未开启：

noauth HTTP 200
basic  HTTP 200

把 auth / user / password 挪到 [Server] 节内再重启，行为立即改变：

noauth HTTP 401
basic  HTTP 200

改配置后先确认键在正确的节里，再看日志：

tail -n 3 /var/log/gns3/gns3_server.log

2026-10-27 13:59:17 INFO run.py:236 HTTP authentication is enabled with username 'root'

二、[Server] 节：监听与鉴权

2.1 host / port

端口改动实测：把 port 改为 3081 并重启，监听随之切换，原端口完全无响应：

sed -i 's/^port = 3080/port = 3081/' /etc/gns3/gns3_server.conf
systemctl restart gns3-server
ss -ltnp | grep 308
curl -s -o /dev/null -w 'curl 3080 HTTP %{http_code}\n' --max-time 3 http://127.0.0.1:3080/v2/version
curl -s -o /dev/null -w 'curl 3081 HTTP %{http_code}\n' http://127.0.0.1:3081/v2/version

LISTEN 0      100          0.0.0.0:3081       0.0.0.0:*    users:(("gns3server",pid=3016,fd=14))
curl 3080 HTTP 000
curl 3081 HTTP 200

改端口时别忘了同步 upstream 反代、防火墙与客户端里的地址，否则表现为"服务活着但连不上"。

2.2 ssl / certfile / certkey

开启后本地 compute 的连接协议会自动切成 https，日志会提示：

Protocol changed to 'https' for local compute because SSL is enabled

自签证书场景，客户端需要信任对应 CA，否则表现为 TLS 校验失败而不是鉴权失败。

2.3 auth / user / password

鉴权开启后的实测响应：

curl -s -o /dev/null -w 'noauth HTTP %{http_code}\n' http://127.0.0.1:3080/v2/version
curl -s -o /dev/null -w 'basic  HTTP %{http_code}\n' -u root:q1w2e3r4 http://127.0.0.1:3080/v2/version
curl -s -i http://127.0.0.1:3080/v2/version | head -4

noauth HTTP 401
basic  HTTP 200
HTTP/1.1 401 Unauthorized
Connection: close
X-Route: /v2/version
Server: Python/3.10 GNS3/2.2.61

两个细节值得注意：

• auth = true 但 user 为空时，服务不会带着空账号跑，启动阶段就退出；
• console 的 WebSocket 路径（console/ws）不在鉴权范围内，这是设计行为——浏览器里的 console 连接不带 Basic 头也能建立。

配置权限建议 600，因为密码是明文：

chmod 600 /etc/gns3/gns3_server.conf
ls -l /etc/gns3/gns3_server.conf

-rw------- 1 root root 397 /etc/gns3/gns3_server.conf

2.4 local（本地模式）

local 默认 false。设为 true 时服务以本地模式运行，启动日志会明确警告：

2026-10-27 14:01:05 WARNING run.py:229 Local mode is enabled. Beware, clients will have full control on your filesystem

含义是客户端可以借服务端在本机文件系统上做操作，仅适合"个人单机桌面"场景；多人共用的服务端不要开。

三、[Server] 节：路径类参数

实测要点：

1. projects_path 与 images_path 必须可写。工程创建成功后会立刻在磁盘上落目录：

   ls -l /var/lib/gns3/projects
   

   drwxr-xr-x 5 root root 4096 Oct 27 13:22 9449a0e6-73b7-4796-b4eb-2375267c1726
   

2. 首次启动会向 images_path/QEMU 安装内置磁盘文件（empty8G、empty10G 等），占用约 12 MB，属正常初始化：

   du -sh /var/lib/gns3/images/QEMU
   ls /var/lib/gns3/images/QEMU | head
   

   12M	/var/lib/gns3/images/QEMU
   empty10G.qcow2
   empty8G.qcow2
   

3. config_path 是历史遗留键：源码中对 config_path 的读取点为 0，写了也不影响任何行为（配置文件位置由启动参数 --config 决定）。

4. symbols_path 的默认值是 ~/GNS3/symbols（注意是用户主目录，不是 /var/lib），以 root 运行就是 /root/GNS3/symbols；自定义图标没显示时先查这个目录。

四、[Server] 节：console / UDP 端口与桥接

端口分配由服务端的端口管理器统一管控，从下面的范围里取空闲端口分配给节点 console 与 UDP 通道。

实测记录：

• 节点启动后返回的 console 端口从 5000 开始递增，实测第一个节点为 console 5000、console_host 0.0.0.0。注意 allow_remote_console 为 false 时，console_host 上报的是节点允许的地址，但实际绑定仍受该开关影响，远程直连前先把开关打开：

  grep -a "Remote console connections are allowed" /var/log/gns3/gns3_server.log | tail -1
  

  WARNING port_manager.py:117 Remote console connections are allowed
  

• ubridge_path 写相对路径时按 PATH 查找，找不到就报节点启动失败：

  uBridge is not available, path doesn't exist, or you just installed GNS3 and need to restart your user session to refresh user permissions.
  

  服务器上建议写成绝对路径（如 /usr/bin/ubridge），避免不同启动环境 PATH 不一致。

• default_nat_interface 在 Linux 上默认 virbr0，需要宿主已安装 libvirt 且 virbr0 存在；没有 libvirt 时 NAT 节点会起不来，应改成本机真实出口网卡名，例如：

  default_nat_interface = eth0
  

五、[Server] 节：模板与虚拟化检查

实测与建议：

• enable_builtin_templates = false 时，新装环境里看不到内置模板（路由器/交换机模板列表为空），需要自己导入 appliance 文件；
• hardware_virtualization_check 只做检测与提示，不阻断纯软件模拟的 QEMU 节点启动；在没有硬件虚拟化的机器上如果不想看到相关提示，可以置 false；
• report_errors 内网环境建议保持 false，避免服务端在网络不可达时产生额外的上报重试日志。

六、[Qemu] 节：硬件加速与运行时

QEMU 是 2.2.61 里最常用的节点后端。该节的读取点集中在 qemu_vm.py，共有六个真正生效的键。

6.1 覆盖关系

源码逻辑是"兼容旧键优先"：Linux 上只要 enable_kvm 有值（哪怕是 false），就覆盖 enable_hardware_acceleration；require_kvm 同理覆盖 require_hardware_acceleration。所以配置文件里只写 enable_kvm = false 时，等效于"关闭硬件加速、且不要求硬件加速"。

6.2 实测：KVM 不可用时的行为

本机 /dev/kvm 节点存在但打不开（详见安装篇），enable_kvm = false 时节点正常启动，命令行不带加速参数：

qemu-system-x86_64 -name Q1 ... -machine smm=off ... -display none

改成 enable_kvm = true 后重启服务，再启动同一节点，接口先返回成功：

start HTTP 200

但约 3 秒后节点自动变为 stopped，命令行里已经带上了 -enable-kvm，而日志中没有对应的 KVM 错误提示：

curl -s http://127.0.0.1:3080/v2/projects/$PID/nodes/$NID | python3 -c 'import sys,json;d=json.load(sys.stdin);print(d["status"])'

stopped

这是一个容易被误判的行为：不要只看启动接口的 HTTP 200，必须等几秒再查节点状态。若希望"拿不到硬件加速就明确失败"，应同时设置：

[Qemu]
enable_kvm = true
require_kvm = true

此时启动会直接抛出类似错误，而不是静默退出：

Hardware acceleration can only be used with the following Qemu executables: qemu-system-x86_64, qemu-system-i386, qemu-kvm

6.3 qemu_path 在该节无效（重要）

很多人会在 [Qemu] 节写 qemu_path = /usr/bin/qemu-system-x86_64，以为能固定二进制路径。实测确认：2.2.61 不读取该节的 qemu_path，源码中 qemu_path 只出现在节点/模板的 JSON 结构与创建接口里，属于"每个 QEMU 节点自己的属性"，不是全局配置。

验证方式：把该键改成一个不存在的路径并重启，二进制探测结果完全不变：

sed -i 's#^qemu_path = .*#qemu_path = /usr/local/bin/qemu-system-x86_64-notexist#' /etc/gns3/gns3_server.conf
systemctl restart gns3-server
curl -s http://127.0.0.1:3080/v2/compute/qemu/binaries

[
    {"path": "/usr/bin/qemu-system-i386", "version": "6.2.0"},
    {"path": "/usr/bin/qemu-system-x86_64-spice", "version": "6.2.0"},
    {"path": "/usr/bin/qemu-system-x86_64", "version": "6.2.0"},
    {"path": "/usr/bin/qemu-system-x86_64-microvm", "version": "6.2.0"},
    {"path": "/bin/qemu-system-i386", "version": "6.2.0"},
    {"path": "/bin/qemu-system-x86_64-spice", "version": "6.2.0"},
    {"path": "/bin/qemu-system-x86_64", "version": "6.2.0"},
    {"path": "/bin/qemu-system-x86_64-microvm", "version": "6.2.0"}
]

要换二进制，正确做法是创建节点或模板时传 qemu_path，或通过模板的 JSON 定义固定下来。

6.4 ovmf_firmware_dir 与 UEFI

使用 UEFI 启动的 QEMU 节点需要该目录下有 OVMF_CODE.fd 与 OVMF_VARS.fd。Ubuntu 上由 ovmf 包提供，缺失时表现为节点创建成功但启动阶段报固件文件不存在。默认路径 /usr/share/OVMF 与 Ubuntu 的包路径一致，一般无需修改。

6.5 allow_unsafe_options

默认 false。为 true 时允许在节点自定义参数里传入被禁用的 QEMU 选项；否则命中禁用列表会直接报：

Forbidden additional option: <option>

生产环境保持默认值，避免客户端传参绕过限制。

七、[Dynamips] 节

Dynamips 用于模拟传统 Cisco 路由器，该节只有四个键，全部在 compute/dynamips/__init__.py 中读取。

实测注意：Ubuntu 的 dynamips 二进制带文件能力 cap_net_admin,cap_net_raw，在受限的运行环境里执行会报 operation not permitted，此时不是路径问题，而是缺少相应能力；另外 dynamips --version 输出为：

Cisco Router Simulation Platform (version 0.2.14-amd64/Linux stable)

sparse_memory_support 与 ghost_ios_support 关闭后能规避个别老旧 IOS 文件的兼容问题，代价是内存占用上升。

八、[VPCS] 节

这个节只有一个键，但它背后有一个版本硬门槛：服务端会执行 vpcs -v 并解析输出中的 Welcome to Virtual PC Simulator, version x.y.z，低于 0.6.1 直接拒绝启动节点：

VPCS executable version must be >= 0.6.1 but not a 0.8

两点实测结论：

1. Ubuntu 22.04 仓库自带的是 0.5b2，必然触发上面的报错；升级到 0.8.4 后节点可正常启动并拿到 console 端口：

   vpcs -v
   

   Welcome to Virtual PC Simulator, version 0.8.4
   Dedicated to Daling.
   

2. 报错文案里的"but not a 0.8"是历史遗留描述，与当前判断逻辑不符——实测 0.8.4 完全可用，不要被这句话误导去降级。

另外，0.8b 及以上版本会关闭 VPCS 的 relay 特性；低于该版本时日志会提示：

The VPCS relay feature could not be disabled because the VPCS version is below 0.8b

九、另一种节点后端（映像型节点）

2.2.61 还内置了以现成系统映像直接起节点的后端（节点类型在接口里以独立类型呈现），适合"快速拉起一台轻量 Linux 节点"的场景。它的配置情况比较特殊，经常被误解，这里单独说明：

1. 没有独立的配置节。2.2.61 源码中对该后端不存在任何配置节读取点，也就是说在 gns3_server.conf 里给它单独写一节（例如 [Xxx]）不会产生任何效果。

2. 通信地址硬编码。该后端连接宿主引擎的 socket 路径在源码中写死（初始化时直接赋值为固定字符串），不读环境变量，也没有配置文件键可改。因此它只能连接"本机默认地址"上的引擎，跨主机部署需要另想办法。

3. 唯一相关的配置是 [Server] 的 resources_path。该后端会把运行所需资源释放到 resources_path 下的子目录；不配置时使用平台默认数据目录。要控制落盘位置，改 [Server] 即可：

   [Server]
   resources_path = /var/lib/gns3/resources
   

4. 可用映像清单与节点操作全走接口。这类节点的映像清单、拉取、删除都通过 REST 完成（详见《GNS3 2.2.61 REST API 使用详解》），配置文件里没有可声明的位置。

如果你的需求是"节点隔离但不想维护第二套配置体系"，用这个后端即可；如果需要指定远端引擎或自定义 socket，2.2.61 的配置层做不到，需要改源码或改用外部编排。

十、参数修改的正确姿势

1. 改之前备份：

   cp /etc/gns3/gns3_server.conf /etc/gns3/gns3_server.conf.bak
   

2. 确认键落在正确的节内（见 1.4），布尔值统一写 true / false，不要写 True / yes 之外的变体；

3. 重启并确认进程真的换了配置：

   systemctl restart gns3-server
   systemctl status gns3-server --no-pager -l | head -8
   

   ● gns3-server.service - GNS3 server 2.2.61
        Active: active (running)
   

4. 用接口自证，而不是只看进程在不在：

   curl -s http://127.0.0.1:3080/v2/version
   

   {
       "local": false,
       "version": "2.2.61"
   }
   

5. 回滚：把备份覆盖回去再重启，配置不会写入工程数据，回滚无副作用。

十一、参数速查表

十二、参考与延伸阅读

• GNS3 官方文档：https://docs.gns3.com/
• gns3-server 源码（配置读取点）：https://github.com/GNS3/gns3-server
• 站内：《Ubuntu 22.04 安装 GNS3 2.2.61 服务端指南》