Welcome to API documentation!¶

Warning

This documentation are for developers for user documentation go to https://gns3.com/

The API is not stable, feel free to post comments on our website https://gns3.com/

This documentation cover the GNS3 API and ressources for GNS3 developers.

If you want a quick demo on how to use the API read: Sample session using curl

API¶

General¶

Architecture¶

GNS3 is splitted in four part:

the GUI (project gns3-gui, gns3-web)

the controller (project gns3-server)

the compute (project gns3-server)

the emulators (qemu, iou, dynamips...)

The controller pilot everything it’s the part that manage the state of a project, save it on disk. Only one controller exists.

The GUI display the topology. The GUI has only direct contact with the controller.

The compute are where emulator are executed. If the compute is on the same server as the controller, they are in the same process.

For each node of the topology will start an emulator instance.

A small schema:

+---------------+                  +----------+     +------+
|               |                  | COMPUTE  +-----> QEMU |
|  GNS3 GUI     |              +---> SERVER 1 |     +------+
|  QT interface +-----+        |   +----------+
|               |     |        |                    +---+
+---------------+    +v--------++               +--->IOU|
                     |CONTROLLER|               |   +---+
      +---------+    +^--------++  +---------+  |
      | GNS3 WEB+-----+        |   | COMPUTE +--+
      +---------+              +---> SERVER 2+--+   +--------+
                                   +---------+  +--->DYNAMIPS|
                                                    +--------+

If you want to pilot GNS3 you need to use the controller API.

Communications¶

All the communication are done over HTTP using JSON.

Errors¶

In case of error a standard HTTP error is raise and you got a JSON like that

{
    "status": 409,
    "message": "Conflict"
}

409 error could be display to the user. They are normal behavior they are used to warn user about something he should change and they are not an internal software error.

Limitations¶

Concurrency¶

A node can’t process multiple request in the same time. But you can make multiple request on multiple node. It’s transparent for the client when the first request on a Node start a lock is acquire for this node id and released for the next request at the end. You can safely send all the requests in the same time and let the server manage an efficent concurrency.

We think it can be a little slower for some operations, but it’s remove a big complexity for the client due to the fact only some command on some node can be concurrent.

Authentication¶

You can use HTTP basic auth to protect the access to the API. And run the API over HTTPS.

Notifications¶

You can receive notification from the server if you listen the HTTP stream /notifications or the websocket.

Read Notifications for more informations

Previous versions¶

API version 1¶

Shipped with GNS3 1.3, 1.4 and 1.5. This API doesn’t support the controller system and save used a commit system instead of live save.

Glossary¶

Node¶

A Virtual Machine (Dynamips, IOU, Qemu, VPCS...), a cloud, a builtin device (switch, hub...)

Drawing¶

Drawing are visual element not used by the network emulation. Like text, images, rectangle... They are pure SVG elements.

Adapter¶

The physical network interface. The adapter can contain multiple ports.

Port¶

A port is an opening on network adapter that cable plug into.

For example a VM can have a serial and an ethernet adapter plugged in. The ethernet adapter can have 4 ports.

Controller¶

The central server managing everything in GNS3. A GNS3 controller will manage multiple GNS3 compute node.

Compute¶

The process running on each server with GNS3. The GNS3 compute node is controlled by the GNS3 controller.

Symbol¶

Symbol are the icon used for nodes.

Scene¶

The drawing area

Sample session using curl¶

You need to read the Glossary, and General before.

Full endpoints list is available: Endpoints

Warning

Beware the output of this sample is truncated in order to simplify the understanding. Please read the documentation for the exact output.

You can check the server version with a simple curl command:

# curl "http://localhost:3080/v2/version"
{
    "version": "2.0.0dev1"
}

List computes¶

We will list the computes node where we can run our nodes:

# curl "http://localhost:3080/v2/computes"
[
    {
        "compute_id": "local",
        "connected": true,
        "host": "127.0.0.1",
        "name": "Local",
        "port": 3080,
        "protocol": "http",
        "user": "admin"
    }
]

In this sample we have only one compute where we can run our nodes. This compute as a special id: local. This mean it’s the local server embed in the GNS3 controller.

Create project¶

The next step is to create a project.

# curl -X POST "http://localhost:3080/v2/projects" -d '{"name": "test"}'
{
    "name": "test",
    "project_id": "b8c070f7-f34c-4b7b-ba6f-be3d26ed073f",
}

Create nodes¶

With this project id we can now create two VPCS Node.

# curl -X POST "http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/nodes" -d '{"name": "VPCS 1", "node_type": "vpcs", "compute_id": "local"}'
{
    "compute_id": "local",
    "console": 5000,
    "console_host": "127.0.0.1",
    "console_type": "telnet",
    "name": "VPCS 1",
    "node_id": "f124dec0-830a-451e-a314-be50bbd58a00",
    "node_type": "vpcs",
    "project_id": "b8c070f7-f34c-4b7b-ba6f-be3d26ed073f",
    "properties": {
        "startup_script": null,
        "startup_script_path": null
    },
    "status": "stopped"
}

