mirror of
https://github.com/GNS3/gns3-server
synced 2024-12-25 16:28:11 +00:00
214 lines
6.2 KiB
ReStructuredText
214 lines
6.2 KiB
ReStructuredText
Communications
|
|
===============
|
|
|
|
All the communication are done over HTTP using JSON.
|
|
|
|
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"
|
|
}
|
|
|
|
Sample session using curl
|
|
=========================
|
|
|
|
.. warning::
|
|
|
|
Beware the output of this sample is truncated in order
|
|
to simplify the understanding. Please read the
|
|
documentation for the exact output.
|
|
|
|
You can check the server version with a simple curl command:
|
|
|
|
.. code-block:: shell-session
|
|
|
|
# curl "http://localhost:3080/v1/version"
|
|
{
|
|
"version": "1.3.dev1"
|
|
}
|
|
|
|
|
|
The next step is to create a project.
|
|
|
|
.. code-block:: shell-session
|
|
|
|
# curl -X POST "http://localhost:3080/v1/projects" -d '{"name": "test"}'
|
|
{
|
|
"project_id": "42f9feee-3217-4104-981e-85d5f0a806ec",
|
|
"temporary": false,
|
|
"name": "Test"
|
|
}
|
|
|
|
With this project id we can now create two VPCS VM.
|
|
|
|
.. code-block:: shell-session
|
|
|
|
# curl -X POST "http://localhost:3080/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/vpcs/vms" -d '{"name": "VPCS 1"}'
|
|
{
|
|
"console": 2000,
|
|
"name": "VPCS 1",
|
|
"project_id": "42f9feee-3217-4104-981e-85d5f0a806ec",
|
|
"vm_id": "24d2e16b-fbef-4259-ae34-7bc21a41ee28"
|
|
}%
|
|
|
|
# curl -X POST "http://localhost:3080/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/vpcs/vms" -d '{"name": "VPCS 2"}'
|
|
{
|
|
"console": 2001,
|
|
"name": "VPCS 2",
|
|
"vm_id": "daefc24a-103c-4717-8e01-6517d931c1ae"
|
|
}
|
|
|
|
Now we need to link the two VPCS. The first step is to allocate on the remote servers
|
|
two UDP ports.
|
|
|
|
.. code-block:: shell-session
|
|
|
|
# curl -X POST "http://localhost:3080/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/ports/udp" -d '{}'
|
|
{
|
|
"udp_port": 10000
|
|
}
|
|
|
|
# curl -X POST "http://localhost:3080/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/ports/udp" -d '{}'
|
|
{
|
|
"udp_port": 10001
|
|
}
|
|
|
|
|
|
We can create the bidirectionnal communication between the two VPCS. The
|
|
communication is made by creating two UDP tunnels.
|
|
|
|
.. code-block:: shell-session
|
|
|
|
# curl -X POST "http://localhost:3080/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/vpcs/vms/24d2e16b-fbef-4259-ae34-7bc21a41ee28/adapters/0/ports/0/nio" -d '{"lport": 10000, "rhost": "127.0.0.1", "rport": 10001, "type": "nio_udp"}'
|
|
{
|
|
"lport": 10000,
|
|
"rhost": "127.0.0.1",
|
|
"rport": 10001,
|
|
"type": "nio_udp"
|
|
}
|
|
|
|
# curl -X POST "http://localhost:3080/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/vpcs/vms/daefc24a-103c-4717-8e01-6517d931c1ae/adapters/0/ports/0/nio" -d '{"lport": 10001, "rhost": "127.0.0.1", "rport": 10000, "type": "nio_udp"}'
|
|
{
|
|
"lport": 10001,
|
|
"rhost": "127.0.0.1",
|
|
"rport": 10000,
|
|
"type": "nio_udp"
|
|
}
|
|
|
|
Now we can start the two VM
|
|
|
|
.. code-block:: shell-session
|
|
|
|
# curl -X POST "http://localhost:3080/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/vpcs/vms/24d2e16b-fbef-4259-ae34-7bc21a41ee28/start" -d "{}"
|
|
# curl -X POST "http://localhost:3080/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/vpcs/vms/daefc24a-103c-4717-8e01-6517d931c1ae/start" -d '{}'
|
|
|
|
Everything should be started now. You can connect via telnet to the different VM.
|
|
The port is the field console in the create VM request.
|
|
|
|
.. code-block:: shell-session
|
|
|
|
# telnet 127.0.0.1 2000
|
|
Trying 127.0.0.1...
|
|
Connected to localhost.
|
|
Escape character is '^]'.
|
|
|
|
Welcome to Virtual PC Simulator, version 0.6
|
|
Dedicated to Daling.
|
|
Build time: Dec 29 2014 12:51:46
|
|
Copyright (c) 2007-2014, Paul Meng (mirnshi@gmail.com)
|
|
All rights reserved.
|
|
|
|
VPCS is free software, distributed under the terms of the "BSD" licence.
|
|
Source code and license can be found at vpcs.sf.net.
|
|
For more information, please visit wiki.freecode.com.cn.
|
|
|
|
Press '?' to get help.
|
|
|
|
VPCS> ip 192.168.1.1
|
|
Checking for duplicate address...
|
|
PC1 : 192.168.1.1 255.255.255.0
|
|
|
|
VPCS> disconnect
|
|
|
|
Good-bye
|
|
Connection closed by foreign host.
|
|
|
|
# telnet 127.0.0.1 2001
|
|
telnet 127.0.0.1 2001
|
|
Trying 127.0.0.1...
|
|
Connected to localhost.
|
|
Escape character is '^]'.
|
|
|
|
Welcome to Virtual PC Simulator, version 0.6
|
|
Dedicated to Daling.
|
|
Build time: Dec 29 2014 12:51:46
|
|
Copyright (c) 2007-2014, Paul Meng (mirnshi@gmail.com)
|
|
All rights reserved.
|
|
|
|
VPCS is free software, distributed under the terms of the "BSD" licence.
|
|
Source code and license can be found at vpcs.sf.net.
|
|
For more information, please visit wiki.freecode.com.cn.
|
|
|
|
Press '?' to get help.
|
|
|
|
VPCS> ip 192.168.1.2
|
|
Checking for duplicate address...
|
|
PC1 : 192.168.1.2 255.255.255.0
|
|
|
|
VPCS> ping 192.168.1.1
|
|
84 bytes from 192.168.1.1 icmp_seq=1 ttl=64 time=0.179 ms
|
|
84 bytes from 192.168.1.1 icmp_seq=2 ttl=64 time=0.218 ms
|
|
84 bytes from 192.168.1.1 icmp_seq=3 ttl=64 time=0.190 ms
|
|
84 bytes from 192.168.1.1 icmp_seq=4 ttl=64 time=0.198 ms
|
|
84 bytes from 192.168.1.1 icmp_seq=5 ttl=64 time=0.185 ms
|
|
|
|
VPCS> disconnect
|
|
Good-bye
|
|
Connection closed by foreign host.
|
|
|
|
Limitations
|
|
============
|
|
|
|
Concurrency
|
|
------------
|
|
|
|
A VM can't process multiple request in the same time. But you can make
|
|
multiple request on multiple VM. It's transparent for the client
|
|
when the first request on a VM start a lock is acquire for this VM 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 VM can be
|
|
concurrent.
|
|
|
|
|
|
Authentication
|
|
-----------------
|
|
|
|
In this version of the API you have no authentification system. If you
|
|
listen on your network interface instead of localhost be carefull. Due
|
|
to the nature of the multiple supported VM it's easy for an user to
|
|
upload and run code on your machine.
|
|
|
|
|
|
Notifications
|
|
=============
|
|
|
|
You can receive notification from the server if you listen the HTTP stream /notifications.
|
|
|
|
The available notification are:
|
|
* ping
|
|
* vm.created
|
|
* vm.started
|
|
* vm.stopped
|
|
* log.error
|
|
|