GNS3 Documentation

Release 1.5.0dev1

GNS3 Team

December 22, 2015

 Contents

1 Communications 3

2 Errors 5

3 Sample session using curl 7

4 Limitations 11
4.1 Concurrency . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11
4.2 Authentification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11

5 Notifications 13

6 Glossary 15
6.1 VM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6.2 Adapter . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15
6.3 Port . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15

7 Development 17
7.1 Code convention . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
7.2 Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
7.3 Tests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17

8 API Endpoints 19
8.1 Config . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 19
8.2 Docker . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
8.3 Dynamips device . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
8.4 Dynamips vm . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32
8.5 File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
8.6 Iou . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
8.7 Network . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
8.8 Project . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 64
8.9 Qemu . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 73
8.10 Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
8.11 Version . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 89
8.12 Virtualbox . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 91
8.13 Vmware . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 104
8.14 Vpcs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 113

i
ii
 GNS3 Documentation, Release 1.5.0dev1

Warning: The API is not stable, feel free to post comments on our website https://gns3.com/

Contents 1
GNS3 Documentation, Release 1.5.0dev1

2 Contents
 CHAPTER 1

Communications

All the communication are done over HTTP using JSON.

3
GNS3 Documentation, Release 1.5.0dev1

4 Chapter 1. Communications
 CHAPTER 2

Errors

In case of error a standard HTTP error is raise and you got a JSON like that
{
"status": 409,
"message": "Conflict"
}

5
GNS3 Documentation, Release 1.5.0dev1

6 Chapter 2. Errors
 CHAPTER 3

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:
# curl "http://localhost:8000/v1/version"
{
"version": "1.3.dev1"
}

The next step is to create a project.

# curl -X POST "http://localhost:8000/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.

# curl -X POST "http://localhost:8000/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/vpcs/vms" -d '
{
"console": 2000,
"name": "VPCS 1",
"project_id": "42f9feee-3217-4104-981e-85d5f0a806ec",
"vm_id": "24d2e16b-fbef-4259-ae34-7bc21a41ee28"
}%

# curl -X POST "http://localhost:8000/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/vpcs/vms" -d '