# curl -X POST "http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/nodes" -d '{"name": "VPCS 2", "node_type": "vpcs", "compute_id": "local"}'
{
    "compute_id": "local",
    "console": 5001,
    "console_host": "127.0.0.1",
    "console_type": "telnet",
    "name": "VPCS 2",
    "node_id": "83892a4d-aea0-4350-8b3e-d0af3713da74",
    "node_type": "vpcs",
    "project_id": "b8c070f7-f34c-4b7b-ba6f-be3d26ed073f",
    "properties": {
        "startup_script": null,
        "startup_script_path": null
    },
    "status": "stopped"
}

The properties dictionnary contains all setting specific to a node type (dynamips, docker, vpcs...)

Link nodes¶

Now we need to link the two VPCS by connecting their port 0 together.

# curl -X POST  "http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/links" -d '{"nodes": [{"adapter_number": 0, "node_id": "f124dec0-830a-451e-a314-be50bbd58a00", "port_number": 0}, {"adapter_number": 0, "node_id": "83892a4d-aea0-4350-8b3e-d0af3713da74", "port_number": 0}]}'
{
    "capture_file_name": null,
    "capture_file_path": null,
    "capturing": false,
    "link_id": "007f2177-6790-4e1b-ac28-41fa226b2a06",
    "nodes": [
        {
            "adapter_number": 0,
            "node_id": "f124dec0-830a-451e-a314-be50bbd58a00",
            "port_number": 0
        },
        {
            "adapter_number": 0,
            "node_id": "83892a4d-aea0-4350-8b3e-d0af3713da74",
            "port_number": 0
        }
    ],
    "project_id": "b8c070f7-f34c-4b7b-ba6f-be3d26ed073f"
}

Start nodes¶

Now we can start the two nodes.

# curl -X POST "http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/nodes/f124dec0-830a-451e-a314-be50bbd58a00/start" -d "{}"
# curl -X POST "http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/nodes/83892a4d-aea0-4350-8b3e-d0af3713da74/start" -d "{}"

Connect to nodes¶

Everything should be started now. You can connect via telnet to the different Node. The port is the field console in the create Node request.

# telnet 127.0.0.1 5000
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.

Welcome to Virtual PC Simulator, version 0.6
Dedicated to Daling.
Build time: Dec 29 2014 12:51:46
Copyright (c) 2007-2014, Paul Meng (mirnshi@gmail.com)
All rights reserved.

VPCS is free software, distributed under the terms of the "BSD" licence.
Source code and license can be found at vpcs.sf.net.
For more information, please visit wiki.freecode.com.cn.

Press '?' to get help.

VPCS> ip 192.168.1.1
Checking for duplicate address...
PC1 : 192.168.1.1 255.255.255.0

VPCS> disconnect

Good-bye
Connection closed by foreign host.

# telnet 127.0.0.1 5001
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.

Welcome to Virtual PC Simulator, version 0.6
Dedicated to Daling.
Build time: Dec 29 2014 12:51:46
Copyright (c) 2007-2014, Paul Meng (mirnshi@gmail.com)
All rights reserved.

VPCS is free software, distributed under the terms of the "BSD" licence.
Source code and license can be found at vpcs.sf.net.
For more information, please visit wiki.freecode.com.cn.

Press '?' to get help.

VPCS> ip 192.168.1.2
Checking for duplicate address...
PC1 : 192.168.1.2 255.255.255.0

VPCS> ping 192.168.1.1
84 bytes from 192.168.1.1 icmp_seq=1 ttl=64 time=0.179 ms
84 bytes from 192.168.1.1 icmp_seq=2 ttl=64 time=0.218 ms
84 bytes from 192.168.1.1 icmp_seq=3 ttl=64 time=0.190 ms
84 bytes from 192.168.1.1 icmp_seq=4 ttl=64 time=0.198 ms
84 bytes from 192.168.1.1 icmp_seq=5 ttl=64 time=0.185 ms

VPCS> disconnect
Good-bye
Connection closed by foreign host.

Stop nodes¶

And we stop the two nodes.

# curl -X POST "http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/nodes/f124dec0-830a-451e-a314-be50bbd58a00/stop" -d "{}"
# curl -X POST "http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/nodes/83892a4d-aea0-4350-8b3e-d0af3713da74/stop" -d "{}"

Add a visual element¶

When you want add visual elements to the topology like rectangle, circle, images you can just send a raw SVG. This will display a red square in the middle of your topologies:

# curl -X POST "http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/drawings" -d '{"x":0, "y": 12, "svg": "<svg width=\"50\" height=\"50\"><rect width=\"50\" height=\"50\" style=\"fill: #ff0000\"></rect></svg>"}'

Tips: you can embed png/jpg... by using a base64 encoding in the SVG.

Create a Qemu node¶

# curl -X POST http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/nodes -d '{"node_type": "qemu", "compute_id": "local", "name": "Microcore1", "properties": {"hda_disk_image": "linux-microcore-6.4.img", "ram": 256, "qemu_path": "qemu-system-x86_64"}}'

