StorPool API Reference

Copyright (c) 2014 - 2016 StorPool. All rights reserved.

This reference document describes the StorPool API version 18.01 and the supported API calls.

  1. General
  2. Peers
    1. List the network peers
  3. Tasks
    1. List tasks
  4. Services
    1. List all StorPool services
    2. List all blocked StorPool servers
  5. Servers
    1. List all disks on a server
    2. Describe a disk on a server
  6. Clients
    1. Get the current status of all the clients
    2. Wait until a client updates to the current configuration
    3. List all the active requests on a client
  7. Disks
    1. List all disks
    2. Describe a disk
    3. Get disk info
    4. Eject a disk
    5. Forget a disk
    6. Ignore a disk
    7. Soft-eject a disk
    8. Pause a disk's soft-eject operation
    9. Cancel a disk's soft-eject operation
    10. Set a disk's description
    11. List all the active requests on a disk
    12. Start scrubbing process
    13. Pause scrubbing process
    14. Continue paused scrubbing process
    15. Retrim disk
  8. Volumes
    1. List all volumes
    2. Get volume and snapshot status
    3. List total used space by each volume
    4. List a single volume
    5. Describe a volume
    6. Get volume info
    7. List the parent snapshots of a volume
    8. Create a new volume
    9. Update a volume
    10. Freeze a volume
    11. Rebase a volume
    12. Abandon disk
    13. Delete a volume
    14. Backup a volume to a remote location
    15. Backup a group of volumes to a remote location
  9. Snapshots
    1. List all snapshots
    2. List snapshots space estimations
    3. List a single snapshot
    4. Describe a snapshot
    5. Get snapshot info
    6. Snapshot a volume
    7. Update a snapshot
    8. Rebase a snapshot
    9. Abandon disk
    10. Delete a snapshot
    11. Delete a snapshot by global id
    12. Create consistent snapshots of a group of volumes
    13. Copy a snapshot from a remote location
    14. Allow a remote location to access a local snapshot
    15. Revoke a remote location's access to a local snapshot
    16. List exported snapshots
    17. List the available remote snapshots
    18. Instruct the remote location that we will no longer use those snapshots
  10. Attachments
    1. List all attachments
    2. Reassign volumes and/or snapshots
    3. Reassign volumes and/or snapshots with confirmation from the clients
  11. Placement Groups
    1. List all placement groups
    2. Describe a single placement group
    3. Create and/or update a placement group
    4. Delete a placement group
    5. List all fault sets
  12. Volume Templates
    1. List all volume templates
    2. List the status of all volume templates
    3. Describe a single volume template
    4. Create a volume template
    5. Update a volume template
    6. Delete a volume template
  13. Volume Relocator
    1. Get the relocator's status
    2. List total per disk relocation estimates
    3. List per disk relocation estimates for a given volume
    4. List per disk relocation estimates for a given snapshot
  14. Balancer
    1. Get the balancer's status
    2. Set the balancer's status
    3. List balancer volume and snapshot status
    4. List total per disk rebalancing estimates
    5. List per disk rebalancing estimated for a given volume
    6. List per disk rebalancing estimates for a given snapshot
    7. Get the disk sets computed by the balancer for a given volume
    8. Get the disk sets computed by the balancer for a given snapshot
    9. List balancer allocation groups
  15. iSCSI
    1. Get the StorPool iSCSI configuration
    2. Modify the StorPool iSCSI configuration
  16. Remote
    1. List the registered remote locations
  17. Data Types

General

The StorPool API can be used with any tool that can generate HTTP requests with the GET and POST methods. The only requirement is to supply the Authorization header and, if required by the request, valid JSON data.

For each call there is an explanation of the HTTP request and response and an example in raw format as it should be sent to the StorPool management service.

Here are two examples using curl using the GET and POST methods respectively and their counterparts as issued by the StorPool CLI:

curl -H "Authorization: Storpool v1:1556129910218014736" 192.168.42.208:81/ctrl/1.0/DisksList
storpool disk list


