| List all drives | |
|---|---|
| GET | /drives/list |
| Returns | for each drive, a list of DRIVE |
| Get single drive info | ||
|---|---|---|
| GET | /drives/DRIVE/info | |
| Returns | KEY VALUE pairs: | |
| name | Drive name | |
| drive | DRIVE | |
| size | size of drive in bytes | |
| status | active | inactive | |
| claimed | present if drive is in use by a server, values are the server uuids | |
| claim:type | optional, either ‘exclusive’ (the default) or ‘shared’ to allow multiple servers to access a drive simultaneously | |
| imaging | ‘true’ if this is underway, or ‘queued’ if waiting for another imaging operation to complete first. If a drive is imaging, a call to /info/full will show the percentage completed. | |
| [read|write]:[bytes|requests] | Cumulative i/o byte/request count for each drive | |
| readers | optional, space-separated list of users allowed to read from a drive or ‘ffffffff-ffff-ffff-ffff-ffffffffffff’ for all users | |
| tags | optional, space-separated list of tags | |
| user:* | optional, user-defined KEY VALUE pairs | |
| encryption:cipher | optional, either ‘none’ or ‘aes-xts-plain’ (the default) | |
| user | owner of the drive | |
| Get all drives info | |
|---|---|
| GET | /drives/info |
| Returns | for each drive, KEY VALUE pairs as drive info |
| Create a drive | ||
|---|---|---|
| POST | /drives/create | |
| Expects | KEY VALUE pairs: | |
| name | Drive name | |
| size | size of drive in bytes | |
| claim:type | optional, either ‘exclusive’ (the default) or ‘shared’ to allow multiple servers to access a drive simultaneously | |
| readers | optional, space-separated list of users allowed to read from a drive or ‘ffffffff-ffff-ffff-ffff-ffffffffffff’ for all users | |
| tags | optional, space-separated list of tags | |
| user:* | optional, user-defined KEY VALUE pairs | |
| avoid | optional, space-separated list of existing drives to ensure this new drive is created on physical different hardware than those existing drives | |
| encryption:cipher | optional, either ‘none’ or ‘aes-xts-plain’ (the default) | |
| Returns | KEY VALUE pairs as drive info | |
| Notes | size is specified in bytes, optionally with a k/M/G/T suffix. | |
| Destroy a drive | |
|---|---|
| POST | /drives/DRIVE/destroy |
| Expects | Empty POST |
| Returns | HTTP 204 No Content |
| Set extra drive data | ||
|---|---|---|
| POST | /drives/DRIVE/set | |
| Expects | KEY VALUE pairs: | |
| name | Drive name | |
| size | size of drive in bytes | |
| claim:type | optional, either ‘exclusive’ (the default) or ‘shared’ to allow multiple servers to access a drive simultaneously | |
| readers | optional, space-separated list of users allowed to read from a drive or ‘ffffffff-ffff-ffff-ffff-ffffffffffff’ for all users | |
| tags | optional, space-separated list of tags | |
| user:* | optional, user-defined KEY VALUE pairs | |
| Returns | KEY VALUE pairs as drive info | |
| Notes | size is specified in bytes, optionally with a k/M/G/T suffix. | |
| Image a drive from another drive | |
|---|---|
| POST | /drives/DRIVE/image/SOURCE[/CONVERSION] |
| Expects | Empty POST |
| Returns | HTTP 204 No Content |
| Notes | Supports ‘gzip’ or ‘gunzip’ conversions. The actual imaging process is asynchronous, with progress reported via drive info. |
| Read binary data from a drive | |
|---|---|
| GET | /drives/DRIVE/read/OFFSET/SIZE |
| Returns | Binary data (Content-Type: application/octet-stream) |
| Notes | OFFSET and SIZE are specified in bytes, optionally with a k/M/G/T suffix. At present, SIZE may not exceed 4MB for a single request. Our drive download tool automatically reads the drive in 4MB chunks. You should do the same for large downloads. |
| Write binary data to a drive | |
|---|---|
| POST | /drives/DRIVE/write[/OFFSET] |
| Expects | Binary data (Content-Type: application/octet-stream) Supports raw data or Content-Encoding: gzip Does not support Transfer-Encoding: chunked |
| Returns | HTTP 204 No Content |
| Notes | OFFSET is the offset in the target drive at which to start writing, not an offset in the input stream. It is specified in bytes, optionally with a k/M/G/T suffix. Our drive upload tool automatically splits the input file into 4MB chunks and transfers each chunk gzipped. You should do the same for large uploads. |
0 Comments