{
    "command_line": "",
    "compute_id": "local",
    "console": 5001,
    "console_host": "127.0.0.1",
    "console_type": "telnet",
    "first_port_name": null,
    "height": 59,
    "label": {
        "rotation": 0,
        "style": "font-family: TypeWriter;font-size: 10;font-weight: bold;fill: #000000;fill-opacity: 1.0;",
        "text": "Microcore1",
        "x": null,
        "y": -40
    },
    "name": "Microcore1",
    "node_directory": "/Users/noplay/GNS3/projects/untitled/project-files/qemu/9e4eb45b-22f5-450d-8277-2934fbd0aa20",
    "node_id": "9e4eb45b-22f5-450d-8277-2934fbd0aa20",
    "node_type": "qemu",
    "port_name_format": "Ethernet{0}",
    "port_segment_size": 0,
    "ports": [
        {
            "adapter_number": 0,
            "data_link_types": {
                "Ethernet": "DLT_EN10MB"
            },
            "link_type": "ethernet",
            "name": "Ethernet0",
            "port_number": 0,
            "short_name": "e0/0"
        }
    ],
    "project_id": "b8c070f7-f34c-4b7b-ba6f-be3d26ed073f",
    "properties": {
        "acpi_shutdown": false,
        "adapter_type": "e1000",
        "adapters": 1,
        "boot_priority": "c",
        "cdrom_image": "",
        "cdrom_image_md5sum": null,
        "cpu_throttling": 0,
        "cpus": 1,
        "hda_disk_image": "linux-microcore-6.4.img",
        "hda_disk_image_md5sum": "877419f975c4891c019947ceead5c696",
        "hda_disk_interface": "ide",
        "hdb_disk_image": "",
        "hdb_disk_image_md5sum": null,
        "hdb_disk_interface": "ide",
        "hdc_disk_image": "",
        "hdc_disk_image_md5sum": null,
        "hdc_disk_interface": "ide",
        "hdd_disk_image": "",
        "hdd_disk_image_md5sum": null,
        "hdd_disk_interface": "ide",
        "initrd": "",
        "initrd_md5sum": null,
        "kernel_command_line": "",
        "kernel_image": "",
        "kernel_image_md5sum": null,
        "legacy_networking": false,
        "mac_address": "00:af:69:aa:20:00",
        "options": "",
        "platform": "x86_64",
        "process_priority": "low",
        "qemu_path": "/usr/local/bin/qemu-system-x86_64",
        "ram": 256,
        "usage": ""
    },
    "status": "stopped",
    "symbol": ":/symbols/computer.svg",
    "width": 65,
    "x": 0,
    "y": 0,
    "z": 0
}

Create a dynamips node¶

# curl http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/nodes -d '{"symbol": ":/symbols/router.svg", "name": "R1", "properties": {"platform": "c7200", "nvram": 512, "image": "c7200-adventerprisek9-mz.124-24.T8.image", "ram": 512, "slot3": "PA-GE", "system_id": "FTX0945W0MY", "slot0": "C7200-IO-FE", "slot2": "PA-GE", "slot1": "PA-GE",  "idlepc": "0x606e0538", "startup_config_content": "hostname %h\n"}, "compute_id": "local", "node_type": "dynamips"}'

{
    "command_line": null,
    "compute_id": "local",
    "console": 5002,
    "console_host": "127.0.0.1",
    "console_type": "telnet",
    "first_port_name": null,
    "height": 45,
    "label": {
        "rotation": 0,
        "style": "font-family: TypeWriter;font-size: 10;font-weight: bold;fill: #000000;fill-opacity: 1.0;",
        "text": "R1",
        "x": null,
        "y": -32
    },
    "name": "R1",
    "node_directory": "/Users/noplay/GNS3/projects/untitled/project-files/dynamips",
    "node_id": "f7367e7e-804e-48be-9037-284d4d9b059e",
    "node_type": "dynamips",
    "port_name_format": "Ethernet{0}",
    "port_segment_size": 0,
    "ports": [
        {
            "adapter_number": 0,
            "data_link_types": {
                "Ethernet": "DLT_EN10MB"
            },
            "link_type": "ethernet",
            "name": "FastEthernet0/0",
            "port_number": 0,
            "short_name": "f0/0"
        },
        {
            "adapter_number": 1,
            "data_link_types": {
                "Ethernet": "DLT_EN10MB"
            },
            "link_type": "ethernet",
            "name": "GigabitEthernet0/0",
            "port_number": 0,
            "short_name": "g0/0"
        },
        {
            "adapter_number": 2,
            "data_link_types": {
                "Ethernet": "DLT_EN10MB"
            },
            "link_type": "ethernet",
            "name": "GigabitEthernet1/0",
            "port_number": 0,
            "short_name": "g1/0"
        },
        {
            "adapter_number": 3,
            "data_link_types": {
                "Ethernet": "DLT_EN10MB"
            },
            "link_type": "ethernet",
            "name": "GigabitEthernet2/0",
            "port_number": 0,
            "short_name": "g2/0"
        }
    ],
    "project_id": "b8c070f7-f34c-4b7b-ba6f-be3d26ed073f",
    "properties": {
        "auto_delete_disks": false,
        "aux": null,
        "clock_divisor": 4,
        "disk0": 64,
        "disk1": 0,
        "dynamips_id": 2,
        "exec_area": 64,
        "idlemax": 500,
        "idlepc": "0x606e0538",
        "idlesleep": 30,
        "image": "c7200-adventerprisek9-mz.124-24.T8.image",
        "image_md5sum": "b89d30823cbbda460364991ed18449c7",
        "mac_addr": "ca02.dcbb.0000",
        "midplane": "vxr",
        "mmap": true,
        "npe": "npe-400",
        "nvram": 512,
        "platform": "c7200",
        "power_supplies": [
            1,
            1
        ],
        "private_config": "",
        "private_config_content": "",
        "ram": 512,
        "sensors": [
            22,
            22,
            22,
            22
        ],
        "slot0": "C7200-IO-FE",
        "slot1": "PA-GE",
        "slot2": "PA-GE",
        "slot3": "PA-GE",
        "slot4": null,
        "slot5": null,
        "slot6": null,
        "sparsemem": true,
        "startup_config": "configs/i2_startup-config.cfg",
        "startup_config_content": "!\nhostname R1\n",
        "system_id": "FTX0945W0MY"
    },
    "status": "stopped",
    "symbol": ":/symbols/router.svg",
    "width": 66,
    "x": 0,
    "y": 0,
    "z": 0
}