curl -d '{"addDisks":["1"]}' -H "Authorization: Storpool v1:1556129910218014736" 192.168.42.208:81/ctrl/1.0/PlacementGroupUpdate/hdd
storpool placementGroup hdd addDisk 1

Python programs may use the API by importing the Python StorPool bindings (use 'pypi install storpool' to install them):

# Use the default StorPool configuration settings

>>>import spapi
>>>api=spapi.Api.fromConfig()

# Use an already-created spconfig.SPConfig object
>>>api=spapi.Api.fromConfig(cfg=cfg)

# Explicitly specify the hostname, port, and authentication string
>>>api=spapi.Api(host='192.168.0.5', port=80, auth='1556560560218011653')

# Use the created API access object
>>>api.peersList()

{
  1: {
       'networks': {
         0: {
          'mac': '00:4A:E6:5F:34:C3'
         }
       }
  },
  2: {
       'networks': {
         0: {
          'mac': '52:54:E6:5F:34:DF'
         }
       }
  },
  3: {
        'networks': {
          0: {
           'mac': '52:57:5F:54:E6:3A'
          }
        }
  }
}

The calls that may be used may be found in the file spapi.py

Note: Requests will sometimes use GET instead of POST and consequently, will not require JSON. Responses on the other hand always produce JSON content.

Peers

List the network peers (NetworkPeersList)

List the network nodes running the StorPool beacon including information such as the ID of the node, the networks it communicates through and the corresponding MAC addresses.

  1. Request:
  2. Response:

Tasks

List tasks (TasksList)

List the currently active recovery tasks. This call will return JSON data only when there is a relocation in progress. Under normal operation of the cluster it will return no data.

  1. Request:
  2. Response:

Services

List all StorPool services (ServicesList)

List all the services in the cluster (StorPool servers, clients, management, etc). If the whole cluster is not operational this call will return an error.

  1. Request:
  2. Response:

List all blocked StorPool servers (ServersListBlocked)

List the currently active StorPool servers even before the cluster has become operational, along with information about any missing disks that the cluster is waiting for.

  1. Request:
  2. Response:

Servers

List all disks on a server (ServerDisksList)

Return detailed information about each disk on the given server.

  1. Request:
  2. Response:

Describe a disk on a server (ServerDiskDescribe)

Return detailed information about a disk on the given server and the objects on it.

  1. Request:
  2. Response:

Clients

Get the current status of all the clients (ClientsConfigDump)

Return the status of each client including its current generation and generation update status.

  1. Request:
  2. Response:

Wait until a client updates to the current configuration (ClientConfigWait)

Return the same JSON as ClientsConfigDump but block until the client has updated its configuration information to the current generation at the time of the request.

  1. Request:
  2. Response:

List all the active requests on a client (ClientActiveRequests)

List detailed information about the requests being currently processed on the given client.

  1. Request:
  2. Response:

Disks

List all disks (DisksList)

  1. Request:
  2. Response:

Describe a disk (DiskDescribe)

List all disks including detailed information about the objects on each disk.

  1. Request:
  2. Response:

Get disk info (DiskGetInfo)

List all disks including information about the volumes stored on each disk.

  1. Request:
  2. Response:

Eject a disk (DiskEject)

Stop operations on the given disk even if it is not empty.

  1. Request:
  2. Response:

Forget a disk (DiskForget)

Remove the disk from any placement groups or volumes that it is used in.

  1. Request:
  2. Response:

Ignore a disk (DiskIgnore)

Try to boot the cluster by ignoring this disk.

  1. Request:
  2. Response:

Soft-eject a disk (DiskSoftEject)

Stop writes to the given disk and start relocating all the data stored on it to other disks.

  1. Request:
  2. Response:

Pause a disk's soft-eject operation (DiskSoftEjectPause)

Temporarily pause the relocation tasks for the disk. This can be helpful in heavy load situations.

  1. Request:
  2. Response:

Cancel a disk's soft-eject operation (DiskSoftEjectCancel)

Stop the relocation tasks for the disk and mark it as usable again. After this operation data will be moved back to the disk.

  1. Request:
  2. Response:

Set a disk's description (DiskSetDescription)

  1. Request:
  2. Response:

List all the active requests on a disk (DiskActiveRequests)

