Currently (GNS3 v2.0/2.1) the possibilities to integrate external programs or scripts into GNS3 are limited. You can create a custom console application. It doesn’t have to be a terminal application, you can start any program or script. Right-click on a device, then select “Custom console”. Then choose “Custom” to define a custom command and save it for later use. Some variables can be passed as command line arguments to the application, see the screenshot.

Custom Console

The main drawbacks are:

  • It’s a bit difficult to find, hardly anyone looks at “Custom console” for external programs.
  • When you select multiple devices, a new command is started for each of them. You can’t start a single program, that handles all selected devices.

Tools integrated in GNS3

Because of that, I developed an alternative solution. Programs / scripts in the GNS3/tools folder are available in the main “Tools” menu and the context menu.

Tools Menu Context Menu

This is not part of the standard GNS3 program, you have to install the source of the modified GNS3 GUI from https://github.com/ehlers/gns3-gui/tree/tools, branch tools. So that’s only feasible for very experienced users.

Tools are executables, that are called by the GNS3 GUI. They normally use the GNS3 API (http://api.gns3.net/) to query and/or modify the current project. The GNS3 GUI is automatically updated, when the project is changed. The programs are installed in the GNS3/tools directory. As the GNS3 GUI checks this directory only at startup, it has to be restarted after adding/removing tools. A short documentation can be found at https://github.com/ehlers/gns3-gui/blob/tools/tools.md.

The tool can be accompanied by a JSON file, that allows to define some properties. I haven’t done that within the GNS3 configuration menu, because I think, that the creator of a tool should define the parameters. The typical user should not be bothered with this.

The option “run in terminal” is mainly implemented to make debugging easy during development. But it also allows to integrate programs without a GUI. In Windows it’s also needed to run Python scripts, Windows refuses to run them in GUI mode.

One major drawback is, that it’s not easy to distribute these tools. If you want to distribute binaries, you need to create them for Windows, Linux and Mac OS X. If you’re using a script language like Python, the user has to install that language. One solution could be a full Python 3 for Windows and OS X included in the GNS3 package. But that would significantly increase the size of GNS3.

Example: Close Project

The GNS3 GUI doesn’t allow to close a project without opening a new one. But sometines, when changing settings, I want to be sure that no project is open.

This Python script close_project.py closes a GNS3 project. It uses the GNS3 API module from https://git.bernhard-ehlers.de/ehlers/gns3api. The easiest way is to download gns3api.py and store it in the GNS3/tools folder. No other non-standard modules are used. Both Python 2 and Python 3 are supported.

#!/usr/bin/python
#
# Close Project - close GNS3 project
#
# Usage: close_project version project_id
#

import sys
import gns3api

def die(*msg_list):
    """ abort program with error message """
    error_msg = ' '.join(str(x) for x in msg_list)
    sys.exit(error_msg.rstrip("\n\r"))


# get command line parameter
if len(sys.argv) >= 3:
    project_id = sys.argv[2]
else:
    die("Usage: close_project version project_id")

# connect to GNS3 controller
try:
    api = gns3api.GNS3Api()
except (IOError, OSError, gns3api.GNS3BaseException) as err:
    die("Can't connect to GNS3 controller:", err)

api.request("POST", ("/v2/projects", project_id, "close"))

With the attached close_project.json it won’t show up in the context menu. So it’s only available in the main “Tools” menu.

{
    "name": "Close Project",
    "context": false
}

Windows only:

  • Windows refuses to run Python scripts like this in GUI mode, add "terminal": true to close_project.json.
  • Windows recognizes gns3api.py as an external tool. To prevent, that it shows in the tool or context menu, create a dummy gns3api.json with { "menu": false, "context": false }.

Showcase: Automatic IOS Base Configuration

With ios_base_config it’s possible to automatically create and deploy an IOS base configuration. For further information have a look at https://git.bernhard-ehlers.de/ehlers/gns3-ios-base-config.