1
0
mirror of https://github.com/GNS3/gns3-server synced 2024-11-13 20:08:55 +00:00

Update documentation.

This commit is contained in:
grossmj 2018-01-31 23:37:02 +07:00
parent e5a4afaeb1
commit 07d2d7b340
10 changed files with 184 additions and 199 deletions

View File

@ -1,30 +1,34 @@
Sample session using curl
=========================
Sample sessions using curl
==========================
You need to read the :doc:`glossary`, and :doc:`general` before.
Read the :doc:`glossary`, and :doc:`general` pages first.
Full endpoints list is available: :doc:`endpoints`
A list of all endpoints is available in :doc:`endpoints`
.. warning::
Beware the output of this sample is truncated in order
to simplify the understanding. Please read the
documentation for the exact output.
Note that the output of the samples can be truncated in
order to simplify their understanding. Please read the
documentation for the exact output meaning.
You can check the server version with a simple curl command:
Server version
###############
Check the server version with a simple curl command:
.. code-block:: shell-session
# curl "http://localhost:3080/v2/version"
{
"version": "2.0.0dev1"
"local": false,
"version": "2.1.4"
}
List computes
##############
We will list the computes node where we can run our nodes:
List all the compute servers:
.. code-block:: shell-session
@ -34,20 +38,20 @@ We will list the computes node where we can run our nodes:
"compute_id": "local",
"connected": true,
"host": "127.0.0.1",
"name": "Local",
"name": "local",
"port": 3080,
"protocol": "http",
"user": "admin"
}
]
In this sample we have only one compute where we can run our nodes. This compute as a special id: local. This
mean it's the local server embed in the GNS3 controller.
There is only one compute server where nodes can be run in this example.
This compute as a special id: local, this is the local server which is embedded in the GNS3 controller.
Create project
###############
Create a project
#################
The next step is to create a project.
The next step is to create a project:
.. code-block:: shell-session
@ -60,7 +64,7 @@ The next step is to create a project.
Create nodes
#############
With this project id we can now create two VPCS Node.
Using the project id, it is now possible to create two VPCS nodes:
.. code-block:: shell-session
@ -87,15 +91,14 @@ With this project id we can now create two VPCS Node.
"node_id": "83892a4d-aea0-4350-8b3e-d0af3713da74",
"node_type": "vpcs",
"project_id": "b8c070f7-f34c-4b7b-ba6f-be3d26ed073f",
"properties": {},
"status": "stopped"
}
The properties dictionnary contains all setting specific to a node type (dynamips, docker, vpcs...)
Link nodes
###########
Now we need to link the two VPCS by connecting their port 0 together.
The two VPCS nodes can be linked together using their port number 0 (VPCS has only one network adapter with one port):
.. code-block:: shell-session
@ -123,7 +126,7 @@ Now we need to link the two VPCS by connecting their port 0 together.
Start nodes
###########
Now we can start the two nodes.
Start the two nodes:
.. code-block:: shell-session
@ -133,8 +136,8 @@ Now we can start the two nodes.
Connect to nodes
#################
Everything should be started now. You can connect via telnet to the different Node.
The port is the field console in the create Node request.
Use a Telnet client to connect to the nodes once they have been started.
The port number can be found in the output when the nodes have been created above.
.. code-block:: shell-session
@ -200,7 +203,7 @@ The port is the field console in the create Node request.
Stop nodes
##########
And we stop the two nodes.
Stop the two nodes:
.. code-block:: shell-session
@ -208,40 +211,41 @@ And we stop the two nodes.
# curl -X POST "http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/nodes/83892a4d-aea0-4350-8b3e-d0af3713da74/stop" -d "{}"
Add a visual element
######################
Add visual elements
####################
When you want add visual elements to the topology like rectangle, circle, images you can just send a raw SVG.
This will display a red square in the middle of your topologies:
Visual elements like rectangle, ellipses or images in the form of raw SVG can be added to a project.
This will display a red square in the middle of your canvas:
.. code-block:: shell-session
# curl -X POST "http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/drawings" -d '{"x":0, "y": 12, "svg": "<svg width=\"50\" height=\"50\"><rect width=\"50\" height=\"50\" style=\"fill: #ff0000\"></rect></svg>"}'
Tips: you can embed png/jpg... by using a base64 encoding in the SVG.
Tip: embed PNG, JPEG etc. images using base64 encoding in the SVG.
Add filter to the link
######################
Add a packet filter
####################
Filter allow you to add error on a link.
Packet filters allow to filter packet on a given link. Here to drop a packet every 5 packets:
.. code-block:: shell-session
curl -X PUT "http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/links/007f2177-6790-4e1b-ac28-41fa226b2a06" -d '{"filters": {"frequency_drop": [5]}}'
Creation of nodes
#################
Node creation
##############
Their is two way of adding nodes. Manual by passing all the information require for a Node.
There are two ways to add nodes.
Or by using an appliance. The appliance is a node model saved in your server.
1. Manually by passing all the information required to create a new node.
2. Using an appliance template stored on your server.
Using an appliance
------------------
Using an appliance template
---------------------------
First you need to list the available appliances
List all the available appliance templates:
.. code-block:: shell-session
@ -268,15 +272,15 @@ First you need to list the available appliances
}
]
Now you can use the appliance and put it at a specific position
Use the appliance template and add coordinates to select where the node will be put on the canvas:
.. code-block:: shell-session
# curl -X POST http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f -d '{"x": 12, "y": 42}'
# curl -X POST http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/appliances/9cd59d5a-c70f-4454-8313-6a9e81a8278f -d '{"x": 12, "y": 42}'
Manual creation of a Qemu node
-------------------------------
------------------------------
.. code-block:: shell-session
@ -360,7 +364,7 @@ Manual creation of a Qemu node
}
Manual creation of a dynamips node
Manual creation of a Dynamips node
-----------------------------------
.. code-block:: shell-session
@ -486,7 +490,7 @@ Manual creation of a dynamips node
Notifications
#############
You can see notification about the changes via the notification feed:
Notifications can be seen by connection to the notification feed:
.. code-block:: shell-session
@ -494,14 +498,14 @@ You can see notification about the changes via the notification feed:
{"action": "ping", "event": {"compute_id": "local", "cpu_usage_percent": 35.7, "memory_usage_percent": 80.7}}
{"action": "node.updated", "event": {"command_line": "/usr/local/bin/vpcs -p 5001 -m 1 -i 1 -F -R -s 10001 -c 10000 -t 127.0.0.1", "compute_id": "local", "console": 5001, "console_host": "127.0.0.1", "console_type": "telnet", "name": "VPCS 2", "node_id": "83892a4d-aea0-4350-8b3e-d0af3713da74", "node_type": "vpcs", "project_id": "b8c070f7-f34c-4b7b-ba6f-be3d26ed073f", "properties": {"startup_script": null, "startup_script_path": null}, "status": "started"}}
A websocket version is also available on http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/notifications/ws
A Websocket notification stream is also available on http://localhost:3080/v2/projects/b8c070f7-f34c-4b7b-ba6f-be3d26ed073f/notifications/ws
Read :doc:`notifications` for more informations
Read :doc:`notifications` for more information.
How to found the endpoints?
Where to find the endpoints?
###########################
Full endpoints list is available: :doc:`endpoints`
A list of all endpoints is available: :doc:`endpoints`
If you start the server with **--debug** you can see all the requests made by the client and by the controller to the computes nodes.
Tip: requests made by a client and by a controller to the computes nodes can been seen if the server is started with the **--debug** parameter.