List detailed information about the requests being currently processed on the given disk.

  1. Request:
  2. Response:

Start scrubbing process (DiskScrubStart)

  1. Request:
  2. Response:

Pause scrubbing process (DiskScrubPause)

  1. Request:
  2. Response:

Continue paused scrubbing process (DiskScrubContinue)

  1. Request:
  2. Response:

Retrim disk (DiskRetrim)

  1. Request:
  2. Response:

Volumes

List all volumes (VolumesList)

Return configuration information about all the volumes.

  1. Request:
  2. Response:

Get volume and snapshot status (VolumesGetStatus)

Return the status of each volume and snapshot.

  1. Request:
  2. Response:

List total used space by each volume (VolumesSpace)

List estimated total virtual space used by each volume.

  1. Request:
  2. Response:

List a single volume (Volume)

Same as VolumeList but only return information about a given volume.

  1. Request:
  2. Response:

Describe a volume (VolumeDescribe)

Return detailed information about the distribution of the volume's data on the disks.

  1. Request:
  2. Response:

Get volume info (VolumeGetInfo)

Return general information about the distribution of the volume's data on the disks.

  1. Request:
  2. Response:

List the parent snapshots of a volume (VolumeListSnapshots)

List a volume's parent snapshots in the same format as VolumeList

  1. Request:
  2. Response:

Create a new volume (VolumeCreate)

  1. Request:
  2. Response:

Update a volume (VolumeUpdate)

Alter the configuration of an existing volume.

  1. Request:
  2. Response:

Freeze a volume (VolumeFreeze)

Convert the volume to a snapshot

  1. Request:
  2. Response:

Rebase a volume (VolumeRebase)

Change the parent of the volume by choosing from the ones higher in the hierarchy or by rebasing it to no parent.

  1. Request:
  2. Response:

Abandon disk (VolumeAbandonDisk)

  1. Request:
  2. Response:

Delete a volume (VolumeDelete)

  1. Request:
  2. Response:

Backup a volume to a remote location (VolumeBackup)

  1. Request:
  2. Response:

Backup a group of volumes to a remote location (VolumesGroupBackup)

  1. Request:
  2. Response:

Snapshots

Snapshots in their essence are very similar to volumes in the sense that many operations supported by volumes are also supported by snapshots (all except write-related operations). They can not be modified and play an essential role in copy-on-write scenarios.

List all snapshots (SnapshotsList)

List all the snapshots in the cluster in the same format as VolumeList.

  1. Request:
  2. Response:

List snapshots space estimations (SnapshotsSpace)

List estimated virtual space used by each snapshot.

  1. Request:
  2. Response:

List a single snapshot (Snapshot)

Same as SnapshotList but only return information about a given snapshot.

  1. Request:
  2. Response:

Describe a snapshot (SnapshotDescribe)

Return detailed information about the distribution of the snapshot's data on the disks.

  1. Request:
  2. Response:

Get snapshot info (SnapshotGetInfo)

Return general information about the distribution of the snapshot's data on the disks.

  1. Request:
  2. Response:

Snapshot a volume (VolumeSnapshot)

Create a snapshot of the given volume; the snapshot becomes the parent of the volume.

  1. Request:
  2. Response:

Update a snapshot (SnapshotUpdate)

Alter the configuration of an existing snapshot.

  1. Request:
  2. Response:

Rebase a snapshot (SnapshotRebase)

Change the parent of the snapshot by choosing from the ones higher in the hierarchy or by rebasing it to no parent.

  1. Request:
  2. Response:

Abandon disk (VolumeAbandonDisk)

  1. Request:
  2. Response:

Delete a snapshot (SnapshotDelete)

  1. Request:
  2. Response:

Delete a snapshot by global id (SnapshotDeleteById)

  1. Request:
  2. Response:

Create consistent snapshots of a group of volumes (VolumesGroupSnapshot)

  1. Request:
  2. Response:

Copy a snapshot from a remote location (SnapshotFromRemote)

  1. Request:
  2. Response:

Allow a remote location to access a local snapshot (SnapshotExport)

  1. Request:
  2. Response:

