From 07d2d7b340def36185edb2144847bbcf531e0499 Mon Sep 17 00:00:00 2001 From: grossmj Date: Wed, 31 Jan 2018 23:37:02 +0700 Subject: [PATCH] Update documentation. --- docs/curl.rst | 102 +++++++++++++------------- docs/development.rst | 11 +-- docs/endpoints.rst | 34 +++++---- docs/file_format.rst | 48 ++++++------ docs/general.rst | 70 ++++++++---------- docs/glossary.rst | 36 ++++----- docs/index.rst | 16 ++-- docs/notifications.rst | 58 +++++++-------- docs/position.rst | 6 +- gns3server/compute/docker/__init__.py | 2 +- 10 files changed, 184 insertions(+), 199 deletions(-) diff --git a/docs/curl.rst b/docs/curl.rst index 02cc2b04..a4acd4d6 100644 --- a/docs/curl.rst +++ b/docs/curl.rst @@ -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": ""}' -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. diff --git a/docs/development.rst b/docs/development.rst index a6fe5bb9..ec73a073 100644 --- a/docs/development.rst +++ b/docs/development.rst @@ -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 - diff --git a/docs/endpoints.rst b/docs/endpoints.rst index c8a2c596..a5e110ed 100644 --- a/docs/endpoints.rst +++ b/docs/endpoints.rst @@ -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: diff --git a/docs/file_format.rst b/docs/file_format.rst index d25b51ef..89a2e3ff 100644 --- a/docs/file_format.rst +++ b/docs/file_format.rst @@ -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 diff --git a/docs/general.rst b/docs/general.rst index 4bb1dd52..f5f34d80 100644 --- a/docs/general.rst +++ b/docs/general.rst @@ -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. diff --git a/docs/glossary.rst b/docs/glossary.rst index 9b25df9f..2260eb45 100644 --- a/docs/glossary.rst +++ b/docs/glossary.rst @@ -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 diff --git a/docs/index.rst b/docs/index.rst index c02cea54..dead8e53 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -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 diff --git a/docs/notifications.rst b/docs/notifications.rst index e0430723..13dc7878 100644 --- a/docs/notifications.rst +++ b/docs/notifications.rst @@ -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 - - diff --git a/docs/position.rst b/docs/position.rst index c3d6511d..dac20da6 100644 --- a/docs/position.rst +++ b/docs/position.rst @@ -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. diff --git a/gns3server/compute/docker/__init__.py b/gns3server/compute/docker/__init__.py index 539f98bc..d2fca166 100644 --- a/gns3server/compute/docker/__init__.py +++ b/gns3server/compute/docker/__init__.py @@ -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 """