Notifications¶

You can see notification about the changes via the notification feed:

# curl "http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/notifications"
{"action": "ping", "event": {"compute_id": "local", "cpu_usage_percent": 35.7, "memory_usage_percent": 80.7}}
{"action": "node.updated", "event": {"command_line": "/usr/local/bin/vpcs -p 5001 -m 1 -i 1 -F -R -s 10001 -c 10000 -t 127.0.0.1", "compute_id": "local", "console": 5001, "console_host": "127.0.0.1", "console_type": "telnet", "name": "VPCS 2", "node_id": "83892a4d-aea0-4350-8b3e-d0af3713da74", "node_type": "vpcs", "project_id": "b8c070f7-f34c-4b7b-ba6f-be3d26ed073f", "properties": {"startup_script": null, "startup_script_path": null}, "status": "started"}}

A websocket version is also available on http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/notifications/ws

Read Notifications for more informations

How to found the endpoints?¶

Full endpoints list is available: Endpoints

If you start the server with –debug you can see all the requests made by the client and by the controller to the computes nodes.

Notifications¶

You can receive notification from the controller allowing you to update your local data.

Notifications endpoints¶

You can listen the HTTP stream /notifications or the websocket.

/v2/projects/{project_id}/notifications

/v2/projects/{project_id}/notifications/ws

We recommend using the websocket.

Available notifications¶

ping ¶

Keep the connection between client and controller.

{
    "compute_id": 12
}

compute.created ¶

Compute has been created.

{
    "capabilities": {
        "node_types": [],
        "version": null
    },
    "compute_id": "my_compute",
    "connected": false,
    "cpu_usage_percent": null,
    "host": "localhost",
    "memory_usage_percent": null,
    "name": "http://julien@localhost:84",
    "port": 84,
    "protocol": "http",
    "user": "julien"
}

compute.updated ¶

Compute has been updated. You will receive a lot of this event because it’s include change of CPU and memory usage on the compute node.

{
    "capabilities": {
        "node_types": [],
        "version": null
    },
    "compute_id": "my_compute_id",
    "connected": false,
    "cpu_usage_percent": null,
    "host": "localhost",
    "memory_usage_percent": null,
    "name": "http://julien@localhost:84",
    "port": 84,
    "protocol": "https",
    "user": "julien"
}

compute.deleted ¶

Compute has been deleted.

{
    "capabilities": {
        "node_types": [],
        "version": null
    },
    "compute_id": "my_compute_id",
    "connected": false,
    "cpu_usage_percent": null,
    "host": "localhost",
    "memory_usage_percent": null,
    "name": "http://julien@localhost:84",
    "port": 84,
    "protocol": "http",
    "user": "julien"
}

node.created ¶

Node has been created.

{
    "a": "b"
}

node.updated ¶

Node has been updated.

{
    "command_line": "",
    "compute_id": "local",
    "console": 5006,
    "console_host": "localhost",
    "console_type": "telnet",
    "first_port_name": null,
    "height": 59,
    "label": {
        "rotation": 0,
        "style": "font-family: TypeWriter;font-size: 10;font-weight: bold;fill: #000000;fill-opacity: 1.0;",
        "text": "PC2",
        "x": 18,
        "y": -25
    },
    "name": "PC2",
    "node_directory": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-of-noplay/pytest-51/test_open0/project-files/vpcs/748bcd89-624a-40eb-a8d3-1d2e85c99b51",
    "node_id": "748bcd89-624a-40eb-a8d3-1d2e85c99b51",
    "node_type": "vpcs",
    "port_name_format": "Ethernet{0}",
    "port_segment_size": 0,
    "ports": [
        {
            "adapter_number": 0,
            "data_link_types": {
                "Ethernet": "DLT_EN10MB"
            },
            "link_type": "ethernet",
            "name": "Ethernet0",
            "port_number": 0,
            "short_name": "e0"
        }
    ],
    "project_id": "3c1be6f9-b4ba-4737-b209-63c47c23359f",
    "properties": {
        "startup_script": "",
        "startup_script_path": "startup.vpc"
    },
    "status": "stopped",
    "symbol": ":/symbols/computer.svg",
    "width": 65,
    "x": -71,
    "y": -98,
    "z": 1
}

