The GNS3 API (http://api.gns3.net/) is a great method to automate and enhance GNS3. David Bombal created a very good series of videos about this topic, see his GNS3 REST API playlist on YouTube.

In David’s videos and in various other examples no authentication is used. But GNS3 by default uses authentication, so this will not work in your installation. You will get a “401 - Unauthorized” error.

Disable GNS3 Server Authentication

The easy way to solve this issue is to turn off the authentication in your local GNS3 server. In the GNS3 preferences -> Server -> Main server disable the “Protect server with password (recommended)” setting.

GNS3 Authentication

While this will give you easy access to the GNS3 API, it has a major drawback. Anyone, who can reach your computer from the LAN or the internet, can also use the GNS3 server without credentials. They can modify or delete your GNS3 projects and destroy hours of work.

Therefore use this option only for short tests, in normal operation enble the password setting.

Use GNS3 API with Password

The secure way is to add the usename and password to your API call. For that a HTTP Authorization header with the credentials has to be added to the API request. For details have a look into this Wikipedia article.

But first you need to know the username and password. You have never specified the credentials and there is no way in the GUI to see or change them.

On the initial setup the GNS3 GUI creates a random username and password and stores it in ~/.config/GNS3/gns3_server.conf (Linux/Mac OS X) or in %APPDATA%\GNS3\gns3_server.ini (Windows).

The first few lines of my configuration file are looking like this:

[Server]
host = 0.0.0.0
port = 3080
ubridge_path = /usr/local/bin/ubridge
auth = True
user = <64_characters_long_random_username>
password =  <64_characters_long_random_password>
images_path = /Users/behlers/GNS3/images
projects_path = /Users/behlers/GNS3/projects
configs_path = /Users/behlers/GNS3/configs

You have three options:

  • Use the username and password from the configuration file.
    The drawback is, that you have to deal with these incredible long strings.
  • Change the “user” and “password” lines for simpler credentials.
    But be sure, you have made a backup and stopped GNS3 before editing.
  • Let your program, that accesses the API, read the configuration file.
    Then the user doesn’t need to know the credentals. My python module gns3api is working that way.

Sending credentials with curl

For command line enthusiasts using curl you need to use the “-u” option.

# curl -i -u 'username:password' http://127.0.0.1:3080/v2/version
HTTP/1.1 200 OK
Connection: close
X-Route: /v2/version
Server: Python/3.6 GNS3/2.1.8
Content-Type: application/json
Content-Length: 45
Date: Sun, 22 Jul 2018 10:56:53 GMT

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

Sending credentials with Postman

A nicer way is to use Postman (https://www.getpostman.com) to access the API. As an alternative to installing a native application, you can use the “Tabbed Postman” extension from the Chrome web store.

In Postman select “Basic Auth” and enter the credentials.

Postman Authentication #1

With “Refresh headers” the encoded HTTP Authorization header is generated. You can now enter the API URL and send the request.

Postman Authentication #2