{
"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.
# curl -X POST "http://localhost:8000/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/ports/udp" -d
{
"udp_port": 10000
}

7
GNS3 Documentation, Release 1.5.0dev1

# curl -X POST "http://localhost:8000/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.
# curl -X POST "http://localhost:8000/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/vpcs/vms/24d2e
{
"lport": 10000,
"rhost": "127.0.0.1",
"rport": 10001,
"type": "nio_udp"
}

# curl -X POST "http://localhost:8000/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/vpcs/vms/daefc

{
"lport": 10001,
"rhost": "127.0.0.1",
"rport": 10000,
"type": "nio_udp"
}

Now we can start the two VM

# curl -X POST "http://localhost:8000/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/vpcs/vms/24d2e
# curl -X POST "http://localhost:8000/v1/projects/42f9feee-3217-4104-981e-85d5f0a806ec/vpcs/vms/daefc

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.
# 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 ([email protected])
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

8 Chapter 3. Sample session using curl

 GNS3 Documentation, Release 1.5.0dev1

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 ([email protected])
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.

9
GNS3 Documentation, Release 1.5.0dev1

10 Chapter 3. Sample session using curl

 CHAPTER 4

Limitations

4.1 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.

4.2 Authentification

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.

11
GNS3 Documentation, Release 1.5.0dev1

12 Chapter 4. Limitations
 CHAPTER 5

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

13
GNS3 Documentation, Release 1.5.0dev1

14 Chapter 5. Notifications
 CHAPTER 6

Glossary

6.1 VM

A Virtual Machine (Dynamips, IOU, Qemu, VPCS...)

6.2 Adapter

The physical network interface. The adapter can contain multiple ports.

6.3 Port

A port is an opening on network adapter that cable plug into.

For example a VM can have a serial and an ethernet adapter plugged in. The ethernet adapter can have 4 ports.

15
GNS3 Documentation, Release 1.5.0dev1

16 Chapter 6. Glossary
 CHAPTER 7

Development

7.1 Code convention

You should respect all the PEP8 convention except the rule about max line length.

7.2 Documentation

7.2.1 Build doc

In the project root folder:

./scripts/documentation.sh

The output is available inside docs/_build/html

7.3 Tests

7.3.1 Run tests

py.test -v

17
GNS3 Documentation, Release 1.5.0dev1

18 Chapter 7. Development
 CHAPTER 8

API Endpoints

8.1 Config

8.1.1 /v1/config/reload

Contents
• /v1/config/reload
– POST /v1/config/reload
* Response status codes
* Sample session

POST /v1/config/reload

Check if version is the same as the server

Response status codes

• 201: Config reload

• 403: Config reload refused

Sample session

curl -i -X POST 'http://localhost:8000/v1/config/reload' -d '{}'

POST /v1/config/reload HTTP/1.1

{}

HTTP/1.1 201
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT

19
GNS3 Documentation, Release 1.5.0dev1

SERVER: Python/3.4 GNS3/1.4.0.dev9

X-ROUTE: /v1/config/reload

8.2 Docker

8.2.1 /v1/docker/images

Contents
• /v1/docker/images
– GET /v1/docker/images
* Response status codes

GET /v1/docker/images

Get all available Docker images

Response status codes

• 200: Success

8.2.2 /v1/projects/{project_id}/docker/images

Contents
• /v1/projects/{project_id}/docker/images
– POST /v1/projects/{project_id}/docker/images
* Parameters
* Response status codes
* Input
* Output

POST /v1/projects/{project_id}/docker/images

Create a new Docker container

Parameters

• project_id: UUID for the project

20 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Response status codes

• 400: Invalid request

• 201: Instance created
• 409: Conflict

Input

Output

8.2.3 /v1/projects/{project_id}/docker/images/{id}

Contents
• /v1/projects/{project_id}/docker/images/{id}
– DELETE /v1/projects/{project_id}/docker/images/{id}
* Parameters
* Response status codes

DELETE /v1/projects/{project_id}/docker/images/{id}

Delete a Docker container

Parameters

• id: ID for the container

• project_id: UUID for the project

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance deleted

8.2.4 /v1/projects/{project_id}/docker/images/{id}/adapters/{adapter_number:d+}/ports/{port_nu

8.2. Docker 21
GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/docker/images/{id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio
– POST /v1/projects/{project_id}/docker/images/{id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio
* Parameters
* Response status codes
– DELETE /v1/projects/{project_id}/docker/images/{id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio
* Parameters
* Response status codes

POST /v1/projects/{project_id}/docker/images/{id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio

Add a NIO to a Docker container

Parameters

• adapter_number: Adapter where the nio should be added

• id: ID of the container
• project_id: UUID for the project
• port_number: Port on the adapter

Response status codes

• 400: Invalid request

• 201: NIO created
• 404: Instance doesn’t exist

DELETE /v1/projects/{project_id}/docker/images/{id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio

Remove a NIO from a Docker container

Parameters

• adapter_number: Adapter where the nio should be added

• id: ID of the container
• project_id: UUID for the project
• port_number: Port on the adapter

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: NIO deleted

22 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

8.2.5 /v1/projects/{project_id}/docker/images/{id}/reload

Contents
• /v1/projects/{project_id}/docker/images/{id}/reload
– POST /v1/projects/{project_id}/docker/images/{id}/reload
* Parameters
* Response status codes
* Input
* Output

POST /v1/projects/{project_id}/docker/images/{id}/reload

Restart a Docker container

Parameters

• id: ID of the container

• project_id: UUID of the project

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance restarted

Input

Output

8.2.6 /v1/projects/{project_id}/docker/images/{id}/start

Contents
• /v1/projects/{project_id}/docker/images/{id}/start
– POST /v1/projects/{project_id}/docker/images/{id}/start
* Parameters
* Response status codes
* Input
* Output

POST /v1/projects/{project_id}/docker/images/{id}/start

Start a Docker container

8.2. Docker 23
GNS3 Documentation, Release 1.5.0dev1

Parameters

• id: ID of the container

• project_id: UUID of the project

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance started

Input

Output

8.2.7 /v1/projects/{project_id}/docker/images/{id}/stop

Contents
• /v1/projects/{project_id}/docker/images/{id}/stop
– POST /v1/projects/{project_id}/docker/images/{id}/stop
* Parameters
* Response status codes
* Input
* Output

POST /v1/projects/{project_id}/docker/images/{id}/stop

Stop a Docker container

Parameters

• id: ID of the container

• project_id: UUID of the project

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance stopped

24 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Input

Output

8.2.8 /v1/projects/{project_id}/docker/images/{id}/suspend

Contents
• /v1/projects/{project_id}/docker/images/{id}/suspend
– POST /v1/projects/{project_id}/docker/images/{id}/suspend
* Parameters
* Response status codes
* Input
* Output

POST /v1/projects/{project_id}/docker/images/{id}/suspend

Pause a Docker container

Parameters

• id: ID of the container

• project_id: UUID of the project

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance paused

Input

Output

8.3 Dynamips device

8.3.1 /v1/projects/{project_id}/dynamips/devices

8.3. Dynamips device 25

GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/dynamips/devices
– POST /v1/projects/{project_id}/dynamips/devices
* Parameters
* Response status codes
* Input
* Output

POST /v1/projects/{project_id}/dynamips/devices

Create a new Dynamips device instance

Parameters

• project_id: UUID for the project

Response status codes

• 400: Invalid request

• 201: Instance created
• 409: Conflict

Input

Output

8.3.2 /v1/projects/{project_id}/dynamips/devices/{device_id}

26 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/dynamips/devices/{device_id}
– GET /v1/projects/{project_id}/dynamips/devices/{device_id}
* Parameters
* Response status codes
* Output
– PUT /v1/projects/{project_id}/dynamips/devices/{device_id}
* Parameters
* Response status codes
* Input
· Types
· EthernetSwitchPort
· Body
* Output
– DELETE /v1/projects/{project_id}/dynamips/devices/{device_id}
* Parameters
* Response status codes

GET /v1/projects/{project_id}/dynamips/devices/{device_id}

Get a Dynamips device instance

Parameters

• device_id: UUID for the instance

• project_id: UUID for the project

Response status codes

• 200: Success
• 400: Invalid request
• 404: Instance doesn’t exist

Output

PUT /v1/projects/{project_id}/dynamips/devices/{device_id}

Update a Dynamips device instance

Parameters

• device_id: UUID for the instance

• project_id: UUID for the project

8.3. Dynamips device 27

GNS3 Documentation, Release 1.5.0dev1

Response status codes

• 200: Instance updated

• 400: Invalid request
• 404: Instance doesn’t exist
• 409: Conflict

Input

Types

EthernetSwitchPort Ethernet switch port

Body

Output

DELETE /v1/projects/{project_id}/dynamips/devices/{device_id}

Delete a Dynamips device instance

Parameters

• device_id: UUID for the instance

• project_id: UUID for the project

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance deleted

8.3.3 /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/nio

28 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/nio
– POST /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/nio
* Parameters
* Response status codes
* Input
· Types
· Ethernet
· LinuxEthernet
· NAT
· NULL
· TAP
· UDP
· UNIX
· VDE
· Body
– DELETE /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/nio
* Parameters
* Response status codes

POST /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/nio

Add a NIO to a Dynamips device instance

Parameters

• device_id: UUID for the instance

• project_id: UUID for the project
• port_number: Port on the device

Response status codes

• 400: Invalid request

• 201: NIO created
• 404: Instance doesn’t exist

Input

Types

Ethernet Generic Ethernet Network Input/Output

LinuxEthernet Linux Ethernet Network Input/Output

8.3. Dynamips device 29

GNS3 Documentation, Release 1.5.0dev1

NAT NAT Network Input/Output

NULL NULL Network Input/Output

TAP TAP Network Input/Output

UDP UDP Network Input/Output

UNIX UNIX Network Input/Output

VDE VDE Network Input/Output

Body

DELETE /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/nio

Remove a NIO from a Dynamips device instance

Parameters

• device_id: UUID for the instance

• project_id: UUID for the project
• port_number: Port on the device

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: NIO deleted

8.3.4 /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/start_capt

Contents
• /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/start_capture
– POST /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/start_capture
* Parameters
* Response status codes
* Input

POST /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/start_capture

Start a packet capture on a Dynamips device instance

30 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Parameters

• device_id: UUID for the instance

• project_id: UUID for the project
• port_number: Port on the device

Response status codes

• 200: Capture started

• 400: Invalid request
• 404: Instance doesn’t exist

Input

8.3.5 /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/stop_captu

Contents
• /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/stop_capture
– POST /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/stop_capture
* Parameters
* Response status codes

POST /v1/projects/{project_id}/dynamips/devices/{device_id}/ports/{port_number:d+}/stop_capture

Stop a packet capture on a Dynamips device instance

Parameters

• device_id: UUID for the instance

• project_id: UUID for the project
• port_number: Port on the device

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Capture stopped

8.3. Dynamips device 31

GNS3 Documentation, Release 1.5.0dev1

8.4 Dynamips vm

8.4.1 /v1/dynamips/vms

Contents
• /v1/dynamips/vms
– GET /v1/dynamips/vms
* Response status codes

GET /v1/dynamips/vms

Retrieve the list of Dynamips VMS

Response status codes

• 200: List of Dynamips VM retrieved

8.4.2 /v1/dynamips/vms/{path}

Contents
• /v1/dynamips/vms/{path}
– POST /v1/dynamips/vms/{path}
* Response status codes

POST /v1/dynamips/vms/{path}

Upload Dynamips image.

Response status codes

• 204: Image uploaded

8.4.3 /v1/projects/{project_id}/dynamips/vms

Contents
• /v1/projects/{project_id}/dynamips/vms
– POST /v1/projects/{project_id}/dynamips/vms
* Parameters
* Response status codes
* Input
* Output

32 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

POST /v1/projects/{project_id}/dynamips/vms

Create a new Dynamips VM instance

Parameters

• project_id: UUID for the project

Response status codes

• 400: Invalid request

• 201: Instance created
• 409: Conflict

Input

Output

8.4.4 /v1/projects/{project_id}/dynamips/vms/{vm_id}

Contents
• /v1/projects/{project_id}/dynamips/vms/{vm_id}
– GET /v1/projects/{project_id}/dynamips/vms/{vm_id}
* Parameters
* Response status codes
* Output
– PUT /v1/projects/{project_id}/dynamips/vms/{vm_id}
* Parameters
* Response status codes
* Input
* Output
– DELETE /v1/projects/{project_id}/dynamips/vms/{vm_id}
* Parameters
* Response status codes

GET /v1/projects/{project_id}/dynamips/vms/{vm_id}

Get a Dynamips VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

8.4. Dynamips vm 33
GNS3 Documentation, Release 1.5.0dev1

Response status codes

• 200: Success
• 400: Invalid request
• 404: Instance doesn’t exist

Output

PUT /v1/projects/{project_id}/dynamips/vms/{vm_id}

Update a Dynamips VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 200: Instance updated

• 400: Invalid request
• 404: Instance doesn’t exist
• 409: Conflict

Input

Output

DELETE /v1/projects/{project_id}/dynamips/vms/{vm_id}

Delete a Dynamips VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance deleted

34 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

8.4.5 /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port

Contents
• /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio
– POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio
* Parameters
* Response status codes
– DELETE /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio
* Parameters
* Response status codes

POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio

Add a NIO to a Dynamips VM instance

Parameters

• adapter_number: Adapter where the nio should be added

• project_id: UUID for the project
• port_number: Port on the adapter
• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 201: NIO created
• 404: Instance doesn’t exist

DELETE /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/ni

Remove a NIO from a Dynamips VM instance

Parameters

• adapter_number: Adapter from where the nio should be removed

• project_id: UUID for the project
• port_number: Port on the adapter
• vm_id: UUID for the instance

8.4. Dynamips vm 35
GNS3 Documentation, Release 1.5.0dev1

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: NIO deleted

8.4.6 /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port

Contents
• /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/start_capture
– POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/start_capt
* Parameters
* Response status codes
* Input

POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/start

Start a packet capture on a Dynamips VM instance

Parameters

• adapter_number: Adapter to start a packet capture

• project_id: UUID for the project
• port_number: Port on the adapter
• vm_id: UUID for the instance

Response status codes

• 200: Capture started

• 400: Invalid request
• 404: Instance doesn’t exist

Input

8.4.7 /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port

Contents
• /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/stop_capture
– POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/stop_capt
* Parameters
* Response status codes

36 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/stop

Stop a packet capture on a Dynamips VM instance

Parameters

• adapter_number: Adapter to stop a packet capture

• project_id: UUID for the project
• port_number: Port on the adapter (always 0)
• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Capture stopped

8.4.8 /v1/projects/{project_id}/dynamips/vms/{vm_id}/auto_idlepc

Contents
• /v1/projects/{project_id}/dynamips/vms/{vm_id}/auto_idlepc
– GET /v1/projects/{project_id}/dynamips/vms/{vm_id}/auto_idlepc
* Response status codes

GET /v1/projects/{project_id}/dynamips/vms/{vm_id}/auto_idlepc

Retrieve the idlepc proposals

Response status codes

• 200: Best Idle-pc value found

• 400: Invalid request
• 404: Instance doesn’t exist

8.4.9 /v1/projects/{project_id}/dynamips/vms/{vm_id}/configs

8.4. Dynamips vm 37
GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/dynamips/vms/{vm_id}/configs
– GET /v1/projects/{project_id}/dynamips/vms/{vm_id}/configs
* Response status codes
* Output

GET /v1/projects/{project_id}/dynamips/vms/{vm_id}/configs

Retrieve the startup and private configs content

Response status codes

• 200: Configs retrieved

• 400: Invalid request
• 404: Instance doesn’t exist

Output

8.4.10 /v1/projects/{project_id}/dynamips/vms/{vm_id}/configs/save

Contents
• /v1/projects/{project_id}/dynamips/vms/{vm_id}/configs/save
– POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/configs/save
* Response status codes

POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/configs/save

Save the startup and private configs content

Response status codes

• 200: Configs saved

• 400: Invalid request
• 404: Instance doesn’t exist

8.4.11 /v1/projects/{project_id}/dynamips/vms/{vm_id}/idlepc_proposals

38 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/dynamips/vms/{vm_id}/idlepc_proposals
– GET /v1/projects/{project_id}/dynamips/vms/{vm_id}/idlepc_proposals
* Response status codes

GET /v1/projects/{project_id}/dynamips/vms/{vm_id}/idlepc_proposals

Retrieve the idlepc proposals

Response status codes

• 200: Idle-PCs retrieved

• 400: Invalid request
• 404: Instance doesn’t exist

8.4.12 /v1/projects/{project_id}/dynamips/vms/{vm_id}/reload

Contents
• /v1/projects/{project_id}/dynamips/vms/{vm_id}/reload
– POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/reload
* Parameters
* Response status codes

POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/reload

Reload a Dynamips VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance reloaded

8.4. Dynamips vm 39
GNS3 Documentation, Release 1.5.0dev1

8.4.13 /v1/projects/{project_id}/dynamips/vms/{vm_id}/resume

Contents
• /v1/projects/{project_id}/dynamips/vms/{vm_id}/resume
– POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/resume
* Parameters
* Response status codes

POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/resume

Resume a suspended Dynamips VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance resumed

8.4.14 /v1/projects/{project_id}/dynamips/vms/{vm_id}/start

Contents
• /v1/projects/{project_id}/dynamips/vms/{vm_id}/start
– POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/start
* Parameters
* Response status codes

POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/start

Start a Dynamips VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

40 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance started

8.4.15 /v1/projects/{project_id}/dynamips/vms/{vm_id}/stop

Contents
• /v1/projects/{project_id}/dynamips/vms/{vm_id}/stop
– POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/stop
* Parameters
* Response status codes

POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/stop

Stop a Dynamips VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance stopped

8.4.16 /v1/projects/{project_id}/dynamips/vms/{vm_id}/suspend

Contents
• /v1/projects/{project_id}/dynamips/vms/{vm_id}/suspend
– POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/suspend
* Parameters
* Response status codes

POST /v1/projects/{project_id}/dynamips/vms/{vm_id}/suspend

Suspend a Dynamips VM instance

8.4. Dynamips vm 41
GNS3 Documentation, Release 1.5.0dev1

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance suspended

8.5 File

8.5.1 /v1/files/stream

Contents
• /v1/files/stream
– GET /v1/files/stream
* Response status codes
* Input

GET /v1/files/stream

Stream a file from the server

Response status codes

• 200: File retrieved

• 409: Can’t access to file
• 404: File doesn’t exist

Input

8.6 Iou

8.6.1 /v1/iou/vms

42 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/iou/vms
– GET /v1/iou/vms
* Response status codes
* Sample session

GET /v1/iou/vms

Retrieve the list of IOU VMS

Response status codes

• 200: List of IOU VM retrieved

Sample session

curl -i -X GET 'http://localhost:8000/v1/iou/vms'

GET /v1/iou/vms HTTP/1.1

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 72
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/iou/vms

[
{
"filename": "iou.bin",
"path": "iou.bin"
}
]

8.6.2 /v1/iou/vms/{path}

Contents
• /v1/iou/vms/{path}
– POST /v1/iou/vms/{path}
* Response status codes

8.6. Iou 43
GNS3 Documentation, Release 1.5.0dev1

POST /v1/iou/vms/{path}

Upload IOU image.

Response status codes

• 204: Image uploaded

8.6.3 /v1/projects/{project_id}/iou/vms

Contents
• /v1/projects/{project_id}/iou/vms
– POST /v1/projects/{project_id}/iou/vms
* Parameters
* Response status codes
* Input
* Output
* Sample session

POST /v1/projects/{project_id}/iou/vms

Create a new IOU instance

Parameters

• project_id: UUID for the project

Response status codes

• 400: Invalid request

• 201: Instance created
• 409: Conflict

Input

Output

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms' -d '

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms HTTP/1.1

{
"name": "PC TEST 1",
"path": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-54/test_iou_create_start

44 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

"startup_config_content": "hostname test",

"vm_id": "57ca3a20-ffd9-4b99-b35c-038552374f05"
}

HTTP/1.1 201
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 755
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/iou/vms

{
"console": 2000,
"ethernet_adapters": 2,
"iourc_path": null,
"l1_keepalives": false,
"md5sum": "e573e8f5c93c6c00783f20c7a170aa6c",
"name": "PC TEST 1",
"nvram": 128,
"path": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-54/test_iou_create_start
"private_config": null,
"project_id": "a1e920ca-338a-4e9f-b363-aa607b09dd80",
"ram": 256,
"serial_adapters": 2,
"startup_config": "startup-config.cfg",
"use_default_iou_values": true,
"vm_directory": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmph6drru9t/a1e920ca-338a-4e9f-
"vm_id": "57ca3a20-ffd9-4b99-b35c-038552374f05"
}

8.6.4 /v1/projects/{project_id}/iou/vms/{vm_id}

Contents
• /v1/projects/{project_id}/iou/vms/{vm_id}
– GET /v1/projects/{project_id}/iou/vms/{vm_id}
* Parameters
* Response status codes
* Output
* Sample session
– PUT /v1/projects/{project_id}/iou/vms/{vm_id}
* Parameters
* Response status codes
* Input
* Output
* Sample session
– DELETE /v1/projects/{project_id}/iou/vms/{vm_id}
* Parameters
* Response status codes
* Sample session

8.6. Iou 45
GNS3 Documentation, Release 1.5.0dev1

GET /v1/projects/{project_id}/iou/vms/{vm_id}

Get a IOU instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 200: Success
• 400: Invalid request
• 404: Instance doesn’t exist

Output

Sample session

curl -i -X GET 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/1c8011

GET /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/1c801186-7a6d-4e92-9a10-9d61e8bdc25a HT

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 721
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/iou/vms/{vm_id}

{
"console": 2000,
"ethernet_adapters": 2,
"iourc_path": null,
"l1_keepalives": false,
"md5sum": "e573e8f5c93c6c00783f20c7a170aa6c",
"name": "PC TEST 1",
"nvram": 128,
"path": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-54/test_iou_get0/iou.bin
"private_config": null,
"project_id": "a1e920ca-338a-4e9f-b363-aa607b09dd80",
"ram": 256,
"serial_adapters": 2,
"startup_config": null,
"use_default_iou_values": true,
"vm_directory": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmph6drru9t/a1e920ca-338a-4e9f-
"vm_id": "1c801186-7a6d-4e92-9a10-9d61e8bdc25a"
}

46 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

PUT /v1/projects/{project_id}/iou/vms/{vm_id}

Update a IOU instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 200: Instance updated

• 400: Invalid request
• 404: Instance doesn’t exist
• 409: Conflict

Input

Output

Sample session

curl -i -X PUT 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/790ce5

PUT /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/790ce54d-8d28-4e33-9a5a-27cae20fc0f2 HT
{
"console": 2001,
"ethernet_adapters": 4,
"iourc_content": "test",
"l1_keepalives": true,
"name": "test",
"nvram": 2048,
"ram": 512,
"serial_adapters": 0,
"startup_config_content": "hostname test",
"use_default_iou_values": true
}

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 799
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/iou/vms/{vm_id}

{
"console": 2001,
"ethernet_adapters": 4,

8.6. Iou 47
GNS3 Documentation, Release 1.5.0dev1

"iourc_path": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmpcnfdf4ax/iourc",
"l1_keepalives": true,
"md5sum": "e573e8f5c93c6c00783f20c7a170aa6c",
"name": "test",
"nvram": 2048,
"path": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-54/test_iou_update0/iou.
"private_config": null,
"project_id": "a1e920ca-338a-4e9f-b363-aa607b09dd80",
"ram": 512,
"serial_adapters": 0,
"startup_config": "startup-config.cfg",
"use_default_iou_values": true,
"vm_directory": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmph6drru9t/a1e920ca-338a-4e9f-
"vm_id": "790ce54d-8d28-4e33-9a5a-27cae20fc0f2"
}

DELETE /v1/projects/{project_id}/iou/vms/{vm_id}

Delete a IOU instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance deleted

Sample session

curl -i -X DELETE 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/468

DELETE /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/468f944e-e195-4a5d-b192-8c954f46d028

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/iou/vms/{vm_id}

8.6.5 /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_numb

48 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio
– POST /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio
* Parameters
* Response status codes
* Sample session
– DELETE /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio
* Parameters
* Response status codes
* Sample session

POST /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio

Add a NIO to a IOU instance

Parameters

• adapter_number: Network adapter where the nio is located

• project_id: UUID for the project
• port_number: Port where the nio should be added
• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 201: NIO created
• 404: Instance doesn’t exist

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/3ae4c

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/3ae4cab0-1bd0-4382-9192-5b78868d1626/a
{
"ethernet_device": "lo0",
"type": "nio_generic_ethernet"
}

HTTP/1.1 201
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 68
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9

8.6. Iou 49
GNS3 Documentation, Release 1.5.0dev1

X-ROUTE: /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:\d+}/ports/{port_number:\

{
"ethernet_device": "lo0",
"type": "nio_generic_ethernet"
}

DELETE /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio

Remove a NIO from a IOU instance

Parameters

• adapter_number: Network adapter where the nio is located

• project_id: UUID for the project
• port_number: Port from where the nio should be removed
• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: NIO deleted

Sample session

curl -i -X DELETE 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/85c

DELETE /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/85c30dd1-bb4f-4826-aa67-74574ffc400a

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:\d+}/ports/{port_number:\

8.6.6 /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_numb

50 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/start_capture
– POST /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/start_capture
* Parameters
* Response status codes
* Input
* Sample session

POST /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/start_captu

Start a packet capture on a IOU VM instance

Parameters

• adapter_number: Adapter to start a packet capture

• project_id: UUID for the project
• port_number: Port on the adapter
• vm_id: UUID for the instance

Response status codes

• 200: Capture started

• 400: Invalid request
• 404: Instance doesn’t exist
• 409: VM not started

Input

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/98a1f

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/98a1fa54-ff5e-4119-85a5-20a7b5fdac31/a
{
"capture_file_name": "test.pcap",
"data_link_type": "DLT_EN10MB"
}

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 158
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9

8.6. Iou 51
GNS3 Documentation, Release 1.5.0dev1

X-ROUTE: /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:\d+}/ports/{port_number:\

{
"pcap_file_path": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmph6drru9t/a1e920ca-338a-4e9
}

8.6.7 /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_numb

Contents
• /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/stop_capture
– POST /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/stop_capture
* Parameters
* Response status codes
* Sample session

POST /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/stop_captu

Stop a packet capture on a IOU VM instance

Parameters

• adapter_number: Adapter to stop a packet capture

• project_id: UUID for the project
• port_number: Port on the adapter (always 0)
• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Capture stopped
• 409: VM not started

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/68c9d

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/68c9da1c-6960-4c6e-aea1-e4f76e313341/a
{}

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive

52 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/iou/vms/{vm_id}/adapters/{adapter_number:\d+}/ports/{port_number:\

8.6.8 /v1/projects/{project_id}/iou/vms/{vm_id}/configs

Contents
• /v1/projects/{project_id}/iou/vms/{vm_id}/configs
– GET /v1/projects/{project_id}/iou/vms/{vm_id}/configs
* Response status codes
* Output
* Sample session

GET /v1/projects/{project_id}/iou/vms/{vm_id}/configs

Retrieve the startup and private configs content

Response status codes

• 200: Configs retrieved

• 400: Invalid request
• 404: Instance doesn’t exist

Output

Sample session

curl -i -X GET 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/46c8a3

GET /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/46c8a3b3-12a2-42ff-9542-0d9e43dea734/co

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 40
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/iou/vms/{vm_id}/configs

{
"startup_config_content": "TEST"
}

8.6. Iou 53
GNS3 Documentation, Release 1.5.0dev1

8.6.9 /v1/projects/{project_id}/iou/vms/{vm_id}/configs/save

Contents
• /v1/projects/{project_id}/iou/vms/{vm_id}/configs/save
– POST /v1/projects/{project_id}/iou/vms/{vm_id}/configs/save
* Response status codes

POST /v1/projects/{project_id}/iou/vms/{vm_id}/configs/save

Save the startup and private configs content

Response status codes

• 200: Configs saved

• 400: Invalid request
• 404: Instance doesn’t exist

8.6.10 /v1/projects/{project_id}/iou/vms/{vm_id}/reload

Contents
• /v1/projects/{project_id}/iou/vms/{vm_id}/reload
– POST /v1/projects/{project_id}/iou/vms/{vm_id}/reload
* Parameters
* Response status codes
* Sample session

POST /v1/projects/{project_id}/iou/vms/{vm_id}/reload

Reload a IOU instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance reloaded

54 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/7aecd

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/7aecd0ae-3b0d-4b00-b8b6-0de9caffd102/r
{}

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/iou/vms/{vm_id}/reload

8.6.11 /v1/projects/{project_id}/iou/vms/{vm_id}/start

Contents
• /v1/projects/{project_id}/iou/vms/{vm_id}/start
– POST /v1/projects/{project_id}/iou/vms/{vm_id}/start
* Parameters
* Response status codes
* Input
* Sample session

POST /v1/projects/{project_id}/iou/vms/{vm_id}/start

Start a IOU instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance started

8.6. Iou 55
GNS3 Documentation, Release 1.5.0dev1

Input

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/f932e

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/f932ec58-f509-44e6-8b30-aa0de3cc98e8/s
{
"iourc_content": "test"
}

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/iou/vms/{vm_id}/start

8.6.12 /v1/projects/{project_id}/iou/vms/{vm_id}/stop

Contents
• /v1/projects/{project_id}/iou/vms/{vm_id}/stop
– POST /v1/projects/{project_id}/iou/vms/{vm_id}/stop
* Parameters
* Response status codes
* Sample session

POST /v1/projects/{project_id}/iou/vms/{vm_id}/stop

Stop a IOU instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance stopped

56 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/abbc1

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/iou/vms/abbc1d5d-0b77-41e2-8681-75ad954e32c6/s
{}

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/iou/vms/{vm_id}/stop

8.7 Network

8.7.1 /v1/interfaces

Contents
• /v1/interfaces
– GET /v1/interfaces
* Response status codes
* Sample session

GET /v1/interfaces

List all the network interfaces available on the server

Response status codes

• 200: OK

Sample session

curl -i -X GET 'http://localhost:8000/v1/interfaces'

GET /v1/interfaces HTTP/1.1

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 6181
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT

8.7. Network 57
GNS3 Documentation, Release 1.5.0dev1

SERVER: Python/3.4 GNS3/1.4.0.dev9

X-ROUTE: /v1/interfaces

[
{
"id": "lo0",
"ip_address": "127.0.0.1",
"name": "lo0"
},
{
"id": "gif0",
"ip_address": "",
"name": "gif0"
},
{
"id": "stf0",
"ip_address": "",
"name": "stf0"
},
{
"id": "en0",
"ip_address": "",
"name": "en0"
},
{
"id": "en1",
"ip_address": "192.168.84.114",
"name": "en1"
},
{
"id": "fw0",
"ip_address": "",
"name": "fw0"
},
{
"id": "en2",
"ip_address": "",
"name": "en2"
},
{
"id": "p2p0",
"ip_address": "",
"name": "p2p0"
},
{
"id": "bridge0",
"ip_address": "",
"name": "bridge0"
},
{
"id": "vboxnet0",
"ip_address": "",
"name": "vboxnet0"
},
{
"id": "vboxnet1",
"ip_address": "",
"name": "vboxnet1"

58 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

},
{
"id": "vboxnet2",
"ip_address": "",
"name": "vboxnet2"
},
{
"id": "vboxnet3",
"ip_address": "192.168.99.1",
"name": "vboxnet3"
},
{
"id": "vmnet1",
"ip_address": "172.16.16.1",
"name": "vmnet1"
},
{
"id": "vmnet2",
"ip_address": "172.16.0.1",
"name": "vmnet2"
},
{
"id": "vmnet3",
"ip_address": "172.16.1.1",
"name": "vmnet3"
},
{
"id": "vmnet4",
"ip_address": "172.16.2.1",
"name": "vmnet4"
},
{
"id": "vmnet5",
"ip_address": "172.16.3.1",
"name": "vmnet5"
},
{
"id": "vmnet6",
"ip_address": "172.16.4.1",
"name": "vmnet6"
},
{
"id": "vmnet7",
"ip_address": "172.16.5.1",
"name": "vmnet7"
},
{
"id": "vmnet8",
"ip_address": "192.168.229.1",
"name": "vmnet8"
},
{
"id": "vmnet9",
"ip_address": "172.16.6.1",
"name": "vmnet9"
},
{
"id": "vmnet10",

8.7. Network 59
GNS3 Documentation, Release 1.5.0dev1

"ip_address": "172.16.7.1",
"name": "vmnet10"
},
{
"id": "vmnet11",
"ip_address": "172.16.8.1",
"name": "vmnet11"
},
{
"id": "vmnet12",
"ip_address": "172.16.9.1",
"name": "vmnet12"
},
{
"id": "vmnet13",
"ip_address": "172.16.10.1",
"name": "vmnet13"
},
{
"id": "vmnet14",
"ip_address": "172.16.11.1",
"name": "vmnet14"
},
{
"id": "vmnet15",
"ip_address": "172.16.12.1",
"name": "vmnet15"
},
{
"id": "vmnet16",
"ip_address": "172.16.13.1",
"name": "vmnet16"
},
{
"id": "vmnet17",
"ip_address": "172.16.14.1",
"name": "vmnet17"
},
{
"id": "vmnet18",
"ip_address": "172.16.15.1",
"name": "vmnet18"
},
{
"id": "vmnet19",
"ip_address": "172.16.17.1",
"name": "vmnet19"
},
{
"id": "vmnet20",
"ip_address": "172.16.18.1",
"name": "vmnet20"
},
{
"id": "vmnet21",
"ip_address": "172.16.19.1",
"name": "vmnet21"
},

60 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

{
"id": "vmnet22",
"ip_address": "172.16.20.1",
"name": "vmnet22"
},
{
"id": "vmnet23",
"ip_address": "172.16.21.1",
"name": "vmnet23"
},
{
"id": "vmnet24",
"ip_address": "172.16.22.1",
"name": "vmnet24"
},
{
"id": "vmnet25",
"ip_address": "172.16.23.1",
"name": "vmnet25"
},
{
"id": "vmnet26",
"ip_address": "172.16.24.1",
"name": "vmnet26"
},
{
"id": "vmnet27",
"ip_address": "172.16.25.1",
"name": "vmnet27"
},
{
"id": "vmnet28",
"ip_address": "172.16.26.1",
"name": "vmnet28"
},
{
"id": "vmnet29",
"ip_address": "172.16.27.1",
"name": "vmnet29"
},
{
"id": "vmnet30",
"ip_address": "172.16.28.1",
"name": "vmnet30"
},
{
"id": "vmnet31",
"ip_address": "172.16.29.1",
"name": "vmnet31"
},
{
"id": "vmnet32",
"ip_address": "172.16.30.1",
"name": "vmnet32"
},
{
"id": "vmnet33",
"ip_address": "172.16.31.1",

8.7. Network 61
GNS3 Documentation, Release 1.5.0dev1

"name": "vmnet33"
},
{
"id": "vmnet34",
"ip_address": "172.16.32.1",
"name": "vmnet34"
},
{
"id": "vmnet35",
"ip_address": "172.16.33.1",
"name": "vmnet35"
},
{
"id": "vmnet36",
"ip_address": "172.16.34.1",
"name": "vmnet36"
},
{
"id": "vmnet37",
"ip_address": "172.16.35.1",
"name": "vmnet37"
},
{
"id": "vmnet38",
"ip_address": "172.16.36.1",
"name": "vmnet38"
},
{
"id": "vmnet39",
"ip_address": "172.16.37.1",
"name": "vmnet39"
},
{
"id": "vmnet40",
"ip_address": "172.16.38.1",
"name": "vmnet40"
},
{
"id": "vmnet41",
"ip_address": "172.16.39.1",
"name": "vmnet41"
},
{
"id": "vmnet42",
"ip_address": "172.16.40.1",
"name": "vmnet42"
},
{
"id": "vmnet43",
"ip_address": "172.16.41.1",
"name": "vmnet43"
},
{
"id": "vmnet44",
"ip_address": "172.16.42.1",
"name": "vmnet44"
},
{

62 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

"id": "vmnet45",
"ip_address": "172.16.43.1",
"name": "vmnet45"
},
{
"id": "vmnet46",
"ip_address": "172.16.44.1",
"name": "vmnet46"
},
{
"id": "vmnet47",
"ip_address": "172.16.45.1",
"name": "vmnet47"
},
{
"id": "vmnet48",
"ip_address": "172.16.46.1",
"name": "vmnet48"
},
{
"id": "vmnet49",
"ip_address": "172.16.47.1",
"name": "vmnet49"
},
{
"id": "vmnet50",
"ip_address": "172.16.48.1",
"name": "vmnet50"
}
]

8.7.2 /v1/projects/{project_id}/ports/udp

Contents
• /v1/projects/{project_id}/ports/udp
– POST /v1/projects/{project_id}/ports/udp
* Parameters
* Response status codes
* Sample session

POST /v1/projects/{project_id}/ports/udp

Allocate an UDP port on the server

Parameters

• project_id: The UUID of the project

8.7. Network 63
GNS3 Documentation, Release 1.5.0dev1

Response status codes

• 201: UDP port allocated

• 404: The project doesn’t exist

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/ports/udp' -d

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/ports/udp HTTP/1.1

{}

HTTP/1.1 201
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 25
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/ports/udp

{
"udp_port": 10000
}

8.8 Project

8.8.1 /v1/projects

Contents
• /v1/projects
– GET /v1/projects
* Response status codes
* Sample session
– POST /v1/projects
* Response status codes
* Input
* Output
* Sample session

GET /v1/projects

List projects opened on the server

64 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Response status codes

• 200: Project list

Sample session

curl -i -X GET 'http://localhost:8000/v1/projects'

GET /v1/projects HTTP/1.1

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 656
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects

[
{
"location": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmppth7jfny",
"name": "test",
"path": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmppth7jfny/00010203-0405-0607-0809
"project_id": "00010203-0405-0607-0809-0a0b0c0d0e0f",
"temporary": false
},
{
"location": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmppth7jfny",
"name": "test",
"path": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmppth7jfny/00010203-0405-0607-0809
"project_id": "00010203-0405-0607-0809-0a0b0c0d0e0b",
"temporary": false
}
]

POST /v1/projects

Create a new project on the server

Response status codes

• 201: Project created

• 409: Project already created

8.8. Project 65
GNS3 Documentation, Release 1.5.0dev1

Input

Output

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects' -d '{"name": "test"}'

POST /v1/projects HTTP/1.1

{
"name": "test"
}

HTTP/1.1 201
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 297
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects

{
"location": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmpz4njup0u",
"name": "test",
"path": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmpz4njup0u/2547d75b-6059-4cff-a2ff-ac7
"project_id": "2547d75b-6059-4cff-a2ff-ac78ad5b98c7",
"temporary": false
}

8.8.2 /v1/projects/{project_id}

Contents
• /v1/projects/{project_id}
– GET /v1/projects/{project_id}
* Parameters
* Response status codes
* Output
* Sample session
– PUT /v1/projects/{project_id}
* Parameters
* Response status codes
* Input
* Output
* Sample session
– DELETE /v1/projects/{project_id}
* Parameters
* Response status codes
* Sample session

66 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

GET /v1/projects/{project_id}

Get project information

Parameters

• project_id: The UUID of the project

Response status codes

• 200: Success
• 404: The project doesn’t exist

Output

Sample session

curl -i -X GET 'http://localhost:8000/v1/projects/00010203-0405-0607-0809-0a0b0c0d0e02'

GET /v1/projects/00010203-0405-0607-0809-0a0b0c0d0e02 HTTP/1.1

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 297
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}

{
"location": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmpytbnsctl",
"name": "test",
"path": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmpytbnsctl/00010203-0405-0607-0809-0a0
"project_id": "00010203-0405-0607-0809-0a0b0c0d0e02",
"temporary": false
}

PUT /v1/projects/{project_id}

Update a project

Parameters

• project_id: The UUID of the project

8.8. Project 67
GNS3 Documentation, Release 1.5.0dev1

Response status codes

• 200: The project has been updated

• 403: You are not allowed to modify this property
• 404: The project doesn’t exist

Input

Output

Sample session

curl -i -X PUT 'http://localhost:8000/v1/projects/51887c6f-8fde-40e7-8904-d4e54fcdb7b4' -d '{"name":

PUT /v1/projects/51887c6f-8fde-40e7-8904-d4e54fcdb7b4 HTTP/1.1

{
"name": "second_name",
"path": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-54/test_update_path_proj
}

HTTP/1.1 403
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 100
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}

{
"message": "You are not allowed to modify the project directory location",
"status": 403
}

DELETE /v1/projects/{project_id}

Delete a project from disk

Parameters

• project_id: The UUID of the project

Response status codes

• 404: The project doesn’t exist

• 204: Changes have been written on disk

68 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Sample session

curl -i -X DELETE 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80'

DELETE /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80 HTTP/1.1

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}

8.8.3 /v1/projects/{project_id}/close

Contents
• /v1/projects/{project_id}/close
– POST /v1/projects/{project_id}/close
* Parameters
* Response status codes
* Sample session

POST /v1/projects/{project_id}/close

Close a project

Parameters

• project_id: The UUID of the project

Response status codes

• 404: The project doesn’t exist

• 204: The project has been closed

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/close' -d '{}

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/close HTTP/1.1

{}

HTTP/1.1 204

8.8. Project 69
GNS3 Documentation, Release 1.5.0dev1

ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/close

8.8.4 /v1/projects/{project_id}/commit

Contents
• /v1/projects/{project_id}/commit
– POST /v1/projects/{project_id}/commit
* Parameters
* Response status codes
* Sample session

POST /v1/projects/{project_id}/commit

Write changes on disk

Parameters

• project_id: The UUID of the project

Response status codes

• 404: The project doesn’t exist

• 204: Changes have been written on disk

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/commit' -d '{

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/commit HTTP/1.1

{}

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/commit

70 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

8.8.5 /v1/projects/{project_id}/files

Contents
• /v1/projects/{project_id}/files
– GET /v1/projects/{project_id}/files
* Parameters
* Response status codes
* Sample session

GET /v1/projects/{project_id}/files

List files of a project

Parameters

• project_id: The UUID of the project

Response status codes

• 200: Return list of files

• 404: The project doesn’t exist

Sample session

curl -i -X GET 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/files'

GET /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/files HTTP/1.1

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 204
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/files

[
{
"md5sum": "ad0234829205b9033196ba818f7a872b",
"path": "test.txt"
},
{
"md5sum": "098f6bcd4621d373cade4e832627b4f6",
"path": "vm-1/dynamips/test.bin"
}
]

8.8. Project 71
GNS3 Documentation, Release 1.5.0dev1

8.8.6 /v1/projects/{project_id}/files/{path:.+}

Contents
• /v1/projects/{project_id}/files/{path:.+}
– GET /v1/projects/{project_id}/files/{path:.+}
* Parameters
* Response status codes

GET /v1/projects/{project_id}/files/{path:.+}

Get a file of a project

Parameters

• project_id: The UUID of the project

Response status codes

• 200: Return the file

• 403: Permission denied
• 404: The file doesn’t exist

8.8.7 /v1/projects/{project_id}/notifications

Contents
• /v1/projects/{project_id}/notifications
– GET /v1/projects/{project_id}/notifications
* Parameters
* Response status codes

GET /v1/projects/{project_id}/notifications

Receive notifications about the projects

Parameters

• project_id: The UUID of the project

Response status codes

• 200: End of stream

• 404: The project doesn’t exist

72 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

8.9 Qemu

8.9.1 /v1/projects/{project_id}/qemu/vms

Contents
• /v1/projects/{project_id}/qemu/vms
– POST /v1/projects/{project_id}/qemu/vms
* Parameters
* Response status codes
* Input
* Output
* Sample session

POST /v1/projects/{project_id}/qemu/vms

Create a new Qemu VM instance

Parameters

• project_id: UUID for the project

Response status codes

• 400: Invalid request

• 201: Instance created
• 409: Conflict

Input

Output

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms' -d

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms HTTP/1.1

{
"hda_disk_image": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-54/test_qemu_c
"name": "PC TEST 1",
"qemu_path": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmp3zzynydr/qemu-system-x86_64",
"ram": 1024
}

HTTP/1.1 201
ACCESS-CONTROL-ALLOW-ORIGIN: *

8.9. Qemu 73
GNS3 Documentation, Release 1.5.0dev1

CONNECTION: keep-alive
CONTENT-LENGTH: 1473
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/qemu/vms

{
"acpi_shutdown": false,
"adapter_type": "e1000",
"adapters": 1,
"boot_priority": "c",
"cdrom_image": "",
"cdrom_image_md5sum": null,
"console": 2000,
"console_type": "telnet",
"cpu_throttling": 0,
"cpus": 1,
"hda_disk_image": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-54/test_qemu_c
"hda_disk_image_md5sum": "c4ca4238a0b923820dcc509a6f75849b",
"hda_disk_interface": "ide",
"hdb_disk_image": "",
"hdb_disk_image_md5sum": null,
"hdb_disk_interface": "ide",
"hdc_disk_image": "",
"hdc_disk_image_md5sum": null,
"hdc_disk_interface": "ide",
"hdd_disk_image": "",
"hdd_disk_image_md5sum": null,
"hdd_disk_interface": "ide",
"initrd": "",
"initrd_md5sum": null,
"kernel_command_line": "",
"kernel_image": "",
"kernel_image_md5sum": null,
"legacy_networking": false,
"mac_address": "00:00:ab:71:f2:00",
"name": "PC TEST 1",
"options": "",
"platform": "x86_64",
"process_priority": "low",
"project_id": "a1e920ca-338a-4e9f-b363-aa607b09dd80",
"qemu_path": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmp3zzynydr/qemu-system-x86_64",
"ram": 1024,
"vm_directory": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmpbbmb6tc1/a1e920ca-338a-4e9f-
"vm_id": "72f88dce-6c67-4e46-b42d-81a8c4f371f2"
}

8.9.2 /v1/projects/{project_id}/qemu/vms/{vm_id}

74 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/qemu/vms/{vm_id}
– GET /v1/projects/{project_id}/qemu/vms/{vm_id}
* Parameters
* Response status codes
* Output
* Sample session
– PUT /v1/projects/{project_id}/qemu/vms/{vm_id}
* Parameters
* Response status codes
* Input
* Output
* Sample session
– DELETE /v1/projects/{project_id}/qemu/vms/{vm_id}
* Parameters
* Response status codes
* Sample session

GET /v1/projects/{project_id}/qemu/vms/{vm_id}

Get a Qemu VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 200: Success
• 400: Invalid request
• 404: Instance doesn’t exist

Output

Sample session

curl -i -X GET 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/a5c7b

GET /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/a5c7b71e-03a5-4fe8-a7c5-ec5bd6e60a62 H

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 1336
CONTENT-TYPE: application/json

8.9. Qemu 75
GNS3 Documentation, Release 1.5.0dev1

DATE: Thu, 08 Jan 2015 16:09:15 GMT

SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/qemu/vms/{vm_id}

{
"acpi_shutdown": false,
"adapter_type": "e1000",
"adapters": 1,
"boot_priority": "c",
"cdrom_image": "",
"cdrom_image_md5sum": null,
"console": 2000,
"console_type": "telnet",
"cpu_throttling": 0,
"cpus": 1,
"hda_disk_image": "",
"hda_disk_image_md5sum": null,
"hda_disk_interface": "ide",
"hdb_disk_image": "",
"hdb_disk_image_md5sum": null,
"hdb_disk_interface": "ide",
"hdc_disk_image": "",
"hdc_disk_image_md5sum": null,
"hdc_disk_interface": "ide",
"hdd_disk_image": "",
"hdd_disk_image_md5sum": null,
"hdd_disk_interface": "ide",
"initrd": "",
"initrd_md5sum": null,
"kernel_command_line": "",
"kernel_image": "",
"kernel_image_md5sum": null,
"legacy_networking": false,
"mac_address": "00:00:ab:0a:62:00",
"name": "PC TEST 1",
"options": "",
"platform": "x86_64",
"process_priority": "low",
"project_id": "a1e920ca-338a-4e9f-b363-aa607b09dd80",
"qemu_path": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmp3zzynydr/qemu-system-x86_64",
"ram": 256,
"vm_directory": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmpbbmb6tc1/a1e920ca-338a-4e9f-
"vm_id": "a5c7b71e-03a5-4fe8-a7c5-ec5bd6e60a62"
}

PUT /v1/projects/{project_id}/qemu/vms/{vm_id}

Update a Qemu VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

76 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Response status codes

• 200: Instance updated

• 400: Invalid request
• 404: Instance doesn’t exist
• 409: Conflict

Input

Output

Sample session

curl -i -X PUT 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/b2e10

PUT /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/b2e10803-4587-4ff9-9efe-d9e761965dba H
{
"console": 2001,
"hdb_disk_image": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-54/test_qemu_u
"name": "test",
"ram": 1024
}

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 1456
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/qemu/vms/{vm_id}

{
"acpi_shutdown": false,
"adapter_type": "e1000",
"adapters": 1,
"boot_priority": "c",
"cdrom_image": "",
"cdrom_image_md5sum": null,
"console": 2001,
"console_type": "telnet",
"cpu_throttling": 0,
"cpus": 1,
"hda_disk_image": "",
"hda_disk_image_md5sum": null,
"hda_disk_interface": "ide",
"hdb_disk_image": "/private/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/pytest-54/test_qemu_u
"hdb_disk_image_md5sum": "c4ca4238a0b923820dcc509a6f75849b",
"hdb_disk_interface": "ide",
"hdc_disk_image": "",
"hdc_disk_image_md5sum": null,
"hdc_disk_interface": "ide",
"hdd_disk_image": "",

8.9. Qemu 77
GNS3 Documentation, Release 1.5.0dev1

"hdd_disk_image_md5sum": null,
"hdd_disk_interface": "ide",
"initrd": "",
"initrd_md5sum": null,
"kernel_command_line": "",
"kernel_image": "",
"kernel_image_md5sum": null,
"legacy_networking": false,
"mac_address": "00:00:ab:5d:ba:00",
"name": "test",
"options": "",
"platform": "x86_64",
"process_priority": "low",
"project_id": "a1e920ca-338a-4e9f-b363-aa607b09dd80",
"qemu_path": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmp3zzynydr/qemu-system-x86_64",
"ram": 1024,
"vm_directory": "/var/folders/3s/r2wbv07n7wg4vrsn874lmxxh0000gn/T/tmpbbmb6tc1/a1e920ca-338a-4e9f-
"vm_id": "b2e10803-4587-4ff9-9efe-d9e761965dba"
}

DELETE /v1/projects/{project_id}/qemu/vms/{vm_id}

Delete a Qemu VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance deleted

Sample session

curl -i -X DELETE 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/d1

DELETE /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/d18deaf3-f59a-423d-8de6-0fab7b3ac21

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/qemu/vms/{vm_id}

78 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

8.9.3 /v1/projects/{project_id}/qemu/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_nu

Contents
• /v1/projects/{project_id}/qemu/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio
– POST /v1/projects/{project_id}/qemu/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio
* Parameters
* Response status codes
* Sample session
– DELETE /v1/projects/{project_id}/qemu/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio
* Parameters
* Response status codes
* Sample session

POST /v1/projects/{project_id}/qemu/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio

Add a NIO to a Qemu VM instance

Parameters

• adapter_number: Network adapter where the nio is located

• project_id: UUID for the project
• port_number: Port on the adapter (always 0)
• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 201: NIO created
• 404: Instance doesn’t exist

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/270e

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/270ea3e8-d916-440b-bc8c-5ce63bbc71b5/
{
"ethernet_device": "eth0",
"type": "nio_generic_ethernet"
}

HTTP/1.1 409
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 89
CONTENT-TYPE: application/json

8.9. Qemu 79
GNS3 Documentation, Release 1.5.0dev1

DATE: Thu, 08 Jan 2015 16:09:15 GMT

SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/qemu/vms/{vm_id}/adapters/{adapter_number:\d+}/ports/{port_number:

{
"message": "NIO of type nio_generic_ethernet is not supported",
"status": 409
}

DELETE /v1/projects/{project_id}/qemu/vms/{vm_id}/adapters/{adapter_number:d+}/ports/{port_number:d+}/nio

Remove a NIO from a Qemu VM instance

Parameters

• adapter_number: Network adapter where the nio is located

• project_id: UUID for the project
• port_number: Port on the adapter (always 0)
• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: NIO deleted

Sample session

curl -i -X DELETE 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/56

DELETE /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/56a77fc8-cdb4-417b-aacd-dc8cbd47736

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/qemu/vms/{vm_id}/adapters/{adapter_number:\d+}/ports/{port_number:

8.9.4 /v1/projects/{project_id}/qemu/vms/{vm_id}/reload

80 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/qemu/vms/{vm_id}/reload
– POST /v1/projects/{project_id}/qemu/vms/{vm_id}/reload
* Parameters
* Response status codes
* Sample session

POST /v1/projects/{project_id}/qemu/vms/{vm_id}/reload

Reload a Qemu VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance reloaded

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/7ba8

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/7ba8c4e8-af84-4c2c-85f7-825e8321ba5d/
{}

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/qemu/vms/{vm_id}/reload

8.9.5 /v1/projects/{project_id}/qemu/vms/{vm_id}/resume

8.9. Qemu 81
GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/qemu/vms/{vm_id}/resume
– POST /v1/projects/{project_id}/qemu/vms/{vm_id}/resume
* Parameters
* Response status codes
* Sample session

POST /v1/projects/{project_id}/qemu/vms/{vm_id}/resume

Resume a Qemu VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance resumed

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/6837

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/68376eea-9e5a-4dd8-97c5-c3155b02cd8e/
{}

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/qemu/vms/{vm_id}/resume

8.9.6 /v1/projects/{project_id}/qemu/vms/{vm_id}/start

82 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/qemu/vms/{vm_id}/start
– POST /v1/projects/{project_id}/qemu/vms/{vm_id}/start
* Parameters
* Response status codes
* Sample session

POST /v1/projects/{project_id}/qemu/vms/{vm_id}/start

Start a Qemu VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance started

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/1f8a

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/1f8a3aaa-fb64-4c51-a9e2-019215012aab/
{}

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/qemu/vms/{vm_id}/start

8.9.7 /v1/projects/{project_id}/qemu/vms/{vm_id}/stop

8.9. Qemu 83
GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/qemu/vms/{vm_id}/stop
– POST /v1/projects/{project_id}/qemu/vms/{vm_id}/stop
* Parameters
* Response status codes
* Sample session

POST /v1/projects/{project_id}/qemu/vms/{vm_id}/stop

Stop a Qemu VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance stopped

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/79c9

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/79c98a6f-9a1b-44c3-be28-ed2f924e3960/
{}

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/qemu/vms/{vm_id}/stop

8.9.8 /v1/projects/{project_id}/qemu/vms/{vm_id}/suspend

84 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/projects/{project_id}/qemu/vms/{vm_id}/suspend
– POST /v1/projects/{project_id}/qemu/vms/{vm_id}/suspend
* Parameters
* Response status codes
* Sample session

POST /v1/projects/{project_id}/qemu/vms/{vm_id}/suspend

Suspend a Qemu VM instance

Parameters

• project_id: UUID for the project

• vm_id: UUID for the instance

Response status codes

• 400: Invalid request

• 404: Instance doesn’t exist
• 204: Instance suspended

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/52cf

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/qemu/vms/52cfc381-0cb0-4d90-868d-8554ef5a9a33/
{}

HTTP/1.1 204
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/qemu/vms/{vm_id}/suspend

8.9.9 /v1/qemu/binaries

8.9. Qemu 85
GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/qemu/binaries
– GET /v1/qemu/binaries
* Response status codes
* Sample session

GET /v1/qemu/binaries

Get a list of available Qemu binaries

Response status codes

• 200: Success
• 400: Invalid request
• 404: Instance doesn’t exist

Sample session

curl -i -X GET 'http://localhost:8000/v1/qemu/binaries'

GET /v1/qemu/binaries HTTP/1.1

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 134
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/qemu/binaries

[
{
"path": "/tmp/1",
"version": "2.2.0"
},
{
"path": "/tmp/2",
"version": "2.1.0"
}
]

8.9.10 /v1/qemu/img

86 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/qemu/img
– POST /v1/qemu/img
* Response status codes
* Input
* Sample session

POST /v1/qemu/img

Create a Qemu image

Response status codes

• 201: Image created

Input

Sample session

curl -i -X POST 'http://localhost:8000/v1/qemu/img' -d '{"cluster_size": 64, "format": "qcow2", "lazy

POST /v1/qemu/img HTTP/1.1

{
"cluster_size": 64,
"format": "qcow2",
"lazy_refcounts": "off",
"path": "/tmp/hda.qcow2",
"preallocation": "metadata",
"qemu_img": "/tmp/qemu-img",
"refcount_bits": 12,
"size": 100
}

HTTP/1.1 201
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 0
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/qemu/img

8.9.11 /v1/qemu/img-binaries

8.9. Qemu 87
GNS3 Documentation, Release 1.5.0dev1

Contents
• /v1/qemu/img-binaries
– GET /v1/qemu/img-binaries
* Response status codes

GET /v1/qemu/img-binaries

Get a list of available Qemu-img binaries

Response status codes

• 200: Success
• 400: Invalid request
• 404: Instance doesn’t exist

8.9.12 /v1/qemu/vms

Contents
• /v1/qemu/vms
– GET /v1/qemu/vms
* Response status codes

GET /v1/qemu/vms

Retrieve the list of Qemu images

Response status codes

• 200: List of Qemu images retrieved

8.9.13 /v1/qemu/vms/{path:.+}

Contents
• /v1/qemu/vms/{path:.+}
– POST /v1/qemu/vms/{path:.+}
* Response status codes

POST /v1/qemu/vms/{path:.+}

Upload Qemu image.

88 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

Response status codes

• 204: Image uploaded

8.10 Server

8.10.1 /v1/server/shutdown

Contents
• /v1/server/shutdown
– POST /v1/server/shutdown
* Response status codes

POST /v1/server/shutdown

Shutdown the local server

Response status codes

• 201: Server is shutting down

• 403: Server shutdown refused

8.11 Version

8.11.1 /v1/version

Contents
• /v1/version
– GET /v1/version
* Response status codes
* Output
* Sample session
– POST /v1/version
* Response status codes
* Input
* Output
* Sample session

GET /v1/version

Retrieve the server version number

8.10. Server 89
GNS3 Documentation, Release 1.5.0dev1

Response status codes

• 200: OK

Output

Sample session

curl -i -X GET 'http://localhost:8000/v1/version'

GET /v1/version HTTP/1.1

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 50
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/version

{
"local": true,
"version": "1.4.0.dev9"
}

POST /v1/version

Check if version is the same as the server

Response status codes

• 200: Same version

• 409: Invalid version

Input

Output

Sample session

curl -i -X POST 'http://localhost:8000/v1/version' -d '{"version": "1.4.0.dev9"}'

POST /v1/version HTTP/1.1

{
"version": "1.4.0.dev9"
}

90 Chapter 8. API Endpoints

 GNS3 Documentation, Release 1.5.0dev1

HTTP/1.1 200
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 31
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/version

{
"version": "1.4.0.dev9"
}

8.12 Virtualbox

8.12.1 /v1/projects/{project_id}/virtualbox/vms

Contents
• /v1/projects/{project_id}/virtualbox/vms
– POST /v1/projects/{project_id}/virtualbox/vms
* Parameters
* Response status codes
* Input
* Output
* Sample session

POST /v1/projects/{project_id}/virtualbox/vms

Create a new VirtualBox VM instance

Parameters

• project_id: UUID for the project

Response status codes

• 400: Invalid request

• 201: Instance created
• 409: Conflict

8.12. Virtualbox 91
GNS3 Documentation, Release 1.5.0dev1

Input

Output

Sample session

curl -i -X POST 'http://localhost:8000/v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/virtualbox/vm

POST /v1/projects/a1e920ca-338a-4e9f-b363-aa607b09dd80/virtualbox/vms HTTP/1.1

{
"linked_clone": false,
"name": "VM1",
"vmname": "VM1"
}

HTTP/1.1 201
ACCESS-CONTROL-ALLOW-ORIGIN: *
CONNECTION: keep-alive
CONTENT-LENGTH: 409
CONTENT-TYPE: application/json
DATE: Thu, 08 Jan 2015 16:09:15 GMT
SERVER: Python/3.4 GNS3/1.4.0.dev9
X-ROUTE: /v1/projects/{project_id}/virtualbox/vms

{
"acpi_shutdown": false,
"adapter_type": "Intel PRO/1000 MT Desktop (82540EM)",
"adapters": 0,
"console": 2000,
"enable_remote_console": false,
"headless": false,
"name": "VM1",
"project_id": "a1e920ca-338a-4e9f-b363-aa607b09dd80",
"ram": 0,
"use_any_adapter": false,
"vm_directory": null,
"vm_id": "7d54caf7-ab92-4a5f-8795-1ebdfcc6994b",
"vmname": "VM1"
}

8.12.2 /v1/projects/{project_id}/virtualbox/vms/{vm_id}

92 Chapter 8. API Endpoints