node.deleted ¶

Node has been deleted.

link.created ¶

Link has been created. Note that a link when created is not yet connected to both part.

{
    "capture_file_name": null,
    "capture_file_path": null,
    "capturing": false,
    "link_id": "9b74fb50-652a-47de-aa7a-f936fad2623a",
    "link_type": "ethernet",
    "nodes": [
        {
            "adapter_number": 0,
            "label": {
                "rotation": 0,
                "style": "font-size: 10; font-style: Verdana",
                "text": "0/3",
                "x": -10,
                "y": -10
            },
            "node_id": "009935d3-bb71-48ee-8f8c-4160ecf36a1f",
            "port_number": 3
        },
        {
            "adapter_number": 2,
            "label": {
                "rotation": 0,
                "style": "font-size: 10; font-style: Verdana",
                "text": "2/4",
                "x": -10,
                "y": -10
            },
            "node_id": "efd15e6d-cc6d-4b85-8e11-0389806f7231",
            "port_number": 4
        }
    ],
    "project_id": "19def516-231c-4a43-8fdb-1d49333c1f8e"
}

link.updated ¶

Link has been updated.

{
    "capture_file_name": null,
    "capture_file_path": null,
    "capturing": false,
    "link_id": "fab9fae2-1ca7-48a5-a3bf-e6cdebf7d89f",
    "link_type": "ethernet",
    "nodes": [
        {
            "adapter_number": 0,
            "label": {
                "text": "Hello",
                "x": 64,
                "y": 0
            },
            "node_id": "d978c6d1-4503-46ce-a11c-432b7dace22c",
            "port_number": 3
        },
        {
            "adapter_number": 2,
            "label": {
                "rotation": 0,
                "style": "font-size: 10; font-style: Verdana",
                "text": "2/4",
                "x": -10,
                "y": -10
            },
            "node_id": "d1779d19-320a-471b-9d50-91dd3d3f3ecd",
            "port_number": 4
        }
    ],
    "project_id": "e49cdc9f-ce2d-48b4-a317-7107f4c2c520"
}

link.deleted ¶

Link has been deleted.

{
    "capture_file_name": null,
    "capture_file_path": null,
    "capturing": false,
    "link_id": "105966d0-8a04-4cf5-95a4-ff13f1de7660",
    "link_type": "ethernet",
    "nodes": [],
    "project_id": "42a1b682-b5bf-4de4-b5af-5366fc20a111"
}

drawing.created ¶

Drawing has been created.

{
    "drawing_id": "377bccc0-779a-44b0-ab5e-98dfd6dc46cd",
    "project_id": "adb641a0-8ec9-4b5a-b8df-cc993638c601",
    "rotation": 0,
    "svg": "<svg height=\"210\" width=\"500\"><line x1=\"0\" y1=\"0\" x2=\"200\" y2=\"200\" style=\"stroke:rgb(255,0,0);stroke-width:2\" /></svg>",
    "x": 10,
    "y": 20,
    "z": 0
}

drawing.updated ¶

Drawing has been updated. To reduce data transfert if the svg field has not change the field is not included.

{
    "drawing_id": "d86ab88f-28bf-4f22-aa4e-e6d3c423b98c",
    "project_id": "8f53f0f7-9967-4a01-884f-36ea1800e5ef",
    "rotation": 0,
    "x": 42,
    "y": 20,
    "z": 0
}

drawing.deleted ¶

Drawing has been deleted.

{
    "drawing_id": "b2f8b12f-a4cc-4621-affc-cf3dcd4ba513",
    "project_id": "24ef7002-5dd6-4054-bf8a-d2aface0885e",
    "rotation": 0,
    "svg": "<svg></svg>",
    "x": 0,
    "y": 0,
    "z": 0
}

project.updated ¶

Project has been updated.

{
    "auto_close": true,
    "auto_open": false,
    "auto_start": false,
    "filename": "test.gns3",
    "name": "test2",
    "path": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmpe4g8gdv7/projects/10010203-0405-0607-0809-0a0b0c0d0e0f",
    "project_id": "10010203-0405-0607-0809-0a0b0c0d0e0f",
    "scene_height": 1000,
    "scene_width": 2000,
    "status": "opened"
}

project.closed ¶

Project has been closed.

{
    "auto_close": true,
    "auto_open": false,
    "auto_start": false,
    "filename": "test.gns3",
    "name": "test",
    "path": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmp0vixjsro/projects/74bd9388-bd2e-41cc-b8da-d014cfb9f908",
    "project_id": "74bd9388-bd2e-41cc-b8da-d014cfb9f908",
    "scene_height": 1000,
    "scene_width": 2000,
    "status": "closed"
}

snapshot.restored ¶

