mirror of https://github.com/GNS3/gns3-server
Jeremy
9 years ago
parent
5e665cc67a
commit
61344a1669
@ -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,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"
|
||||
}
|
||||
@ -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"
|
||||
}
|
||||
@ -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
|
||||
}
|
||||
@ -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
|
||||
}
|
||||
@ -0,0 +1,13 @@
|
||||
/sleep
|
||||
------------------------------
|
||||
|
||||
.. contents::
|
||||
|
||||
GET /sleep
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
Response status codes
|
||||
**************************
|
||||
- **200**: OK
|
||||
|
||||
@ -0,0 +1,13 @@
|
||||
/stream
|
||||
------------------------------
|
||||
|
||||
.. contents::
|
||||
|
||||
GET /stream
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
|
||||
Response status codes
|
||||
**************************
|
||||
- **200**: OK
|
||||
|
||||
@ -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>✔</td><td>string</td><td>Version number human readable</td></tr>
|
||||
</table>
|
||||
|
||||
Sample session
|
||||
***************
|
||||
|
||||
|
||||
.. literalinclude:: examples/get_version.txt
|
||||
|
||||
@ -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>✔</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>✔</td><td>integer</td><td>console TCP port</td></tr>
|
||||
<tr><td>name</td><td>✔</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>
|
||||
|
||||
Sample session
|
||||
***************
|
||||
|
||||
|
||||
.. literalinclude:: examples/post_vpcs.txt
|
||||
|
||||
@ -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>✔</td><td>integer</td><td>console TCP port</td></tr>
|
||||
<tr><td>name</td><td>✔</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>
|
||||
|
||||
|
||||
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>✔</td><td>integer</td><td>console TCP port</td></tr>
|
||||
<tr><td>name</td><td>✔</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>✔</td><td>integer</td><td>console TCP port</td></tr>
|
||||
<tr><td>name</td><td>✔</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>
|
||||
|
||||
@ -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>✔</td><td>string</td><td>Ethernet device name e.g. eth0</td></tr>
|
||||
<tr><td>type</td><td>✔</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>✔</td><td>string</td><td>Ethernet device name e.g. eth0</td></tr>
|
||||
<tr><td>type</td><td>✔</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>✔</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>✔</td><td>string</td><td>TAP device name e.g. tap0</td></tr>
|
||||
<tr><td>type</td><td>✔</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>✔</td><td>integer</td><td>Local port</td></tr>
|
||||
<tr><td>rhost</td><td>✔</td><td>string</td><td>Remote host</td></tr>
|
||||
<tr><td>rport</td><td>✔</td><td>integer</td><td>Remote port</td></tr>
|
||||
<tr><td>type</td><td>✔</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>✔</td><td>string</td><td>path to the UNIX socket file (local)</td></tr>
|
||||
<tr><td>remote_file</td><td>✔</td><td>string</td><td>path to the UNIX socket file (remote)</td></tr>
|
||||
<tr><td>type</td><td>✔</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>✔</td><td>string</td><td>path to the VDE control file</td></tr>
|
||||
<tr><td>local_file</td><td>✔</td><td>string</td><td>path to the VDE control file</td></tr>
|
||||
<tr><td>type</td><td>✔</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>✔</td><td>integer</td><td>VPCS device instance ID</td></tr>
|
||||
<tr><td>nio</td><td>✔</td><td>UDP, Ethernet, LinuxEthernet, TAP, UNIX, VDE, NULL</td><td>Network Input/Output</td></tr>
|
||||
<tr><td>port</td><td>✔</td><td>integer</td><td>Port number</td></tr>
|
||||
<tr><td>port_id</td><td>✔</td><td>integer</td><td>Unique port identifier for the VPCS instance</td></tr>
|
||||
</table>
|
||||
|
||||
Sample session
|
||||
***************
|
||||
|
||||
|
||||
.. literalinclude:: examples/post_vpcsvpcsidnio.txt
|
||||
|
||||
@ -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
|
||||
@ -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
|
||||
|
||||
@ -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"
|
||||
}
|
||||
@ -0,0 +1,18 @@
|
||||
Welcome to API documentation!
|
||||
======================================
|
||||
|
||||
|
||||
.. toctree::
|
||||
general
|
||||
development
|
||||
|
||||
|
||||
API Endpoints
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
.. toctree::
|
||||
:glob:
|
||||
:maxdepth: 2
|
||||
|
||||
api/*
|
||||
|
||||
@ -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
|
||||
@ -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)())
|
||||
@ -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])
|
||||
@ -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})
|
||||
@ -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
|
||||
@ -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
|
||||
@ -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,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"]
|
||||
}
|
||||
@ -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 = "✔"
|
||||
|
||||
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()
|
||||
@ -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')
|
||||
@ -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
|
||||
Loading…
Reference in new issue