Tools integrated in GNS3

[ghost]

I developed a solution, where programs / scripts stored 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 download the source of the GNS3 GUI with git, select branch "2.2", download the patches from https://github.com/grossmj/gns3-gui-tools and integrate them into the GUI source with git am <path to patches>/*. Then install the GUI with pip3 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://github.com/grossmj/gns3-gui-tools/blob/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 gns3api (https://github.com/b-ehlers/gns3api-python). 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 }.

More Examples

A collection of (mostly small) tools is available at https://github.com/Raizo62/gns3-tools-python.

[ghost]

Related issue: #708

[grossmj]

Thanks for posting here :)

[eantowne]

Is this possibly an opportunity for a feature? The ability to extend GNS3 functionality by having custom python scripts be added tot he tools menu by placing them in a specific folder or importing them? As long as the script does not use any libraries not already available from the GNS3 install, could the GNS3 binaries run the script without the host having python installed? Even then, could just be a thing that if people want to use extensions, they need to install python.

[ghost]

Is this possibly an opportunity for a feature?

Yes, it's already discussed in issue #708

The ability to extend GNS3 functionality by having custom python scripts be added tot he tools menu by placing them in a specific folder or importing them?

Don't get it, what is the question?

As long as the script does not use any libraries not already available from the GNS3 install, could the GNS3 binaries run the script without the host having python installed?

In the current implementation, the tools run externally to the GUI as separate processes. You can either use an .exe file or a script to implement them. If you use a script, you have to install the interpreter. In case of Python, that means, you need to install the python interpreter. The GNS3 binary is a compiled python program, that doesn't ship the python interpreter. So GNS3 is no help to run python scripts.

I can think of two ways around that:

• The GNS3 installer includes an option to install python.
• The GUI runs the scripts, written in Python, internally via exec(). I have no idea, if that works within the compiled GUI. And I fear, that misbehaving tools might crash the GUI. So that might be an option for later.

[eantowne]

The ability to extend GNS3 functionality by having custom python scripts be added tot he tools menu by placing them in a specific folder or importing them?

Don't get it, what is the question?

The question being, should the tools be automatically added if found in a specific directory or should they need to be manually imported?

[ghost]

I think, that both ways are fine. A specific directory is very easy to implement, but not so user friendly. In the end, Jeremy has to decide.

[grossmj]

I think both would be great to have 👍