Revoke a remote location's access to a local snapshot (SnapshotUnexport)

  1. Request:
  2. Response:

List exported snapshots (ExportsList)

  1. Request:
  2. Response:

List the available remote snapshots (SnapshotsRemoteList)

  1. Request:
  2. Response:

Instruct the remote location that we will no longer use those snapshots (SnapshotsRemoteUnexport)

  1. Request:
  2. Response:

Attachments

List all attachments (AttachmentsList)

List the volumes and snapshots currently attached to clients along with the read/write rights of each attachment.

  1. Request:
  2. Response:

Reassign volumes and/or snapshots (VolumesReassign)

Perform bulk attach/detach and attachment rights modification.

  1. Request:
  2. Response:

Reassign volumes and/or snapshots with confirmation from the clients (VolumesReassignWait)

Perform bulk attach/detach and attachment rights modification and waits for the clients to catch up.

  1. Request:
  2. Response:

Placement Groups

Placement groups provide a way to specify the disks on which a volume's data should be stored.

List all placement groups (PlacementGroupsList)

  1. Request:
  2. Response:

Describe a single placement group (PlacementGroupDescribe)

Same as PlacementGroupsList but only return information about a given group.

  1. Request:
  2. Response:

Create and/or update a placement group (PlacementGroupUpdate)

If a group by the specified name does not exist, it will be created.

  1. Request:
  2. Response:

Delete a placement group (PlacementGroupDelete)

  1. Request:
  2. Response:

List all fault sets (FaultSetsList)

  1. Request:
  2. Response:

Volume Templates

Templates are a set of rules used for creating many similar volumes.

List all volume templates (VolumeTemplatesList)

  1. Request:
  2. Response:

List the status of all volume templates (VolumeTemplatesStatus)

  1. Request:
  2. Response:

Describe a single volume template (VolumeTemplateDescribe)

Same as VolumeTemplatesList but only return information about a given template.

  1. Request:
  2. Response:

Create a volume template (VolumeTemplateCreate)

  1. Request:
  2. Response:

Update a volume template (VolumeTemplateUpdate)

Alter the configuration of an existing volume template.

  1. Request:
  2. Response:

Delete a volume template (VolumeTemplateDelete)

  1. Request:
  2. Response:

Volume Relocator

This is a service that moves data when needed, e.g. when removing or adding disks.

Get the relocator's status (VolumeRelocatorStatus)

  1. Request:
  2. Response:

List total per disk relocation estimates (VolumeRelocatorDisksList)

  1. Request:
  2. Response:

List per disk relocation estimates for a given volume (VolumeRelocatorVolumeDisks)

  1. Request:
  2. Response:

List per disk relocation estimates for a given snapshot (VolumeRelocatorSnapshotDisks)

  1. Request:
  2. Response:

Balancer

This is a service that decides when it is a good time to move data.

Get the balancer's status (VolumeBalancerStatus)

  1. Request:
  2. Response:

Set the balancer's status (VolumeBalancerStatus)

  1. Request:
  2. Response:

List balancer volume and snapshot status (VolumeBalancerVolumesStatus)

Show which volumes and snapshots will be reallocated by the current balancer run.

  1. Request:
  2. Response:

List total per disk rebalancing estimates (VolumeBalancerDisksList)

  1. Request:
  2. Response:

List per disk rebalancing estimated for a given volume (VolumeBalancerVolumeDisks)

  1. Request:
  2. Response:

List per disk rebalancing estimates for a given snapshot (VolumeBalancerSnapshotDisks)

  1. Request:
  2. Response:

Get the disk sets computed by the balancer for a given volume (VolumeBalancerVolumeDiskSets)

  1. Request:
  2. Response:

Get the disk sets computed by the balancer for a given snapshot (VolumeBalancerSnapshotDiskSets)

  1. Request:
  2. Response:

List balancer allocation groups (VolumeBalancerGroups)

  1. Request:
  2. Response:

iSCSI

Get the StorPool iSCSI configuration (iSCSIConfig)

  1. Request:
  2. Response:

Modify the StorPool iSCSI configuration (iSCSIConfig)

  1. Request:
  2. Response:

Remote

List the registered remote locations (LocationsList)

  1. Request:
  2. Response:

Data Types

"":The constant value "".
"-":The constant value "-".
"all":The constant value "all".
-1:The constant value -1.
0:The constant value 0.
AttachmentPos:integer, 0 <= value <= 1023
AttachmentRights:One of {"rw", "ro"}
BalancerCommand:One of {"start", "stop", "commit"}
BalancerStatus:One of {"nothing to do", "blocked", "waiting", "working", "ready", "commiting"}
Bandwidth:a positive integer or '-' for unlimited
BeaconClusterStatus:One of {"CNODE_DOWN", "CNODE_DAMPING", "CNODE_UP"}
BeaconNodeStatus:One of {"NODE_DOWN", "NODE_UP"}
BridgeId:integer, 1 <= value <= 4096
BridgeStatus:One of {"running", "joining", "down"}
ClientID:integer, 1 <= value <= 4096
ClientStatus:One of {"running", "down"}
ClusterStatus:One of {"running", "waiting", "down"}
DiskDescritpion:string, regex ^[A-Za-z0-9_\- ]{,30}$
DiskID:integer, 0 <= value <= 4095
DiskSoftEjectStatus:One of {"on", "off", "paused"}
GUID:string, regex ^0x[0-9a-fA-F]{2,16}$
Global Location Id:string, regex [a-z0-9]+$
Global Volume Id:string, regex [a-z0-9]+\.[a-z0-9]\.[a-z0-9]+$
IOPS:a positive integer or '-' for unlimited
MAC Address:string, regex ^([0-9a-fA-F]{2}:){5}[0-9a-fA-F]{2}$
MgmtID:integer, 1 <= value <= 4096
NetID:integer, 0 <= value <= 3
NodeID:integer, 0 <= value <= 63
ObjectState:ObjectState, enumeration from 0 to 9
PeerID:integer, 0 <= value <= 65535
PeerStatus:One of {"up", "down"}
PlacementGroupName:a string(128), matching ^[A-Za-z0-9_\-]+$, except {list}
RdmaState:One of {"Idle", "GidReceived", "Connecting", "Connected", "pendingError", "Error"}
RelocatorStatus:One of {"on", "off", "blocked"}
RemoteLocationName:a string(64), matching ^\#?[A-Za-z0-9_\-.:]+$, except {list}
Replication:integer, 1 <= value <= 3
RequestOp:One of {"read", "write", "merge", "system", "entries flush", "#bad_state", "#bad_drOp"}
ServerID:integer, 1 <= value <= 32767
ServerStatus:One of {"running", "waiting", "booting", "down"}
Size:a positive integer divisible by 512
SizeAdd:a positive integer divisible by 512
SnapshotName:a string(200), matching ^\*?[A-Za-z0-9_\-.:@]+$, except {list, status}
VolumeCurentStatus:One of {"up", "up soon", "data lost", "down"}
VolumeName:a string(200), matching ^\#?[A-Za-z0-9_\-.:]+$, except {list, status}
VolumeTagName:a string(200), matching ^[A-Za-z0-9_\-.:]+$, except {}
VolumeTagValue:a string(200), matching ^[A-Za-z0-9_\-.:]*$, except {}
VolumeTemplateName:a string(200), matching ^[A-Za-z0-9_\-]+$, except {list}
bool:true or false.
bool, default=false:A value of type bool. Default value = False.
client status:One of {"ok", "updating", "down"}
float:A floating point number.
iSCSIId:integer, 0 <= value <= 4095
int:An integer value.
long:A long integer value.
null:The constant value null.
str, default="^[A-Za-z0-9_\\-.:]+$":A value of type str. Default value = ^[A-Za-z0-9_\-.:]+$.
str, default="^[a-z0-9\\-.:]+$":A value of type str. Default value = ^[a-z0-9\-.:]+$.
str, default="exports":A value of type str. Default value = exports.
str, default="locations":A value of type str. Default value = locations.
str, default="snapshots":A value of type str. Default value = snapshots.
string:A string value.
true:The constant value true.