View File

@ -4,27 +4,25 @@ Development
Code convention
===============
You should respect all the PEP8 convention except the
rule about max line length.
Respect all the PEP8 convention except the max line length rule.
Source code
===========
Source code is available on github under GPL V3 licence:
Source code is available on Github under the GPL V3 licence:
https://github.com/GNS3/
The GNS3 server: https://github.com/GNS3/gns3-server
The Qt GUI: https://github.com/GNS3/gns3-gui
The GNS3 user interface: https://github.com/GNS3/gns3-gui
Documentation
==============
In the gns3-server project.
The documentation can be found in the gns3-server project.
Build doc
----------
In the project root folder:
.. code-block:: bash
@ -41,4 +39,3 @@ Run tests
.. code-block:: bash
py.test -v

View File

@ -1,21 +1,22 @@
Endpoints
------------
GNS3 expose two type of endpoints:
GNS3 exposes two type of endpoints:
* Controller
* Compute
* Controller endpoints
* Compute endpoints
Controller API Endpoints
~~~~~~~~~~~~~~~~~~~~~~~~
Controller endpoints
~~~~~~~~~~~~~~~~~~~~~
The controller manage all the running topologies. The controller
has knowledge of everything on in GNS3. If you want to create and
manage a topology it's here. The controller will call the compute API
when needed.
The controller manages everything, it is the central decision point
and has a complete view of your network topologies, what nodes run on
which compute server, the links between them etc.
In a standard GNS3 installation you have one controller and one or many
computes.
This is the high level API which can be used by users to manually control
the GNS3 backend. The controller will call the compute endpoints when needed.
A standard GNS3 setup is to have one controller and one or many computes.
.. toctree::
:glob:
@ -24,14 +25,15 @@ computes.
api/v2/controller/*
Compute API Endpoints
~~~~~~~~~~~~~~~~~~~~~~~~~~
Compute Endpoints
~~~~~~~~~~~~~~~~~~
The compute is the GNS3 process running on a server and controlling
the VM process.
A compute is the GNS3 process running on a host. It controls emulators in order to run nodes
(e.g. VMware VMs with VMware Workstation, IOS routers with Dynamips etc.)
.. WARNING::
Consider this endpoints as a private API used by the controller.
These endpoints should be considered low level and private.
They should only be used by the controller or for debugging purposes.
.. toctree::
:glob:

View File

@ -1,11 +1,11 @@
GNS3 file formats
=================
The GNS3 files
===============
The .gns3
##########
.gns3 files
############
It's the topology file of GNS3 this file is a JSON with all
the informations about what is inside the topology.
GNS3 project files in JSON file format with all
the information necessary to save a project.
A minimal version:
@ -30,34 +30,34 @@ The revision is the version of file format:
* 4: GNS3 1.5
* 3: GNS3 1.4
* 2: GNS3 1.3
* 1: GNS3 1.0, 1.1, 1.2 (Not mentionned in the topology file)
* 1: GNS3 1.0, 1.1, 1.2 (Not mentioned in the file)
And the full JSON schema:
The full JSON schema can be found there:
.. literalinclude:: gns3_file.json
The .net
#########
It's topologies made for GNS3 0.8
.net files
###########
Topology files made for GNS3 <= version 1.0. Not supported.
The .gns3p or .gns3project
###########################
It's a zipped version of the .gns3 and all files require for
a topology. The images could be included inside but are optionnals.
The zip could be a ZIP64 if the project is too big for standard
zip file.
The .gns3a or .gns3appliance
.gns3p or .gns3project files
#############################
This file contains details on how to import an appliance in GNS3.
This this a zipped version of a.gns3 file and includes all the required files to easily share a project.
The binary images can optionally be included.
A JSON schema is available here:
The zip can be a ZIP64 if the project is too big for standard zip file.
.gns3a or .gns3appliance files
##############################
These files contain everything needed to create a new appliance template in GNS3.
A JSON schema is available there:
https://github.com/GNS3/gns3-registry/blob/master/schemas/appliance.json
And samples here:
And samples there:
https://github.com/GNS3/gns3-registry/tree/master/appliances

View File

@ -1,29 +1,27 @@
General
################
#######
Architecture
============
GNS3 is splitted in four part:
GNS3 can be divided in four part:
* the GUI (project gns3-gui, gns3-web)
* the controller (project gns3-server)
* the compute (project gns3-server)
* the emulators (qemu, iou, dynamips...)
* the user interface or GUI (gns3-gui or gns3-web projects)
* the controller (gns3-server project)
* the compute (part of the gns3-server project)
* the emulators (Qemu, Dynamips, VirtualBox...)
The controller pilot everything it's the part that manage the state
of a project, save it on disk. Only one controller exists.
The controller pilots everything, it manages the state
of each project. Only one controller should run.
The GUI displays a topology representing a project on a canvas and allow to
perform actions on given project, sending API requests to the controller.
The GUI display the topology. The GUI has only direct contact with
the controller.
The compute controls emulators to run nodes. A compute that is on
the same server as the controller is the same process.
The compute are where emulator are executed. If the compute is on
the same server as the controller, they are in the same process.
For each node of the topology will start an emulator instance.
The compute usually starts an emulator instance for each node.
A small schema::
@ -42,19 +40,18 @@ A small schema::
+--------+
If you want to pilot GNS3 you need to use the controller API.
Use the controller API to work with the GNS3 backend
Communications
===============
==============
All the communication are done over HTTP using JSON.
All communication are done over HTTP using the JSON format.
Errors
======
In case of error a standard HTTP error is raise and you got a
JSON like that
A standard HTTP error is sent in case of an error:
.. code-block:: json
@ -63,10 +60,6 @@ JSON like that
"message": "Conflict"
}
409 error could be display to the user. They are normal behavior
they are used to warn user about something he should change and
they are not an internal software error.
Limitations
============
@ -74,37 +67,34 @@ Limitations
Concurrency
------------
A node can't process multiple request in the same time. But you can make
multiple request on multiple node. It's transparent for the client
when the first request on a Node start a lock is acquire for this node id
and released for the next request at the end. You can safely send all
the requests in the same time and let the server manage an efficent concurrency.
We think it can be a little slower for some operations, but it's remove a big
complexity for the client due to the fact only some command on some node can be
concurrent.
A node cannot processes multiple requests at the same time. However,
multiple requests on multiple nodes can be executed concurrently.
This should be transparent for clients since internal locks are used inside the server,
so it is safe to send multiple requests at the same time and let the server
manage the concurrency.
Authentication
-----------------
--------------
You can use HTTP basic auth to protect the access to the API. And run
the API over HTTPS.
HTTP basic authentication can be used to prevent unauthorized API requests.
It is recommended to set up a VPN if the communication between clients and the server must be encrypted.
Notifications
=============
You can receive notification from the server if you listen the HTTP stream /notifications or the websocket.
Notifications can be received from the server by listening to a HTTP stream or via a Websocket.
Read :doc:`notifications` for more informations
Read :doc:`notifications` for more information
Previous versions
=================
API version 1
-------------
Shipped with GNS3 1.3, 1.4 and 1.5.
This API doesn't support the controller system and save used a commit system instead of live save.
Shipped with GNS3 1.3, 1.4 and 1.5.
This API doesn't support the controller architecture.

View File

@ -4,44 +4,41 @@ Glossary
Topology
--------
The place where you have all things (node, drawing, link...)
Contains everything to represent a virtual network (nodes, visual elements, links...)
Node
-----
----
A Virtual Machine (Dynamips, IOU, Qemu, VPCS...), a cloud, a builtin device (switch, hub...)
A Virtual Machine (Dynamips, IOU, Qemu, VPCS...) or builtin node (cloud, switch, hub...) that run on a compute.
Appliance
---------
A model for a node. When you drag an appliance to the topology a node is created.
A model for a node used to create a node. When you drag an appliance to the topology a node is created.
Appliance template
------------------
A file (.gns3a) use for creating new node model.
A file (.gns3a) used to create a new node.
Drawing
--------
-------
Drawing are visual element not used by the network emulation. Like
text, images, rectangle... They are pure SVG elements.
A Drawing is a visual element like annotations, images, rectangles etc. There are pure SVG elements.
Adapter
-------
The physical network interface. The adapter can contain multiple ports.
A physical network interface, like a PCI card. The adapter can contain multiple ports.
Port
----
A port is an opening on network adapter that cable plug into.
A port is an opening on a network adapter where can be plugged into.
For example a VM can have a serial and an ethernet adapter plugged in.
The ethernet adapter can have 4 ports.
For example a VM can have a serial and an Ethernet adapter.
The Ethernet adapter itself can have 4 ports.
Controller
----------
@ -50,20 +47,23 @@ The central server managing everything in GNS3. A GNS3 controller
will manage multiple GNS3 compute node.
Compute
----------
-------
The process running on each server with GNS3. The GNS3 compute node
is controlled by the GNS3 controller.
Symbol
------
Symbol are the icon used for nodes.
A symbol is an icon used to represent a node on a scene.
Scene
-----
The drawing area
A scene is the drawing area or canvas.
Filter
------
Packet filter this allow to add latency or packet drop.
Packet filter, for instance to add latency on a link or drop packets

View File

@ -2,17 +2,13 @@ Welcome to API documentation!
======================================
.. WARNING::
This documentation are for developers for user documentation go
to https://gns3.com/
The API is not stable, feel free to post comments on our website
https://gns3.com/
This documentation is intended for developers. The user documentation is
available on https://gns3.com/
This documentation cover the GNS3 API and ressources for GNS3 developers.
This documentation describe the GNS3 API and provide information for GNS3 developers.
If you want a quick demo on how to use the API read: :doc:`curl`
For a quick demo on how to use the API read: :doc:`curl`
API
----
@ -26,8 +22,8 @@ API
position
endpoints
GNS3 developements
------------------
GNS3 development
----------------
.. toctree::
development
file_format

View File

@ -1,17 +1,17 @@
Notifications
=============
You can receive notification from the controller allowing you to update your local data.
Notifications can be received from the controller, they can be used to update your local data.
Notifications endpoints
***********************
Notification endpoints
**********************
You can listen the HTTP stream /notifications or the websocket.
Listen to the HTTP stream endpoint or to the Websocket endpoint.
* :doc:`api/v2/controller/project/projectsprojectidnotifications`
* :doc:`api/v2/controller/project/projectsprojectidnotificationsws`
We recommend using the websocket.
It is recommended to use the Websocket endpoint.
Available notifications
***********************
@ -21,7 +21,7 @@ Available notifications
ping
----
Keep the connection between client and controller.
Keep-alive between client and controller. Also used to receive the current CPU and memory usage.
.. literalinclude:: api/notifications/ping.json
@ -29,7 +29,7 @@ Keep the connection between client and controller.
compute.created
----------------
Compute has been created.
A compute has been created.
.. literalinclude:: api/notifications/compute.created.json
@ -37,9 +37,7 @@ Compute has been created.
compute.updated
----------------
Compute has been updated. You will receive a lot of this
event because it's include change of CPU and memory usage
on the compute node.
A compute has been updated.
.. literalinclude:: api/notifications/compute.updated.json
@ -47,7 +45,7 @@ on the compute node.
compute.deleted
---------------
Compute has been deleted.
A compute has been deleted.
.. literalinclude:: api/notifications/compute.deleted.json
@ -55,7 +53,7 @@ Compute has been deleted.
node.created
------------
Node has been created.
A node has been created.
.. literalinclude:: api/notifications/node.created.json
@ -63,7 +61,7 @@ Node has been created.
node.updated
------------
Node has been updated.
A node has been updated.
.. literalinclude:: api/notifications/node.updated.json
@ -71,7 +69,7 @@ Node has been updated.
node.deleted
------------
Node has been deleted.
A node has been deleted.
.. literalinclude:: api/notifications/node.deleted.json
@ -79,8 +77,8 @@ Node has been deleted.
link.created
------------
Link has been created. Note that a link when created
is not yet connected to both part.
A link has been created. Note that a link is not connected
to any node when it is created.
.. literalinclude:: api/notifications/link.created.json
@ -88,7 +86,7 @@ is not yet connected to both part.
link.updated
------------
Link has been updated.
A link has been updated.
.. literalinclude:: api/notifications/link.updated.json
@ -96,7 +94,7 @@ Link has been updated.
link.deleted
------------
Link has been deleted.
A link has been deleted.
.. literalinclude:: api/notifications/link.deleted.json
@ -104,7 +102,7 @@ Link has been deleted.
drawing.created
---------------
Drawing has been created.
A drawing has been created.
.. literalinclude:: api/notifications/drawing.created.json
@ -112,8 +110,8 @@ Drawing has been created.
drawing.updated
---------------
Drawing has been updated. To reduce data transfert if the
svg field has not change the field is not included.
A drawing has been updated. The svg field is only included if it
has changed in order to reduce data transfer.
.. literalinclude:: api/notifications/drawing.updated.json
@ -121,7 +119,7 @@ svg field has not change the field is not included.
drawing.deleted
---------------
Drawing has been deleted.
A drawing has been deleted.
.. literalinclude:: api/notifications/drawing.deleted.json
@ -129,7 +127,7 @@ Drawing has been deleted.
project.updated
---------------
Project has been updated.
A project has been updated.
.. literalinclude:: api/notifications/project.updated.json
@ -137,7 +135,7 @@ Project has been updated.
project.closed
---------------
Project has been closed.
A project has been closed.
.. literalinclude:: api/notifications/project.closed.json
@ -145,14 +143,14 @@ Project has been closed.
snapshot.restored
--------------------------
Snapshot has been restored
A snapshot has been restored
.. literalinclude:: api/notifications/project.snapshot_restored.json
log.error
---------
Send an error to the user
Sends an error
.. literalinclude:: api/notifications/log.error.json
@ -160,7 +158,7 @@ Send an error to the user
log.warning
------------
Send a warning to the user
Sends a warning
.. literalinclude:: api/notifications/log.warning.json
@ -168,7 +166,7 @@ Send a warning to the user
log.info
---------
Send an information to the user
Sends an information
.. literalinclude:: api/notifications/log.info.json
@ -176,8 +174,6 @@ Send an information to the user
settings.updated
-----------------
GUI settings updated. Will be removed in a later release.
GUI settings have been updated. Will be removed in a later release.
.. literalinclude:: api/notifications/settings.updated.json

View File

@ -1,7 +1,7 @@
Positions
=========
In a the project object you have properties scene_height and scene_width this define the
size of the drawing area as px.
A project object contains the scene_height and scene_width properties. This defines the
size of the drawing area in px.
The position of the node are relative to this with 0,0 as center of the area.
The position of the nodes are relative with 0,0 as center of the area.

View File

@ -99,7 +99,7 @@ class Docker(BaseManager):
:param method: HTTP method
:param path: Endpoint in API
:param data: Dictionnary with the body. Will be transformed to a JSON
:param data: Dictionary with the body. Will be transformed to a JSON
:param params: Parameters added as a query arg
"""