arno/gns3-server
1
0
Fork 0
mirror of https://github.com/GNS3/gns3-server synced 2024-12-25 00:08:11 +00:00
Code Issues Releases Wiki Activity

New base server.

Browse Source
This commit is contained in:
Jeremy 2015-01-13 17:05:26 -07:00
parent 5e665cc67a
commit 61344a1669
51 changed files with 2632 additions and 1835 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

177
docs/Makefile Normal file
View File

@ -0,0 +1,177 @@
# Makefile for Sphinx documentation
#
# You can set these variables from the command line.
SPHINXOPTS =
SPHINXBUILD = sphinx-build
PAPER =
BUILDDIR = _build
# User-friendly check for sphinx-build
ifeq ($(shell which $(SPHINXBUILD) >/dev/null 2>&1; echo $$?), 1)
$(error The '$(SPHINXBUILD)' command was not found. Make sure you have Sphinx installed, then set the SPHINXBUILD environment variable to point to the full path of the '$(SPHINXBUILD)' executable. Alternatively you can add the directory with the executable to your PATH. If you don't have Sphinx installed, grab it from http://sphinx-doc.org/)
endif
# Internal variables.
PAPEROPT_a4 = -D latex_paper_size=a4
PAPEROPT_letter = -D latex_paper_size=letter
ALLSPHINXOPTS = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
# the i18n builder cannot share the environment and doctrees with the others
I18NSPHINXOPTS = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
help:
@echo "Please use \`make <target>' where <target> is one of"
@echo " html to make standalone HTML files"
@echo " dirhtml to make HTML files named index.html in directories"
@echo " singlehtml to make a single large HTML file"
@echo " pickle to make pickle files"
@echo " json to make JSON files"
@echo " htmlhelp to make HTML files and a HTML help project"
@echo " qthelp to make HTML files and a qthelp project"
@echo " devhelp to make HTML files and a Devhelp project"
@echo " epub to make an epub"
@echo " latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter"
@echo " latexpdf to make LaTeX files and run them through pdflatex"
@echo " latexpdfja to make LaTeX files and run them through platex/dvipdfmx"
@echo " text to make text files"
@echo " man to make manual pages"
@echo " texinfo to make Texinfo files"
@echo " info to make Texinfo files and run them through makeinfo"
@echo " gettext to make PO message catalogs"
@echo " changes to make an overview of all changed/added/deprecated items"
@echo " xml to make Docutils-native XML files"
@echo " pseudoxml to make pseudoxml-XML files for display purposes"
@echo " linkcheck to check all external links for integrity"
@echo " doctest to run all doctests embedded in the documentation (if enabled)"
clean:
rm -rf $(BUILDDIR)/*
html:
$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."
dirhtml:
$(SPHINXBUILD) -b dirhtml $(ALLSPHINXOPTS) $(BUILDDIR)/dirhtml
@echo
@echo "Build finished. The HTML pages are in $(BUILDDIR)/dirhtml."
singlehtml:
$(SPHINXBUILD) -b singlehtml $(ALLSPHINXOPTS) $(BUILDDIR)/singlehtml
@echo
@echo "Build finished. The HTML page is in $(BUILDDIR)/singlehtml."
pickle:
$(SPHINXBUILD) -b pickle $(ALLSPHINXOPTS) $(BUILDDIR)/pickle
@echo
@echo "Build finished; now you can process the pickle files."
json:
$(SPHINXBUILD) -b json $(ALLSPHINXOPTS) $(BUILDDIR)/json
@echo
@echo "Build finished; now you can process the JSON files."
htmlhelp:
$(SPHINXBUILD) -b htmlhelp $(ALLSPHINXOPTS) $(BUILDDIR)/htmlhelp
@echo
@echo "Build finished; now you can run HTML Help Workshop with the" \
".hhp project file in $(BUILDDIR)/htmlhelp."
qthelp:
$(SPHINXBUILD) -b qthelp $(ALLSPHINXOPTS) $(BUILDDIR)/qthelp
@echo
@echo "Build finished; now you can run "qcollectiongenerator" with the" \
".qhcp project file in $(BUILDDIR)/qthelp, like this:"
@echo "# qcollectiongenerator $(BUILDDIR)/qthelp/GNS3.qhcp"
@echo "To view the help file:"
@echo "# assistant -collectionFile $(BUILDDIR)/qthelp/GNS3.qhc"
devhelp:
$(SPHINXBUILD) -b devhelp $(ALLSPHINXOPTS) $(BUILDDIR)/devhelp
@echo
@echo "Build finished."
@echo "To view the help file:"
@echo "# mkdir -p $$HOME/.local/share/devhelp/GNS3"
@echo "# ln -s $(BUILDDIR)/devhelp $$HOME/.local/share/devhelp/GNS3"
@echo "# devhelp"
epub:
$(SPHINXBUILD) -b epub $(ALLSPHINXOPTS) $(BUILDDIR)/epub
@echo
@echo "Build finished. The epub file is in $(BUILDDIR)/epub."
latex:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo
@echo "Build finished; the LaTeX files are in $(BUILDDIR)/latex."
@echo "Run \`make' in that directory to run these through (pdf)latex" \
"(use \`make latexpdf' here to do that automatically)."
latexpdf:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through pdflatex..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
latexpdfja:
$(SPHINXBUILD) -b latex $(ALLSPHINXOPTS) $(BUILDDIR)/latex
@echo "Running LaTeX files through platex and dvipdfmx..."
$(MAKE) -C $(BUILDDIR)/latex all-pdf-ja
@echo "pdflatex finished; the PDF files are in $(BUILDDIR)/latex."
text:
$(SPHINXBUILD) -b text $(ALLSPHINXOPTS) $(BUILDDIR)/text
@echo
@echo "Build finished. The text files are in $(BUILDDIR)/text."
man:
$(SPHINXBUILD) -b man $(ALLSPHINXOPTS) $(BUILDDIR)/man
@echo
@echo "Build finished. The manual pages are in $(BUILDDIR)/man."
texinfo:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo
@echo "Build finished. The Texinfo files are in $(BUILDDIR)/texinfo."
@echo "Run \`make' in that directory to run these through makeinfo" \
"(use \`make info' here to do that automatically)."
info:
$(SPHINXBUILD) -b texinfo $(ALLSPHINXOPTS) $(BUILDDIR)/texinfo
@echo "Running Texinfo files through makeinfo..."
make -C $(BUILDDIR)/texinfo info
@echo "makeinfo finished; the Info files are in $(BUILDDIR)/texinfo."
gettext:
$(SPHINXBUILD) -b gettext $(I18NSPHINXOPTS) $(BUILDDIR)/locale
@echo
@echo "Build finished. The message catalogs are in $(BUILDDIR)/locale."
changes:
$(SPHINXBUILD) -b changes $(ALLSPHINXOPTS) $(BUILDDIR)/changes
@echo
@echo "The overview file is in $(BUILDDIR)/changes."
linkcheck:
$(SPHINXBUILD) -b linkcheck $(ALLSPHINXOPTS) $(BUILDDIR)/linkcheck
@echo
@echo "Link check complete; look for any errors in the above output " \
"or in $(BUILDDIR)/linkcheck/output.txt."
doctest:
$(SPHINXBUILD) -b doctest $(ALLSPHINXOPTS) $(BUILDDIR)/doctest
@echo "Testing of doctests in the sources finished, look at the " \
"results in $(BUILDDIR)/doctest/output.txt."
xml:
$(SPHINXBUILD) -b xml $(ALLSPHINXOPTS) $(BUILDDIR)/xml
@echo
@echo "Build finished. The XML files are in $(BUILDDIR)/xml."
pseudoxml:
$(SPHINXBUILD) -b pseudoxml $(ALLSPHINXOPTS) $(BUILDDIR)/pseudoxml
@echo
@echo "Build finished. The pseudo-XML files are in $(BUILDDIR)/pseudoxml."

0
gns3server/modules/vpcs/adapters/__init__.py → docs/__init__.py
View File

17
docs/api/examples/get_version.txt Normal file
View File

@ -0,0 +1,17 @@
curl -i -xGET 'http://localhost:8000/version'
GET /version HTTP/1.1
HTTP/1.1 200
CONNECTION: close
CONTENT-LENGTH: 31
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 aiohttp/0.13.1
X-ROUTE: /version
{
"version": "1.2.2.dev2"
}

19
docs/api/examples/post_version.txt Normal file
View File

@ -0,0 +1,19 @@
curl -i -xPOST 'http://localhost:8000/version' -d '{"version": "1.2.2.dev2"}'
POST /version HTTP/1.1
{
"version": "1.2.2.dev2"
}
HTTP/1.1 200
CONNECTION: close
CONTENT-LENGTH: 31
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 aiohttp/0.13.1
X-ROUTE: /version
{
"version": "1.2.2.dev2"
}

21
docs/api/examples/post_vpcs.txt Normal file
View File

@ -0,0 +1,21 @@
curl -i -xPOST 'http://localhost:8000/vpcs' -d '{"name": "PC TEST 1"}'
POST /vpcs HTTP/1.1
{
"name": "PC TEST 1"
}
HTTP/1.1 200
CONNECTION: close
CONTENT-LENGTH: 67
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 aiohttp/0.13.1
X-ROUTE: /vpcs
{
"console": 4242,
"name": "PC TEST 1",
"vpcs_id": 42
}

28
docs/api/examples/post_vpcsvpcsidnio.txt Normal file
View File

@ -0,0 +1,28 @@
curl -i -xPOST 'http://localhost:8000/vpcs/{vpcs_id}/nio' -d '{"id": 42, "nio": {"local_file": "/tmp/test", "remote_file": "/tmp/remote", "type": "nio_unix"}, "port": 0, "port_id": 0}'
POST /vpcs/{vpcs_id}/nio HTTP/1.1
{
"id": 42,
"nio": {
"local_file": "/tmp/test",
"remote_file": "/tmp/remote",
"type": "nio_unix"
},
"port": 0,
"port_id": 0
}
HTTP/1.1 200
CONNECTION: close
CONTENT-LENGTH: 62
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 aiohttp/0.13.1
X-ROUTE: /vpcs/{vpcs_id}/nio
{
"console": 4242,
"name": "PC 2",
"vpcs_id": 42
}

13
docs/api/sleep.rst Normal file
View File

@ -0,0 +1,13 @@
/sleep
------------------------------
.. contents::
GET /sleep
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Response status codes
**************************
- **200**: OK

13
docs/api/stream.rst Normal file
View File

@ -0,0 +1,13 @@
/stream
------------------------------
.. contents::
GET /stream
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Response status codes
**************************
- **200**: OK

28
docs/api/version.rst Normal file
View File

@ -0,0 +1,28 @@
/version
------------------------------
.. contents::
GET /version
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Retrieve server version number
Response status codes
**************************
- **200**: OK
Output
*******
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>version</td><td>&#10004;</td><td>string</td><td>Version number human readable</td></tr>
</table>
Sample session
***************
.. literalinclude:: examples/get_version.txt

46
docs/api/vpcs.rst Normal file
View File

@ -0,0 +1,46 @@
/vpcs
------------------------------
.. contents::
POST /vpcs
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Create a new VPCS and return it
Parameters
**********
- **vpcs_id**: Id of VPCS instance
Response status codes
**************************
- **201**: Success of creation of VPCS
- **409**: Conflict
Input
*******
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>console</td><td> </td><td>integer</td><td>console TCP port</td></tr>
<tr><td>name</td><td>&#10004;</td><td>string</td><td>VPCS device name</td></tr>
<tr><td>vpcs_id</td><td> </td><td>integer</td><td>VPCS device instance ID</td></tr>
</table>
Output
*******
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>console</td><td>&#10004;</td><td>integer</td><td>console TCP port</td></tr>
<tr><td>name</td><td>&#10004;</td><td>string</td><td>VPCS device name</td></tr>
<tr><td>vpcs_id</td><td>&#10004;</td><td>integer</td><td>VPCS device instance ID</td></tr>
</table>
Sample session
***************
.. literalinclude:: examples/post_vpcs.txt

63
docs/api/vpcsvpcsid.rst Normal file
View File

@ -0,0 +1,63 @@
/vpcs/{vpcs_id}
------------------------------
.. contents::
GET /vpcs/{vpcs_id}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Get informations about a VPCS
Parameters
**********
- **vpcs_id**: Id of VPCS instance
Response status codes
**************************
- **200**: OK
Output
*******
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>console</td><td>&#10004;</td><td>integer</td><td>console TCP port</td></tr>
<tr><td>name</td><td>&#10004;</td><td>string</td><td>VPCS device name</td></tr>
<tr><td>vpcs_id</td><td>&#10004;</td><td>integer</td><td>VPCS device instance ID</td></tr>
</table>
PUT /vpcs/{vpcs_id}
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Update VPCS informations
Parameters
**********
- **vpcs_id**: Id of VPCS instance
Response status codes
**************************
- **200**: OK
Input
*******
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>console</td><td>&#10004;</td><td>integer</td><td>console TCP port</td></tr>
<tr><td>name</td><td>&#10004;</td><td>string</td><td>VPCS device name</td></tr>
<tr><td>vpcs_id</td><td>&#10004;</td><td>integer</td><td>VPCS device instance ID</td></tr>
</table>
Output
*******
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>console</td><td>&#10004;</td><td>integer</td><td>console TCP port</td></tr>
<tr><td>name</td><td>&#10004;</td><td>string</td><td>VPCS device name</td></tr>
<tr><td>vpcs_id</td><td>&#10004;</td><td>integer</td><td>VPCS device instance ID</td></tr>
</table>

127
docs/api/vpcsvpcsidnio.rst Normal file
View File

@ -0,0 +1,127 @@
/vpcs/{vpcs_id}/nio
------------------------------
.. contents::
POST /vpcs/{vpcs_id}/nio
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
ADD NIO to a VPCS
Parameters
**********
- **vpcs_id**: Id of VPCS instance
Response status codes
**************************
- **201**: Success of creation of NIO
- **409**: Conflict
Input
*******
Types
+++++++++
Ethernet
^^^^^^^^^^^^^^^^
Generic Ethernet Network Input/Output
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>ethernet_device</td><td>&#10004;</td><td>string</td><td>Ethernet device name e.g. eth0</td></tr>
<tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_generic_ethernet</td></tr>
</table>
LinuxEthernet
^^^^^^^^^^^^^^^^
Linux Ethernet Network Input/Output
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>ethernet_device</td><td>&#10004;</td><td>string</td><td>Ethernet device name e.g. eth0</td></tr>
<tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_linux_ethernet</td></tr>
</table>
NULL
^^^^^^^^^^^^^^^^
NULL Network Input/Output
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_null</td></tr>
</table>
TAP
^^^^^^^^^^^^^^^^
TAP Network Input/Output
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>tap_device</td><td>&#10004;</td><td>string</td><td>TAP device name e.g. tap0</td></tr>
<tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_tap</td></tr>
</table>
UDP
^^^^^^^^^^^^^^^^
UDP Network Input/Output
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>lport</td><td>&#10004;</td><td>integer</td><td>Local port</td></tr>
<tr><td>rhost</td><td>&#10004;</td><td>string</td><td>Remote host</td></tr>
<tr><td>rport</td><td>&#10004;</td><td>integer</td><td>Remote port</td></tr>
<tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_udp</td></tr>
</table>
UNIX
^^^^^^^^^^^^^^^^
UNIX Network Input/Output
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>local_file</td><td>&#10004;</td><td>string</td><td>path to the UNIX socket file (local)</td></tr>
<tr><td>remote_file</td><td>&#10004;</td><td>string</td><td>path to the UNIX socket file (remote)</td></tr>
<tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_unix</td></tr>
</table>
VDE
^^^^^^^^^^^^^^^^
VDE Network Input/Output
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>control_file</td><td>&#10004;</td><td>string</td><td>path to the VDE control file</td></tr>
<tr><td>local_file</td><td>&#10004;</td><td>string</td><td>path to the VDE control file</td></tr>
<tr><td>type</td><td>&#10004;</td><td>enum</td><td>Possible values: nio_vde</td></tr>
</table>
Body
+++++++++
.. raw:: html
<table>
<tr><th>Name</th><th>Mandatory</th><th>Type</th><th>Description</th></tr>
<tr><td>id</td><td>&#10004;</td><td>integer</td><td>VPCS device instance ID</td></tr>
<tr><td>nio</td><td>&#10004;</td><td>UDP, Ethernet, LinuxEthernet, TAP, UNIX, VDE, NULL</td><td>Network Input/Output</td></tr>
<tr><td>port</td><td>&#10004;</td><td>integer</td><td>Port number</td></tr>
<tr><td>port_id</td><td>&#10004;</td><td>integer</td><td>Unique port identifier for the VPCS instance</td></tr>
</table>
Sample session
***************
.. literalinclude:: examples/post_vpcsvpcsidnio.txt

260
docs/conf.py Normal file
View File

@ -0,0 +1,260 @@
#!/usr/bin/env python3
# -*- coding: utf-8 -*-
#
# POC documentation build configuration file, created by
# sphinx-quickstart on Mon Jan 5 14:15:48 2015.
#
# This file is execfile()d with the current directory set to its
# containing dir.
#
# Note that not all possible configuration values are present in this
# autogenerated file.
#
# All configuration values have a default; values that are commented out
# serve to show the default.
import sys
import os
# If extensions (or modules to document with autodoc) are in another directory,
# add these directories to sys.path here. If the directory is relative to the
# documentation root, use os.path.abspath to make it absolute, like shown here.
sys.path.insert(0, os.path.abspath('..'))
from demoserver.version import __version__, __version_info__
# -- General configuration ------------------------------------------------
# If your documentation needs a minimal Sphinx version, state it here.
# needs_sphinx = '1.0'
# Add any Sphinx extension module names here, as strings. They can be
# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
# ones.
extensions = []
# Add any paths that contain templates here, relative to this directory.
templates_path = ['_templates']
# The suffix of source filenames.
source_suffix = '.rst'
# The encoding of source files.
# source_encoding = 'utf-8-sig'
# The master toctree document.
master_doc = 'index'
# General information about the project.
project = 'POC'
copyright = '2015, POC Team'
# The version info for the project you're documenting, acts as replacement for
# |version| and |release|, also used in various other places throughout the
# built documents.
#
# The short X.Y version.
version = '.'.join(map(lambda x: str(x), __version_info__))
# The full version, including alpha/beta/rc tags.
release = __version__
# The language for content autogenerated by Sphinx. Refer to documentation
# for a list of supported languages.
# language = None
# There are two options for replacing |today|: either, you set today to some
# non-false value, then it is used:
# today = ''
# Else, today_fmt is used as the format for a strftime call.
# today_fmt = '%B %d, %Y'
# List of patterns, relative to source directory, that match files and
# directories to ignore when looking for source files.
exclude_patterns = ['_build']
# The reST default role (used for this markup: `text`) to use for all
# documents.
# default_role = None
# If true, '()' will be appended to :func: etc. cross-reference text.
# add_function_parentheses = True
# If true, the current module name will be prepended to all description
# unit titles (such as .. function::).
# add_module_names = True
# If true, sectionauthor and moduleauthor directives will be shown in the
# output. They are ignored by default.
# show_authors = False
# The name of the Pygments (syntax highlighting) style to use.
pygments_style = 'sphinx'
# A list of ignored prefixes for module index sorting.
# modindex_common_prefix = []
# If true, keep warnings as "system message" paragraphs in the built documents.
# keep_warnings = False
# -- Options for HTML output ----------------------------------------------
# The theme to use for HTML and HTML Help pages. See the documentation for
# a list of builtin themes.
html_theme = 'default'
# Theme options are theme-specific and customize the look and feel of a theme
# further. For a list of options available for each theme, see the
# documentation.
# html_theme_options = {}
# Add any paths that contain custom themes here, relative to this directory.
# html_theme_path = []
# The name for this set of Sphinx documents. If None, it defaults to
# "<project> v<release> documentation".
# html_title = None
# A shorter title for the navigation bar. Default is the same as html_title.
# html_short_title = None
# The name of an image file (relative to this directory) to place at the top
# of the sidebar.
# html_logo = None
# The name of an image file (within the static path) to use as favicon of the
# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32
# pixels large.
# html_favicon = None
# Add any paths that contain custom static files (such as style sheets) here,
# relative to this directory. They are copied after the builtin static files,
# so a file named "default.css" will overwrite the builtin "default.css".
html_static_path = ['_static']
# Add any extra paths that contain custom files (such as robots.txt or
# .htaccess) here, relative to this directory. These files are copied
# directly to the root of the documentation.
# html_extra_path = []
# If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
# using the given strftime format.
# html_last_updated_fmt = '%b %d, %Y'
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
# html_use_smartypants = True
# Custom sidebar templates, maps document names to template names.
# html_sidebars = {}
# Additional templates that should be rendered to pages, maps page names to
# template names.
# html_additional_pages = {}
# If false, no module index is generated.
# html_domain_indices = True
# If false, no index is generated.
# html_use_index = True
# If true, the index is split into individual pages for each letter.
# html_split_index = False
# If true, links to the reST sources are added to the pages.
# html_show_sourcelink = True
# If true, "Created using Sphinx" is shown in the HTML footer. Default is True.
# html_show_sphinx = True
# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True.
# html_show_copyright = True
# If true, an OpenSearch description file will be output, and all pages will
# contain a <link> tag referring to it. The value of this option must be the
# base URL from which the finished HTML is served.
# html_use_opensearch = ''
# This is the file name suffix for HTML files (e.g. ".xhtml").
# html_file_suffix = None
# Output file base name for HTML help builder.
htmlhelp_basename = 'POCdoc'
# -- Options for LaTeX output ---------------------------------------------
latex_elements = {
# The paper size ('letterpaper' or 'a4paper').
# 'papersize': 'letterpaper',
# The font size ('10pt', '11pt' or '12pt').
# 'pointsize': '10pt',
# Additional stuff for the LaTeX preamble.
# 'preamble': '',
}
# Grouping the document tree into LaTeX files. List of tuples
# (source start file, target name, title,
# author, documentclass [howto, manual, or own class]).
latex_documents = [
('index', 'POC.tex', 'POC Documentation', 'POC Team', 'manual'),
]
# The name of an image file (relative to this directory) to place at the top of
# the title page.
# latex_logo = None
# For "manual" documents, if this is true, then toplevel headings are parts,
# not chapters.
# latex_use_parts = False
# If true, show page references after internal links.
# latex_show_pagerefs = False
# If true, show URL addresses after external links.
# latex_show_urls = False
# Documents to append as an appendix to all manuals.
# latex_appendices = []
# If false, no module index is generated.
# latex_domain_indices = True
# -- Options for manual page output ---------------------------------------
# One entry per manual page. List of tuples
# (source start file, name, description, authors, manual section).
man_pages = [
('index', 'gns3', 'POC Documentation',
['POC Team'], 1)
]
# If true, show URL addresses after external links.
# man_show_urls = False
# -- Options for Texinfo output -------------------------------------------
# Grouping the document tree into Texinfo files. List of tuples
# (source start file, target name, title, author,
# dir menu entry, description, category)
texinfo_documents = [
('index', 'POC', 'POC Documentation',
'POC Team', 'POC', 'One line description of project.',
'Miscellaneous'),
]
# Documents to append as an appendix to all manuals.
# texinfo_appendices = []
# If false, no module index is generated.
# texinfo_domain_indices = True
# How to display URL addresses: 'footnote', 'no', or 'inline'.
# texinfo_show_urls = 'footnote'
# If true, do not generate a @detailmenu in the "Top" node's menu.
# texinfo_no_detailmenu = False

33
docs/development.rst Normal file
View File

@ -0,0 +1,33 @@
Development
############
Code convention
===============
You should respect all the PEP8 convention except the
rule about max line length.
Documentation
==============
Build doc
----------
In the project root folder:
.. code-block:: bash
./documentation.sh
The output is available inside *docs/_build/html*
Tests
======
Run tests
----------
.. code-block:: bash
py.test -v

12
docs/general.rst Normal file
View File

@ -0,0 +1,12 @@
Errors
======
In case of error a standard HTTP error is raise and you got a
JSON like that
.. code-block:: json
{
"status": 409,
"message": "Conflict"
}

18
docs/index.rst Normal file
View File

@ -0,0 +1,18 @@
Welcome to API documentation!
======================================
.. toctree::
general
development
API Endpoints
~~~~~~~~~~~~~~~
.. toctree::
:glob:
:maxdepth: 2
api/*

242
docs/make.bat Normal file
View File

@ -0,0 +1,242 @@
@ECHO OFF
REM Command file for Sphinx documentation
if "%SPHINXBUILD%" == "" (
set SPHINXBUILD=sphinx-build
)
set BUILDDIR=_build
set ALLSPHINXOPTS=-d %BUILDDIR%/doctrees %SPHINXOPTS% .
set I18NSPHINXOPTS=%SPHINXOPTS% .
if NOT "%PAPER%" == "" (
set ALLSPHINXOPTS=-D latex_paper_size=%PAPER% %ALLSPHINXOPTS%
set I18NSPHINXOPTS=-D latex_paper_size=%PAPER% %I18NSPHINXOPTS%
)
if "%1" == "" goto help
if "%1" == "help" (
:help
echo.Please use `make ^<target^>` where ^<target^> is one of
echo. html to make standalone HTML files
echo. dirhtml to make HTML files named index.html in directories
echo. singlehtml to make a single large HTML file
echo. pickle to make pickle files
echo. json to make JSON files
echo. htmlhelp to make HTML files and a HTML help project
echo. qthelp to make HTML files and a qthelp project
echo. devhelp to make HTML files and a Devhelp project
echo. epub to make an epub
echo. latex to make LaTeX files, you can set PAPER=a4 or PAPER=letter
echo. text to make text files
echo. man to make manual pages
echo. texinfo to make Texinfo files
echo. gettext to make PO message catalogs
echo. changes to make an overview over all changed/added/deprecated items
echo. xml to make Docutils-native XML files
echo. pseudoxml to make pseudoxml-XML files for display purposes
echo. linkcheck to check all external links for integrity
echo. doctest to run all doctests embedded in the documentation if enabled
goto end
)
if "%1" == "clean" (
for /d %%i in (%BUILDDIR%\*) do rmdir /q /s %%i
del /q /s %BUILDDIR%\*
goto end
)
%SPHINXBUILD% 2> nul
if errorlevel 9009 (
echo.
echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
echo.installed, then set the SPHINXBUILD environment variable to point
echo.to the full path of the 'sphinx-build' executable. Alternatively you
echo.may add the Sphinx directory to PATH.
echo.
echo.If you don't have Sphinx installed, grab it from
echo.http://sphinx-doc.org/
exit /b 1
)
if "%1" == "html" (
%SPHINXBUILD% -b html %ALLSPHINXOPTS% %BUILDDIR%/html
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/html.
goto end
)
if "%1" == "dirhtml" (
%SPHINXBUILD% -b dirhtml %ALLSPHINXOPTS% %BUILDDIR%/dirhtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/dirhtml.
goto end
)
if "%1" == "singlehtml" (
%SPHINXBUILD% -b singlehtml %ALLSPHINXOPTS% %BUILDDIR%/singlehtml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The HTML pages are in %BUILDDIR%/singlehtml.
goto end
)
if "%1" == "pickle" (
%SPHINXBUILD% -b pickle %ALLSPHINXOPTS% %BUILDDIR%/pickle
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the pickle files.
goto end
)
if "%1" == "json" (
%SPHINXBUILD% -b json %ALLSPHINXOPTS% %BUILDDIR%/json
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can process the JSON files.
goto end
)
if "%1" == "htmlhelp" (
%SPHINXBUILD% -b htmlhelp %ALLSPHINXOPTS% %BUILDDIR%/htmlhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run HTML Help Workshop with the ^
.hhp project file in %BUILDDIR%/htmlhelp.
goto end
)
if "%1" == "qthelp" (
%SPHINXBUILD% -b qthelp %ALLSPHINXOPTS% %BUILDDIR%/qthelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished; now you can run "qcollectiongenerator" with the ^
.qhcp project file in %BUILDDIR%/qthelp, like this:
echo.^> qcollectiongenerator %BUILDDIR%\qthelp\GNS3.qhcp
echo.To view the help file:
echo.^> assistant -collectionFile %BUILDDIR%\qthelp\GNS3.ghc
goto end
)
if "%1" == "devhelp" (
%SPHINXBUILD% -b devhelp %ALLSPHINXOPTS% %BUILDDIR%/devhelp
if errorlevel 1 exit /b 1
echo.
echo.Build finished.
goto end
)
if "%1" == "epub" (
%SPHINXBUILD% -b epub %ALLSPHINXOPTS% %BUILDDIR%/epub
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The epub file is in %BUILDDIR%/epub.
goto end
)
if "%1" == "latex" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
if errorlevel 1 exit /b 1
echo.
echo.Build finished; the LaTeX files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdf" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf
cd %BUILDDIR%/..
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "latexpdfja" (
%SPHINXBUILD% -b latex %ALLSPHINXOPTS% %BUILDDIR%/latex
cd %BUILDDIR%/latex
make all-pdf-ja
cd %BUILDDIR%/..
echo.
echo.Build finished; the PDF files are in %BUILDDIR%/latex.
goto end
)
if "%1" == "text" (
%SPHINXBUILD% -b text %ALLSPHINXOPTS% %BUILDDIR%/text
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The text files are in %BUILDDIR%/text.
goto end
)
if "%1" == "man" (
%SPHINXBUILD% -b man %ALLSPHINXOPTS% %BUILDDIR%/man
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The manual pages are in %BUILDDIR%/man.
goto end
)
if "%1" == "texinfo" (
%SPHINXBUILD% -b texinfo %ALLSPHINXOPTS% %BUILDDIR%/texinfo
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The Texinfo files are in %BUILDDIR%/texinfo.
goto end
)
if "%1" == "gettext" (
%SPHINXBUILD% -b gettext %I18NSPHINXOPTS% %BUILDDIR%/locale
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The message catalogs are in %BUILDDIR%/locale.
goto end
)
if "%1" == "changes" (
%SPHINXBUILD% -b changes %ALLSPHINXOPTS% %BUILDDIR%/changes
if errorlevel 1 exit /b 1
echo.
echo.The overview file is in %BUILDDIR%/changes.
goto end
)
if "%1" == "linkcheck" (
%SPHINXBUILD% -b linkcheck %ALLSPHINXOPTS% %BUILDDIR%/linkcheck
if errorlevel 1 exit /b 1
echo.
echo.Link check complete; look for any errors in the above output ^
or in %BUILDDIR%/linkcheck/output.txt.
goto end
)
if "%1" == "doctest" (
%SPHINXBUILD% -b doctest %ALLSPHINXOPTS% %BUILDDIR%/doctest
if errorlevel 1 exit /b 1
echo.
echo.Testing of doctests in the sources finished, look at the ^
results in %BUILDDIR%/doctest/output.txt.
goto end
)
if "%1" == "xml" (
%SPHINXBUILD% -b xml %ALLSPHINXOPTS% %BUILDDIR%/xml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The XML files are in %BUILDDIR%/xml.
goto end
)
if "%1" == "pseudoxml" (
%SPHINXBUILD% -b pseudoxml %ALLSPHINXOPTS% %BUILDDIR%/pseudoxml
if errorlevel 1 exit /b 1
echo.
echo.Build finished. The pseudo-XML files are in %BUILDDIR%/pseudoxml.
goto end
)
:end

12
gns3server/__init__.py
View File

@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2013 GNS3 Technologies Inc.
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@ -15,14 +15,4 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
# __version__ is a human-readable version number.
# __version_info__ is a four-tuple for programmatic comparison. The first
# three numbers are the components of the version number. The fourth
# is zero for an official release, positive for a development branch,
# or negative for a release candidate or beta (after the base version
# number has been incremented)
#from .module_manager import ModuleManager
#from .server import Server
from .version import __version__

37
gns3server/builtins/server_version.py
View File

@ -1,37 +0,0 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2014 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
Sends version to requesting clients in JSON-RPC Websocket handler.
"""
from ..version import __version__
from ..jsonrpc import JSONRPCResponse
def server_version(handler, request_id, params):
"""
Builtin destination to return the server version.
:param handler: JSONRPCWebSocket instance
:param request_id: JSON-RPC call identifier
:param params: JSON-RPC method params (not used here)
"""
json_message = {"version": __version__}
handler.write_message(JSONRPCResponse(json_message, request_id)())

2
gns3server/config.py
View File

@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2014 GNS3 Technologies Inc.
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by

2
gns3server/handlers/file_upload_handler.py
View File

@ -19,6 +19,8 @@
Simple file upload & listing handler.
"""
#TODO: file upload with aiohttp
import os
import stat

204
gns3server/handlers/jsonrpc_websocket.py
View File

@ -1,204 +0,0 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2013 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
JSON-RPC protocol over Websockets.
"""
import zmq
import uuid
import tornado.websocket
from .auth_handler import GNS3WebSocketBaseHandler
from tornado.escape import json_decode
from ..jsonrpc import JSONRPCParseError
from ..jsonrpc import JSONRPCInvalidRequest
from ..jsonrpc import JSONRPCMethodNotFound
from ..jsonrpc import JSONRPCNotification
from ..jsonrpc import JSONRPCCustomError
import logging
log = logging.getLogger(__name__)
class JSONRPCWebSocket(GNS3WebSocketBaseHandler):
"""
STOMP protocol over Tornado Websockets with message
routing to ZeroMQ dealer clients.
:param application: Tornado Application instance
:param request: Tornado Request instance
:param zmq_router: ZeroMQ router socket
"""
clients = set()
destinations = {}
version = 2.0 # only JSON-RPC version 2.0 is supported
def __init__(self, application, request, zmq_router):
tornado.websocket.WebSocketHandler.__init__(self, application, request)
self._session_id = str(uuid.uuid4())
self.zmq_router = zmq_router
def check_origin(self, origin):
return True
@property
def session_id(self):
"""
Session ID uniquely representing a Websocket client
:returns: the session id
"""
return self._session_id
@classmethod
def dispatch_message(cls, stream, message):
"""
Sends a message to Websocket client
:param message: message from a module (received via ZeroMQ)
"""
# Module name that is replying
module = message[0].decode("utf-8")
# ZMQ responses are encoded in JSON
# format is a JSON array: [session ID, JSON-RPC response]
try:
json_message = json_decode(message[1])
except ValueError as e:
stream.send_string("Cannot decode message!")
log.critical("Couldn't decode message: {}".format(e))
return
session_id = json_message[0]
jsonrpc_response = json_message[1]
log.debug("Received message from module {}: {}".format(module, json_message))
for client in cls.clients:
if client.session_id == session_id:
client.write_message(jsonrpc_response)
@classmethod
def register_destination(cls, destination, module):
"""
Registers a destination handled by a module.
Used to route requests to the right module.
:param destination: destination string
:param module: module string
"""
# Make sure the destination is not already registered
# by another module for instance
assert destination not in cls.destinations
if destination.startswith("builtin"):
log.debug("registering {} as a built-in destination".format(destination))
else:
log.debug("registering {} as a destination for the {} module".format(destination, module))
cls.destinations[destination] = module
def open(self):
"""
Invoked when a new WebSocket is opened.
"""
log.info("Websocket client {} connected".format(self.session_id))
authenticated_user = self.get_current_user()
if authenticated_user:
self.clients.add(self)
log.info("Websocket authenticated user: %s" % (authenticated_user))
else:
self.close()
log.info("Websocket non-authenticated user attempt: %s" % (authenticated_user))
def on_message(self, message):
"""
Handles incoming messages.
:param message: message received over the Websocket
"""
log.debug("Received Websocket message: {}".format(message))
if self.zmq_router.closed:
# no need to proceed, the ZeroMQ router has been closed.
return
try:
request = json_decode(message)
jsonrpc_version = request["jsonrpc"]
method = request["method"]
# This is a JSON-RPC notification if request_id is None
request_id = request.get("id")
except:
return self.write_message(JSONRPCParseError()())
if jsonrpc_version != self.version:
return self.write_message(JSONRPCInvalidRequest()())
if len(self.clients) > 1:
#TODO: multiple client support
log.warn("GNS3 server doesn't support multiple clients yet")
return self.write_message(JSONRPCCustomError(-3200,
"There are {} clients connected, the GNS3 server cannot handle multiple clients yet".format(len(self.clients)),
request_id)())
if method not in self.destinations:
if request_id:
log.warn("JSON-RPC method not found: {}".format(method))
return self.write_message(JSONRPCMethodNotFound(request_id)())
else:
# This is a notification, silently ignore this error...
return
if method.startswith("builtin") and request_id:
log.info("calling built-in method {}".format(method))
self.destinations[method](self, request_id, request.get("params"))
return
module = self.destinations[method]
# ZMQ requests are encoded in JSON
# format is a JSON array: [session ID, JSON-RPC request]
zmq_request = [self.session_id, request]
# Route to the correct module
self.zmq_router.send_string(module, zmq.SNDMORE)
# Send the JSON request
self.zmq_router.send_json(zmq_request)
def on_close(self):
"""
Invoked when the WebSocket is closed.
"""
log.info("Websocket client {} disconnected".format(self.session_id))
self.clients.remove(self)
# Reset the modules if there are no clients anymore
# Modules must implement a reset destination
if not self.clients and not self.zmq_router.closed:
for destination, module in self.destinations.items():
if destination.endswith("reset"):
# Route to the correct module
self.zmq_router.send_string(module, zmq.SNDMORE)
# Send the JSON request
notification = JSONRPCNotification(destination)()
self.zmq_router.send_json([self.session_id, notification])

33
gns3server/handlers/version_handler.py
View File

@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2013 GNS3 Technologies Inc.
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@ -15,12 +15,33 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
from .auth_handler import GNS3BaseHandler
from ..web.route import Route
from ..schemas.version import VERSION_SCHEMA
from ..version import __version__
from aiohttp.web import HTTPConflict
class VersionHandler(GNS3BaseHandler):
class VersionHandler:
def get(self):
response = {'version': __version__}
self.write(response)
@classmethod
@Route.get(
r"/version",
description="Retrieve the server version number",
output=VERSION_SCHEMA)
def version(request, response):
response.json({'version': __version__})
@classmethod
@Route.post(
r"/version",
description="Check if version is the same as the server",
output=VERSION_SCHEMA,
input=VERSION_SCHEMA,
status_codes={
200: "Same version",
409: "Invalid version"
})
def check_version(request, response):
if request.json["version"] != __version__:
raise HTTPConflict(reason="Invalid version")
response.json({'version': __version__})

85
gns3server/handlers/vpcs_handler.py Normal file
View File

@ -0,0 +1,85 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
from ..web.route import Route
from ..modules.vpcs import VPCS
# schemas
from ..schemas.vpcs import VPCS_CREATE_SCHEMA
from ..schemas.vpcs import VPCS_OBJECT_SCHEMA
from ..schemas.vpcs import VPCS_ADD_NIO_SCHEMA
class VPCSHandler(object):
@classmethod
@Route.post(
r"/vpcs",
parameters={
"vpcs_id": "Id of VPCS instance"
},
status_codes={
201: "Success of creation of VPCS",
409: "Conflict"
},
description="Create a new VPCS and return it",
input=VPCS_CREATE_SCHEMA,
output=VPCS_OBJECT_SCHEMA)
def create(request, response):
vpcs = VPCS.instance()
i = yield from vpcs.create(request.json)
response.json({'name': request.json['name'],
"vpcs_id": i,
"console": 4242})
@classmethod
@Route.get(
r"/vpcs/{vpcs_id}",
parameters={
"vpcs_id": "Id of VPCS instance"
},
description="Get information about a VPCS",
output=VPCS_OBJECT_SCHEMA)
def show(request, response):
response.json({'name': "PC 1", "vpcs_id": 42, "console": 4242})
@classmethod
@Route.put(
r"/vpcs/{vpcs_id}",
parameters={
"vpcs_id": "Id of VPCS instance"
},
description="Update VPCS information",
input=VPCS_OBJECT_SCHEMA,
output=VPCS_OBJECT_SCHEMA)
def update(request, response):
response.json({'name': "PC 1", "vpcs_id": 42, "console": 4242})
@classmethod
@Route.post(
r"/vpcs/{vpcs_id}/nio",
parameters={
"vpcs_id": "Id of VPCS instance"
},
status_codes={
201: "Success of creation of NIO",
409: "Conflict"
},
description="ADD NIO to a VPCS",
input=VPCS_ADD_NIO_SCHEMA)
def create_nio(request, response):
# TODO: raise 404 if VPCS not found
response.json({'name': "PC 2", "vpcs_id": 42, "console": 4242})

184
gns3server/jsonrpc.py
View File

@ -1,184 +0,0 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2013 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
JSON-RPC protocol implementation.
http://www.jsonrpc.org/specification
"""
import json
import uuid
class JSONRPCObject(object):
"""
Base object for JSON-RPC requests, responses,
notifications and errors.
"""
def __init__(self):
return JSONRPCEncoder().default(self)
def __str__(self, *args, **kwargs):
return json.dumps(self, cls=JSONRPCEncoder)
def __call__(self):
return JSONRPCEncoder().default(self)
class JSONRPCEncoder(json.JSONEncoder):
"""
Creates the JSON-RPC message.
"""
def default(self, obj):
"""
Returns a Python dictionary corresponding to a JSON-RPC message.
"""
if isinstance(obj, JSONRPCObject):
message = {"jsonrpc": 2.0}
for field in dir(obj):
if not field.startswith('_'):
value = getattr(obj, field)
message[field] = value
return message
return json.JSONEncoder.default(self, obj)
class JSONRPCInvalidRequest(JSONRPCObject):
"""
Error response for an invalid request.
"""
def __init__(self):
JSONRPCObject.__init__(self)
self.id = None
self.error = {"code": -32600, "message": "Invalid Request"}
class JSONRPCMethodNotFound(JSONRPCObject):
"""
Error response for an method not found.
:param request_id: JSON-RPC identifier
"""
def __init__(self, request_id):
JSONRPCObject.__init__(self)
self.id = request_id
self.error = {"code": -32601, "message": "Method not found"}
class JSONRPCInvalidParams(JSONRPCObject):
"""
Error response for invalid parameters.
:param request_id: JSON-RPC identifier
"""
def __init__(self, request_id):
JSONRPCObject.__init__(self)
self.id = request_id
self.error = {"code": -32602, "message": "Invalid params"}
class JSONRPCInternalError(JSONRPCObject):
"""
Error response for an internal error.
:param request_id: JSON-RPC identifier (optional)
"""
def __init__(self, request_id=None):
JSONRPCObject.__init__(self)
self.id = request_id
self.error = {"code": -32603, "message": "Internal error"}
class JSONRPCParseError(JSONRPCObject):
"""
Error response for parsing error.
"""
def __init__(self):
JSONRPCObject.__init__(self)
self.id = None
self.error = {"code": -32700, "message": "Parse error"}
class JSONRPCCustomError(JSONRPCObject):
"""
Error response for an custom error.
:param code: JSON-RPC error code
:param message: JSON-RPC error message
:param request_id: JSON-RPC identifier (optional)
"""
def __init__(self, code, message, request_id=None):
JSONRPCObject.__init__(self)
self.id = request_id
self.error = {"code": code, "message": message}
class JSONRPCResponse(JSONRPCObject):
"""
JSON-RPC successful response.
:param result: JSON-RPC result
:param request_id: JSON-RPC identifier
"""
def __init__(self, result, request_id):
JSONRPCObject.__init__(self)
self.id = request_id
self.result = result
class JSONRPCRequest(JSONRPCObject):
"""
JSON-RPC request.
:param method: JSON-RPC destination method
:param params: JSON-RPC params for the corresponding method (optional)
:param request_id: JSON-RPC identifier (generated by default)
"""
def __init__(self, method, params=None, request_id=None):
JSONRPCObject.__init__(self)
if request_id is None:
request_id = str(uuid.uuid4())
self.id = request_id
self.method = method
if params:
self.params = params
class JSONRPCNotification(JSONRPCObject):
"""
JSON-RPC notification.
:param method: JSON-RPC destination method
:param params: JSON-RPC params for the corresponding method (optional)
"""
def __init__(self, method, params=None):
JSONRPCObject.__init__(self)
self.method = method
if params:
self.params = params

23
gns3server/main.py
View File

@ -1,7 +1,7 @@
#!/usr/bin/env python
# -*- coding: utf-8 -*-
#
# Copyright (C) 2013 GNS3 Technologies Inc.
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@ -19,20 +19,23 @@
import os
import datetime
import sys
import multiprocessing
import locale
#TODO: importing this module also configures logging options (colors etc.)
#see https://github.com/tornadoweb/tornado/blob/master/tornado/log.py#L208
import tornado.options
from gns3server.server import Server
from gns3server.version import __version__
import logging
log = logging.getLogger(__name__)
#TODO: migrate command line options to argparse
# command line options
from tornado.options import define
define("host", default="0.0.0.0", help="run on the given host/IP address", type=str)
define("port", default=8000, help="run on the given port", type=int)
define("ipc", default=False, help="use IPC for module communication", type=bool)
define("version", default=False, help="show the version", type=bool)
define("quiet", default=False, help="do not show output on stdout", type=bool)
define("console_bind_to_any", default=True, help="bind console ports to any local IP address", type=bool)
@ -50,7 +53,7 @@ def locale_check():
or there: http://robjwells.com/post/61198832297/get-your-us-ascii-out-of-my-face
"""
# no need to check on Windows or when frozen
# no need to check on Windows or when this application is frozen
if sys.platform.startswith("win") or hasattr(sys, "frozen"):
return
@ -82,10 +85,7 @@ def main():
Entry point for GNS3 server
"""
if sys.platform.startswith("win"):
# necessary on Windows to freeze the application
multiprocessing.freeze_support()
#TODO: migrate command line options to argparse (don't forget the quiet mode).
try:
tornado.options.parse_command_line()
except (tornado.options.Error, ValueError):
@ -109,6 +109,7 @@ def main():
user_log.info("GNS3 server version {}".format(__version__))
user_log.info("Copyright (c) 2007-{} GNS3 Technologies Inc.".format(current_year))
#TODO: end todo
# we only support Python 3 version >= 3.3
if sys.version_info < (3, 3):
@ -118,8 +119,7 @@ def main():
major=sys.version_info[0], minor=sys.version_info[1],
micro=sys.version_info[2], pid=os.getpid()))
# check for the correct locale
# (UNIX/Linux only)
# check for the correct locale (UNIX/Linux only)
locale_check()
try:
@ -128,8 +128,7 @@ def main():
log.critical("the current working directory doesn't exist")
return
server = Server(options.host, options.port, options.ipc, options.console_bind_to_any)
server.load_modules()
server = Server(options.host, options.port, options.console_bind_to_any)
server.run()
if __name__ == '__main__':

117
gns3server/module_manager.py
View File

@ -1,117 +0,0 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2013 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
import inspect
import pkgutil
from .modules import IModule
import logging
log = logging.getLogger(__name__)
class Module(object):
"""
Module representation for the module manager
:param name: module name
:param cls: module class to be instantiated when
the module is activated
"""
def __init__(self, name, cls):
self._name = name
self._cls = cls
@property
def name(self):
return self._name
@name.setter
def name(self, new_name):
self._name = new_name
def cls(self):
return self._cls
class ModuleManager(object):
"""
Manages modules
:param module_paths: path from where module are loaded
"""
def __init__(self, module_paths=['modules']):
self._modules = []
self._module_paths = module_paths
def load_modules(self):
"""
Finds all the possible modules (classes with IModule as a parent)
"""
for _, name, ispkg in pkgutil.iter_modules(self._module_paths):
if (ispkg):
log.debug("analyzing {} package directory".format(name))
try:
file, pathname, description = imp.find_module(name, self._module_paths)
module = imp.load_module(name, file, pathname, description)
classes = inspect.getmembers(module, inspect.isclass)
for module_class in classes:
if issubclass(module_class[1], IModule):
# make sure the module class has IModule as a parent
if module_class[1].__module__ == name:
log.info("loading {} module".format(module_class[0].lower()))
info = Module(name=module_class[0].lower(), cls=module_class[1])
self._modules.append(info)
except Exception:
log.critical("error while analyzing {} package directory".format(name), exc_info=1)
finally:
if file:
file.close()
def get_all_modules(self):
"""
Returns all modules.
:returns: list of Module objects
"""
return self._modules
def activate_module(self, module, *args, **kwargs):
"""
Activates a given module.
:param module: module to activate (Module object)
:param args: args passed to the module
:param kwargs: kwargs passed to the module
:returns: instantiated module class
"""
module_class = module.cls()
try:
module_instance = module_class(module.name, *args, **kwargs)
except Exception:
log.critical("error while activating the {} module".format(module.name), exc_info=1)
return None
log.info("activating the {} module".format(module.name))
return module_instance

17
gns3server/modules/__init__.py
View File

@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2013 GNS3 Technologies Inc.
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@ -16,16 +16,11 @@
# along with this program. If not, see <http://www.gnu.org/licenses/>.
import sys
from .base import IModule
from .deadman import DeadMan
from .dynamips import Dynamips
from .qemu import Qemu
from .vpcs import VPCS
from .virtualbox import VirtualBox
MODULES = [DeadMan, Dynamips, VPCS, VirtualBox, Qemu]
MODULES = [VPCS]
if sys.platform.startswith("linux"):
# IOU runs only on Linux
from .iou import IOU
MODULES.append(IOU)
#if sys.platform.startswith("linux"):
# # IOU runs only on Linux
# from .iou import IOU
# MODULES.append(IOU)

359
gns3server/modules/base.py
View File

@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2013 GNS3 Technologies Inc.
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@ -15,327 +15,52 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
Base class (interface) for modules
"""
import os
import sys
import traceback
import gns3server.jsonrpc as jsonrpc
import multiprocessing
import zmq
import signal
from gns3server.config import Config
from jsonschema import validate, ValidationError
import logging
log = logging.getLogger(__name__)
import asyncio
class IModule(multiprocessing.Process):
"""
Module interface.
:param name: module name
:param args: arguments for the module
:param kwargs: named arguments for the module
"""
modules = {}
def __init__(self, name, *args, **kwargs):
config = Config.instance()
server_config = config.get_default_section()
self._images_dir = os.path.expandvars(os.path.expanduser(server_config.get("upload_directory", "~/GNS3/images")))
multiprocessing.Process.__init__(self, name=name)
self._context = None
self._ioloop = None
self._stream = None
self._dealer = None
self._zmq_host = args[0] # ZeroMQ server address
self._zmq_port = args[1] # ZeroMQ server port
self._current_session = None
self._current_destination = None
self._current_call_id = None
self._stopping = False
self._cloud_settings = config.cloud_settings()
def _setup(self):
"""
Sets up PyZMQ and creates the stream to handle requests
"""
self._context = zmq.Context()
self._ioloop = zmq.eventloop.ioloop.IOLoop.instance()
self._stream = self._create_stream(self._zmq_host, self._zmq_port, self._decode_request)
def _create_stream(self, host=None, port=0, callback=None):
"""
Creates a new ZMQ stream.
:returns: ZMQ stream instance
"""
self._dealer = self._context.socket(zmq.DEALER)
self._dealer.setsockopt(zmq.IDENTITY, self.name.encode("utf-8"))
if host and port:
log.info("ZeroMQ client ({}) connecting to {}:{}".format(self.name, host, port))
try:
self._dealer.connect("tcp://{}:{}".format(host, port))
except zmq.error.ZMQError as e:
log.critical("Could not connect to ZeroMQ server on {}:{}, reason: {}".format(host, port, e))
raise SystemExit
else:
log.info("ZeroMQ client ({}) connecting to ipc:///tmp/gns3.ipc".format(self.name))
try:
self._dealer.connect("ipc:///tmp/gns3.ipc")
except zmq.error.ZMQError as e:
log.critical("Could not connect to ZeroMQ server on ipc:///tmp/gns3.ipc, reason: {}".format(e))
raise SystemExit
stream = zmq.eventloop.zmqstream.ZMQStream(self._dealer, self._ioloop)
if callback:
stream.on_recv(callback)
return stream
def add_periodic_callback(self, callback, time):
"""
Adds a periodic callback to the ioloop.
:param callback: callback to be called
:param time: frequency when the callback is executed
"""
periodic_callback = zmq.eventloop.ioloop.PeriodicCallback(callback, time, self._ioloop)
return periodic_callback
def run(self):
"""
Starts the event loop
"""
def signal_handler(signum=None, frame=None):
log.warning("Module {} got signal {}, exiting...".format(self.name, signum))
self.stop(signum)
signals = [signal.SIGTERM, signal.SIGINT]
if not sys.platform.startswith("win"):
signals.extend([signal.SIGHUP, signal.SIGQUIT])
else:
signals.extend([signal.SIGBREAK])
for sig in signals:
signal.signal(sig, signal_handler)
log.info("{} module running with PID {}".format(self.name, self.pid))
self._setup()
try:
self._ioloop.start()
except KeyboardInterrupt:
return
log.info("{} module has stopped".format(self.name))
def _shutdown(self):
"""
Shutdowns the I/O loop and the ZeroMQ stream & socket
"""
self._ioloop.stop()
if self._stream and not self._stream.closed:
# close the zeroMQ stream
self._stream.close()
if self._dealer and not self._dealer.closed:
# close the ZeroMQ dealer socket
self._dealer.close()
def stop(self, signum=None):
"""
Adds a callback to stop the event loop & ZeroMQ.
:param signum: signal number (if called by the signal handler)
"""
if not self._stopping:
self._stopping = True
if signum:
self._ioloop.add_callback_from_signal(self._shutdown)
else:
self._ioloop.add_callback(self._shutdown)
def send_response(self, results):
"""
Sends a response back to the requester.
:param results: JSON results to the ZeroMQ server
"""
jsonrpc_response = jsonrpc.JSONRPCResponse(results, self._current_call_id)()
# add session to the response
response = [self._current_session, jsonrpc_response]
log.debug("ZeroMQ client ({}) sending: {}".format(self.name, response))
self._stream.send_json(response)
def send_param_error(self):
"""
Sends a param error back to the requester.
"""
jsonrpc_response = jsonrpc.JSONRPCInvalidParams(self._current_call_id)()
# add session to the response
response = [self._current_session, jsonrpc_response]
log.info("ZeroMQ client ({}) sending JSON-RPC param error for call id {}".format(self.name, self._current_call_id))
self._stream.send_json(response)
def send_internal_error(self):
"""
Sends a param error back to the requester.
"""
jsonrpc_response = jsonrpc.JSONRPCInternalError()()
# add session to the response
response = [self._current_session, jsonrpc_response]
log.critical("ZeroMQ client ({}) sending JSON-RPC internal error".format(self.name))
self._stream.send_json(response)
def send_custom_error(self, message, code=-3200):
"""
Sends a custom error back to the requester.
"""
jsonrpc_response = jsonrpc.JSONRPCCustomError(code, message, self._current_call_id)()
# add session to the response
response = [self._current_session, jsonrpc_response]
log.info("ZeroMQ client ({}) sending JSON-RPC custom error: {} for call id {}".format(self.name,
message,
self._current_call_id))
self._stream.send_json(response)
def send_notification(self, destination, results):
"""
Sends a notification
:param destination: destination (or method)
:param results: JSON results to the ZeroMQ router
"""
jsonrpc_response = jsonrpc.JSONRPCNotification(destination, results)()
# add session to the response
response = [self._current_session, jsonrpc_response]
log.debug("ZeroMQ client ({}) sending: {}".format(self.name, response))
self._stream.send_json(response)
def _decode_request(self, request):
"""
Decodes the request to JSON.
:param request: request from ZeroMQ server
"""
# server is shutting down, do not process
# more request
if self._stopping:
return
# handle special request to stop the module
# e.g. useful on Windows where the
# SIGBREAK signal cound't be propagated
if request[0] == b"stop":
self.stop()
return
try:
request = zmq.utils.jsonapi.loads(request[0])
except ValueError:
self._current_session = None
self.send_internal_error()
return
log.debug("ZeroMQ client ({}) received: {}".format(self.name, request))
self._current_session = request[0]
self._current_call_id = request[1].get("id")
destination = request[1].get("method")
params = request[1].get("params")
if destination not in self.modules[self.name]:
self.send_internal_error()
return
log.debug("Routing request to {}: {}".format(destination, request[1]))
try:
self.modules[self.name][destination](self, params)
except Exception as e:
log.error("uncaught exception {type}".format(type=type(e)), exc_info=1)
exc_type, exc_value, exc_tb = sys.exc_info()
lines = traceback.format_exception(exc_type, exc_value, exc_tb)
tb = "".join(lines)
self.send_custom_error("uncaught exception {type}: {string}\n{tb}".format(type=type(e),
string=str(e),
tb=tb))
def validate_request(self, request, schema):
"""
Validates a request.
:param request: request (JSON-RPC params)
:param schema: JSON-SCHEMA to validate the request
:returns: True or False
"""
# check if we have a request
if request is None:
self.send_param_error()
return False
log.debug("received request {}".format(request))
# validate the request
try:
validate(request, schema)
except ValidationError as e:
self.send_custom_error("request validation error: {}".format(e))
return False
return True
def destinations(self):
"""
Destinations handled by this module.
:returns: list of destinations
"""
if not self.name in self.modules:
log.warn("no destinations found for module {}".format(self.name))
return []
return self.modules[self.name].keys()
#TODO: make this more generic (not json but *args?)
class BaseModule(object):
_instance = None
@classmethod
def route(cls, destination):
"""
Decorator to register a destination routed to a method
def instance(cls):
if cls._instance is None:
cls._instance = cls()
asyncio.async(cls._instance.run())
return cls._instance
:param destination: destination to be routed
"""
def __init__(self):
self._queue = asyncio.Queue()
def wrapper(method):
module = destination.split(".")[0]
if not module in cls.modules:
cls.modules[module] = {}
cls.modules[module][destination] = method
return method
return wrapper
@classmethod
def destroy(cls):
future = asyncio.Future()
cls._instance._queue.put_nowait((future, None, ))
yield from asyncio.wait([future])
cls._instance = None
@property
def images_directory(self):
@asyncio.coroutine
def put(self, json):
return self._images_dir
future = asyncio.Future()
self._queue.put_nowait((future, json, ))
yield from asyncio.wait([future])
return future.result()
@asyncio.coroutine
def run(self):
while True:
future, json = yield from self._queue.get()
if json is None:
future.set_result(True)
break
try:
result = yield from self.process(json)
future.set_result(result)
except Exception as e:
future.set_exception(e)
@asyncio.coroutine
def process(self, json):
raise NotImplementedError

652
gns3server/modules/old_vpcs/__init__.py Normal file
View File

@ -0,0 +1,652 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2014 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
"""
VPCS server module.
"""
import os
import base64
import socket
import shutil
from gns3server.modules import IModule
from gns3server.config import Config
from .vpcs_device import VPCSDevice
from .vpcs_error import VPCSError
from .nios.nio_udp import NIO_UDP
from .nios.nio_tap import NIO_TAP
from ..attic import find_unused_port
from .schemas import VPCS_CREATE_SCHEMA
from .schemas import VPCS_DELETE_SCHEMA
from .schemas import VPCS_UPDATE_SCHEMA
from .schemas import VPCS_START_SCHEMA
from .schemas import VPCS_STOP_SCHEMA
from .schemas import VPCS_RELOAD_SCHEMA
from .schemas import VPCS_ALLOCATE_UDP_PORT_SCHEMA
from .schemas import VPCS_ADD_NIO_SCHEMA
from .schemas import VPCS_DELETE_NIO_SCHEMA
from .schemas import VPCS_EXPORT_CONFIG_SCHEMA
import logging
log = logging.getLogger(__name__)
class VPCS(IModule):
"""
VPCS module.
:param name: module name
:param args: arguments for the module
:param kwargs: named arguments for the module
"""
def __init__(self, name, *args, **kwargs):
# get the VPCS location
config = Config.instance()
vpcs_config = config.get_section_config(name.upper())
self._vpcs = vpcs_config.get("vpcs_path")
if not self._vpcs or not os.path.isfile(self._vpcs):
paths = [os.getcwd()] + os.environ["PATH"].split(os.pathsep)
# look for VPCS in the current working directory and $PATH
for path in paths:
try:
if "vpcs" in os.listdir(path) and os.access(os.path.join(path, "vpcs"), os.X_OK):
self._vpcs = os.path.join(path, "vpcs")
break
except OSError:
continue
if not self._vpcs:
log.warning("VPCS binary couldn't be found!")
elif not os.access(self._vpcs, os.X_OK):
log.warning("VPCS is not executable")
# a new process start when calling IModule
IModule.__init__(self, name, *args, **kwargs)
self._vpcs_instances = {}
self._console_start_port_range = vpcs_config.get("console_start_port_range", 4501)
self._console_end_port_range = vpcs_config.get("console_end_port_range", 5000)
self._allocated_udp_ports = []
self._udp_start_port_range = vpcs_config.get("udp_start_port_range", 20501)
self._udp_end_port_range = vpcs_config.get("udp_end_port_range", 21000)
self._host = vpcs_config.get("host", kwargs["host"])
self._console_host = vpcs_config.get("console_host", kwargs["console_host"])
self._projects_dir = kwargs["projects_dir"]
self._tempdir = kwargs["temp_dir"]
self._working_dir = self._projects_dir
def stop(self, signum=None):
"""
Properly stops the module.
:param signum: signal number (if called by the signal handler)
"""
# delete all VPCS instances
for vpcs_id in self._vpcs_instances:
vpcs_instance = self._vpcs_instances[vpcs_id]
vpcs_instance.delete()
IModule.stop(self, signum) # this will stop the I/O loop
def get_vpcs_instance(self, vpcs_id):
"""
Returns a VPCS device instance.
:param vpcs_id: VPCS device identifier
:returns: VPCSDevice instance
"""
if vpcs_id not in self._vpcs_instances:
log.debug("VPCS device ID {} doesn't exist".format(vpcs_id), exc_info=1)
self.send_custom_error("VPCS device ID {} doesn't exist".format(vpcs_id))
return None
return self._vpcs_instances[vpcs_id]
@IModule.route("vpcs.reset")
def reset(self, request):
"""
Resets the module.
:param request: JSON request
"""
# delete all vpcs instances
for vpcs_id in self._vpcs_instances:
vpcs_instance = self._vpcs_instances[vpcs_id]
vpcs_instance.delete()
# resets the instance IDs
VPCSDevice.reset()
self._vpcs_instances.clear()
self._allocated_udp_ports.clear()
self._working_dir = self._projects_dir
log.info("VPCS module has been reset")
@IModule.route("vpcs.settings")
def settings(self, request):
"""
Set or update settings.
Optional request parameters:
- path (path to vpcs)
- working_dir (path to a working directory)
- project_name
- console_start_port_range
- console_end_port_range
- udp_start_port_range
- udp_end_port_range
:param request: JSON request
"""
if request is None:
self.send_param_error()
return
if "path" in request and request["path"]:
self._vpcs = request["path"]
log.info("VPCS path set to {}".format(self._vpcs))
for vpcs_id in self._vpcs_instances:
vpcs_instance = self._vpcs_instances[vpcs_id]
vpcs_instance.path = self._vpcs
if "working_dir" in request:
new_working_dir = request["working_dir"]
log.info("this server is local with working directory path to {}".format(new_working_dir))
else:
new_working_dir = os.path.join(self._projects_dir, request["project_name"])
log.info("this server is remote with working directory path to {}".format(new_working_dir))
if self._projects_dir != self._working_dir != new_working_dir:
if not os.path.isdir(new_working_dir):
try:
shutil.move(self._working_dir, new_working_dir)
except OSError as e:
log.error("could not move working directory from {} to {}: {}".format(self._working_dir,
new_working_dir,
e))
return
# update the working directory if it has changed
if self._working_dir != new_working_dir:
self._working_dir = new_working_dir
for vpcs_id in self._vpcs_instances:
vpcs_instance = self._vpcs_instances[vpcs_id]
vpcs_instance.working_dir = os.path.join(self._working_dir, "vpcs", "pc-{}".format(vpcs_instance.id))
if "console_start_port_range" in request and "console_end_port_range" in request:
self._console_start_port_range = request["console_start_port_range"]
self._console_end_port_range = request["console_end_port_range"]
if "udp_start_port_range" in request and "udp_end_port_range" in request:
self._udp_start_port_range = request["udp_start_port_range"]
self._udp_end_port_range = request["udp_end_port_range"]
log.debug("received request {}".format(request))
@IModule.route("vpcs.create")
def vpcs_create(self, request):
"""
Creates a new VPCS instance.
Mandatory request parameters:
- name (VPCS name)
Optional request parameters:
- console (VPCS console port)
Response parameters:
- id (VPCS instance identifier)
- name (VPCS name)
- default settings
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_CREATE_SCHEMA):
return
name = request["name"]
console = request.get("console")
vpcs_id = request.get("vpcs_id")
try:
if not self._vpcs:
raise VPCSError("No path to a VPCS executable has been set")
vpcs_instance = VPCSDevice(name,
self._vpcs,
self._working_dir,
vpcs_id,
console,
self._console_host,
self._console_start_port_range,
self._console_end_port_range)
except VPCSError as e:
self.send_custom_error(str(e))
return
response = {"name": vpcs_instance.name,
"id": vpcs_instance.id}
defaults = vpcs_instance.defaults()
response.update(defaults)
self._vpcs_instances[vpcs_instance.id] = vpcs_instance
self.send_response(response)
@IModule.route("vpcs.delete")
def vpcs_delete(self, request):
"""
Deletes a VPCS instance.
Mandatory request parameters:
- id (VPCS instance identifier)
Response parameter:
- True on success
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_DELETE_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
try:
vpcs_instance.clean_delete()
del self._vpcs_instances[request["id"]]
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response(True)
@IModule.route("vpcs.update")
def vpcs_update(self, request):
"""
Updates a VPCS instance
Mandatory request parameters:
- id (VPCS instance identifier)
Optional request parameters:
- any setting to update
- script_file_base64 (base64 encoded)
Response parameters:
- updated settings
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_UPDATE_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
config_path = os.path.join(vpcs_instance.working_dir, "startup.vpc")
try:
if "script_file_base64" in request:
# a new startup-config has been pushed
config = base64.decodebytes(request["script_file_base64"].encode("utf-8")).decode("utf-8")
config = config.replace("\r", "")
config = config.replace('%h', vpcs_instance.name)
try:
with open(config_path, "w") as f:
log.info("saving script file to {}".format(config_path))
f.write(config)
except OSError as e:
raise VPCSError("Could not save the configuration {}: {}".format(config_path, e))
# update the request with the new local startup-config path
request["script_file"] = os.path.basename(config_path)
elif "script_file" in request:
if os.path.isfile(request["script_file"]) and request["script_file"] != config_path:
# this is a local file set in the GUI
try:
with open(request["script_file"], "r", errors="replace") as f:
config = f.read()
with open(config_path, "w") as f:
config = config.replace("\r", "")
config = config.replace('%h', vpcs_instance.name)
f.write(config)
request["script_file"] = os.path.basename(config_path)
except OSError as e:
raise VPCSError("Could not save the configuration from {} to {}: {}".format(request["script_file"], config_path, e))
elif not os.path.isfile(config_path):
raise VPCSError("Startup-config {} could not be found on this server".format(request["script_file"]))
except VPCSError as e:
self.send_custom_error(str(e))
return
# update the VPCS settings
response = {}
for name, value in request.items():
if hasattr(vpcs_instance, name) and getattr(vpcs_instance, name) != value:
try:
setattr(vpcs_instance, name, value)
response[name] = value
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response(response)
@IModule.route("vpcs.start")
def vpcs_start(self, request):
"""
Starts a VPCS instance.
Mandatory request parameters:
- id (VPCS instance identifier)
Response parameters:
- True on success
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_START_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
try:
vpcs_instance.start()
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response(True)
@IModule.route("vpcs.stop")
def vpcs_stop(self, request):
"""
Stops a VPCS instance.
Mandatory request parameters:
- id (VPCS instance identifier)
Response parameters:
- True on success
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_STOP_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
try:
vpcs_instance.stop()
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response(True)
@IModule.route("vpcs.reload")
def vpcs_reload(self, request):
"""
Reloads a VPCS instance.
Mandatory request parameters:
- id (VPCS identifier)
Response parameters:
- True on success
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_RELOAD_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
try:
if vpcs_instance.is_running():
vpcs_instance.stop()
vpcs_instance.start()
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response(True)
@IModule.route("vpcs.allocate_udp_port")
def allocate_udp_port(self, request):
"""
Allocates a UDP port in order to create an UDP NIO.
Mandatory request parameters:
- id (VPCS identifier)
- port_id (unique port identifier)
Response parameters:
- port_id (unique port identifier)
- lport (allocated local port)
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_ALLOCATE_UDP_PORT_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
try:
port = find_unused_port(self._udp_start_port_range,
self._udp_end_port_range,
host=self._host,
socket_type="UDP",
ignore_ports=self._allocated_udp_ports)
except Exception as e:
self.send_custom_error(str(e))
return
self._allocated_udp_ports.append(port)
log.info("{} [id={}] has allocated UDP port {} with host {}".format(vpcs_instance.name,
vpcs_instance.id,
port,
self._host))
response = {"lport": port,
"port_id": request["port_id"]}
self.send_response(response)
@IModule.route("vpcs.add_nio")
def add_nio(self, request):
"""
Adds an NIO (Network Input/Output) for a VPCS instance.
Mandatory request parameters:
- id (VPCS instance identifier)
- port (port number)
- port_id (unique port identifier)
- nio (one of the following)
- type "nio_udp"
- lport (local port)
- rhost (remote host)
- rport (remote port)
- type "nio_tap"
- tap_device (TAP device name e.g. tap0)
Response parameters:
- port_id (unique port identifier)
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_ADD_NIO_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
port = request["port"]
try:
nio = None
if request["nio"]["type"] == "nio_udp":
lport = request["nio"]["lport"]
rhost = request["nio"]["rhost"]
rport = request["nio"]["rport"]
try:
#TODO: handle IPv6
with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
sock.connect((rhost, rport))
except OSError as e:
raise VPCSError("Could not create an UDP connection to {}:{}: {}".format(rhost, rport, e))
nio = NIO_UDP(lport, rhost, rport)
elif request["nio"]["type"] == "nio_tap":
tap_device = request["nio"]["tap_device"]
if not self.has_privileged_access(self._vpcs):
raise VPCSError("{} has no privileged access to {}.".format(self._vpcs, tap_device))
nio = NIO_TAP(tap_device)
if not nio:
raise VPCSError("Requested NIO does not exist or is not supported: {}".format(request["nio"]["type"]))
except VPCSError as e:
self.send_custom_error(str(e))
return
try:
vpcs_instance.port_add_nio_binding(port, nio)
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response({"port_id": request["port_id"]})
@IModule.route("vpcs.delete_nio")
def delete_nio(self, request):
"""
Deletes an NIO (Network Input/Output).
Mandatory request parameters:
- id (VPCS instance identifier)
- port (port identifier)
Response parameters:
- True on success
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_DELETE_NIO_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
port = request["port"]
try:
nio = vpcs_instance.port_remove_nio_binding(port)
if isinstance(nio, NIO_UDP) and nio.lport in self._allocated_udp_ports:
self._allocated_udp_ports.remove(nio.lport)
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response(True)
@IModule.route("vpcs.export_config")
def export_config(self, request):
"""
Exports the script file from a VPCS instance.
Mandatory request parameters:
- id (vm identifier)
Response parameters:
- script_file_base64 (script file base64 encoded)
- False if no configuration can be exported
"""
# validate the request
if not self.validate_request(request, VPCS_EXPORT_CONFIG_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
response = {}
script_file_path = os.path.join(vpcs_instance.working_dir, vpcs_instance.script_file)
try:
with open(script_file_path, "rb") as f:
config = f.read()
response["script_file_base64"] = base64.encodebytes(config).decode("utf-8")
except OSError as e:
self.send_custom_error("unable to export the script file: {}".format(e))
return
if not response:
self.send_response(False)
else:
self.send_response(response)
@IModule.route("vpcs.echo")
def echo(self, request):
"""
Echo end point for testing purposes.
:param request: JSON request
"""
if request is None:
self.send_param_error()
else:
log.debug("received request {}".format(request))
self.send_response(request)

0
gns3server/modules/vpcs/nios/__init__.py → gns3server/modules/old_vpcs/adapters/__init__.py
View File

0
gns3server/modules/vpcs/adapters/adapter.py → gns3server/modules/old_vpcs/adapters/adapter.py
View File

0
gns3server/modules/vpcs/adapters/ethernet_adapter.py → gns3server/modules/old_vpcs/adapters/ethernet_adapter.py
View File

0
gns3server/modules/old_vpcs/nios/__init__.py Normal file
View File

0
gns3server/modules/vpcs/nios/nio_tap.py → gns3server/modules/old_vpcs/nios/nio_tap.py
View File

0
gns3server/modules/vpcs/nios/nio_udp.py → gns3server/modules/old_vpcs/nios/nio_udp.py
View File

0
gns3server/modules/vpcs/schemas.py → gns3server/modules/old_vpcs/schemas.py
View File

0
gns3server/modules/vpcs/vpcs_device.py → gns3server/modules/old_vpcs/vpcs_device.py
View File

0
gns3server/modules/vpcs/vpcs_error.py → gns3server/modules/old_vpcs/vpcs_error.py
View File

639
gns3server/modules/vpcs/__init__.py
View File

@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2014 GNS3 Technologies Inc.
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@ -19,634 +19,19 @@
VPCS server module.
"""
import os
import base64
import socket
import shutil
import asyncio
from gns3server.modules import IModule
from gns3server.config import Config
from .vpcs_device import VPCSDevice
from .vpcs_error import VPCSError
from .nios.nio_udp import NIO_UDP
from .nios.nio_tap import NIO_TAP
from ..attic import find_unused_port
from ..base import BaseModule
from .schemas import VPCS_CREATE_SCHEMA
from .schemas import VPCS_DELETE_SCHEMA
from .schemas import VPCS_UPDATE_SCHEMA
from .schemas import VPCS_START_SCHEMA
from .schemas import VPCS_STOP_SCHEMA
from .schemas import VPCS_RELOAD_SCHEMA
from .schemas import VPCS_ALLOCATE_UDP_PORT_SCHEMA
from .schemas import VPCS_ADD_NIO_SCHEMA
from .schemas import VPCS_DELETE_NIO_SCHEMA
from .schemas import VPCS_EXPORT_CONFIG_SCHEMA
import logging
log = logging.getLogger(__name__)
class VPCS(BaseModule):
@asyncio.coroutine
def process(self, json):
yield from asyncio.sleep(1)
return 42
class VPCS(IModule):
"""
VPCS module.
:param name: module name
:param args: arguments for the module
:param kwargs: named arguments for the module
"""
def __init__(self, name, *args, **kwargs):
# get the VPCS location
config = Config.instance()
vpcs_config = config.get_section_config(name.upper())
self._vpcs = vpcs_config.get("vpcs_path")
if not self._vpcs or not os.path.isfile(self._vpcs):
paths = [os.getcwd()] + os.environ["PATH"].split(os.pathsep)
# look for VPCS in the current working directory and $PATH
for path in paths:
try:
if "vpcs" in os.listdir(path) and os.access(os.path.join(path, "vpcs"), os.X_OK):
self._vpcs = os.path.join(path, "vpcs")
break
except OSError:
continue
if not self._vpcs:
log.warning("VPCS binary couldn't be found!")
elif not os.access(self._vpcs, os.X_OK):
log.warning("VPCS is not executable")
# a new process start when calling IModule
IModule.__init__(self, name, *args, **kwargs)
self._vpcs_instances = {}
self._console_start_port_range = vpcs_config.get("console_start_port_range", 4501)
self._console_end_port_range = vpcs_config.get("console_end_port_range", 5000)
self._allocated_udp_ports = []
self._udp_start_port_range = vpcs_config.get("udp_start_port_range", 20501)
self._udp_end_port_range = vpcs_config.get("udp_end_port_range", 21000)
self._host = vpcs_config.get("host", kwargs["host"])
self._console_host = vpcs_config.get("console_host", kwargs["console_host"])
self._projects_dir = kwargs["projects_dir"]
self._tempdir = kwargs["temp_dir"]
self._working_dir = self._projects_dir
def stop(self, signum=None):
"""
Properly stops the module.
:param signum: signal number (if called by the signal handler)
"""
# delete all VPCS instances
for vpcs_id in self._vpcs_instances:
vpcs_instance = self._vpcs_instances[vpcs_id]
vpcs_instance.delete()
IModule.stop(self, signum) # this will stop the I/O loop
def get_vpcs_instance(self, vpcs_id):
"""
Returns a VPCS device instance.
:param vpcs_id: VPCS device identifier
:returns: VPCSDevice instance
"""
if vpcs_id not in self._vpcs_instances:
log.debug("VPCS device ID {} doesn't exist".format(vpcs_id), exc_info=1)
self.send_custom_error("VPCS device ID {} doesn't exist".format(vpcs_id))
return None
return self._vpcs_instances[vpcs_id]
@IModule.route("vpcs.reset")
def reset(self, request):
"""
Resets the module.
:param request: JSON request
"""
# delete all vpcs instances
for vpcs_id in self._vpcs_instances:
vpcs_instance = self._vpcs_instances[vpcs_id]
vpcs_instance.delete()
# resets the instance IDs
VPCSDevice.reset()
self._vpcs_instances.clear()
self._allocated_udp_ports.clear()
self._working_dir = self._projects_dir
log.info("VPCS module has been reset")
@IModule.route("vpcs.settings")
def settings(self, request):
"""
Set or update settings.
Optional request parameters:
- path (path to vpcs)
- working_dir (path to a working directory)
- project_name
- console_start_port_range
- console_end_port_range
- udp_start_port_range
- udp_end_port_range
:param request: JSON request
"""
if request is None:
self.send_param_error()
return
if "path" in request and request["path"]:
self._vpcs = request["path"]
log.info("VPCS path set to {}".format(self._vpcs))
for vpcs_id in self._vpcs_instances:
vpcs_instance = self._vpcs_instances[vpcs_id]
vpcs_instance.path = self._vpcs
if "working_dir" in request:
new_working_dir = request["working_dir"]
log.info("this server is local with working directory path to {}".format(new_working_dir))
else:
new_working_dir = os.path.join(self._projects_dir, request["project_name"])
log.info("this server is remote with working directory path to {}".format(new_working_dir))
if self._projects_dir != self._working_dir != new_working_dir:
if not os.path.isdir(new_working_dir):
try:
shutil.move(self._working_dir, new_working_dir)
except OSError as e:
log.error("could not move working directory from {} to {}: {}".format(self._working_dir,
new_working_dir,
e))
return
# update the working directory if it has changed
if self._working_dir != new_working_dir:
self._working_dir = new_working_dir
for vpcs_id in self._vpcs_instances:
vpcs_instance = self._vpcs_instances[vpcs_id]
vpcs_instance.working_dir = os.path.join(self._working_dir, "vpcs", "pc-{}".format(vpcs_instance.id))
if "console_start_port_range" in request and "console_end_port_range" in request:
self._console_start_port_range = request["console_start_port_range"]
self._console_end_port_range = request["console_end_port_range"]
if "udp_start_port_range" in request and "udp_end_port_range" in request:
self._udp_start_port_range = request["udp_start_port_range"]
self._udp_end_port_range = request["udp_end_port_range"]
log.debug("received request {}".format(request))
@IModule.route("vpcs.create")
def vpcs_create(self, request):
"""
Creates a new VPCS instance.
Mandatory request parameters:
- name (VPCS name)
Optional request parameters:
- console (VPCS console port)
Response parameters:
- id (VPCS instance identifier)
- name (VPCS name)
- default settings
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_CREATE_SCHEMA):
return
name = request["name"]
console = request.get("console")
vpcs_id = request.get("vpcs_id")
try:
if not self._vpcs:
raise VPCSError("No path to a VPCS executable has been set")
vpcs_instance = VPCSDevice(name,
self._vpcs,
self._working_dir,
vpcs_id,
console,
self._console_host,
self._console_start_port_range,
self._console_end_port_range)
except VPCSError as e:
self.send_custom_error(str(e))
return
response = {"name": vpcs_instance.name,
"id": vpcs_instance.id}
defaults = vpcs_instance.defaults()
response.update(defaults)
self._vpcs_instances[vpcs_instance.id] = vpcs_instance
self.send_response(response)
@IModule.route("vpcs.delete")
def vpcs_delete(self, request):
"""
Deletes a VPCS instance.
Mandatory request parameters:
- id (VPCS instance identifier)
Response parameter:
- True on success
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_DELETE_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
try:
vpcs_instance.clean_delete()
del self._vpcs_instances[request["id"]]
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response(True)
@IModule.route("vpcs.update")
def vpcs_update(self, request):
"""
Updates a VPCS instance
Mandatory request parameters:
- id (VPCS instance identifier)
Optional request parameters:
- any setting to update
- script_file_base64 (base64 encoded)
Response parameters:
- updated settings
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_UPDATE_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
config_path = os.path.join(vpcs_instance.working_dir, "startup.vpc")
try:
if "script_file_base64" in request:
# a new startup-config has been pushed
config = base64.decodebytes(request["script_file_base64"].encode("utf-8")).decode("utf-8")
config = config.replace("\r", "")
config = config.replace('%h', vpcs_instance.name)
try:
with open(config_path, "w") as f:
log.info("saving script file to {}".format(config_path))
f.write(config)
except OSError as e:
raise VPCSError("Could not save the configuration {}: {}".format(config_path, e))
# update the request with the new local startup-config path
request["script_file"] = os.path.basename(config_path)
elif "script_file" in request:
if os.path.isfile(request["script_file"]) and request["script_file"] != config_path:
# this is a local file set in the GUI
try:
with open(request["script_file"], "r", errors="replace") as f:
config = f.read()
with open(config_path, "w") as f:
config = config.replace("\r", "")
config = config.replace('%h', vpcs_instance.name)
f.write(config)
request["script_file"] = os.path.basename(config_path)
except OSError as e:
raise VPCSError("Could not save the configuration from {} to {}: {}".format(request["script_file"], config_path, e))
elif not os.path.isfile(config_path):
raise VPCSError("Startup-config {} could not be found on this server".format(request["script_file"]))
except VPCSError as e:
self.send_custom_error(str(e))
return
# update the VPCS settings
response = {}
for name, value in request.items():
if hasattr(vpcs_instance, name) and getattr(vpcs_instance, name) != value:
try:
setattr(vpcs_instance, name, value)
response[name] = value
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response(response)
@IModule.route("vpcs.start")
def vpcs_start(self, request):
"""
Starts a VPCS instance.
Mandatory request parameters:
- id (VPCS instance identifier)
Response parameters:
- True on success
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_START_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
try:
vpcs_instance.start()
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response(True)
@IModule.route("vpcs.stop")
def vpcs_stop(self, request):
"""
Stops a VPCS instance.
Mandatory request parameters:
- id (VPCS instance identifier)
Response parameters:
- True on success
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_STOP_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
try:
vpcs_instance.stop()
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response(True)
@IModule.route("vpcs.reload")
def vpcs_reload(self, request):
"""
Reloads a VPCS instance.
Mandatory request parameters:
- id (VPCS identifier)
Response parameters:
- True on success
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_RELOAD_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
try:
if vpcs_instance.is_running():
vpcs_instance.stop()
vpcs_instance.start()
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response(True)
@IModule.route("vpcs.allocate_udp_port")
def allocate_udp_port(self, request):
"""
Allocates a UDP port in order to create an UDP NIO.
Mandatory request parameters:
- id (VPCS identifier)
- port_id (unique port identifier)
Response parameters:
- port_id (unique port identifier)
- lport (allocated local port)
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_ALLOCATE_UDP_PORT_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
try:
port = find_unused_port(self._udp_start_port_range,
self._udp_end_port_range,
host=self._host,
socket_type="UDP",
ignore_ports=self._allocated_udp_ports)
except Exception as e:
self.send_custom_error(str(e))
return
self._allocated_udp_ports.append(port)
log.info("{} [id={}] has allocated UDP port {} with host {}".format(vpcs_instance.name,
vpcs_instance.id,
port,
self._host))
response = {"lport": port,
"port_id": request["port_id"]}
self.send_response(response)
@IModule.route("vpcs.add_nio")
def add_nio(self, request):
"""
Adds an NIO (Network Input/Output) for a VPCS instance.
Mandatory request parameters:
- id (VPCS instance identifier)
- port (port number)
- port_id (unique port identifier)
- nio (one of the following)
- type "nio_udp"
- lport (local port)
- rhost (remote host)
- rport (remote port)
- type "nio_tap"
- tap_device (TAP device name e.g. tap0)
Response parameters:
- port_id (unique port identifier)
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_ADD_NIO_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
port = request["port"]
try:
nio = None
if request["nio"]["type"] == "nio_udp":
lport = request["nio"]["lport"]
rhost = request["nio"]["rhost"]
rport = request["nio"]["rport"]
try:
#TODO: handle IPv6
with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as sock:
sock.connect((rhost, rport))
except OSError as e:
raise VPCSError("Could not create an UDP connection to {}:{}: {}".format(rhost, rport, e))
nio = NIO_UDP(lport, rhost, rport)
elif request["nio"]["type"] == "nio_tap":
tap_device = request["nio"]["tap_device"]
if not self.has_privileged_access(self._vpcs):
raise VPCSError("{} has no privileged access to {}.".format(self._vpcs, tap_device))
nio = NIO_TAP(tap_device)
if not nio:
raise VPCSError("Requested NIO does not exist or is not supported: {}".format(request["nio"]["type"]))
except VPCSError as e:
self.send_custom_error(str(e))
return
try:
vpcs_instance.port_add_nio_binding(port, nio)
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response({"port_id": request["port_id"]})
@IModule.route("vpcs.delete_nio")
def delete_nio(self, request):
"""
Deletes an NIO (Network Input/Output).
Mandatory request parameters:
- id (VPCS instance identifier)
- port (port identifier)
Response parameters:
- True on success
:param request: JSON request
"""
# validate the request
if not self.validate_request(request, VPCS_DELETE_NIO_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
port = request["port"]
try:
nio = vpcs_instance.port_remove_nio_binding(port)
if isinstance(nio, NIO_UDP) and nio.lport in self._allocated_udp_ports:
self._allocated_udp_ports.remove(nio.lport)
except VPCSError as e:
self.send_custom_error(str(e))
return
self.send_response(True)
@IModule.route("vpcs.export_config")
def export_config(self, request):
"""
Exports the script file from a VPCS instance.
Mandatory request parameters:
- id (vm identifier)
Response parameters:
- script_file_base64 (script file base64 encoded)
- False if no configuration can be exported
"""
# validate the request
if not self.validate_request(request, VPCS_EXPORT_CONFIG_SCHEMA):
return
# get the instance
vpcs_instance = self.get_vpcs_instance(request["id"])
if not vpcs_instance:
return
response = {}
script_file_path = os.path.join(vpcs_instance.working_dir, vpcs_instance.script_file)
try:
with open(script_file_path, "rb") as f:
config = f.read()
response["script_file_base64"] = base64.encodebytes(config).decode("utf-8")
except OSError as e:
self.send_custom_error("unable to export the script file: {}".format(e))
return
if not response:
self.send_response(False)
else:
self.send_response(response)
@IModule.route("vpcs.echo")
def echo(self, request):
"""
Echo end point for testing purposes.
:param request: JSON request
"""
if request is None:
self.send_param_error()
else:
log.debug("received request {}".format(request))
self.send_response(request)
@asyncio.coroutine
def create(self, json):
i = yield from self.put(json)
return i

0
gns3server/schemas/__init__.py Normal file
View File

34
gns3server/_compat.py → gns3server/schemas/version.py
View File

@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2013 GNS3 Technologies Inc.
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@ -15,22 +15,16 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
import sys
PY2 = sys.version_info[0] == 2
if not PY2:
unichr = chr
range_type = range
text_type = str
string_types = (str,)
else:
unichr = unichr
text_type = unicode # @UndefinedVariable
range_type = xrange # @UndefinedVariable
string_types = (str, unicode) # @UndefinedVariable
try:
from urllib.parse import urlencode
except ImportError:
from urllib import urlencode
VERSION_SCHEMA = {
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "object",
'required': ['version'],
"additionalProperties": False,
"properties": {
"version": {
"description": "Version number human readable",
"type": "string",
"minLength": 5,
}
}
}

270
gns3server/schemas/vpcs.py Normal file
View File

@ -0,0 +1,270 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
VPCS_CREATE_SCHEMA = {
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Request validation to create a new VPCS instance",
"type": "object",
"properties": {
"name": {
"description": "VPCS device name",
"type": "string",
"minLength": 1,
},
"vpcs_id": {
"description": "VPCS device instance ID",
"type": "integer"
},
"console": {
"description": "console TCP port",
"minimum": 1,
"maximum": 65535,
"type": "integer"
},
},
"additionalProperties": False,
"required": ["name"]
}
VPCS_ADD_NIO_SCHEMA = {
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Request validation to add a NIO for a VPCS instance",
"type": "object",
"definitions": {
"UDP": {
"description": "UDP Network Input/Output",
"properties": {
"type": {
"enum": ["nio_udp"]
},
"lport": {
"description": "Local port",
"type": "integer",
"minimum": 1,
"maximum": 65535
},
"rhost": {
"description": "Remote host",
"type": "string",
"minLength": 1
},
"rport": {
"description": "Remote port",
"type": "integer",
"minimum": 1,
"maximum": 65535
}
},
"required": ["type", "lport", "rhost", "rport"],
"additionalProperties": False
},
"Ethernet": {
"description": "Generic Ethernet Network Input/Output",
"properties": {
"type": {
"enum": ["nio_generic_ethernet"]
},
"ethernet_device": {
"description": "Ethernet device name e.g. eth0",
"type": "string",
"minLength": 1
},
},
"required": ["type", "ethernet_device"],
"additionalProperties": False
},
"LinuxEthernet": {
"description": "Linux Ethernet Network Input/Output",
"properties": {
"type": {
"enum": ["nio_linux_ethernet"]
},
"ethernet_device": {
"description": "Ethernet device name e.g. eth0",
"type": "string",
"minLength": 1
},
},
"required": ["type", "ethernet_device"],
"additionalProperties": False
},
"TAP": {
"description": "TAP Network Input/Output",
"properties": {
"type": {
"enum": ["nio_tap"]
},
"tap_device": {
"description": "TAP device name e.g. tap0",
"type": "string",
"minLength": 1
},
},
"required": ["type", "tap_device"],
"additionalProperties": False
},
"UNIX": {
"description": "UNIX Network Input/Output",
"properties": {
"type": {
"enum": ["nio_unix"]
},
"local_file": {
"description": "path to the UNIX socket file (local)",
"type": "string",
"minLength": 1
},
"remote_file": {
"description": "path to the UNIX socket file (remote)",
"type": "string",
"minLength": 1
},
},
"required": ["type", "local_file", "remote_file"],
"additionalProperties": False
},
"VDE": {
"description": "VDE Network Input/Output",
"properties": {
"type": {
"enum": ["nio_vde"]
},
"control_file": {
"description": "path to the VDE control file",
"type": "string",
"minLength": 1
},
"local_file": {
"description": "path to the VDE control file",
"type": "string",
"minLength": 1
},
},
"required": ["type", "control_file", "local_file"],
"additionalProperties": False
},
"NULL": {
"description": "NULL Network Input/Output",
"properties": {
"type": {
"enum": ["nio_null"]
},
},
"required": ["type"],
"additionalProperties": False
},
},
"properties": {
"id": {
"description": "VPCS device instance ID",
"type": "integer"
},
"port_id": {
"description": "Unique port identifier for the VPCS instance",
"type": "integer"
},
"port": {
"description": "Port number",
"type": "integer",
"minimum": 0,
"maximum": 0
},
"nio": {
"type": "object",
"description": "Network Input/Output",
"oneOf": [
{"$ref": "#/definitions/UDP"},
{"$ref": "#/definitions/Ethernet"},
{"$ref": "#/definitions/LinuxEthernet"},
{"$ref": "#/definitions/TAP"},
{"$ref": "#/definitions/UNIX"},
{"$ref": "#/definitions/VDE"},
{"$ref": "#/definitions/NULL"},
]
},
},
"additionalProperties": False,
"required": ["id", "port_id", "port", "nio"]
}
VPCS_OBJECT_SCHEMA = {
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "VPCS instance",
"type": "object",
"properties": {
"name": {
"description": "VPCS device name",
"type": "string",
"minLength": 1,
},
"vpcs_id": {
"description": "VPCS device instance ID",
"type": "integer"
},
"console": {
"description": "console TCP port",
"minimum": 1,
"maximum": 65535,
"type": "integer"
},
},
"additionalProperties": False,
"required": ["name", "vpcs_id", "console"]
}
VBOX_CREATE_SCHEMA = {
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "Request validation to create a new VirtualBox VM instance",
"type": "object",
"properties": {
"name": {
"description": "VirtualBox VM instance name",
"type": "string",
"minLength": 1,
},
"vbox_id": {
"description": "VirtualBox VM instance ID",
"type": "integer"
},
},
"additionalProperties": False,
"required": ["name"],
}
VBOX_OBJECT_SCHEMA = {
"$schema": "http://json-schema.org/draft-04/schema#",
"description": "VirtualBox instance",
"type": "object",
"properties": {
"name": {
"description": "VirtualBox VM name",
"type": "string",
"minLength": 1,
},
"vbox_id": {
"description": "VirtualBox VM instance ID",
"type": "integer"
},
},
"additionalProperties": False,
"required": ["name", "vbox_id"]
}

378
gns3server/server.py
View File

@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2013 GNS3 Technologies Inc.
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@ -19,51 +19,36 @@
Set up and run the server.
"""
import zmq
from zmq.eventloop import ioloop, zmqstream
ioloop.install()
import sys
import os
import tempfile
import sys
import signal
import errno
import socket
import tornado.ioloop
import tornado.web
import tornado.autoreload
import pkg_resources
import asyncio
import aiohttp
import ipaddress
import base64
import uuid
import functools
import types
import time
from pkg_resources import parse_version
from .web.route import Route
from .config import Config
from .handlers.jsonrpc_websocket import JSONRPCWebSocket
from .handlers.version_handler import VersionHandler
from .handlers.file_upload_handler import FileUploadHandler
from .handlers.auth_handler import LoginHandler
from .builtins.server_version import server_version
from .builtins.interfaces import interfaces
from .modules import MODULES
#FIXME: have something generic to automatically import handlers so the routes can be found
from .handlers.version_handler import VersionHandler
from .handlers.vpcs_handler import VPCSHandler
import logging
log = logging.getLogger(__name__)
class Server(object):
class Server:
# built-in handlers
handlers = [(r"/version", VersionHandler),
(r"/upload", FileUploadHandler),
(r"/login", LoginHandler)]
def __init__(self, host, port, ipc, console_bind_to_any):
def __init__(self, host, port, console_bind_to_any):
self._host = host
self._port = port
self._router = None
self._stream = None
self._loop = None
self._start_time = time.time()
if console_bind_to_any:
if ipaddress.ip_address(self._host).version == 6:
@ -73,263 +58,106 @@ class Server(object):
else:
self._console_host = self._host
if ipc:
self._zmq_port = 0 # this forces to use IPC for communications with the ZeroMQ server
#TODO: server config file support, to be reviewed
# # get the projects and temp directories from the configuration file (passed to the modules)
# config = Config.instance()
# server_config = config.get_default_section()
# # default projects directory is "~/GNS3/projects"
# self._projects_dir = os.path.expandvars(os.path.expanduser(server_config.get("projects_directory", "~/GNS3/projects")))
# self._temp_dir = server_config.get("temporary_directory", tempfile.gettempdir())
#
# try:
# os.makedirs(self._projects_dir)
# log.info("projects directory '{}' created".format(self._projects_dir))
# except FileExistsError:
# pass
# except OSError as e:
# log.error("could not create the projects directory {}: {}".format(self._projects_dir, e))
@asyncio.coroutine
def _run_application(self, app):
server = yield from self._loop.create_server(app.make_handler(), self._host, self._port)
return server
def _stop_application(self):
"""
Cleanup the modules (shutdown running emulators etc.)
"""
#TODO: clean everything from here
self._loop.stop()
def _signal_handling(self):
def signal_handler(signame):
log.warning("server has got signal {}, exiting...".format(signame))
self._stop_application()
signals = ["SIGTERM", "SIGINT"]
if sys.platform.startswith("win"):
signals.extend(["SIGBREAK"])
else:
# communication between the ZeroMQ server and the modules (ZeroMQ dealers)
# is IPv4 and local (127.0.0.1)
try:
# let the OS find an unused port for the ZeroMQ server
with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
sock.bind(("127.0.0.1", 0))
self._zmq_port = sock.getsockname()[1]
except OSError as e:
log.critical("server cannot listen to {}: {}".format(self._host, e))
raise SystemExit
self._ipc = ipc
self._modules = []
signals.extend(["SIGHUP", "SIGQUIT"])
# get the projects and temp directories from the configuration file (passed to the modules)
config = Config.instance()
server_config = config.get_default_section()
# default projects directory is "~/GNS3/projects"
self._projects_dir = os.path.expandvars(os.path.expanduser(server_config.get("projects_directory", "~/GNS3/projects")))
self._temp_dir = server_config.get("temporary_directory", tempfile.gettempdir())
for signal_name in signals:
callback = functools.partial(signal_handler, signal_name)
if sys.platform.startswith("win"):
# add_signal_handler() is not yet supported on Windows
signal.signal(getattr(signal, signal_name), callback)
else:
self._loop.add_signal_handler(getattr(signal, signal_name), callback)
try:
os.makedirs(self._projects_dir)
log.info("projects directory '{}' created".format(self._projects_dir))
except FileExistsError:
pass
except OSError as e:
log.error("could not create the projects directory {}: {}".format(self._projects_dir, e))
def _reload_hook(self):
def load_modules(self):
"""
Loads the modules.
"""
def reload():
#=======================================================================
# cwd = os.path.dirname(os.path.abspath(__file__))
# module_path = os.path.join(cwd, 'modules')
# log.info("loading modules from {}".format(module_path))
# module_manager = ModuleManager([module_path])
# module_manager.load_modules()
# for module in module_manager.get_all_modules():
# instance = module_manager.activate_module(module,
# "127.0.0.1", # ZeroMQ server address
# self._zmq_port, # ZeroMQ server port
# projects_dir=self._projects_dir,
# temp_dir=self._temp_dir)
# if not instance:
# continue
# self._modules.append(instance)
# destinations = instance.destinations()
# for destination in destinations:
# JSONRPCWebSocket.register_destination(destination, module.name)
# instance.start() # starts the new process
#=======================================================================
log.info("reloading")
self._stop_application()
os.execv(sys.executable, [sys.executable] + sys.argv)
# special built-in to return the server version
JSONRPCWebSocket.register_destination("builtin.version", server_version)
# special built-in to return the available interfaces on this host
JSONRPCWebSocket.register_destination("builtin.interfaces", interfaces)
for module in MODULES:
instance = module(module.__name__.lower(),
"127.0.0.1", # ZeroMQ server address
self._zmq_port, # ZeroMQ server port
host=self._host, # server host address
console_host=self._console_host,
projects_dir=self._projects_dir,
temp_dir=self._temp_dir)
self._modules.append(instance)
destinations = instance.destinations()
for destination in destinations:
JSONRPCWebSocket.register_destination(destination, instance.name)
instance.start() # starts the new process
# code extracted from tornado
for module in sys.modules.values():
# Some modules play games with sys.modules (e.g. email/__init__.py
# in the standard library), and occasionally this can cause strange
# failures in getattr. Just ignore anything that's not an ordinary
# module.
if not isinstance(module, types.ModuleType):
continue
path = getattr(module, "__file__", None)
if not path:
continue
if path.endswith(".pyc") or path.endswith(".pyo"):
path = path[:-1]
modified = os.stat(path).st_mtime
if modified > self._start_time:
log.debug("file {} has been modified".format(path))
reload()
self._loop.call_later(1, self._reload_hook)
def run(self):
"""
Starts the Tornado web server and ZeroMQ server.
Starts the server.
"""
settings = {
"debug":True,
"cookie_secret": base64.b64encode(uuid.uuid4().bytes + uuid.uuid4().bytes),
"login_url": "/login",
}
#TODO: SSL support for Rackspace cloud integration (here or with nginx for instance).
self._loop = asyncio.get_event_loop()
app = aiohttp.web.Application()
for method, route, handler in Route.get_routes():
log.debug("adding route: {} {}".format(method, route))
app.router.add_route(method, route, handler)
for module in MODULES:
log.debug("loading module {}".format(module.__name__))
module.instance()
ssl_options = {}
log.info("starting server on {}:{}".format(self._host, self._port))
self._loop.run_until_complete(self._run_application(app))
self._signal_handling()
#FIXME: remove it in production
self._loop.call_later(1, self._reload_hook)
try:
cloud_config = Config.instance().get_section_config("CLOUD_SERVER")
cloud_settings = {
"required_user" : cloud_config['WEB_USERNAME'],
"required_pass" : cloud_config['WEB_PASSWORD'],
}
settings.update(cloud_settings)
if cloud_config["SSL_ENABLED"] == "yes":
ssl_options = {
"certfile" : cloud_config["SSL_CRT"],
"keyfile" : cloud_config["SSL_KEY"],
}
log.info("Certs found - starting in SSL mode")
except KeyError:
log.info("Missing cloud.conf - disabling HTTP auth and SSL")
router = self._create_zmq_router()
# Add our JSON-RPC Websocket handler to Tornado
self.handlers.extend([(r"/", JSONRPCWebSocket, dict(zmq_router=router))])
if hasattr(sys, "frozen"):
templates_dir = "templates"
else:
templates_dir = pkg_resources.resource_filename("gns3server", "templates")
tornado_app = tornado.web.Application(self.handlers,
template_path=templates_dir,
**settings) # FIXME: debug mode!
try:
user_log = logging.getLogger('user_facing')
user_log.info("Starting server on {}:{} (Tornado v{}, PyZMQ v{}, ZMQ v{})".format(
self._host, self._port, tornado.version, zmq.__version__, zmq.zmq_version()))
kwargs = {"address": self._host}
if ssl_options:
kwargs["ssl_options"] = ssl_options
if parse_version(tornado.version) >= parse_version("3.1"):
kwargs["max_buffer_size"] = 524288000 # 500 MB file upload limit
tornado_app.listen(self._port, **kwargs)
except OSError as e:
if e.errno == errno.EADDRINUSE: # socket already in use
logging.critical("socket in use for {}:{}".format(self._host, self._port))
self._cleanup(graceful=False)
ioloop = tornado.ioloop.IOLoop.instance()
self._stream = zmqstream.ZMQStream(router, ioloop)
self._stream.on_recv_stream(JSONRPCWebSocket.dispatch_message)
tornado.autoreload.add_reload_hook(self._reload_callback)
def signal_handler(signum=None, frame=None):
try:
log.warning("Server got signal {}, exiting...".format(signum))
self._cleanup(signum)
except RuntimeError:
# to ignore logging exception: RuntimeError: reentrant call inside <_io.BufferedWriter name='<stderr>'>
pass
signals = [signal.SIGTERM, signal.SIGINT]
if not sys.platform.startswith("win"):
signals.extend([signal.SIGHUP, signal.SIGQUIT])
else:
signals.extend([signal.SIGBREAK])
for sig in signals:
signal.signal(sig, signal_handler)
try:
ioloop.start()
except (KeyboardInterrupt, SystemExit):
self._loop.run_forever()
except KeyboardInterrupt:
log.info("\nExiting...")
self._cleanup()
def _create_zmq_router(self):
"""
Creates the ZeroMQ router socket to send
requests to modules.
:returns: ZeroMQ router socket
"""
context = zmq.Context()
context.linger = 0
self._router = context.socket(zmq.ROUTER)
if self._ipc:
try:
self._router.bind("ipc:///tmp/gns3.ipc")
except zmq.error.ZMQError as e:
log.critical("Could not start ZeroMQ server on ipc:///tmp/gns3.ipc, reason: {}".format(e))
self._cleanup(graceful=False)
raise SystemExit
log.info("ZeroMQ server listening to ipc:///tmp/gns3.ipc")
else:
try:
self._router.bind("tcp://127.0.0.1:{}".format(self._zmq_port))
except zmq.error.ZMQError as e:
log.critical("Could not start ZeroMQ server on 127.0.0.1:{}, reason: {}".format(self._zmq_port, e))
self._cleanup(graceful=False)
raise SystemExit
log.info("ZeroMQ server listening to 127.0.0.1:{}".format(self._zmq_port))
return self._router
def stop_module(self, module):
"""
Stop a given module.
:param module: module name
"""
if not self._router.closed:
self._router.send_string(module, zmq.SNDMORE)
self._router.send_string("stop")
def _reload_callback(self):
"""
Callback for the Tornado reload hook.
"""
for module in self._modules:
if module.is_alive():
module.terminate()
module.join(timeout=1)
def _shutdown(self):
"""
Shutdowns the I/O loop and the ZeroMQ stream & socket.
"""
if self._stream and not self._stream.closed:
# close the ZeroMQ stream
self._stream.close()
if self._router and not self._router.closed:
# close the ZeroMQ router socket
self._router.close()
ioloop = tornado.ioloop.IOLoop.instance()
ioloop.stop()
def _cleanup(self, signum=None, graceful=True):
"""
Shutdowns any running module processes
and adds a callback to stop the event loop & ZeroMQ
:param signum: signal number (if called by a signal handler)
:param graceful: gracefully stop the modules
"""
# terminate all modules
for module in self._modules:
if module.is_alive() and graceful:
log.info("stopping {}".format(module.name))
self.stop_module(module.name)
module.join(timeout=3)
if module.is_alive():
# just kill the module if it is still alive.
log.info("terminating {}".format(module.name))
module.terminate()
module.join(timeout=1)
ioloop = tornado.ioloop.IOLoop.instance()
if signum:
ioloop.add_callback_from_signal(self._shutdown)
else:
ioloop.add_callback(self._shutdown)

2
gns3server/start_server.py
View File

@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2013 GNS3 Technologies Inc.
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by

13
gns3server/version.py
View File

@ -1,6 +1,6 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2013 GNS3 Technologies Inc.
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
@ -15,13 +15,4 @@
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
# __version__ is a human-readable version number.
# __version_info__ is a four-tuple for programmatic comparison. The first
# three numbers are the components of the version number. The fourth
# is zero for an official release, positive for a development branch,
# or negative for a release candidate or beta (after the base version
# number has been incremented)
__version__ = "1.2.2.dev2"
__version_info__ = (1, 2, 2, 0)
__version__ = "1.3.dev1"

0
gns3server/web/__init__.py Normal file
View File

131
gns3server/web/documentation.py Normal file
View File

@ -0,0 +1,131 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
import re
import os.path
from .route import Route
class Documentation(object):
"""Extract API documentation as Sphinx compatible files"""
def __init__(self, route):
self._documentation = route.get_documentation()
def write(self):
for path in sorted(self._documentation):
filename = self._file_path(path)
handler_doc = self._documentation[path]
with open("docs/api/{}.rst".format(filename), 'w+') as f:
f.write('{}\n------------------------------\n\n'.format(path))
f.write('.. contents::\n')
for method in handler_doc["methods"]:
f.write('\n{} {}\n'.format(method["method"], path))
f.write('~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n')
f.write('{}\n\n'.format(method["description"]))
if len(method["parameters"]) > 0:
f.write("Parameters\n**********\n")
for parameter in method["parameters"]:
desc = method["parameters"][parameter]
f.write("- **{}**: {}\n".format(parameter, desc))
f.write("\n")
f.write("Response status codes\n*******************\n")
for code in method["status_codes"]:
desc = method["status_codes"][code]
f.write("- **{}**: {}\n".format(code, desc))
f.write("\n")
if "properties" in method["input_schema"]:
f.write("Input\n*******\n")
self._write_definitions(f, method["input_schema"])
self.__write_json_schema(f, method["input_schema"])
if "properties" in method["output_schema"]:
f.write("Output\n*******\n")
self.__write_json_schema(f, method["output_schema"])
self._include_query_example(f, method, path)
def _include_query_example(self, f, method, path):
"""If a sample session is available we include it in documentation"""
m = method["method"].lower()
query_path = "examples/{}_{}.txt".format(m, self._file_path(path))
if os.path.isfile("docs/api/{}".format(query_path)):
f.write("Sample session\n***************\n")
f.write("\n\n.. literalinclude:: {}\n\n".format(query_path))
def _file_path(self, path):
return re.sub('[^a-z0-9]', '', path)
def _write_definitions(self, f, schema):
if "definitions" in schema:
f.write("Types\n+++++++++\n")
for definition in sorted(schema['definitions']):
desc = schema['definitions'][definition].get("description")
f.write("{}\n^^^^^^^^^^^^^^^^\n{}\n\n".format(definition, desc))
self._write_json_schema(f, schema['definitions'][definition])
f.write("Body\n+++++++++\n")
def _write_json_schema_object(self, f, obj, schema):
"""
obj is current object in JSON schema
schema is the whole schema including definitions
"""
for name in sorted(obj.get("properties", {})):
prop = obj["properties"][name]
mandatory = " "
if name in obj.get("required", []):
mandatory = "&#10004;"
if "enum" in prop:
field_type = "enum"
prop['description'] = "Possible values: {}".format(', '.join(prop['enum']))
else:
field_type = prop.get("type", "")
# Resolve oneOf relation to their human type.
if field_type == 'object' and 'oneOf' in prop:
field_type = ', '.join(map(lambda p: p['$ref'].split('/').pop(), prop['oneOf']))
f.write(" <tr><td>{}</td>\
<td>{}</td> \
<td>{}</td> \
<td>{}</td> \
</tr>\n".format(
name,
mandatory,
field_type,
prop.get("description", "")
))
def _write_json_schema(self, f, schema):
# TODO: rewrite this using RST for portability
f.write(".. raw:: html\n\n <table>\n")
f.write(" <tr> \
<th>Name</th> \
<th>Mandatory</th> \
<th>Type</th> \
<th>Description</th> \
</tr>\n")
self._write_json_schema_object(f, schema, schema)
f.write(" </table>\n\n")
if __name__ == '__main__':
Documentation(Route).write()

41
gns3server/web/response.py Normal file
View File

@ -0,0 +1,41 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
import json
import jsonschema
import aiohttp.web
class Response(aiohttp.web.Response):
def __init__(self, route=None, output_schema=None, headers={}, **kwargs):
self._route = route
self._output_schema = output_schema
headers['X-Route'] = self._route
super().__init__(headers=headers, **kwargs)
def json(self, answer):
"""Pass a Python object and return a JSON as answer"""
self.content_type = "application/json"
if self._output_schema is not None:
try:
jsonschema.validate(answer, self._output_schema)
except jsonschema.ValidationError as e:
raise aiohttp.web.HTTPBadRequest(text="{}".format(e))
self.body = json.dumps(answer, indent=4, sort_keys=True).encode('utf-8')

113
gns3server/web/route.py Normal file
View File

@ -0,0 +1,113 @@
# -*- coding: utf-8 -*-
#
# Copyright (C) 2015 GNS3 Technologies Inc.
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program. If not, see <http://www.gnu.org/licenses/>.
import json
import jsonschema
import asyncio
import aiohttp
from .response import Response
@asyncio.coroutine
def parse_request(request, input_schema):
"""Parse body of request and raise HTTP errors in case of problems"""
content_length = request.content_length
if content_length is not None and content_length > 0:
body = yield from request.read()
try:
request.json = json.loads(body.decode('utf-8'))
except ValueError as e:
raise aiohttp.web.HTTPBadRequest(text="Invalid JSON {}".format(e))
try:
jsonschema.validate(request.json, input_schema)
except jsonschema.ValidationError as e:
raise aiohttp.web.HTTPBadRequest(text="Request is not {} '{}' in schema: {}".format(
e.validator,
e.validator_value,
json.dumps(e.schema)))
return request
class Route(object):
""" Decorator adding:
* json schema verification
* routing inside handlers
* documentation information about endpoints
"""
_routes = []
_documentation = {}
@classmethod
def get(cls, path, *args, **kw):
return cls._route('GET', path, *args, **kw)
@classmethod
def post(cls, path, *args, **kw):
return cls._route('POST', path, *args, **kw)
@classmethod
def put(cls, path, *args, **kw):
return cls._route('PUT', path, *args, **kw)
@classmethod
def _route(cls, method, path, *args, **kw):
# This block is executed only the first time
output_schema = kw.get("output", {})
input_schema = kw.get("input", {})
cls._path = path
cls._documentation.setdefault(cls._path, {"methods": []})
def register(func):
route = cls._path
cls._documentation[route]["methods"].append({
"method": method,
"status_codes": kw.get("status_codes", {200: "OK"}),
"parameters": kw.get("parameters", {}),
"output_schema": output_schema,
"input_schema": input_schema,
"description": kw.get("description", "")
})
func = asyncio.coroutine(func)
@asyncio.coroutine
def control_schema(request):
# This block is executed at each method call
try:
request = yield from parse_request(request, input_schema)
response = Response(route=route, output_schema=output_schema)
yield from func(request, response)
except aiohttp.web.HTTPException as e:
response = Response(route=route)
response.set_status(e.status)
response.json({"message": e.text, "status": e.status})
return response
cls._routes.append((method, cls._path, control_schema))
return control_schema
return register
@classmethod
def get_routes(cls):
return cls._routes
@classmethod
def get_documentation(cls):
return cls._documentation

2
setup.py
View File

@ -64,7 +64,7 @@ setup(
"Intended Audience :: Information Technology",
"Topic :: System :: Networking",
"License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
'Natural Language :: English',
"Natural Language :: English",
"Operating System :: OS Independent",
"Programming Language :: Python",
"Programming Language :: Python :: 3",