Bernhard's Homepage

GNS3 - Integrate Programs / Scripts

GNS3 - Integrate Programs / Scripts

Currently (GNS3 v2.x) 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 download the source of the GNS3 GUI with git, select branch “2.2”, download the patches from https://git.bernhard-ehlers.de/ehlers/gns3-gui-tools and integrate them into the GUI source with git am --committer-date-is-author-date <path to patches>/*. Then install the GUI with python3 setup.py install. 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 (https://gns3-server.readthedocs.io/) 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://git.bernhard-ehlers.de/ehlers/gns3-gui-tools/src/branch/master/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 sometimes, 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.

#!/usr/bin/python3
# verify the path, it might be /usr/local/bin/python3

"""
Close Project - close GNS3 project

Usage: close_project version parameter-file project-id [sel-item ...]
"""

import os
import sys
import gns3api

# get command line parameter
if len(sys.argv) < 4:
    sys.exit("usage: close_project version parameter-file project-id [sel-item ...]")
try:
    with open(sys.argv[2], "r") as file:
        cntl_url, cntl_user, cntl_passwd, *_ = file.read(512).splitlines()
    if sys.argv[2].endswith(".tmp"):
        os.remove(sys.argv[2])
except (OSError, ValueError) as err:
    sys.exit("Can't get controller connection params: {}".format(err))
project_id = sys.argv[3]

# connect to GNS3 controller
try:
    api = gns3api.GNS3Api(cntl_url, cntl_user, cntl_passwd)
except gns3api.GNS3ApiException as err:
    sys.exit("Can't connect to GNS3 controller: {}".format(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. Install it by copying ios_base_config.py, ios_base_config.json and gns3api.py to the GNS3/tools directory. Afterwards restart the GNS3 GUI.