Snapshot has been restored

log.error ¶

Send an error to the user

{
    "message": "Permission denied on /tmp"
}

log.warning ¶

Send a warning to the user

{
    "message": "Warning ASA 8 is not officialy supported by GNS3"
}

log.info ¶

Send an information to the user

{
    "message": "Image uploaded"
}

settings.updated ¶

GUI settings updated. Will be removed in a later release.

{
    "test": true
}

Positions¶

In a the project object you have properties scene_height and scene_width this define the size of the drawing area as px.

The position of the node are relative to this with 0,0 as center of the area.

Endpoints¶

GNS3 expose two type of endpoints:

Controller

Compute

Controller API Endpoints¶

The controller manage all the running topologies. The controller has knowledge of everything on in GNS3. If you want to create and manage a topology it’s here. The controller will call the compute API when needed.

In a standard GNS3 installation you have one controller and one or many computes.

Compute¶

/v2/computes ¶

Contents

/v2/computes
- POST /v2/computes
- GET /v2/computes
  - Response status codes

POST /v2/computes ¶

Register a compute server

Name	Type	Description
compute_id	string	Server identifier
host	string	Server host
name	string	Server name
password	['string', 'null']	Password for authentication
port	integer	Server port
protocol	enum	Possible values: http, https
user	['string', 'null']	User for authentication

Name	Mandatory	Type	Description
capabilities		object	Get what a server support
compute_id	✔	string	Server identifier
connected		boolean	Whether the controller is connected to the compute server or not
cpu_usage_percent		['number', 'null']	CPU usage of the compute. Read only
host	✔	string	Server host
memory_usage_percent		['number', 'null']	RAM usage of the compute. Read only
name	✔	string	Server name
port	✔	integer	Server port
protocol	✔	enum	Possible values: http, https
user		['string', 'null']	User for authentication

Name	Type	Description
drawing_id	string	Drawing UUID
project_id	string	Project UUID
rotation	integer	Rotation of the element
svg	string	SVG content of the drawing
x	integer	X property
y	integer	Y property
z	integer	Z property

Name	Mandatory	Type	Description
capture_file_name		['string', 'null']	Read only property. The name of the capture file if capture is running
capture_file_path		['string', 'null']	Read only property. The full path of the capture file if capture is running
capturing		boolean	Read only property. True if a capture running on the link
link_id		string	Link UUID
link_type		enum	Possible values: ethernet, serial
nodes	✔	array	List of the VMS
project_id		string	Project UUID

Name	Type	Description
command_line	['null', 'string']	Command line use to start the node
compute_id	string	Compute identifier
console	['integer', 'null']	Console TCP port
console_host	string	Console host. Warning if the host is 0.0.0.0 or :: (listen on all interfaces) you need to use the same address you use to connect to the controller.
console_type	enum	Possible values: vnc, telnet, http, null
first_port_name	['string', 'null']	Name of the first port
height	integer	Height of the node (Read only)
label	object
name	string	Node name
node_directory	['null', 'string']	Working directory of the node. Read only
node_id	string	Node UUID
node_type	enum	Possible values: cloud, nat, ethernet_hub, ethernet_switch, frame_relay_switch, atm_switch, docker, dynamips, vpcs, virtualbox, vmware, iou, qemu
port_name_format	string	Formating for port name {0} will be replace by port number
port_segment_size	integer	Size of the port segment
ports	array	List of node ports READ only
project_id	string	Project UUID
properties	object	Properties specific to an emulator
status	enum	Possible values: stopped, started, suspended
symbol	['string', 'null']	Symbol of the node
width	integer	Width of the node (Read only)
x	integer	X position of the node
y	integer	Y position of the node
z	integer	Z position of the node

Name	Mandatory	Type	Description
auto_close		boolean	Project auto close
name	✔	['string', 'null']	Project name
path		['string', 'null']	Project directory
project_id		['string', 'null']	Project UUID
scene_height		integer	Height of the drawing area
scene_width		integer	Width of the drawing area

Name	Mandatory	Type	Description
auto_close		boolean	Project auto close when client cut off the notifications feed
auto_open		boolean	Project open when GNS3 start
auto_start		boolean	Project start when opened
filename		['string', 'null']	Project filename
name		['string', 'null']	Project name
path		['string', 'null']	Project directory
project_id	✔	string	Project UUID
scene_height		integer	Height of the drawing area
scene_width		integer	Width of the drawing area
status		enum	Possible values: opened, closed

Name	Mandatory	Type	Description
local		boolean	Whether this is a local server or not
version	✔	string	Version number

Name	Mandatory	Type	Description
created_at	✔	integer	Date of the snapshot (UTC timestamp)
name	✔	string	Project name
project_id	✔	string	Project UUID
snapshot_id	✔	string	Snapshot UUID

Name	Mandatory	Type	Description
mappings		object	ATM mappings
name	✔	string	ATM switch name
node_id			Node UUID

Name	Mandatory	Type	Description
capture_file_name	✔	string	Capture file name
data_link_type		enum	Possible values: DLT_ATM_RFC1483, DLT_EN10MB, DLT_FRELAY, DLT_C_HDLC, DLT_PPP_SERIAL

