Library Drives¶
Allowed HTTP methods¶
| Method | Description |
|---|---|
| GET | get / list object/s |
Note
See RFC 2616 for more details on HTTP methods semantics
Listing¶
- GET /libdrives/¶
Gets the list of library drives to which the authenticated user has access.
| param fields: | A set of field names specifying the returned fields |
|---|---|
| statuscode 200: | no error |
Example request:
GET /api/2.0/libdrives/?limit=5 HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
Example response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"meta": {
"limit": 5,
"offset": 0,
"total_count": 116
},
"objects": [
{
"affinities": [],
"allow_multimount": false,
"arch": "64",
"category": [
"general"
],
"description": "Debian 7.1.0 Netinstall AMD64.",
"favourite": false,
"image_type": "install",
"install_notes": "1. Attach the CD. \\n\r\nPlease be aware that the CD needs to be attached to the server as IDE. \\n\r\n \\n\r\n2. Attach a Drive. \\n\r\nPlease be aware that the minimum drive size where you are going to install the OS should be 5 GB. \\n\r\n \\n\r\n3. Connecting to your server via VNC. \\n\r\na) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n\r\nb) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n\r\nOR \\n\r\nc) Having installed a compatible VNC client, open a VNC connection to your server through the UI. \\n\r\nd) Enter your VNC url and VNC password as displayed on your Server Properties Window. \\n\r\n \\n\r\n4. Minimum Hardware Requirements. \\n\r\nThe recommended minimum hardware requirements as published by debian.org are: 1GB RAM and 1GHz CPU",
"jobs": [],
"licenses": [],
"media": "cdrom",
"meta": {},
"mounted_on": [],
"name": "Debian 7.1.0 Netinstall",
"os": "linux",
"owner": null,
"paid": false,
"resource_uri": "/api/2.0/libdrives/22bd1b24-ea78-47bb-a59b-a09ed5407867/",
"size": 536870912,
"status": "unmounted",
"storage_type": null,
"tags": [],
"url": "http://debian.org/",
"uuid": "22bd1b24-ea78-47bb-a59b-a09ed5407867"
},
{
"affinities": [],
"allow_multimount": false,
"arch": "64",
"category": [
"general"
],
"description": "OpenBSD 5.3 Netinstall CD",
"favourite": false,
"image_type": "install",
"install_notes": "1. Attach the CD. \\n\r\nPlease be aware that the CD needs to be attached to the server as IDE. \\n\r\n \\n\r\n2. Attach a Drive. \\n\r\nPlease be aware that the minimum drive size where you are going to install the OS should be 5 GB. \\n\r\n \\n\r\n3. Connecting to your server via VNC. \\n\r\na) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n\r\nb) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n\r\nOR \\n\r\nc) Having installed a compatible VNC client, open a VNC connection to your server through the UI. \\n\r\nd) Enter your VNC url and VNC password as displayed on your Server Properties Window. \\n\r\n \\n\r\n4. Minimum Hardware Requirements. \\n\r\nThe recommended minimum hardware requirements as published by openbsd.org: http://www.openbsd.org/faq/faq3.html#SelectHW",
"jobs": [],
"licenses": [],
"media": "cdrom",
"meta": {},
"mounted_on": [],
"name": "OpenBSD 5.3 Netinstall",
"os": "linux",
"owner": null,
"paid": false,
"resource_uri": "/api/2.0/libdrives/2860a9bc-a210-45df-a46e-42f1a3a0ed75/",
"size": 536870912,
"status": "unmounted",
"storage_type": null,
"tags": [],
"url": "",
"uuid": "2860a9bc-a210-45df-a46e-42f1a3a0ed75"
},
{
"affinities": [],
"allow_multimount": false,
"arch": "32",
"category": [
"general"
],
"description": "Ubuntu 12.10 Server - 32bit - Install CD\r\n",
"favourite": false,
"image_type": "install",
"install_notes": "1. Attach the CD. \\n\r\nPlease be aware that the CD needs to be attached to the server as IDE. \\n\r\n \\n\r\n2. Attach a Drive. \\n\r\nPlease be aware that the minimum drive size where you are going to install the OS should be 5 GB. \\n\r\n \\n\r\n3. Connecting to your server via VNC. \\n\r\na) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n\r\nb) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n\r\nOR \\n\r\nc) Having installed a compatible VNC client, open a VNC connection to your server through the UI. \\n\r\nd) Enter your VNC url and VNC password as displayed on your Server Properties Window. \\n\r\n \\n\r\n4. Minimum Hardware Requirements. \\n\r\nThe recommended minimum hardware requirements as published by ubuntu.org are: 1GB RAM and 1GHz CPU",
"jobs": [],
"licenses": [],
"media": "cdrom",
"meta": {},
"mounted_on": [],
"name": "Ubuntu 12.10 Server",
"os": "linux",
"owner": null,
"paid": false,
"resource_uri": "/api/2.0/libdrives/582300b5-df62-495d-8c2d-430b3bf0f9e9/",
"size": 1000000000,
"status": "unmounted",
"storage_type": null,
"tags": [],
"url": "http://ubuntu.com/",
"uuid": "582300b5-df62-495d-8c2d-430b3bf0f9e9"
},
{
"affinities": [],
"allow_multimount": false,
"arch": "64",
"category": [
"general"
],
"description": "Fedora 20 Beta - 64bit Install DVD",
"favourite": false,
"image_type": "install",
"install_notes": "1. Attach the CD. \\n\r\nPlease be aware that the CD needs to be attached to the server as IDE. \\n\r\n \\n\r\n2. Attach a Drive. \\n\r\nPlease be aware that the minimum drive size where you are going to install the OS should be 10GB. \\n\r\n \\n\r\n3. Connecting to your server via VNC. \\n\r\na) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n\r\nb) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n\r\nOR \\n\r\nc) Having installed a compatible VNC client, open a VNC connection to your server through the UI. \\n\r\nd) Enter your VNC url and VNC password as displayed on your Server Properties Window. \\n\r\n \\n\r\n4. Minimum Hardware Requirements. \\n\r\nThe recommended minimum hardware requirements as published by Fedoraproject.org are: 1GB RAM and 0.5MHz CPU \\n\r\n \\n",
"jobs": [],
"licenses": [],
"media": "cdrom",
"meta": {},
"mounted_on": [],
"name": "Fedora 20 Beta",
"os": "linux",
"owner": null,
"paid": false,
"resource_uri": "/api/2.0/libdrives/7203aa05-a6c3-4056-94b9-a8d940cac706/",
"size": 4581228544,
"status": "unmounted",
"storage_type": null,
"tags": [],
"url": "http://fedoraproject.org/",
"uuid": "7203aa05-a6c3-4056-94b9-a8d940cac706"
},
{
"affinities": [],
"allow_multimount": false,
"arch": "64",
"category": [
"general"
],
"description": "NetBSD 6.1.1 - amd64 - CD",
"favourite": false,
"image_type": "install",
"install_notes": "1. Attach the CD. \\n\r\nPlease be aware that the CD needs to be attached to the server as IDE. \\n\r\n \\n\r\n2. Attach a Drive. \\n\r\nPlease be aware that the minimum drive size where you are going to install the OS should be 5GB. \\n\r\n \\n\r\n3. Connecting to your server via VNC. \\n\r\na) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n\r\nb) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n\r\nOR \\n\r\nc) Having installed a compatible VNC client, open a VNC connection to your server through the UI. \\n\r\nd) Enter your VNC url and VNC password as displayed on your Server Properties Window. \\n\r\n \\n\r\n4. Minimum Hardware Requirements. \\n\r\nThe recommended minimum hardware requirements as published by Netbsd.org are: 0.5 GB RAM and 0.5GHz CPU \\n\r\n \\n\r\n",
"jobs": [],
"licenses": [],
"media": "cdrom",
"meta": {},
"mounted_on": [],
"name": "NetBSD 6.1.1",
"os": "other",
"owner": null,
"paid": false,
"resource_uri": "/api/2.0/libdrives/b1501e22-bca3-4ec4-a3b0-852bae8773d1/",
"size": 536870912,
"status": "unmounted",
"storage_type": null,
"tags": [],
"url": "http://www.netbsd.org/",
"uuid": "b1501e22-bca3-4ec4-a3b0-852bae8773d1"
}
]
}
Detailed listing¶
Note
For consistency, we left /libdrives/detail/ url enabled, but it returns the same level of detail as the list call.
List single drive¶
- GET /libdrives/{uuid}/¶
Gets detailed information for library drive identified by uuid.
| statuscode 200: | no error |
|---|
Example request:
GET /api/2.0/libdrives/22bd1b24-ea78-47bb-a59b-a09ed5407867/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
Example response:
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"affinities": [],
"allow_multimount": false,
"arch": "64",
"category": [
"general"
],
"description": "Debian 7.1.0 Netinstall AMD64.",
"favourite": false,
"image_type": "install",
"install_notes": "1. Attach the CD. \\n\r\nPlease be aware that the CD needs to be attached to the server as IDE. \\n\r\n \\n\r\n2. Attach a Drive. \\n\r\nPlease be aware that the minimum drive size where you are going to install the OS should be 5 GB. \\n\r\n \\n\r\n3. Connecting to your server via VNC. \\n\r\na) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n\r\nb) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n\r\nOR \\n\r\nc) Having installed a compatible VNC client, open a VNC connection to your server through the UI. \\n\r\nd) Enter your VNC url and VNC password as displayed on your Server Properties Window. \\n\r\n \\n\r\n4. Minimum Hardware Requirements. \\n\r\nThe recommended minimum hardware requirements as published by debian.org are: 1GB RAM and 1GHz CPU",
"jobs": [],
"licenses": [],
"media": "cdrom",
"meta": {},
"mounted_on": [],
"name": "Debian 7.1.0 Netinstall",
"os": "linux",
"owner": null,
"paid": false,
"resource_uri": "/api/2.0/libdrives/22bd1b24-ea78-47bb-a59b-a09ed5407867/",
"size": 536870912,
"status": "mounted",
"storage_type": null,
"tags": [],
"url": "http://debian.org/",
"uuid": "22bd1b24-ea78-47bb-a59b-a09ed5407867"
}
Attaching library drive¶
If the library drive is a CDROM media, you can attach it directly to an owned server the same way you attach a regular drive - specifying the library drive uuid.
Cloning library drive¶
- POST /libdrives/{uuid}/action/?do=clone¶
If a library drive is not a CDROM, you have to clone it in your account in order to use it. You can clone a library drive the same way you clone a regular drive.
Licensed drive images¶
Some drives in the library may require additional subscriptions or payment to be used. This is visible from the licenses field in the drive definition. When you clone such image from drives library to your account, the licenses remain bound to the cloned drive and can’t be altered upon drive edit. See also Licenses list regarding how to list all defined licenses.
Recognizing library drives¶
Note that library drives can be queried through regular drives API using /drives/{uuid}/. If the drive uuid happens to be the uuid of a library drive, the drive defintion will be retrieved. In order to differentiate between owned and library drive, one can check the owner attribute, which is null for library drives.
It is possible to get a library drive through the drives API, because there isn’t a way to know in advance whether an attached drive in a server definition is owned by the user or one from library.
Library drives are not listed in the list and detailed list for ordinary drives.
Example:
Get the drive from /drives/{uuid}/:
GET /api/2.0/drives/22bd1b24-ea78-47bb-a59b-a09ed5407867/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"affinities": [],
"allow_multimount": false,
"jobs": [],
"licenses": [],
"media": "cdrom",
"meta": {},
"mounted_on": [],
"name": "Debian 7.1.0 Netinstall",
"owner": null,
"resource_uri": "/api/2.0/drives/22bd1b24-ea78-47bb-a59b-a09ed5407867/",
"runtime": {
"is_snapshotable": true,
"snapshots_allocated_size": 0,
"storage_type": "dssd"
},
"size": 536870912,
"snapshots": [],
"status": "unmounted",
"storage_type": "dssd",
"tags": [],
"uuid": "22bd1b24-ea78-47bb-a59b-a09ed5407867"
}
Notice that there is no owner (it is null).
Get the same drive from /libdrives/{uuid}/:
GET /api/2.0/libdrives/22bd1b24-ea78-47bb-a59b-a09ed5407867/ HTTP/1.1
Content-Type: application/json
Authorization: Basic SWYgeW91IGZvdW5kIHRoaXMsIGhhdmUgYSBjb29raWUsIHlvdSBkZXNlcnZlIGl0IDop
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"affinities": [],
"allow_multimount": false,
"arch": "64",
"category": [
"general"
],
"description": "Debian 7.1.0 Netinstall AMD64.",
"favourite": false,
"image_type": "install",
"install_notes": "1. Attach the CD. \\n\r\nPlease be aware that the CD needs to be attached to the server as IDE. \\n\r\n \\n\r\n2. Attach a Drive. \\n\r\nPlease be aware that the minimum drive size where you are going to install the OS should be 5 GB. \\n\r\n \\n\r\n3. Connecting to your server via VNC. \\n\r\na) Go to the \u201cProperties\u201d tab of the server and Turn on the VNC Tunnel by clicking the button right next to it \\n\r\nb) In order to use the inbuilt client click on the icon right next to the VNC link and choose \u201cOpen in Dialog Window\u201d or \u201cOpen in new browser window/tab\u201d \\n\r\nOR \\n\r\nc) Having installed a compatible VNC client, open a VNC connection to your server through the UI. \\n\r\nd) Enter your VNC url and VNC password as displayed on your Server Properties Window. \\n\r\n \\n\r\n4. Minimum Hardware Requirements. \\n\r\nThe recommended minimum hardware requirements as published by debian.org are: 1GB RAM and 1GHz CPU",
"jobs": [],
"licenses": [],
"media": "cdrom",
"meta": {},
"mounted_on": [],
"name": "Debian 7.1.0 Netinstall",
"os": "linux",
"owner": null,
"paid": false,
"resource_uri": "/api/2.0/libdrives/22bd1b24-ea78-47bb-a59b-a09ed5407867/",
"size": 536870912,
"status": "mounted",
"storage_type": null,
"tags": [],
"url": "http://debian.org/",
"uuid": "22bd1b24-ea78-47bb-a59b-a09ed5407867"
}
Schema¶
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"allowed_detail_http_methods": [
"get"
],
"allowed_list_http_methods": [
"get"
],
"default_format": "application/json",
"default_limit": 20,
"fields": {
"affinities": {
"choices": [
"ssd"
],
"default": [],
"help_text": "A list of affinities this drive should belong to",
"readonly": false,
"required": false,
"type": "list"
},
"allow_multimount": {
"default": false,
"help_text": "Allow the drive to be mounted on multiple guests. Not taken into account when drive is cdrom.",
"readonly": false,
"required": false,
"type": "boolean"
},
"arch": {
"default": null,
"help_text": "Operating system bit architecture the drive.",
"readonly": false,
"required": true,
"type": "string"
},
"category": {
"default": [],
"help_text": "Category of the drive.",
"readonly": false,
"required": false,
"type": "list"
},
"description": {
"default": null,
"help_text": "Description of drive image.",
"readonly": false,
"required": false,
"type": "string"
},
"favourite": {
"default": null,
"help_text": "Favourite drive image for user.",
"readonly": false,
"required": true,
"type": "boolean"
},
"image_type": {
"default": null,
"help_text": "Type of drive image.",
"readonly": false,
"required": true,
"type": "string"
},
"install_notes": {
"default": null,
"help_text": "Install notes for the drive image.",
"readonly": false,
"required": false,
"type": "string"
},
"jobs": {
"default": "No default provided.",
"help_text": "Background jobs related to this resource",
"readonly": true,
"required": true,
"type": "related"
},
"licenses": {
"default": [],
"fields": {
"amount": {
"default": 1,
"help_text": "Number of licenses",
"readonly": false,
"required": false,
"type": "integer"
},
"license": {
"default": "No default provided.",
"help_text": "A single related resource. Can be either a URI or set of nested resource data.",
"readonly": false,
"required": true,
"type": "related"
},
"user": {
"default": null,
"help_text": "Owner of the license",
"readonly": false,
"required": false,
"type": "related"
}
},
"help_text": "A list of licenses attached to this drive",
"readonly": false,
"required": false,
"type": "related"
},
"media": {
"choices": [
"cdrom",
"disk"
],
"default": null,
"help_text": "Media representation type",
"readonly": false,
"required": true,
"type": "string"
},
"meta": {
"default": {},
"help_text": "User defined meta information",
"readonly": false,
"required": false,
"type": "dict"
},
"mounted_on": {
"default": "No default provided.",
"help_text": "Servers on which this drive is mounted on",
"readonly": true,
"required": false,
"type": "related"
},
"name": {
"default": null,
"help_text": "Human readable name of the drive",
"readonly": false,
"required": true,
"type": "string"
},
"os": {
"default": null,
"help_text": "Operating system of the drive.",
"readonly": false,
"required": true,
"type": "string"
},
"owner": {
"default": null,
"help_text": "Owner of the drive",
"readonly": true,
"required": false,
"type": "related"
},
"paid": {
"default": null,
"help_text": "Paid or free.",
"readonly": false,
"required": true,
"type": "boolean"
},
"resource_uri": {
"default": "No default provided.",
"help_text": "Unicode string data. Ex: \"Hello World\"",
"readonly": true,
"required": true,
"type": "string"
},
"size": {
"default": null,
"help_text": "Size of the drive in bytes",
"readonly": false,
"required": true,
"type": "integer"
},
"status": {
"default": "No default provided.",
"help_text": "Status of the drive.",
"readonly": true,
"required": true,
"type": "string"
},
"storage_type": {
"default": "No default provided.",
"help_text": "Underlying storage",
"readonly": false,
"required": true,
"type": "string"
},
"tags": {
"default": "No default provided.",
"help_text": "Many related resources. Can be either a list of URIs or list of individually nested resource data.",
"readonly": false,
"required": false,
"type": "related"
},
"url": {
"default": null,
"help_text": "Operating system bit architecture the drive.",
"readonly": false,
"required": false,
"type": "string"
},
"uuid": {
"default": null,
"help_text": "UUID of the drive",
"readonly": true,
"required": true,
"type": "string"
}
},
"filtering": {
"name": 0,
"name__contains": 0,
"tag": "<function get_tag_filter_args at 0x5dd61b8>",
"uuid": 0
}
}