Introduction

The GNS3 2.x server provides an API, which allows other programs to retrieve informations and modify GNS3 projects. As the most important application, the GNS3 GUI uses this API to control the server. That shows how powerful the API is.

The API uses HTTP messages, containing the commands and responses. The command arguments and the results are JSON encoded, a simple, human-readable format.

The GNS3 API is documented in https://gns3-server.readthedocs.io/. The controller endpoints https://gns3-server.readthedocs.io/en/stable/endpoints.html#controller-endpoints are the only interesting part, the compute endpoints are for internal use within GNS3. Be sure you select the GNS3 version you are using (on the lower right of the page).

David Bombal created a very good series of videos about this topic, see his GNS3 REST API playlist on YouTube. It’s a good idea to first watch David’s videos and then come back.

First steps

Lets get the GNS3 version number.

For that you need to send a “/v2/version” request to the server. The server address is configured in the GNS3 server preferences, normally 127.0.0.1 (host binding) on port 3080.

So you will need to send the HTTP request http://127.0.0.1:3080/v2/version.

If everything works well, GNS3 will respond with something like

{
  "local": true,
  "version": "2.1.21"
}

If you try that HTTP request in a browser, you will very likely get an “Authentication required” dialog. That’s because the access to the GNS3 server is protected by username and password. See the API Authentication article, how to handle that. For the first tests, it makes sense to deactivate authentication. But that allows anyone to access your GNS3 server. So in the long run authentication should be activated.

Test Clients

Using the browser for sending API requests will work only in some basic cases. The browser’s user interface is not designed to create complex HTTP requests.

The API documentation uses the command line tool curl. While you can create any request you like, it gets inconvenient when handling long parameter lists.

One popular alternative is Postman (https://www.getpostman.com). This free application is available for Windows, Linux and macOS. It’s use is shown in David’s videos. Another simple option are browser extensions, for example Tabbed Postman for Chrome or RESTED for Firefox.

Here I’m using the RESTED extension in Firefox to request the version. I used the instructions in API Authentication to provide the username and password needed for authentication.

RESTED show version

Postman, as well as the browser extensions, allow to save requests to collections, so they can easily repeated at a later time.

Project and Node Identifiers

The API uses UUIDs, a long sequence of hexadecimal characters enriched by some ‘-‘ characters, to identify an item. The names of projects and nodes are just attributes, they have mainly documentary use for the API. So one of the first tasks of an application is to map the names, used by us poor humans, to UUIDs for the API.

First issue a “GET /v2/projects” request to get a list of all projects. Use the name attribute to select the project and get the project_id.

Here an excerpt of an example project list returned by the API:

[
    {
        "name": "test1",
        "project_id": "00010203-0405-0607-0809-0a0b0c0d0e0f",
        "status": "closed",
        ...
    },
    {
        "name": "test2",
        "project_id": "2986c282-e260-4ca2-bfb8-7fdb1124fb18",
        "status": "opened",
        ...
    },
    ...
]

If the project is not in status “opened”, you need to open it with “POST /v2/projects/{project_id}/open”.

Then get a list of nodes in that project with “GET /v2/projects/{project_id}/nodes”. From this list extract the name and the node_id of each node and create a mapping table.

Watching the API usage of the GNS3 GUI

For me it was very instructive to watch the GUI when using the API. The simplest and clearest way I found was to use Wireshark to sniff the communication between GUI and server.

The GUI and the controller component of the server are normally running both on the local computer. On Linux and macOS you simply need to sniff the loopback interface. On Windows it’s not that easy, its TCP/IP stack does not implement a network loopback interface. For details see https://wiki.wireshark.org/CaptureSetup/Loopback. The best way I found is to install Npcap and use its loopback adapter. Npcap was known to cause some problems within GNS3, but I didn’t notice any glitches with Npcap v0.9982.

After start sniffing on the loopback, Wireshark shows a lot of traffic. Using the display filter “http” makes it much clearer. Every second a “GET /v2/computes” is issued by the GUI. You will also see the internal communication within the local server, those “/v2/compute/…” messages. You can safely ignore these two message types.

Here an example, when moving a node in the GUI, the highlighted message is the relevant one.

Wireshark capture

To get a textual display of this request, select it in the packet list window and then right-click / Follow / HTTP Stream.

Wireshark HTTP stream

Close this window with “Back”, this restores the previous display filter. Otherwise you have to set the display filter back to “http” manually.

Use of the API in a Programming Language

While playing with some test clients is informative, you normally want to use the API for automating things. And for that you need a programming language. David Bombal uses cURL and bash scripting in his GNS3 REST API talks. But the bash is not well suited for managing structured data. So using bash is only useful for basic tasks.

Any programming language, that allows to create HTTP requests and that can handle JSON data, is able make use of the API. So most (if not all) languages are suitable. A very popular language in the networking environment is Python. As Python natively supports HTTP requests and JSON, it’s well suited for accessing the API.

A major drawback is, that GNS3 hasn’t created a library for any language to interface the API. Every developer has to create it’s own library, that creates the HTTP requests and translates JSON from/to the internal data representation.

For Python I’ve created a very simple python module named gns3api, see https://git.bernhard-ehlers.de/ehlers/gns3api. You have to download gns3api.py and store it in the same directory as the python script.

Maarten van der Woord has created another python module, that interfaces to the GNS3 API: PyGNS3 (https://github.com/mvdwoord/PyGNS3). I haven’t tried that, but it looks very promising.

Final Tips

  • Start small
    Don’t try to create a node as your first task. Start simple, for example start/stop nodes, move nodes.
  • Not all parameters are required
    Most API calls have a long list of parameters, setting all of them makes a request quite big. But that’s normally not needed. The API documentation lists, which parameter are mandatory, most are optional. So make your requests clearer by specifying only the necessary parameters.