Name	Mandatory	Type	Description
node_types	✔	array	Node type supported by the compute
platform		string	Platform where the compute is running
version	✔	['string', 'null']	Version number

Name	Mandatory	Type	Description
name	✔	string	Interface name
special	✔	boolean	If true the interface is non standard (firewire for example)
type	✔	enum	Possible values: ethernet, tap

Name	Mandatory	Type	Description
interfaces		array
name	✔	string	Cloud name
node_id			Node UUID
ports_mapping		array

Name	Mandatory	Type	Description
adapters		['integer', 'null']	Number of adapters
aux		['integer', 'null']	Auxiliary TCP port
console		['integer', 'null']	Console TCP port
console_http_path		string	Path of the web interface
console_http_port		integer	Internal port in the container for the HTTP server
console_resolution		['string', 'null']	Console resolution for VNC
console_type		enum	Possible values: telnet, vnc, http, https
container_id		string	Docker container ID Read only
environment		['string', 'null']	Docker environment variables
image	✔	string	Docker image name
name	✔	string	Docker container name
node_id		string	Node UUID
start_command		['string', 'null']	Docker CMD entry

Name	Mandatory	Type	Description
auto_delete_disks		boolean	Automatically delete nvram and disk files
aux		['null', 'integer']	Auxiliary console TCP port
chassis		string	Cisco router chassis model
clock_divisor		integer	Clock divisor
console		integer	Console TCP port
console_type		enum	Possible values: telnet
disk0		integer	Disk0 size in MB
disk1		integer	Disk1 size in MB
dynamips_id		integer	Dynamips ID
exec_area		integer	Exec area value
idlemax		integer	Idlemax value
idlepc		string	Idle-PC value
idlesleep		integer	Idlesleep value
image	✔	string	Path to the IOS image
image_md5sum		['string', 'null']	Checksum of the IOS image
iomem		integer	I/O memory percentage
mac_addr		string	Base MAC address
midplane		enum	Possible values: std, vxr
mmap		boolean	MMAP feature
name	✔	string	Dynamips VM instance name
node_id			Node UUID
npe		enum	Possible values: npe-100, npe-150, npe-175, npe-200, npe-225, npe-300, npe-400, npe-g2
nvram		integer	Amount of NVRAM in KB
platform	✔	string	Cisco router platform
power_supplies		array	Power supplies status
private_config		string	Path to the IOS private configuration file
private_config_content		string	Content of IOS private configuration file
ram	✔	integer	Amount of RAM in MB
sensors		array	Temperature sensors
slot0			Network module slot 0
slot1			Network module slot 1
slot2			Network module slot 2
slot3			Network module slot 3
slot4			Network module slot 4
slot5			Network module slot 5
slot6			Network module slot 6
sparsemem		boolean	Sparse memory feature
startup_config		string	Path to the IOS startup configuration file
startup_config_content		string	Content of IOS startup configuration file
system_id		string	System ID
wic0			Network module WIC slot 0
wic1			Network module WIC slot 0
wic2			Network module WIC slot 0

Name	Mandatory	Type	Description
name	✔	string	Ethernet hub name
node_id			Node UUID
ports_mapping		array

Name	Mandatory	Type	Description
ethertype		enum	Possible values: null, 0x8100, 0x88A8, 0x9100, 0x9200
name	✔	string	Port name
port_number	✔	integer	Port number
type	✔	enum	Possible values: access, dot1q, qinq
vlan		integer	VLAN number

Name	Mandatory	Type	Description
name	✔	string	Ethernet switch name
node_id			Node UUID
ports_mapping		array

Name	Mandatory	Type	Description
mappings		object	Frame Relay mappings
name	✔	string	Frame Relay switch name
node_id			Node UUID

Welcome to API documentation!¶

API¶

General¶

Architecture¶

Communications¶

Errors¶

Limitations¶

Concurrency¶

Authentication¶

Notifications¶

Previous versions¶

API version 1¶

Glossary¶

Node¶

Drawing¶

Adapter¶

Port¶

Controller¶

Compute¶

Symbol¶

Scene¶

Sample session using curl¶

List computes¶

Create project¶

Create nodes¶

Link nodes¶

Start nodes¶

Connect to nodes¶

Stop nodes¶

Add a visual element¶

Create a Qemu node¶

Create a dynamips node¶

Notifications¶

How to found the endpoints?¶

Notifications¶

Notifications endpoints¶

Available notifications¶

Positions¶

Endpoints¶

Controller API Endpoints¶

Compute¶

Drawing¶

Gns3 vm¶

Link¶

Node¶

Project¶

Server¶

Snapshot¶

Symbol¶

Compute API Endpoints¶

Atm switch¶

Capabilities¶

Cloud¶

Docker¶

