GNS3 - Integrate Programs / Scripts
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.
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.
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 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.
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
toclose_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.