Name	Type	Description
command_line	string	Last command line used by GNS3 to start QEMU
console	integer	Console TCP port
console_type	enum	Possible values: telnet
ethernet_adapters	integer	How many ethernet adapters are connected to the IOU
iourc_content	['string', 'null']	Content of the iourc file. Ignored if Null
l1_keepalives	boolean	Always up ethernet interface
md5sum	['string', 'null']	Checksum of iou binary
name	string	IOU VM name
node_directory	string	Path to the node working directory
node_id	string	IOU VM UUID
nvram	integer	Allocated NVRAM KB
path	string	Path of iou binary
private_config	['string', 'null']	Path of the private-config content relative to project directory
private_config_content	['string', 'null']	Private-config of IOU
project_id	string	Project UUID
ram	integer	Allocated RAM MB
serial_adapters	integer	How many serial adapters are connected to the IOU
startup_config	['string', 'null']	Path of the startup-config content relative to project directory
startup_config_content	['string', 'null']	Startup-config of IOU
status	enum	Possible values: started, stopped, suspended
use_default_iou_values	['boolean', 'null']	Use default IOU values

Name	Type	Description
name	string	Nat name
node_id	string	Node UUID
ports_mapping	array
project_id	string	Project UUID
status	enum	Possible values: started, stopped, suspended

Name	Mandatory	Type	Description
acpi_shutdown		['boolean', 'null']	ACPI shutdown support
adapter_type		['string', 'null']	QEMU adapter type
adapters		['integer', 'null']	Number of adapters
bios_image		string	QEMU bios image path
bios_image_md5sum		['string', 'null']	QEMU bios image checksum
boot_priority		enum	Possible values: c, d, n, cn, cd
cdrom_image		string	QEMU cdrom image path
cdrom_image_md5sum		['string', 'null']	QEMU cdrom image checksum
console		['integer', 'null']	Console TCP port
console_type		enum	Possible values: telnet, vnc
cpu_throttling		['integer', 'null']	Percentage of CPU allowed for QEMU
cpus		['integer', 'null']	Number of vCPUs
hda_disk_image		string	QEMU hda disk image path
hda_disk_image_md5sum		['string', 'null']	QEMU hda disk image checksum
hda_disk_interface		string	QEMU hda interface
hdb_disk_image		string	QEMU hdb disk image path
hdb_disk_image_md5sum		['string', 'null']	QEMU hdb disk image checksum
hdb_disk_interface		string	QEMU hdb interface
hdc_disk_image		string	QEMU hdc disk image path
hdc_disk_image_md5sum		['string', 'null']	QEMU hdc disk image checksum
hdc_disk_interface		string	QEMU hdc interface
hdd_disk_image		string	QEMU hdd disk image path
hdd_disk_image_md5sum		['string', 'null']	QEMU hdd disk image checksum
hdd_disk_interface		string	QEMU hdd interface
initrd		string	QEMU initrd path
initrd_md5sum		['string', 'null']	QEMU initrd path
kernel_command_line		['string', 'null']	QEMU kernel command line
kernel_image		string	QEMU kernel image path
kernel_image_md5sum		['string', 'null']	QEMU kernel image checksum
legacy_networking		['boolean', 'null']	Use QEMU legagy networking commands (-net syntax)
linked_clone		boolean	Whether the VM is a linked clone or not
mac_address		['string', 'null']	QEMU MAC address
name	✔	string	QEMU VM instance name
node_id			Node UUID
options		['string', 'null']	Additional QEMU options
platform		enum	Possible values: aarch64, alpha, arm, cris, i386, lm32, m68k, microblaze, microblazeel, mips, mips64, mips64el, mipsel, moxie, or32, ppc, ppc64, ppcemb, s390x, sh4, sh4eb, sparc, sparc64, tricore, unicore32, x86_64, xtensa, xtensaeb, null
process_priority		enum	Possible values: realtime, very high, high, normal, low, very low, null
qemu_path		['string', 'null']	Path to QEMU
ram		['integer', 'null']	Amount of RAM in MB
usage		string	How to use the qemu VM

Name	Mandatory	Type	Description
adapter_type		enum	Possible values: ide, lsilogic, buslogic, legacyESX
cluster_size		integer
format	✔	enum	Possible values: qcow2, qcow, vpc, vdi, vmdk, raw
lazy_refcounts		enum	Possible values: on, off
path	✔	string	Absolute or relative path of the image
preallocation		enum	Possible values: off, metadata, falloc, full
qemu_img	✔	string	Path to the qemu-img binary
refcount_bits		integer
size	✔	integer	Image size in Megabytes
static		enum	Possible values: on, off
subformat		enum	Possible values: dynamic, fixed, streamOptimized, twoGbMaxExtentSparse, twoGbMaxExtentFlat, monolithicSparse, monolithicFlat
zeroed_grain		enum	Possible values: on, off

Name	Mandatory	Type	Description
acpi_shutdown		boolean	ACPI shutdown
adapter_type		string	VirtualBox adapter type
adapters		integer	Number of adapters
console		integer	Console TCP port
console_type		enum	Possible values: telnet
headless		boolean	Headless mode
linked_clone		boolean	Whether the VM is a linked clone or not
name	✔	string	VirtualBox VM instance name
node_id			Node UUID
ram		integer	Amount of RAM
use_any_adapter		boolean	Allow GNS3 to use any VirtualBox adapter
vmname	✔	string	VirtualBox VM name (in VirtualBox itself)