Returns cluster status.
Example JSON output::
{
"data": {
"status": "stopped",
"enabled": false
},
"error": null
}
Fields explanation:
- "status" - current cluster status:
- "stopped" - cluster services are not running
- "locked" - cluster locked reading state because it is changing
it's state from stopped to starting
- "starting" - cluster is being started
- "started" - cluster services are running
- "stopping" - cluster is being stopped
- "enabled" - Boolean flag that indicates if cluster should be started
on system boot. It tells if user requested cluster to start or not.
@return: Http code 200 on success.
N/A
Return default settings for corosync.
Example JSON output::
{
"data": {
"config_version": 1.0,
"crypto_cipher": "aes256",
"crypto_hash": "sha1",
"downcheck": 1000,
"expected_votes": 2,
"fail_recv_const": 2500,
"join": 50,
"max_messages": 17,
"max_network_delay": 50,
"mcastport": 5405,
"netmtu": 1500,
"provider": "corosync_votequorum",
"rrp_autorecovery_check_timeout": 1000,
"rrp_mode": "active",
"rrp_problem_count_timeout": 2000,
"secauth": "on",
"seqno_unchanged_const": 30,
"token": 1000,
"token_coefficient": 650,
"token_retransmits_before_loss_const": 4,
"transport": "udpu",
"two_nodes": 1,
"version": 2,
"window_size": 50
},
"error": null
}
Fields explanation:
- "config_version": version of configuration file used to prevent joining old nodes with not up-to-date configuration. Useful when we add new features which won't be backward compatible.
- "crypto_cipher": specifies which cipher should be used to encrypt all messages. Possible values: none, aes256, aes192, aes128 and 3des. Requires crypto_hash. Default: aes256.
- "crypto_hash": specifies which authentication should be used to authenticate all messages. Possible values: none, md5, sha1, sha256, sha384, sha512. Default: sha1.
- "downcheck": timeout in ms how long to wait before checking that a network interface is back up after it has been downed. Default: 1000 ms.
- "expected_votes": the expected votes value is used by cman to determine quorum.
- "fail_recv_const": specifies how many rotations of the token without receiving any of the messages when messages should be received may occur before a new configuration is formed. Default: 2500.
- "join": timeout in ms how long to wait for join messages in the membership protocol. Default: 50 ms.
- "max_messages": maximum number of messages that may be send by one processor holding token. Limited to 256000 / netmtu to prevent overflow of the kernel transmit buffers. Default: 17.
- "max_network_delay": the approximate delay that network takes to transport one packet from one machine to another. Too large value can break failure detection using heartbeat. Default: 50 ms.
- "mcastport": this specifies the UDP port number. It is possible to use the same multicast address on a network with the corosync services configured for different UDP ports. Please note corosync uses two UDP ports mcastport (for mcast receives) and mcastport - 1 (for mcast sends).
- "netmtu": network maximum transmit unit. Default: 1500. For large frames reccomended: MTU - 18.
- "provider": only corosync_votequorum is supported,
- "rrp_autorecovery_check_timeout": time in ms to check if the failed ring can be auto-recovered. Default: 1000 ms.
- "rrp_mode": mode of redundant ring, possible values: none, active, passive.
- "rrp_problem_count_timeout": timeout in ms to wait before decrementing the problem count by 1 for a particular ring to ensure a link is not marked faulty for transient network failures. Default: 2000.
- "secauth": disable encryption, possible values: on, off.
- "seqno_unchanged_const": specifies how many rotations of the token without any multicast traffic should occur before the hold timer is started. Default: 30
- "token": token loss timeout - this is the time spent detecting a failure of a processor in the current configuration. A new configuration takes about 50 ms (look at the membership protocol). Default: 1000 ms.
- "token_coefficient": used only when there are at least 3 nodes. Real token timeout is then computed as token + (number_of_nodes - 2) * token_coefficient. Used for scale token timeout every time new node is added. If set to 0 this feature is disabled. Default: 650 ms.
- "token_retransmits_before_loss_const": identifies how many token retransmits should be attempted before forming a new configuration. If set token_retransmit and hold options will be automatically calculated from retransmits_before_loss and token. Default: 4.
- "transport": transport mechanism used, possible values: udp, udpu, iba.
- "two_nodes": enables two node cluster operation.
- "version": must be set to 2,
- "window_size": maximum nuber of messages that may be sent on one rotation (sample values in man corosync.conf). Should not be larger than 256000 / netmtu. Default: 50.
@return: Http code 200 on success.
N/A
Get status of LDAP database synchronization between cluster nodes.
Example JSON output::
{
"data": {
"is_synchronized": True
},
"error": null
}
Fields description:
- "is_synchronized" - boolean flag that describes if LDAP database
is synchronized between nodes:
- true - databases are synchronized
- false - databases are not synchronized
- null - synchronization is not running (when cluster is stopped
it is not running)
@return: Http code 200 on success
N/A
Lists all nodes in cluster.
Example JSON output::
{
"data":
[
{
"localnode": false,
"status": null,
"hostname": "dssJ0000311",
"reachable": true,
"address": "192.168.251.54",
"id": "15615ae1"
},
{
"localnode": true,
"status": null,
"hostname": "dssJ0000312",
"reachable": true,
"address": "192.168.251.55",
"id": "d7e44639"
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Add node to the cluster.
Required JSON keys:
- "address" - string with the IP address of the remote node (e.g. ``192.168.251.54``).
- "password" - string with the password to the remote node (e.g. ``invalid``).
Example JSON input::
{
"address": "192.168.251.54",
"password": "invalid"
}
@return: Http code 200 on success.
{
"properties": {
"address": {
"type": "string"
},
"password": {
"type": "string"
}
},
"required": ["address", "password"]
}
Remove node from the cluster.
@param node_id: Identifier of node to delete (e.g. ``15615ae1``).
@type node_id: str
@return: Http code 201 on success.
N/A
Get data about certain node.
@param node_id: Identifier of node (e.g. ``15615ae1``).
@type node_id: str
Example JSON output::
{
"data":
{
"localnode": false,
"status": null,
"hostname": "dssJ0000311",
"reachable": true,
"address": "192.168.251.54",
"id": "15615ae1"
},
"error": null
}
@return: Http code 200 on success.
N/A
Get cluster state from given node.
@param node_id: Identifier of node.
@type node_id: str
@return: Http code 200 on success.
N/A
List FC targets from given node.
Example JSON output::
{
"data": [
{
"status": "OK",
"is_target_mode_enabled": false,
"is_hw_target": true,
"alias": null,
"parent_host": null,
"wwn": "21:00:00:0e:1e:2a:81:e0"
}
],
"error": null
}
@param node_id: ID of node for which FC targets will be listed.
@type node_id: str
@return: Http code 200 on success and list with all FC ports.
N/A
None
N/A
Lists NICs of a certain node.
@param node_id: Identifier of node (e.g. ``15615ae1``).
@type node_id: str
Example JSON output::
{
"data":
[
{
"status": "connected",
"negotiated_speed": 1000,
"name": "eth2",
"duplex": "Full",
"type": "interface",
"mac_address": "02:00:C0:A8:05:34",
"operational_state": "up",
"broadcast": null,
"netmask": "24",
"carrier": true,
"is_up": true,
"address": "192.168.2.220",
"model": "Intel Corporation 82540EM Gigabit Ethernet Controller (rev 03)",
"configuration": "static",
"speed": 1000,
"gateway": null
},
{
"status": "connected",
"name": "eth1",
"duplex": "Full",
"type": "interface",
"address": "15.15.15.54",
"operational_state": "up",
"negotiated_speed": 1000,
"netmask": "24",
"carrier": true,
"is_up": true,
"mac_address": "02:00:0F:0F:0F:36",
"model": "Intel Corporation 82540EM Gigabit Ethernet Controller (rev 03)",
"configuration": "dhcp",
"speed": 1000
},
{
"status": "connected",
"name": "eth0",
"duplex": "Full",
"type": "interface",
"address": "192.168.251.54",
"operational_state": "up",
"negotiated_speed": 1000,
"netmask": "20",
"carrier": true,
"is_up": true,
"mac_address": "02:00:C0:A8:FB:36",
"model": "Intel Corporation 82540EM Gigabit Ethernet Controller (rev 03)",
"configuration": "dhcp",
"speed": 1000
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Get data about certain interface of the given node.
@param node_id: Identifier of node (e.g. ``15615ae1``).
@type node_id: str
@param interface: Interface name (e.g. ``eth0``).
@type interface: str
Example JSON output::
{
"data":
{
"status": "connected",
"name": "eth0",
"duplex": "Full",
"type": "interface",
"address": "192.168.251.54",
"operational_state": "up",
"negotiated_speed": 1000,
"netmask": "20",
"carrier": true,
"is_up": true,
"mac_address": "02:00:C0:A8:FB:36",
"model": "Intel Corporation 82540EM Gigabit Ethernet Controller (rev 03)",
"configuration": "dhcp",
"speed": 1000
},
"error": null
}
@return: Http code 200 on success.
N/A
List pools of given node.
Example JSON output:
Pool with one mirror vdev that uses two disks::
{
"data": [
{
"name": "Pool-0",
"status": 24,
"health" : "ONLINE",
"scan": null,
"operation" : "none",
"iostats": {"read": "0", "write": "0", "chksum": "0"},
"vdevs": [
{
"name": "mirror-0",
"type": "mirror",
"health": "ONLINE",
"iostats": {"read": "0", "write": "0", "chksum": "0"},
"disks": [
{
"name": "sdb",
"id": "wwn-0x5000c5001c11581c",
"sn": "5VP1YAQQ",
"model": "ST31000528AS ",
"path": null,
"health": "ONLINE",
"size": 1000204886016,
"iostats": {"read": "0", "write": "0", "chksum": "0"},
"led": "off"
},
{
"name": "sdc",
"id" : "ata-ST3250310AS_9RY03FX0",
"sn" : "9RY03FX0",
"model" : "ST3250310AS ",
"path" : null,
"health" : "ONLINE",
"size" : 250059350016
"iostats": {"read": "0", "write": "0", "chksum": "0"},
"led": "off"
}
],
"vdev_replacings": [],
"vdev_spares": []
}
]
}
],
"error": null
}
@param node_id: Identifier of node (e.g. ``15615ae1``).
@type node_id: str
@return: Http code 200 on success.
N/A
Get data about pool that is present on given node.
Example JSON output:
Returned JSON is in the same format as for L{get_node_pools} except that
single pool object is returned instead of array with all pools.
@param node_id: Identifier of node (e.g. ``15615ae1``).
@type node_id: str
@param poolname: Name of pool for which data will be retrieved.
@type poolname: str
@return: Http code 200 on success.
N/A
Returns list of all ping nodes and their statuses on certain nodes.
Example JSON output::
{
"data":
[
{
"id": "192.168.251.16",
"statuses":
[
{
"status": "Unknown",
"node_id": "167f0ba7"
},
{
"status": "OK",
"node_id": "2b1c8848"
}
],
"address": "192.168.251.16"
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Add ping node to the cluster.
Example JSON input::
{
"address": "192.168.251.17"
}
@return: Http code 201 on success.
{
"properties": {
"address": {
"type": "string"
}
},
"required": ["address"]
}
Return status of certain ping node on this node.
Example JSON output::
{
"data":
{
"status": "Waiting",
"id": "192.168.251.16",
"address": "192.168.251.16"
},
"error": null
}
@return: Http code 200 on success.
N/A
Removes ping node from the cluster.
@param ping_node: Identifier of ping node (actually IP, e.g. ``192.168.251.17``).
@type ping_node: str
@return: Http code 204 on success.
N/A
Gets all remote disks paths.
Example JSON output::
{
"data": [
{
"interfaces": [
{
"interface": "eth0",
"node_id": "98f441f6",
"status": "ok"
},
{
"interface": "eth0",
"node_id": "bb2adfb7",
"status": "ok"
}
],
"id": 0
},
{
"interfaces": [
{
"interface": "eth1",
"node_id": "98f441f6",
"status": "ok"
},
{
"interface": "eth1",
"node_id": "bb2adfb7",
"status": "ok"
}
],
"id": 1
}
],
"error": null
}
Field explanation:
- "interfaces" - list of interfaces used on each node,
- "interface" - interface name,
- "node_id" - node id where interface is present,
- "status" - path status, possible values: N/A, Ok, Failed, Unknown
- "id" - path id.
@return: Http code 200 on success.
N/A
Adds remote disk path to the cluster configuration.
Required JSON keys:
- "interface" - interface name,
- "node_id" - node id where interface is present.
Example JSON input::
{
"interfaces": [
{
"interface": "eth1",
"node_id": "bb2adfb7"
},
{
"interface": "eth1",
"node_id": "98f441f6"
}
]
}
Example JSON output::
{
"data": null,
"error": null
}
@return: Http code 200 on success, 500 on failure.
{
"properties": {
"interfaces": {
"type": "array",
"items": {
"properties": {
"node_id": {
"type": "string"
},
"interface": {
"type": "string"
}
},
"required": ["node_id", "interface"]
},
"minItems": 2,
"maxItems": 2,
"uniqueItems": true
}
},
"required": ["interfaces"]
}
Gets path configuration.
@param path_id: path id.
@type path_id: integer
Example JSON output::
{
"data": {
"interfaces": [
{
"interface": "eth0",
"node_id": "98f441f6",
"status": "ok"
},
{
"interface": "eth0",
"node_id": "bb2adfb7",
"status": "ok"
}
],
"id": 0
},
"error": null
}
Field explanation:
- "interfaces" - list of interfaces used on each node,
- "interface" - interface name,
- "node_id" - node id where interface is present,
- "status" - path status, possible values: N/A, Ok, Failed, Waiting
- "id" - path id.
@return: Http code 200 on success.
N/A
Deletes remote disk path.
@param path_id: path id.
@type path_id: integer
Example JSON output::
{
"data": null,
"error": null
}
@return: Http code 200 on success, 500 on failure.
N/A
Returns data about all ZFS pools provided by cluster.
Example JSON output::
{
"data": [
{
"managed": true,
"name": "Pool-0",
"node_id": "389d55bb",
"pool_id": "10756046862619325340",
"status": "started"
},
{
"managed": false,
"name": "Pool-1",
"node_id": "389d55bb",
"pool_id": "17125258861533269582",
"status": "started"
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Moves ZFS pool and its resource to another node.
@param resource_name: Name of the zpool that's going to be moved (e.g. ``PoolA``).
@type resource_name: str
Required JSON keys:
- "node_id" - str with identifier of remote node.
Example JSON input::
{
"node_id": "167f0ba7"
}
@return: Http code 200 on success.
{
"properties": {
"node_id": {
"type": "string"
}
},
"required": ["node_id"]
}
Return data about given ZFS pool, provided by this node.
@param pool_name: Name of the pool (e.g. ``PoolA``).
@type pool_name: str
Example JSON output::
{
"data": {
"managed": true,
"name": "Pool-0",
"node_id": "389d55bb",
"pool_id": "10756046862619325340",
"status": "started"
},
"error": null
}
@return: Http code 200 on success.
N/A
Gets all rings configured within the cluster.
Example JSON output::
{
"data": [
{
"status": "ok",
"interfaces": [
{
"interface": "eth0",
"node_id": "98f441f6"
},
{
"interface": "eth0",
"node_id": "bb2adfb7"
}
],
"id": 0
},
{
"status": "ok",
"interfaces": [
{
"interface": "eth1",
"node_id": "98f441f6"
},
{
"interface": "eth1",
"node_id": "bb2adfb7"
}
],
"id": 1
}
],
"error": null
}
Field explanation:
- "status" - ring status, possible values: n/a, faulty, ok
- "interfaces" - list of interfaces used on each node,
- "interface" - interface name,
- "node_id" - node id where interface is present,
- "id" - ring id.
@return: Http code 200 on success.
N/A
Adds new ring to the cluster configuration.
Required JSON keys:
- "interface" - interface name,
- "node_id" - node id where interface is present.
Example JSON input::
{
"interfaces": [
{
"interface": "eth1",
"node_id": "bb2adfb7"
},
{
"interface": "eth1",
"node_id": "98f441f6"
}
]
}
Example JSON output::
{
"data": null,
"error": null
}
Example JSON output 2::
{
"data": null,
"error": {
"class": "opene.cluster.rings.RingsPoolError",
"errno": 3,
"message": "Interface eth40 for node bb2adfb7 does not exist in cluster configuration.",
}
}
@return: Http code 200 on success, 500 on failure.
{
"properties": {
"interfaces": {
"type": "array",
"items": {
"properties": {
"node_id": {
"type": "string"
},
"interface": {
"type": "string"
}
},
"required": ["node_id", "interface"]
},
"minItems": 2,
"uniqueItems": true
}
},
"required": ["interfaces"]
}
Gets ring configuration.
@param ring_id: ring id.
@type ring_id: number
Example JSON output::
{
"data": {
"status": "ok",
"interfaces": [
{
"interface": "eth0",
"node_id": "98f441f6"
},
{
"interface": "eth0",
"node_id": "bb2adfb7"
}
],
"id": 0
},
"error": null
}
Field explanation:
- "status" - ring status, possible values: n/a, faulty, ok
- "interfaces" - list of interfaces used on each node,
- "interface" - interface name,
- "node_id" - node id where interface is present,
- "id" - ring id.
@return: Http code 200 on success.
N/A
Deletes ring.
@param ring_id: ring id.
@type ring_id: number
Example JSON output::
{
"data": null,
"error": null
}
Example JSON output 2::
{
"data": null,
"error": {
"class": "opene.cluster.rings.RingsPoolError",
"errno": 2,
"message": "Ring does not exist.",
]
}
}
@return: Http code 200 on success, 500 on failure.
N/A
Returns SCSI-3 Persistent Reservation Synchronization status.
Example JSON output::
{
"data": {
"status": "off",
"state": "off"
},
"error": null
}
Fields explanation:
- "status" - indicates if PRS is running, possible values:
"on" - PRS connection is established and running,
"off" - PRS connection is not established.
- "state" - indicates if PRS is registered in the system, possible values:
"on" - registered,
"off" - not registered.
@return: Http code 200 on success.
N/A
None
{
"properties": {
"device_name": {
"type": "string"
},
"lun_path": {
"type": "string"
},
"options": {
"properties": {
"read_only": {
"type": "integer"
},
"blocksize": {
"oneOf": [{
"type": "string"
}, {
"type": "integer"
}]
},
"write_through": {
"type": "integer"
},
"filesize": {
"type": "integer"
},
"thin_provisioned": {
"type": "integer"
}
},
"additionalProperties": false,
"required": ["blocksize"]
},
"prod_id": {
"type": "string"
},
"device_handler": {
"type": "string"
}
},
"required": ["device_name", "lun_path", "options"],
"additionalProperties": false
}
Refreshes iSCSI sysfs handlers.
Needed to establish SCSI-3 Persistent Reservation Synchronization.
Example JSON input::
Endpoint doesn't get any data.
@return: On successful refresh http code 200 is returned.
N/A
None
{
"properties": {
"handers_list": {
"type": "array"
}
},
"required": ["handers_list"],
"additionalProperties": false
}
Starts SCSI-3 Persistent Reservation Synchronization.
Required JSON keys:
- "cluster" - bool which indicates PRS start mode.
- true - establishes PRS among all nodes if cluster is registered,
if not then PRS will be only registered and stared when cluster starts.
- false - join mode for PRS.
Example JSON input::
{
"cluster": true
}
@return: On successful start http code 200 is returned.
{
"properties": {
"cluster": {
"type": "boolean"
}
},
"required": ["cluster"]
}
Stops SCSI-3 Persistent Reservation Synchronization.
Required JSON keys:
- "cluster" - bool which indicates PRS stop mode.
- true - teardowns PRS among all nodes if cluster is registered,
if not then PRS is just unregistered.
- false - local stop mode for PRS.
Example JSON input::
{
"cluster": true
}
@return: On successful stop http code 200 is returned.
{
"properties": {
"cluster": {
"type": "boolean"
}
},
"required": ["cluster"]
}
Get cluster options.
Example JSON output::
{
"data": {
"config_version": 1.0,
"crypto_cipher": "aes256",
"crypto_hash": "sha1",
"downcheck": 1000,
"expected_votes": 2,
"fail_recv_const": 2500,
"join": 50,
"max_messages": 17,
"max_network_delay": 50,
"mcastport": 5405,
"netmtu": 1500,
"provider": "corosync_votequorum",
"rrp_autorecovery_check_timeout": 1000,
"rrp_mode": "active",
"rrp_problem_count_timeout": 2000,
"secauth": "on",
"seqno_unchanged_const": 30,
"token": 1000,
"token_coefficient": 650,
"token_retransmits_before_loss_const": 4,
"transport": "udpu",
"two_nodes": 1,
"version": 2,
"window_size": 50
},
"error": null
}
Fields explanation:
- "config_version": version of configuration file used to prevent joining old nodes with not up-to-date configuration. Useful when we add new features which won't be backward compatible.
- "crypto_cipher": specifies which cipher should be used to encrypt all messages. Possible values: none, aes256, aes192, aes128 and 3des. Requires crypto_hash. Default: aes256.
- "crypto_hash": specifies which authentication should be used to authenticate all messages. Possible values: none, md5, sha1, sha256, sha384, sha512. Default: sha1.
- "downcheck": timeout in ms how long to wait before checking that a network interface is back up after it has been downed. Default: 1000 ms.
- "expected_votes": the expected votes value is used by cman to determine quorum.
- "fail_recv_const": specifies how many rotations of the token without receiving any of the messages when messages should be received may occur before a new configuration is formed. Default: 2500.
- "join": timeout in ms how long to wait for join messages in the membership protocol. Default: 50 ms.
- "max_messages": maximum number of messages that may be send by one processor holding token. Limited to 256000 / netmtu to prevent overflow of the kernel transmit buffers. Default: 17.
- "max_network_delay": the approximate delay that network takes to transport one packet from one machine to another. Too large value can break failure detection using heartbeat. Default: 50 ms.
- "mcastport": this specifies the UDP port number. It is possible to use the same multicast address on a network with the corosync services configured for different UDP ports. Please note corosync uses two UDP ports mcastport (for mcast receives) and mcastport - 1 (for mcast sends).
- "netmtu": network maximum transmit unit. Default: 1500. For large frames reccomended: MTU - 18.
- "provider": only corosync_votequorum is supported,
- "rrp_autorecovery_check_timeout": time in ms to check if the failed ring can be auto-recovered. Default: 1000 ms.
- "rrp_mode": mode of redundant ring, possible values: none, active, passive.
- "rrp_problem_count_timeout": timeout in ms to wait before decrementing the problem count by 1 for a particular ring to ensure a link is not marked faulty for transient network failures. Default: 2000.
- "secauth": disable encryption, possible values: on, off.
- "seqno_unchanged_const": specifies how many rotations of the token without any multicast traffic should occur before the hold timer is started. Default: 30
- "token": token loss timeout - this is the time spent detecting a failure of a processor in the current configuration. A new configuration takes about 50 ms (look at the membership protocol). Default: 1000 ms.
- "token_coefficient": used only when there are at least 3 nodes. Real token timeout is then computed as token + (number_of_nodes - 2) * token_coefficient. Used for scale token timeout every time new node is added. If set to 0 this feature is disabled. Default: 650 ms.
- "token_retransmits_before_loss_const": identifies how many token retransmits should be attempted before forming a new configuration. If set token_retransmit and hold options will be automatically calculated from retransmits_before_loss and token. Default: 4.
- "transport": transport mechanism used, possible values: udp, udpu, iba.
- "two_nodes": enables two node cluster operation.
- "version": must be set to 2,
- "window_size": maximum nuber of messages that may be sent on one rotation (sample values in man corosync.conf). Should not be larger than 256000 / netmtu. Default: 50.
@return: Http code 200 on success.
N/A
Set cluster options.
Required JSON keys:
- any property, at least one is required.
Optional JSON keys:
- "config_version": version of configuration file used to prevent joining old nodes with not up-to-date configuration. Useful when we add new features which won't be backward compatible.
- "crypto_cipher": specifies which cipher should be used to encrypt all messages. Possible values: none, aes256, aes192, aes128 and 3des. Requires crypto_hash. Default: aes256.
- "crypto_hash": specifies which authentication should be used to authenticate all messages. Possible values: none, md5, sha1, sha256, sha384, sha512. Default: sha1.
- "downcheck": timeout in ms how long to wait before checking that a network interface is back up after it has been downed. Default: 1000 ms.
- "expected_votes": the expected votes value is used by cman to determine quorum.
- "fail_recv_const": specifies how many rotations of the token without receiving any of the messages when messages should be received may occur before a new configuration is formed. Default: 2500.
- "join": timeout in ms how long to wait for join messages in the membership protocol. Default: 50 ms.
- "max_messages": maximum number of messages that may be send by one processor holding token. Limited to 256000 / netmtu to prevent overflow of the kernel transmit buffers. Default: 17.
- "max_network_delay": the approximate delay that network takes to transport one packet from one machine to another. Too large value can break failure detection using heartbeat. Default: 50 ms.
- "mcastport": this specifies the UDP port number. It is possible to use the same multicast address on a network with the corosync services configured for different UDP ports. Please note corosync uses two UDP ports mcastport (for mcast receives) and mcastport - 1 (for mcast sends).
- "netmtu": network maximum transmit unit. Default: 1500. For large frames reccomended: MTU - 18.
- "provider": only corosync_votequorum is supported,
- "rrp_autorecovery_check_timeout": time in ms to check if the failed ring can be auto-recovered. Default: 1000 ms.
- "rrp_mode": mode of redundant ring, possible values: none, active, passive.
- "rrp_problem_count_timeout": timeout in ms to wait before decrementing the problem count by 1 for a particular ring to ensure a link is not marked faulty for transient network failures. Default: 2000.
- "secauth": disable encryption, possible values: on, off.
- "seqno_unchanged_const": specifies how many rotations of the token without any multicast traffic should occur before the hold timer is started. Default: 30
- "token": token loss timeout - this is the time spent detecting a failure of a processor in the current configuration. A new configuration takes about 50 ms (look at the membership protocol). Default: 1000 ms.
- "token_coefficient": used only when there are at least 3 nodes. Real token timeout is then computed as token + (number_of_nodes - 2) * token_coefficient. Used for scale token timeout every time new node is added. If set to 0 this feature is disabled. Default: 650 ms.
- "token_retransmits_before_loss_const": identifies how many token retransmits should be attempted before forming a new configuration. If set token_retransmit and hold options will be automatically calculated from retransmits_before_loss and token. Default: 4.
- "transport": transport mechanism used, possible values: udp, udpu, iba.
- "two_nodes": enables two node cluster operation.
- "version": must be set to 2,
- "window_size": maximum nuber of messages that may be sent on one rotation (sample values in man corosync.conf). Should not be larger than 256000 / netmtu. Default: 50.
Example JSON input::
{
"config_version": 1.0,
"crypto_cipher": "aes256",
"crypto_hash": "sha1",
"downcheck": 1000,
"expected_votes": 2,
"fail_recv_const": 2500,
"join": 50,
"max_messages": 17,
"max_network_delay": 50,
"mcastport": 5405,
"netmtu": 1500,
"provider": "corosync_votequorum",
"rrp_autorecovery_check_timeout": 1000,
"rrp_mode": "active",
"rrp_problem_count_timeout": 2000,
"secauth": "on",
"seqno_unchanged_const": 30,
"token": 1000,
"token_coefficient": 650,
"token_retransmits_before_loss_const": 4,
"transport": "udpu",
"two_nodes": 1,
"version": 2,
"window_size": 50
}
@return: On successful config creation http code 201 is returned.
{
"properties": {
"version": {
"type": "number"
},
"secauth": {
"type": "string"
},
"netmtu": {
"type": "number"
},
"crypto_cipher": {
"type": "string"
},
"expected_votes": {
"type": "number"
},
"mcastport": {
"type": "number"
},
"token_retransmits_before_loss_const": {
"type": "number"
},
"max_network_delay": {
"type": "number"
},
"transport": {
"type": "string"
},
"max_messages": {
"type": "number"
},
"crypto_hash": {
"type": "string"
},
"window_size": {
"type": "number"
},
"two_nodes": {
"type": "number"
},
"fail_recv_const": {
"type": "number"
},
"seqno_unchanged_const": {
"type": "number"
},
"provider": {
"type": "string"
},
"token_coefficient": {
"type": "number"
},
"config_version": {
"type": "number"
},
"downcheck": {
"type": "number"
},
"rrp_autorecovery_check_timeout": {
"type": "number"
},
"rrp_mode": {
"type": "string"
},
"join": {
"type": "number"
},
"rrp_problem_count_timeout": {
"type": "number"
},
"token": {
"type": "number"
}
}
}
Starts cluster in different modes.
Required JSON keys:
- "mode" - cluster start mode, possible values:
- "cluster" - starts cluster services on all nodes,
- "join" - joins local node to the already running cluster,
- "local" - starts cluster service locally (the other node presence is not required).
Example JSON input::
{
"mode": "cluster"
}
@return: On successful start http code 200 is returned.
{
"properties": {
"mode": {
"enum": ["cluster", "join", "local"]
},
"force": {
"type": "boolean"
}
},
"required": ["mode"]
}
Stops cluster in different modes.
Required JSON keys:
- "mode" - cluster stop mode, possible values:
- "cluster" - stops cluster services on all nodes,
- "local" - stops cluster service on local node only (other nodes are stopping too),
- "node" - stops cluster service on local node only and moves resources to the available nodes
Example JSON input::
{
"mode": "cluster"
}
@return: On successful stop http code 200 is returned.
{
"properties": {
"mode": {
"enum": ["cluster", "local", "node"]
}
},
"required": ["mode"]
}
Updates cache data about remote node NICs.
Required JSON keys:
- "node_id" - string with the identifier of the remote node to be deleted (e.g. ``15615ae1``).
- "network_configuration" - array of objects with configurations of certain NICs.
Example JSON input::
{
"node_id": "15615ae1",
"network_configuration": [
{
"status": "connected",
"broadcast": null,
"name": "eth0",
"duplex": "Full",
"speed": 1000,
"address": "192.168.2.220",
"operational_state": "up",
"negotiated_speed": 1000,
"netmask": "24",
"carrier": true,
"is_up": true,
"mac_address": "02:00:C0:A8:05:35",
"model": "Intel Corporation 82540EM Gigabit Ethernet Controller (rev 03)",
"configuration": "static",
"type": "interface",
"gateway": null
}
]
}
@return: Http code 201 on success.
{
"properties": {
"node_id": {
"type": "string"
},
"network_configuration": {
"type": "array"
}
},
"required": ["node_id", "network_configuration"]
}
None
N/A
None
N/A
None
{
"oneOf": [{
"properties": {
"availability": {
"type": "string",
"enum": ["unlocked", "locked"]
}
},
"required": ["availability"],
"additionalProperties": false
}, {
"properties": {
"availability": {
"type": "string",
"enum": ["locked-by-passwd"]
},
"passwd": {
"type": "string",
"maximum": 255,
"minimum": 0
}
},
"required": ["availability", "passwd"],
"additionalProperties": false
}]
}
Get all disks present in system.
Example JSON output::
{
"data": [
{
"name": "sda",
"id": "ata-ST3250410AS_9RY05WFW",
"model": "ST3250410AS ",
"sn": "9RY05WFW",
"path": null,
"used": true,
"assignment": "system_disk",
"pool_name": null,
"size": 250059350016,
"led": {"locate": False, "fault": True},
"spare": [],
"type": "single",
"origin": "local"
},
{
"name": "sdf",
"id": "scsi-0QEMU_QEMU_HARDDISK_drive-scsi0-0-5",
"model": "QEMU HARDDISK ",
"sn": "",
"path": "pci-0000:00:06.0-scsi-0:0:5:0",
"used": false,
"assignment": "free_disk",
"pool_name": null,
"size": 10737418240,
"led": {"locate": False, "fault": True},
"spare": [],
"type": "single",
"origin": "local"
},
{
"origin": "local",
"pool_name": null,
"used": true,
"led": {"locate": False, "fault": True},
"name": "nvme0n1",
"spares": [],
"assignment": "partitioned_for_cache_log",
"sn": "S33WNX0J805447",
"path": null,
"model": "SAMSUNG MZVLW128",
"size": 128035676160,
"type": "nvme",
"id": "nvme-S33WNX0J805447",
"partitions": [
{
"pool_name": "Pool-0",
"used": true,
"name": "Partition 1",
"assignment": "active_pool_disk",
"number": 1,
"device_name": "nvme0n1p1",
"id": "nvme-S33WNX0J805447-part1",
"size": 11811160064
}
],
}
"error" : null
}
Disk fields description:
- "used" - bool flag that indicates if disk is used by any pool or
system
- "assignment" - explains where disk is used:
- "active_pool_disk" - disk is part of active pool
- "exported_pool_disk" - disk is part of exported (inactive) pool
- "system_disk" - system that is currently running is installed on
this disk
- "free_disk" - disk is not used by any pool or system
- "partitioned_for_cache_log" - NVMe disk that is partitioned,
those partitions can be used as cache or log devices in a pool
- "pool_name" - name of pool to which disk belongs or null if disk
isn't used
- "size" - size in bytes
- "spare" - array containing names of pools where disk is used as a
spare, this array contains items only if disk is used as a spare;
Currently system doesn't allow to assign same spare disk to more than
one pool and because of that this array might have at most one item. On
the other hand zfs allow to assign same disk as spare to many pools.
This feature is currently unused.
- "sn" - disk serial number, it might be empty string if it is not
possible to read disk serial number for any reason
- "path" - disk path in, it might be set to null in many cases because
this data is usually not available
- "led" - Indicates if disk identification or fault indication should
be enabled or disabled. Field must be a dictionary with keys: "locate"
and "fault" set to a boolean value.
- "type" - type of disk device:
- "single" - one single disk
- "multipath" - disk with multipath configuration
- "origin" - origin of the device:
- "local" - local disk
- "iscsi" - disk connected via iSCSI Initiator
- "partitions" - List of partitions present on the NVMe disk, non NVMe
disks has this list empty even if actual partitions are present in the
system. Each partition contains following fields:
- "id" - ID of partition used to identify it, this ID have to be
passed to the REST API for example to create pool that use
NVMe partition as cache or log device.
- "name" - Text description of the partition.
- "device_name" - Name of partition device in /dev like "nvme0n1p1"
- "size" - Size of the partition in bytes.
- "number" - Partition number.
- "used" - The same as for disk, flag indicating if partition is
in use.
- "assignment" - The same as for disk, explains where partition is
used:
- "free_disk" - Partition is not used by any pool.
- "active_pool_disk" - Partition is used by active pool disk.
- "exported_pool_disk" - Partition is used by exported pool.
- "pool_name" - The same as for disk, name of pool that uses
partition or null if partition is not used by any pool
@return: Http code 200 on success.
N/A
Get data about disk with given ID.
Example JSON output::
{
"data": {
"name": "sdf",
"id": "scsi-0QEMU_QEMU_HARDDISK_drive-scsi0-0-5",
"model": "QEMU HARDDISK ",
"sn": "",
"path": "pci-0000:00:06.0-scsi-0:0:5:0",
"size": 10737418240,
"led": {"locate": False, "fault": True},
"type": "single",
"origin": "local"
},
"error" : null
}
@param disk_id: ID of disk to list.
@type disk_id: str
@return: Http code 200 on success.
N/A
Enable or disable disk identification.
Optional JSON keys:
- "led" - Indicates if disk identification or fault indication should
be enabled or disabled. Field must be a dictionary with keys: "locate"
and "fault" set to a boolean value.
Example JSON input::
{
"led": {
"locate": True,
"fault": False
}
}
@param disk_id: ID of disk to modify.
@type disk_id: str
@return: Http code 204 on success.
{
"properties": {
"led": {
"type": "object",
"properties": {
"locate": {
"type": "boolean"
},
"fault": {
"type": "boolean"
}
}
}
},
"required": ["led"]
}
Create partitions on NVMe device for use as zfs cache or log devices.
It is possible to request creation of single partition by providing single
configuration or to request creation of multiple partitions by providing
array of partition configurations.
Required JSON keys:
- "number" - Number of partition to create, it have to be unique for
particular disk.
- "size" - Size of the partition, it is possible to provide size as
integer representing number of bytes or as string with suffix for unit.
For example to create partition in size of 50 GiB simply supply as size
string "50G". Supported suffixes are K, M, G, T, P.
Optionsal JSON keys:
- "name" - Optional string with partition description saved in
partition table.
Example JSON input for single partition::
{
"number": 1,
"size": "50G",
"name": "Partition for Pool-0 cache.
}
Example JSON input for multiple partitions::
[
{
"number": 1,
"size": "50G",
"name": "Partition for Pool-0 cache.
},
{
"number": 2,
"size": "50G",
"name": "Partition for Pool-0 log.
}
]
@param disk_id: ID of the disk on which partitions will be created.
@type disk_id: str
@return: Http code 204 on success.
N/A
Remove all partitions form the disk.
@param disk_id: ID of the disk on which partitions will be removed.
@type disk_id: str
@return: Http code 204 on success.
N/A
Get SED disk data for disk with given ID.
Example JSON output::
{
"data": {
"id": "scsi-SQEMU_QEMU_HARDDISK_66272-6",
"is_sed_supported": false,
"is_locked": null
},
"error": null
}
Fields used in by SED disk has the same format and meaning as described in
L{get_sed_disks}.
@param disk_id: ID of the disk to fetch SED data.
@type disk_id: str
@return: Http code 200 on success.
N/A
None
N/A
If the device identified by 'disk_id' supports SED, reverts the device to
factory defaults, which:
- Erases ALL data from the device,
- Unlocks the device.
POST:/api/v3/disks//sed/revert_to_factory_defaults
Example JSON input:
{
"PSID": "1ATL6GTY0R2RH4SHLKJP3624X30O031M"
}
Fields:
- PSID: Physical Secure ID printed on the disk label, unique to each drive.
Must be provided using only capital letters with no dashes.
{
"properties": {
"PSID": {
"type": "string"
}
},
"required": ["PSID"]
}
Inform the operating system about partition table changes.
@return: Http code 201 on success.
{
"properties": {
"discard_zdb_labels": {
"oneOf": [{
"type": "array",
"items": {
"type": "string"
}
}, {
"type": "null"
}]
},
"clear_zdb_labels": {
"oneOf": [{
"type": "array",
"items": {
"type": "string"
}
}, {
"type": "null"
}]
}
}
}
Rescan all SCSI devices in system.
New SCSI devices will be registered and those that are not available any
more will be unregistered.
@return: Http code 204 on success.
N/A
Get SED disk data for all disks in the system.
Example JSON output::
{
"data": [
{
"id": "scsi-SQEMU_QEMU_HARDDISK_66272-6",
"is_sed_supported": false,
"is_locked": null
},
{
"id": "scsi-SQEMU_QEMU_HARDDISK_66272-5",
"is_sed_supported": false,
"is_locked": null
}
]
}
Fields description:
- "id" - ID of the disk.
- "is_sed_supported" - Boolean flag that indicates if given disk
supports SED (true) or not (false).
- "is_locked" - Boolean flag that indicates if disk is locked (true)
or unlocked (false). This field is set to null if disk does not support
SED.
@return: Http code 200 on success.
N/A
List disks that isn't used in any pool.
Example JSON output:
Array with disks in same format as in L{get_all_disks_from_system}.
Array will contain only disks that isn't used in any active or exported
pool. Also system disk won't be listed in this array - all items will have
field "used" set to false.
@return: Http code 200 on success.
N/A
Get disk used by pools or system.
Example JSON output:
Array with disks in same format as in L{get_all_disks_from_system}.
Array will contain only disks that are used in any active or exported pool
or as disk used by system. All items will have field "used" set to true.
@return: Http code 200 on success.
N/A
Some of the endpoints in the system use a 'query' URL parameter. This parameter is used
to filter a collection of elements for the purpose of retrieving or deleting those elements.
The value for this parameter should be a JSON document consistent with following syntax:
{
"": , // Only match entries that have this exact value for the given key
"": { "": } // Match entries that match a condition specified by he operator
...
}
Examples:
1. Simple query 1 - match only entries that have key "name" equal to the value "Pool-1"
{
"name": "Pool-1"
}
2. Simple query 2 - match only entries that have BOTH of the following fields match the specfied values.
{
"name": "Dataset",
"read_only": true
}
3. Simple query 3 - match on a nested key. If the entries have a "operation" key that itself
is an object with key "status", then the following query will match on the "status" nested inside of
the "operation".
{
"operation.status": "running"
}
4. Complex query 1 - match keys where a key is greater than a set value
{
"time": { "$gt": 167890000 }
}
5. Complex query 2 - match a range of values
{
"status": {"$in": ["stopped", "failed"]}
}
6. Complex query 3 - combine the above methods. Retrieve entries with "SITE-1" in the name,
and "read_only" nested inside "options" set to false.
{
"name": { "$regex": "SITE-1"}
"options.read_only": false
}
List of useful operators:
$eq - matches a specific value( { "$eq": 1234 } )
$ne - matches values not equal to a specific value
$gt - matches values that are greater than some other value
$gte - matches values that are greater than or equal to some other value
$lt - matches values that are greater than some other value
$lte - matches values that are greater than or equal to some other value
$regex - retrieves entries with a text value matching a regular expression ( {"$regex": "search_string"} )
$in - matches values in a list ( {"$in": ["a", "b"]} )
$nin - matches values not in a list
N/A
None
N/A
None
N/A
None
N/A
None
N/A
None
N/A
None
N/A
Creates group in given backend.
Example JSON input:
{
"name": "newuser",
"backend": "AD"
}
Fields:
- 'name' - group name
- 'backend' - authentication backend to use
@return: Http code 201 on success.
{
"properties": {
"name": {
"type": "string"
},
"backend_name": {
"type": "string"
}
},
"required": ["name", "backend_name"],
"additionalProperties": false
}
Example JSON output::
{
"data":{
results : 2,
entries : [
{
"gid" : 1000,
"backend" : "LDAP",
"name" : "Administrators"
},
{
"gid" : 1001,
"backend" : "LDAP",
"name" : "Users"
}
]
},
"error":null
}
@return: Http code 200 on success.
N/A
Example JSON output::
{
"data":{
"id" : 1,
"name" : "Administrators",
"entries_no" : 20000
},
"error":null
}
@return: Http code 200 on success.
N/A
Deletes group from given backend.
Example JSON input:
{
"backend": "AD"
}
Fields:
- 'backend' - authentication backend to use
@return: Http code 204 on success.
N/A
Example JSON output::
@return: Http code 200 on success.
N/A
Example JSON input::
{
"users": ["user1","user2"],
"backend": "LDAP"
}
Fields:
- 'users' - list of users to add
- 'backend' - authentication backend to use
@return: Http code 204 on success.
{
"properties": {
"users": {
"type": "array"
},
"backend_name": {
"type": "string"
}
},
"required": ["users", "backend_name"],
"additionalProperties": false
}
Example JSON input::
{
"users": ["user1","user2"],
"backend": "LDAP"
}
Fields:
- 'users' - list of users to remove
- 'backend' - authentication backend to use
@return: Http code 204 on success.
{
"properties": {
"users": {
"type": "array"
},
"backend_name": {
"type": "string"
}
},
"required": ["users", "backend_name"],
"additionalProperties": false
}
Lists all active (already applied and used in product) extension keys.
N/A
Lists all active (already applied and used in product) extension keys.
N/A
Returns info about given extension key.
N/A
Apply given extension key in product.
{
"properties": {
"key": {
"type": "string"
}
},
"required": ["key"]
}
Validate if given extension key is correct.
{
"properties": {
"key": {
"type": "string"
},
"pk": {
"type": "string"
}
},
"required": ["key", "pk"]
}
Returns already used product key.
N/A
Apply given product key in product.
{
"properties": {
"key": {
"type": "string"
}
},
"required": ["key"]
}
Validate if given product key is correct.
{
"properties": {
"key": {
"type": "string"
}
},
"required": ["key"]
}
List events from errors.db
Parameters passed to GET:
- GET /logs?_dc=1407325895155&page=1&start=0&limit=50 HTTP/1.1" 200
NOTE: filter in code is equal to page.
- errors - allow to select if error messages will be returned, when set
to 1 messages of this type are returned, when set to 0 (or any other
string including empty one) error messages will not be returned. For
example:
GET /logs?errors=1 - error messages will be returned
GET /logs?errors=0 - error messages won't be returned
- warnings - the same as errors but for warning messages
- info - the same as errors but for info messages
- If any of error, warnings or info argument is not present in the url,
it defaults to include given type of message in the output.
- start_datetime - date and time that is used to filter returned
messages, only those messages that were reported after specified date
and time will be returned. Format of date and time is:
"YYYY-mm-dd HH:MM:SS".
- end_datetime - the same date and time as start_datetime except that
it filters out any messages that were reported after specified date
and time.
N/A
Delete events
N/A
Mark elements as read
JSON input: {"is_read": true}
{
"properties": {
"is_read": {
"type": "boolean"
}
},
"required": ["is_read"]
}
Delete all events
N/A
Get raw output from check_mk_agent script.
Example JSON output::
{
"data": {
"output": "output from check_mk_agent script"
},
"error": null
}
@return: Http code 200 on success.
N/A
Get raw output from raid_info script.
Example JSON output::
{
"data": {
"output": "output from raid_info script"
},
"error": null
}
@return: Http code 200 on success.
N/A
Get raw output from raid_info script using custom command.
Example JSON output::
{
"data": {
"output": "output from raid_info script"
},
"error": null
}
@param custom_command: Custom argument that will be passed to raid_info
script.
@type custom_command: str
@return: Http code 200 on success.
N/A
Lists all available sensors.
Example JSON output::
{
"data":[
"load",
"process",
"misc",
"memory",
"cpu",
"disks"
],
"error":null
}
@return: Http code 200 on success.
N/A
Sets snmp_monitoring service status.
Example JSON input::
{
"state": "start"
}
@return: Http code 200 on success.
{
"properties": {
"state": {
"type": "string",
"enum": ["start", "stop"]
}
},
"required": ["state"]
}
Lists requested data for given sensor.
Editing "start", "end", and "step" parameters is performed by URL query arguments e.g.:
GET:/api/v1/monitoring/snmp/cpu/?start=end-15min&end=now&step=60
Example JSON output::
{
"data":{
"cpu":{
"meta":{
"start":1432824840,
"step":60,
"end":1432824840,
"legend":[
"system",
"user",
"idle",
"nice"
]
},
"data":[
[
4182899.9667,
3264657.9667,
164705679.6,
0
]
]
}
},
"error":null
}
When monitored configuration refers to individual values JSON contains
list of samples for those values. Each sample contains an array with data
for monitored fields. Fields are described in meta.legend array. Field
name in meta.legend array coresponds to data item in data array at the same
index.
If monitored configuration refers to multiple devices, list of those
devices is returned. To access data for selected device it is required
to issue an request that includes device name in the url.
@return: Http code 200 on success.
N/A
Sets single sensor status.
Sensor name should be given in URI request parameter e.g.: POST:api/v1/snmp/monitoring/cpu
Example JSON input::
{
"state": "stop"
}
@return: Http code 200 on success.
{
"properties": {
"state": {
"type": "string",
"enum": ["start", "stop"]
}
},
"required": ["state"]
}
Lists requested data only for given sensor's device.
Editing "start", "end", and "step" parameters is performed by URL query arguments e.g.:
GET:/api/v1/monitoring/snmp/disks/sda?start=end-15min&end=now&step=90
Example JSON output::
{
"data":{
"sda":{
"meta":{
"start":1432825110,
"step":90,
"end":1432825110,
"legend":[
"read_accesses",
"written_bytes",
"write_accesses",
"read_bytes"
]
},
"data":[
[
2830.0,
0.0,
27.0,
21281280.0
]
]
}
},
"error":null
}
@return: Http code 200 on success.
N/A
List all multipath configurations.
Example JSON output::
{
"data": [
{
"wwid": "wwn-0xSCST_BIO777f037922da870be55a4e9",
"dm_name": "dm-6",
"vendor": "SCST_BIO",
"product": "777f037922da870b",
"size": 10737418240,
"path_faults": 0,
"paths_count": 2,
"available_paths": 2,
"is_applied": true,
"path_grouping_policy": "failover",
"path_selector": null,
"prio": null,
"failback": null,
"rr_min_io_rq": null,
"rr_weight": null,
"flush_on_last_del": null,
"no_path_retry": "fail",
"remove_flag": false
}
],
"error": null
}
Multipath fields description:
- "wwid" - id of disk for which multipath is created
- "dm_name" - name of device mapper device
- "vendor" - vendor of disk
- "product" - product name or serial number of disk
- "size" - size of disk in bytes
- "path_faults" - total number of faults on all paths, describes how
many times since last configuration any of the paths failed
- "paths_count" - total number of discovered paths to disk
- "available_paths" - number of ready paths that can be used to send
data, paths_count - available_paths = failed paths
- "is_applied" - boolean flag that describes if configuration is
actually up and running in multipath daemon
- "path_grouping_policy" - multipath configuration field
- "path_selector" - multipath configuration field
- "prio" - multipath configuration field
- "failback" - multipath configuration field
- "rr_weight" - multipath configuration field
- "flush_on_last_del" - multipath configuration field
- "no_path_retry" - multipath configuration field
- "remove_flag" - Boolean flag that indicates if particular
configuration is marked for removal. If set to true it means that
there were request to remove configuration but at that time it wasyn't
possible to execute it. Particular configuration is used by active
pool and cannot be removed until pool is exported.
To check available settings for configuration fields please refer to
multipath, multipath.constants package. Check also multipath documentation,
those options have the same names and meanings as those in
/etc/multipath.conf. If particular field is set to null then it means that
it uses value from defaults, basically this option is not saved in
/etc/multipath.conf.
@return: Http code 200 on success.
N/A
Create new multipath configuration.
Required JSON keys:
- "wwid" - ID of disk for which multipath is configured. This value can
be ID of disk read from /dev/disk/by-id. It will be translated to wwid
of multipath automatically. It is also possible to use exact wwid of
multipath but ID of disk is always used across output instead of wwid.
Optional JSON keys are configuration settings. Refer to multipath,
multipath.constants packages and to multipath documentation for detailed
information.
Example JSON input:
- configuration with default values::
{
"wwid": "idOfDisk"
}
- configuration with customized values::
{
"wwid": "idOfDisk",
"path_group_policy": "multibus",
"path_selector": "round-robin 0"
}
@return: Http code 201 on success.
{
"properties": {
"wwid": {
"type": "string"
},
"path_grouping_policy": {
"type": "string"
},
"path_selector": {
"type": "string"
},
"prio": {
"type": "string"
},
"failback": {
"anyOf": [{
"type": "string"
}, {
"type": "integer"
}]
},
"rr_min_io_rq": {
"type": "integer"
},
"rr_weight": {
"type": "string"
},
"flush_on_last_del": {
"type": "string"
},
"no_path_retry": {
"anyOf": [{
"type": "string"
}, {
"type": "integer"
}]
}
},
"required": ["wwid"],
"additionalProperties": false
}
Get multipath with given id.
Example JSON output:
Output is in the same format as for L{get_all_multipaths} except that only
single item is returned instead of an array with multipath configurations.
@param wwid: ID of disk for which multipath is configured. This value can
be ID of disk read from /dev/disk/by-id. It will be translated to wwid of
multipath automatically. It is also possible to use exact wwid of multipath
but ID of disk is always used across output instead of wwid.
@type wwid: str
@return: Http code 200 on success.
N/A
Edit existing multipath configuration with given id.
Optional JSON keys are configuration settings. Refer to multipath,
multipath.constants packages and to multipath documentation for detailed
information.
Example JSON input::
{
"path_grouping_policy": "multibus",
"prio": "const"
}
Example JSON output:
If modification of multipath is successful then modified multipath is
returned. Output is in the same format as for L{get_all_multipaths} except
that only single item is returned instead of an array with multipath
configurations. Setting optional fields to null will case that settings
from defaults will be used.
@param wwid: ID of disk for which multipath is configured. This value can
be ID of disk read from /dev/disk/by-id. It will be translated to wwid of
multipath automatically. It is also possible to use exact wwid of multipath
but ID of disk is always used across output instead of wwid.
@type wwid: str
@return: Http code 200 on success.
{
"properties": {
"path_grouping_policy": {
"anyOf": [{
"type": "string"
}, {
"type": "null"
}]
},
"path_selector": {
"anyOf": [{
"type": "string"
}, {
"type": "null"
}]
},
"prio": {
"anyOf": [{
"type": "string"
}, {
"type": "null"
}]
},
"failback": {
"anyOf": [{
"type": "string"
}, {
"type": "integer"
}, {
"type": "null"
}]
},
"rr_min_io_rq": {
"anyOf": [{
"type": "integer"
}, {
"type": "null"
}]
},
"rr_weight": {
"anyOf": [{
"type": "string"
}, {
"type": "null"
}]
},
"flush_on_last_del": {
"anyOf": [{
"type": "string"
}, {
"type": "null"
}]
},
"no_path_retry": {
"anyOf": [{
"type": "string"
}, {
"type": "integer"
}, {
"type": "null"
}]
}
},
"additionalProperties": false
}
Remove multipath with given id.
Multipath might not be removed if it is used by active pool. In that case
it will be marked to remove, and it will stay active until removal is
possible.
@param wwid: ID of disk for which multipath is configured. This value can
be ID of disk read from /dev/disk/by-id. It will be translated to wwid of
multipath automatically. It is also possible to use exact wwid of multipath
but ID of disk is always used across output instead of wwid.
@type wwid: str
@return: Http code 204 if multipath was removed or http code 202 (accepted)
if multipath was marked to remove.
N/A
Reset number of available paths in given multipath.
Number of available paths is set to the value of currently available paths.
However if particular multipath doesn't have any path available then value
is set to 1 path. It is set lik that because multipath with 0 paths is
logically incorrect.
@param wwid: ID of disk for which multipath is configured. This value can
be ID of disk read from /dev/disk/by-id. It will be translated to wwid of
multipath automatically. It is also possible to use exact wwid of multipath
but ID of disk is always used across output instead of wwid.
@type wwid: str
@return: Http code 200 on success.
N/A
List default settings used by multipath.
If particular multipath has some option set to null then it will use value
from defaults settings.
Example JSON output::
{
"data": {
"path_grouping_policy" : "multibus",
"path_selector" : "round-robin 0",
"prio" : "const",
"failback" : "manual",
"rr_min_io_rq" : 1,
"rr_weight" : "uniform",
"flush_on_last_del" : "no",
"no_path_retry" : "fail",
"path_checker": "directio",
"checker_timeout": null
},
"error" : null
}
@return: Http code 200 on success.
N/A
Edit default settings used by multipath.
Options set in defaults will be used by any multipath that has same setting
set to null.
All JSON keys are optional, tose are multipath settings. Refer to multipath
documentation for details:
- "path_grouping_policy"
- "path_selector"
- "prio"
- "failback"
- "rr_min_io_rq"
- "rr_weight"
- "flush_on_last_del"
- "no_path_retry"
- "path_checker"
- "checker_timeout" - setting this field to null will cause that
default setting will be obtained for particular device
Example JSON input::
{
"path_grouping_policy" : "multibus",
"path_selector" : "round-robin 0",
"prio" : "const"
}
On success end-point will return settings in same format as in
L{get_default_multipath_settings}.
@return Http code 200 on success.
{
"properties": {
"path_grouping_policy": {
"type": "string"
},
"path_selector": {
"type": "string"
},
"prio": {
"type": "string"
},
"failback": {
"anyOf": [{
"type": "string"
}, {
"type": "integer"
}]
},
"rr_min_io_rq": {
"type": "integer"
},
"rr_weight": {
"type": "string"
},
"flush_on_last_del": {
"type": "string"
},
"no_path_retry": {
"anyOf": [{
"type": "string"
}, {
"type": "integer"
}]
},
"path_checker": {
"type": "string"
},
"checker_timeout": {
"anyOf": [{
"type": "integer"
}, {
"type": "null"
}]
}
},
"additionalProperties": false
}
Return status of multipath service.
Multipath service can be either enabled or disabled which is indicated by
returned boolean flag. Enabled service automatically configures multipath
configurations for devices that are connected to the system with more than
one path. Disabled multipath service does not perform such configuration,
system uses path to disk that was detected as last connected one. When
multipath service is disabled it is also not allowed to perform any manual
configuration of multipath devices.
It is possible to have status in a state where enabled flag is set to false
indicating disabled multipath service while at the same time there are
some active multipath configurations present in the system. This state
indicates that in order to complete disable operation it is required to
freed up multipath devices to allow removal of those configurations.
Depending on what uses multipath devices following actions may be performed
in order to finish disable of multipath service:
- export of the pools that use multipath configurations: if any pool
uses given multipath device, its configuration cannot be removed until
pool is exported
- removal of remote disks path: if disk is exported to remote node in
the cluster its configuration will be removed once remote disks path
is removed
- reboot of the system: this will always work independent on what
currently uses multipath device, after the reboot configuration will
be cleaned up
Output fields description:
- "enabled" - boolean flag that indicates if multipath service is
enabled or disabled.
- "multipaths" - list with currently active multipath configurations
Example JSON output::
{
"data": {
"enabled": true,
"multipaths": []
}
}
@return: Http code 200 on success.
N/A
Change status of multipath service.
Enable or disable multipath service. When service is disabled all available
configurations are removed and service is disabled. After this operation
new multipath configuration won't be configured until service is enabled.
Once service is enabled all disks that are connected by more than one path
will be configured as multipath.
After disable of multipath service configurations that are in use
(for example as disks in active pool or as disks exported to remote node in
the cluster) won't be removed. Those configurations will be removed once
device is freed up. This means that it might be necessary to export the
pool, remove remote disks path or perform system reboot in order to
complete disable of multipath service.
Optional input JSON keys:
- "enabled" - Boolean flag that controls if multipath service is
enabled or dissabled.
Example JSON input::
{
"enabled": false
}
Endpoint returns status of multipath configuration after changing the
state. Status contains enabled flag and list of currently configured
multipaths. If request to disable multipath service was issued and response
contains some multipath configurations, it indicates that those
configurations are in use and have to be freed up in order to finish the
opeartion.
Output fields description:
- "enabled" - boolean flag that indicates if multipath service is
enabled or disabled.
- "multipaths" - list with currently active multipath configurations
Example JSON output::
{
"data": {
"enabled": true,
"multipaths": []
}
}
@return: Http code 200 on success.
{
"properties": {
"enabled": {
"type": "boolean"
}
}
}
Get interface that is set as default gateway.
Example JSON output::
{
"data" : {
"interface" : "eth0"
},
"error" : null
}
N/A
Set given interface as default gateway.
Required JSON keys:
- "interface" - Name of interface that will be set as default gateway.
Static configurations could be set as default gateway only if it has
gateway field set.
Example JSON input::
{
"interface": "eth0"
}
@return: Http code 201 on success.
{
"properties": {
"interface": {
"type": "string"
}
},
"required": ["interface"],
"additionalProperties": false
}
Get list of DNS saved in configuration.
Saved DNS are in use only if default gateway is set to static configuration.
Example JSON output::
{
"data" : {
"servers" : [ "192.168.1.1", "8.8.8.8" ]
},
"error" : null
}
@return: Http code 200 on success.
N/A
Save list of DNS servers in configuration.
Saved DNS are in use only if default gateway is set to static configuration.
Required JSON keys:
- "servers" - Array with IP addresses of DNS.
Example JSON input::
{
"servers": ["192.168.1.1", "8.8.8.8"]
}
{
"properties": {
"servers": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["servers"],
"additionalProperties": false
}
List all network interfaces.
Example JSON output::
{
"data": [
{
"name": "eth0",
"type": "interface",
"status": "connected",
"configuration": "static",
"is_up": true,
"address": "192.168.0.220",
"netmask": "24",
"gateway" : null,
"broadcast": null,
"mac_address": "02:00:C0:A8:05:C6",
"negotiated_speed": 1000,
"speed": 1000,
"duplex": "Full",
"operational_state": "up",
"carrier": true,
"model": "Intel Corporation 82540EM Gigabit Ethernet Controller (rev 03)"
}
],
"error": null
}
Network interface fields description:
- "type" - Type of interface:
- "interface" - single interface configuration,
- "bonding" - bonding configuration,
- "slave" - interface used in bonding.
- "status" - Indicates if network adapter for given configuration is
present:
- "connected" - interface is present in system,
- "missing" - interface is not present in system,
- "degraded" - used for bonding configurations that has some slave
interfaces missing.
- "configuration" - Type of configuration:
- "static" - static configuration with manually assigned address,
- "dhcp" - configuration that obtain address from DHCP server.
- "is_up" - Boolean flag that indicates if configuration is enabled or
disabled.
- "gateway" - Gateway IP address, this field is used only for static
configurations, for DHCP configuration this field will be set to null.
@return: Http code 200 on success.
N/A
Create new configuration that uses more that one physical interface.
Currently only bonding configuration can be created that way. When bonding
will be created url for new configuration will be returned.
Required JSON keys:
- "type" - Type of interface, it is required to set this field to value
"bonding" because this is only one type of interface that can be
created. Field is required to indicate that only bonding could be
created.
- "configuration" - Type of configuration, allowed values are:
- "dhcp" - to configure bonding using DHCP,
- "static" - to configure bonding using manual settings, when this
value is supplied additional data have to be send in request:
- "address" - IP address of interface.
- "netmask" - Netmask of interface.
- "slaves" - Array with names of network interfaces that will be used
to create bonding configuration.
Optional JSON keys:
- "name" - Name of bonding configuration it have to be in format bondX
where X is bonding number. If name won't be specified system will
assign default name.
- "is_up" - Boolean flag that indicates if interface should be bring up.
This value defaults to true - interface is bring up.
- "gateway" - IP address of gateway, this field is valid only for
static configuration.
- "broadcast" - Broadcast IP address, this field is valid only for
static configuration.
- "primary_interface" - Name of interface that will be used as primary
interface in bonding, not every bonding mode support this setting.
- "bond_primary_reselect" - Primary (interface) reselection policy. Not every
bonding mode support this setting.
- "bond_mode" - Set bonding mode, allowed values: "balance-rr",
"active-backup", "balance-xor", "broadcast", "802.3ad", "balance-tlb",
"balance-alb"
- "mac_address" - Set MAC address for bonding configuration.
- "bond_miimon" - Number of milliseconds for miimon.
- "bond_downdelay" - Number of milliseconds for downdelay, must be
multiple of miimon.
- "bond_updelay" - Number of milliseconds for updelay, must be multiple
of miimon.
Example JSON input:
- Bonding configured using DHCP::
{
"type": "bonding",
"configuration": "dhcp",
"slaves": ["eth1", "eth2"],
"bond_mode": "active-backup",
"primary_interface": "eth1",
"bond_primary_reselect": "failure"
}
- Bonding using static configuration::
{
"type": "bonding",
"configuration": "static",
"address": "192.168.224.155",
"netmask": "255.255.255.0",
"slaves": ["eth1", "eth2"],
"bond_mode": "active-backup",
"primary_interface": "eth1",
"bond_primary_reselect": "failure"
}
- VLAN using DHCP configuration:
{
"type": "vlan",
"name": "eth1.5",
"configuration": "dhcp",
}
- VLAN using static configuration:
{
"type": "vlan",
"name": "eth1.5",
"address" : "10.10.10.5",
"netmask" : "255.255.255.0",
"broadcast": "10.10.10.255",
"configuration": "static",
"gateway": "10.10.10.1"
}
Example JSON output::
{
"data": {
"url" : "/api/v1/network/interfaces/bond0"
},
"error": null
}
{
"data": {
"url" : "/api/v1/network/interfaces/eth1.5"
},
"error": null
}
@return: Http code 201 on success
{
"properties": {
"name": {
"type": "string"
},
"type": {
"type": "string"
},
"configuration": {
"type": "string",
"enum": ["dhcp", "static"]
},
"is_up": {
"type": "boolean"
},
"address": {
"type": "string"
},
"netmask": {
"type": "string"
},
"gateway": {
"type": "string"
},
"broadcast": {
"type": "string"
},
"slaves": {
"type": "array"
},
"primary_interface": {
"type": "string"
},
"bond_primary_reselect": {
"type": "string"
},
"bond_mode": {
"type": "string"
},
"mac_address": {
"type": "string"
},
"bond_miimon": {
"type": "integer"
},
"bond_downdelay": {
"type": "integer"
},
"bond_updelay": {
"type": "integer"
}
},
"required": ["type", "configuration"],
"additionalProperties": false
}
Get interface with given name.
Example JSON output:
Output is in the same format as for L{list_configurations} except that only
single item is returned instead of an array with network configurations.
@param interface: Name of interface to list.
@type interface: str
@return: Http code 200 on success.
N/A
Change given interface configuration.
By using this end-point it is possible to modify interface configuration.
It is possible to change type of configuration from static to DHCP and
likewise. It is not possible to change type of interface, in order to create
or delete bonding use create_new_configuration end-point. It is not
possible to directly edit slave interfaces it is only possible to edit
bonding configuration and change array with slave interfaces.
Optional JSON keys:
- "type" - Type of interface, it cannot be modified and if this field
is set it must have the same value as is currently set.
- "configuration" - Change configuration of interface:
- "dhcp" - Use DHCP to configure interface.
- "static" - Use manual settings to configure interface. If this
value is changed from "dhcp" configuration then it is required to
supply fields "address" and "netmask"
- "is_up" - Boolean flag that indicates interface status.
- "address" - IP address of interface - valid only for static
configuration.
- "netmask" - Netmask of interface - valid only for static
configuration.
- "gateway" - IP address of gateway - valid only for static
configuration. It is possible to set it to null in order to remove
this value.
- "broadcast" - Broadcast IP address - valid only for static
configuration. It is possible to set it to null in order to remove this
value.
- "bond_primary_reselect" - Primary (interface) reselection policy. Not every
bonding mode support this setting.
- "slaves" - Array with name of slave interfaces. This field is allowed
only for bonding.
- "mac_address" - MAC address, this field is allowed only for bonding.
- "bond_miimon" - Number of milliseconds for miimon, this field is
allowed only for bonding.
- "bond_downdelay" - Number of milliseconds for downdelay, must be
multiple of miimon, this field is allowed only for bonding.
- "bond_updelay" - Number of milliseconds for updelay, must be multiple
of miimon, this field is allowed only for bonding.
Example JSON input:
- Change configuration to DHCP::
{
"configuration": "dhcp"
}
- Change configuration to static from DHCP::
{
"configuration": "static",
"address": "192.168.248.124",
"netmask": "255.255.255.0",
"gateway": "192.168.248.1"
}
Edit IP address of static configuration::
{
"address": "192.168.220.188"
}
@param interface: Name of interface to edit.
@type interface: str
@return: Http code 201 on success.
{
"properties": {
"type": {
"type": "string"
},
"configuration": {
"type": "string",
"enum": ["dhcp", "static"]
},
"is_up": {
"type": "boolean"
},
"address": {
"type": "string"
},
"netmask": {
"type": "string"
},
"gateway": {
"oneOf": [{
"type": "string"
}, {
"type": "null"
}]
},
"broadcast": {
"oneOf": [{
"type": "string"
}, {
"type": "null"
}]
},
"slaves": {
"type": "array"
},
"primary_interface": {
"oneOf": [{
"type": "string"
}, {
"type": "null"
}]
},
"bond_primary_reselect": {
"oneOf": [{
"type": "string"
}, {
"type": "null"
}]
},
"bond_mode": {
"type": "string"
},
"mac_address": {
"type": "string"
},
"bond_miimon": {
"type": "integer"
},
"bond_downdelay": {
"type": "integer"
},
"bond_updelay": {
"type": "integer"
}
},
"additionalProperties": false
}
Removes following types of configuration:
- Bonding,
- VLAN.
Note for Bonding:
Default configurations will be created for each part of removed object.
@param interface: Name of interface to delete.
@type interface: str
@return: Http code 204 on success.
N/A
Get interface that is set as default gateway.
Example JSON output::
{
"interface": "eth0",
"gateway": "192.168.0.1",
"ip": "192.168.0.5",
"netmask": "255.255.255.255"
}
N/A
Set given interface as default gateway.
Required JSON keys:
- "interface" - Name of interface.
- "ip" - IP address of the destination.
- "netmask" - Netmask address of the destination.
Optional JSON keys:
- "gateway" - IP address of the gateway.
Example JSON input::
{
"interface": "eth0",
"gateway": "192.168.0.1",
"ip": "192.168.0.5",
"netmask": "255.255.255.255"
}
@return: Http code 201 on success.
{
"properties": {
"interface": {
"type": "string"
},
"ip": {
"type": "string",
"format": "ipv4"
},
"netmask": {
"type": "string",
"format": "ipv4"
},
"gateway": {
"oneOf": [{
"type": "string",
"format": "ipv4"
}, {
"type": "null"
}, {
"type": "string",
"maxLength": 0
}]
}
},
"required": ["interface", "ip", "netmask"],
"additionalProperties": false
}
Deletes routing entry.
{
"properties": {
"ip": {
"type": "string",
"format": "ipv4"
},
"netmask": {
"type": "string",
"format": "ipv4"
}
},
"required": ["ip", "netmask"]
}
Return reserved size for new zvol
Example of usage: {"volsize": "322122547200", "volblocksize": "512", "copies": "1"}
WARNING: volsize is passed as GIBIBYTES (GiB). Blocksize and optional argument copies is passed as bytes.
volsize is converted to bytes on the python side.
Max value of volsize is 17 179 869 183 GiB
{
"properties": {
"pool_name": {
"type": "string"
},
"volsize": {
"type": "string"
},
"volblocksize": {
"type": "string"
},
"copies": {
"type": "string"
}
},
"required": ["pool_name", "volsize", "volblocksize"]
}
None
N/A
None
{
"properties": {
"name": {
"type": "string"
}
},
"required": ["name"],
"additionalProperties": false
}
Disable odps task.
Example JSON input::
{
"name": "Pool-0/MyDataset"
}
{
"properties": {
"name": {
"type": "string"
}
},
"required": ["name"],
"additionalProperties": false
}
Enable odps task.
Example JSON input::
{
"name": "Pool-0/MyDataset"
}
{
"properties": {
"name": {
"type": "string"
}
},
"required": ["name"],
"additionalProperties": false
}
None
N/A
None
{
"properties": {
"address": {
"type": "string"
},
"user": {
"type": "string"
},
"password": {
"type": "string"
}
},
"required": ["address", "user", "password"],
"additionalProperties": false
}
None
N/A
None
N/A
None
N/A
None
N/A
Modify odp resource.
Example JSON input::
{
"paused": true
}
{
"properties": {
"odp_src_data": {
"type": "object",
"properties": {
"paused": {
"type": "boolean"
}
}
}
},
"additionalProperties": false
}
None
N/A
None
N/A
None
{
"properties": {
"address": {
"type": "string"
},
"password": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": ["address", "password"],
"additionalProperties": false
}
None
N/A
None
N/A
None
N/A
None
N/A
None
N/A
None
N/A
None
{
"properties": {
"plan": {
"type": ["string", "null"]
},
"dest_plan": {
"type": ["string", "null"]
}
},
"additionalProperties": false
}
None
N/A
Example JSON output::
{
"data": {
"results": 2,
"entries": [
{
"name": "Pool-A1/ImagesZvol",
"type": "volume",
"enabled": "on",
"plan": "12hour=>15minutes",
"description": "Replication of images",
"dedup": false,
"mbuffer": true,
"mbuffersize": "5G",
"rate_limit": "100M",
"esx_datastore": "",
"tsformat": "autosnap_%Y-%m-%d-%H%M%S",
"destinations": [
{
"plan": "2weeks=>6hours",
"dataset": "Pool-B1/BackupZvol"
}
],
},
{
"name": "Pool-A1/DocumentsDataset",
"type": "filesystem",
"enabled": "on",
"plan": "1d=>1h",
"description": "Documents replication",
"dedup": false,
"mbuffer": false,
"mbuffersize": "1G",
"rate_limit": "off",
"esx_datastore": "192.168.1.1:443/ha-datacenter/local.iSCSI-1",
"tsformat": "autosnap_%Y-%m-%d-%H%M%S",
"destinations": [
{
"plan": "1week=>8hours",
"dataset": "Pool-A2/BackupDataset"
},
{
"plan": "3m=>1d",
"dataset": "192.168.2.2:40000/Pool-B1/LongTermDataset"
}
]
}
]
},
"error": null
}
N/A
Example JSON input::
{
"name": "Pool-A1/DocumentsDataset",
"plan": "1d=>1h",
"description": "Documents replication",
"dedup": false,
"granular_resync": false,
"mbuffer": false,
"mbuffersize": "1G",
"rate_limit': "100M",
"esx_datastore": "192.168.1.1:443/ha-datacenter/local.iSCSI-1",
"destinations": [
{
"plan": "1weeks=>6hours",
"dataset": "Pool-A2/BackupDataset"
},
{
"plan": "3months=>1day",
"dataset": "192.168.2.2:40000/Pool-B1/LongTermDataset"
}
]
}
{
"properties": {
"name": {
"type": "string"
},
"plan": {
"type": "string"
},
"description": {
"type": "string"
},
"dedup": {
"type": "boolean"
},
"granular_resync": {
"type": "boolean"
},
"mbuffer": {
"type": "boolean"
},
"mbuffersize": {
"type": "string"
},
"rate_limit": {
"type": "string"
},
"tsformat": {
"type": "string"
},
"esx_datastore": {
"type": "string"
},
"destinations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"dataset": {
"type": "string"
},
"plan": {
"type": "string"
}
},
"required": ["dataset"]
}
}
},
"required": ["name"],
"additionalProperties": false
}
Example JSON input::
{
"name": "Pool-0/MyDataset"
}
{
"properties": {
"name": {
"type": "string"
}
},
"required": ["name"],
"additionalProperties": false
}
None
N/A
Example JSON input::
{
"plan": "12hours=>15minutes",
"description": "Replication of images",
"dedup": false,
"granular_resync": false,
"mbuffersize": "5G",
"mbuffer": "off",
"rate_limit": "off",
"esx_datastore": "",
"destinations": [
{
"plan": "1day=>2hours",
"dataset": "Pool-B1/BackupImages"
}
]
}
{
"properties": {
"plan": {
"type": "string"
},
"description": {
"type": "string"
},
"dedup": {
"type": "boolean"
},
"granular_resync": {
"type": "boolean"
},
"mbuffer": {
"type": "boolean"
},
"mbuffersize": {
"type": "string"
},
"rate_limit": {
"type": "string"
},
"tsformat": {
"type": "string"
},
"esx_datastore": {
"type": "string"
},
"destinations": {
"type": "array",
"items": {
"type": "object",
"properties": {
"dataset": {
"type": "string"
},
"plan": {
"type": "string"
}
},
"required": ["dataset"]
}
}
},
"additionalProperties": false
}
None
N/A
None
N/A
Modify odp resource.
Example JSON input::
{
"paused": true
}
{
"properties": {
"odp_src_data": {
"type": "object",
"properties": {
"paused": {
"type": "boolean"
}
}
}
},
"additionalProperties": false
}
None
N/A
List all pools in system.
End-point return array containing configurations of all pools in system.
Example JSON output:
Pool with one mirror vdev that uses two disks::
{
"data": [
{
"name": "Pool-0",
"status": 24,
"health" : "ONLINE",
"scan": null,
"operation" : "none",
"sysvol_upgrade": "not_needed",
"iostats": {"read": "0", "write": "0", "chksum": "0"},
"vdevs": [
{
"name": "mirror-0",
"type": "mirror",
"health": "ONLINE",
"iostats": {"read": "0", "write": "0", "chksum": "0"},
"disks": [
{
"name": "sdb",
"id": "wwn-0x5000c5001c11581c",
"sn": "5VP1YAQQ",
"model": "ST31000528AS ",
"path": null,
"health": "ONLINE",
"size": 1000204886016,
"iostats": {"read": "0", "write": "0", "chksum": "0"},
"led": "off",
"origin": "iscsi"
},
{
"name": "sdc",
"id" : "ata-ST3250310AS_9RY03FX0",
"sn" : "9RY03FX0",
"model" : "ST3250310AS ",
"path" : null,
"health" : "ONLINE",
"size" : 250059350016,
"iostats": {"read": "0", "write": "0", "chksum": "0"},
"led": "off",
"origin": "local"
}
],
"vdev_replacings": [],
"vdev_spares": []
}
]
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Create new pool.
Configuration of pool is provided in JSON formatted data.
Required JSON keys:
- "name" - String with name of pool.
- "vdevs" - Array with objects that describe vdevs of pool. Each item
of array contain description of single vdev. Every item requires
following keys:
- "type" - string with type of vdev, only following values are
allowed: "mirror", "raidz1", "raidz2", "raidz3", "log",
"log mirror", "spare", "cache", "" (empty string is used to
indicate single type of vdev, one disk)
- "disk" - array with ids of disks that form particular vdev, array
is used even if particular vdev requires only one disk
Example JSON input::
{
"name": "TestPool",
"vdevs": [
{"type": "mirror", "disks": ["id1", "id2"]},
{"type": "mirror", "disks": ["id3", "id4"]},
{"type": "", "disks": ["id5"]}
]
}
{
"name": "PoolWithProperties",
"vdevs": [
{"type": "", "disks": ["id10"]}
]
}
Example JSON output:
End-point doesn't return any data.
@return: On successful pool creation http code 201 is returned.
{
"properties": {
"name": {
"type": "string"
},
"vdevs": {
"type": "array",
"items": {
"properties": {
"type": {
"type": "string",
"enum": ["", "mirror", "raidz1", "raidz2", "raidz3", "log", "log mirror", "spare", "cache", "special", "special mirror", "dedup", "dedup mirror"]
},
"disks": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["type", "disks"]
}
}
},
"required": ["name", "vdevs"]
}
Get all datasets in given pool.
@param pool_name: Name of the pool to which datasets belongs to (e.g. ``MyPool``).
@type pool_name: str
Example JSON output::
{
"data":
[
{
"origin": null,
"compression": "lz4",
"primarycache": "all",
"logbias": "latency",
"dedup": "off",
"copies": "1",
"sync": "standard",
"full_name": "MyPool/CommonSet",
"quota": null,
"reservation": "107374182",
"refreservation": null,
"atime": "off",
"secondarycache": "all",
"name": "CommonSet"
},
{
"origin": null,
"compression": "lz4",
"primarycache": "all",
"logbias": "latency",
"dedup": "off",
"copies": "1",
"sync": "standard",
"full_name": "MyPool/PrivateSet",
"quota": null,
"reservation": "107374182",
"refreservation": null,
"atime": "off",
"secondarycache": "all",
"name": "PrivateSet"
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Creates dataset on a given pool.
@param pool_name: Name of the pool to which dataset will belong to (e.g. ``MyPool``).
@type pool_name: str
Required JSON keys:
- "name" - string with name of the dataset to be created (e.g. ``NewSet``).
Example JSON input::
{
"name": "NewSet"
}
@return: Http code 201 on success.
{
"properties": {
"name": {
"type": "string"
}
},
"additionalProperties": false,
"required": ["name"]
}
Get data about certain dataset.
@param pool_name: Name of the pool to which dataset belongs to (e.g. ``MyPool``).
@type pool_name: str
@param dataset_name: Name of the dataset (e.g. ``CommonSet``).
@type dataset_name: str
Example JSON output::
{
"data":
{
"origin": null,
"compression": "lz4",
"primarycache": "all",
"logbias": "latency",
"dedup": "off",
"copies": "1",
"sync": "standard",
"full_name": "MyPool/CommonSet",
"quota": null,
"reservation": "107374182",
"refreservation": null,
"atime": "off",
"secondarycache": "all",
"name": "CommonSet"
},
"error": null
}
@return: Http code 200 on success.
N/A
Modifies properties of certain dataset.
@param pool_name: Name of the pool to which dataset belongs to (e.g. ``MyPool``).
@type pool_name: str
@param dataset_name: Name of the dataset (e.g. ``CommonSet``).
@type dataset_name: str
Optional JSON keys:
- "name" - string with the new name for a dataset.
- "copies" - (1, 2, 3)
- "compression" - ('on', 'off', 'lzjb', 'gzip', 'gzip-1', 'gzip-2', 'gzip-3', 'gzip-4', 'gzip-5', 'gzip-6',
'gzip-7', 'gzip-8', 'gzip-9', 'zle', 'lz4')
- "primarycache" - ('all', 'none', 'metadata')
- "logbias" - ('latency', 'throughput')
- "atime" - ('on', 'off')
- "dedup" - ('on', 'off', 'verify', 'sha256', 'sha256,verify')
- "secondarycache" - ('all', 'none', 'metadata')
- "sync" - ('standard', 'always', 'disabled')
Example JSON input::
{
"sync": "always"
}
@return: Http code 201 on success.
{
"properties": {
"name": {
"type": "string"
}
},
"additionalProperties": false
}
Delete given dataset.
@param pool_name: Name of the pool to which dataset belongs to (e.g. ``MyPool``).
@type pool_name: str
@param dataset_name: Name of the dataset (e.g. ``CommonSet``).
@type dataset_name: str
@return: Http code 204 on success.
{
"properties": {
"keep_shares": {
"type": "boolean"
},
"check_snapshot_clones": {
"type": "boolean"
}
}
}
Creates snapshot of a given dataset.
@param pool_name: Name of the pool to which dataset belongs to (e.g. ``MyPool``).
@type pool_name: str
@param dataset_name: Name of the dataset (e.g. ``PrivateSet``).
@type dataset_name: str
Required JSON keys:
- "name" - string with name of the snapshot to be created (e.g. ``NewSnapshot``).
Example JSON input::
{
"name": "NewSnapshot"
}
@return: Http code 201 on success.
{
"properties": {
"name": {
"type": "string"
}
},
"required": ["name"]
}
Lists snapshots of a given dataset.
@param pool_name: Name of the pool to which dataset belongs to (e.g. ``MyPool``).
@type pool_name: str
@param dataset_name: Name of the dataset (e.g. ``PrivateSet``).
@type dataset_name: str
Example JSON output::
{
"data":
[
{
"name": "NewSnapshot"
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Get data about certain snapshot.
@param pool_name: Name of the pool to which dataset belongs to (e.g. ``MyPool``).
@type pool_name: str
@param dataset_name: Name of the dataset to which snapshot belongs to (e.g. ``PrivateSet``).
@type dataset_name: str
@param snapshot_name: Name of the snapshot (e.g. ``NewSnapshot``).
@type snapshot_name: str
Example JSON output::
{
"data":
{
"setuid": "on",
"referenced": "98304",
"userrefs": "0",
"primarycache": "all",
"creation": "2015-6-15 13:53:58",
"casesensitivity": "sensitive",
"utf8only": "off",
"xattr": "on",
"compressratio": "1.00x",
"written": "98304",
"version": "5",
"type": "snapshot",
"secondarycache": "all",
"used": "0",
"exec": "on",
"refcompressratio": "1.00x",
"clones": "",
"normalization": "none",
"name": "NewSnapshot",
"defer_destroy": "off",
"mlslabel": "none",
"devices": "on",
"nbmand": "off"
},
"error": null
}
@return: Http code 200 on success.
N/A
Delete given snapshot.
@param pool_name: Name of the pool to which dataset belongs to (e.g. ``MyPool``).
@type pool_name: str
@param dataset_name: Name of the dataset to which snapshot belongs to (e.g. ``PrivateSet``).
@type dataset_name: str
@param snapshot_name: Name of the snapshot to be deleted (e.g. ``NewSnapshot``).
@type snapshot_name: str
@return: Http code 204 on success.
{
"properties": {
"keep_shares": {
"type": "boolean"
}
}
}
Creates clone of a dataset from snapshot.
Required JSON keys:
- "name" - string with name of the clone to be created (e.g. ``MyClone``).
Optional JSON keys:
- "copies" - (1, 2, 3)
- "compression" - ('on', 'off', 'lzjb', 'gzip', 'gzip-1', 'gzip-2', 'gzip-3', 'gzip-4', 'gzip-5', 'gzip-6',
'gzip-7', 'gzip-8', 'gzip-9', 'zle', 'lz4')
- "primarycache" - ('all', 'none', 'metadata')
- "logbias" - ('latency', 'throughput')
- "atime" - ('on', 'off')
- "dedup" - ('on', 'off', 'verify', 'sha256', 'sha256,verify')
- "secondarycache" - ('all', 'none', 'metadata')
- "sync" - ('standard', 'always', 'disabled')
Example JSON input::
{
"name": "MyClone",
"dedup": "sha256,verify"
}
@return: Http code 200 on success.
{
"properties": {
"name": {
"type": "string"
}
},
"additionalProperties": false,
"required": ["name"]
}
Get all clones of a dataset made of snapshot.
@param pool_name: Name of the pool to which dataset belongs to (e.g. ``MyPool``).
@type pool_name: str
@param dataset_name: Name of the dataset to which snapshot belongs to (e.g. ``CommonSet``).
@type dataset_name: str
@param snapshot_name: Name of the snapshot to be listed (e.g. ``MySnapshot``).
@type snapshot_name: str
Example JSON output::
{
"data":
[
{
"name": "MyClone"
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Get clone of dataset created from given snapshot.
@param pool_name: Name of the pool to which dataset belongs to (e.g. ``MyPool``).
@type pool_name: str
@param dataset_name: Name of the dataset to which snapshot belongs to (e.g. ``CommonSet``).
@type dataset_name: str
@param snapshot_name: Name of the snapshot which was cloned (e.g. ``MySnapshot``).
@type snapshot_name: str
@param clone_name: Name of tpromotehe clone (e.g. ``MyClone``).
@type clone_name: str
Example JSON output::
{
"data":
{
"origin": "MyPool/CommonSet@MySnapshot",
"compression": "off",
"primarycache": "all",
"logbias": "latency",
"dedup": "sha256,verify",
"copies": "1",
"sync": "standard",
"full_name": "MyPool/MyClone",
"quota": null,
"reservation": "107374182",
"refreservation": null,
"atime": "on",
"secondarycache": "all",
"name": "MyClone"
},
"error": null
}
@return: Http code 200 on success.
N/A
Delete given clone.
@param pool_name: Name of the pool to which dataset belongs to (e.g. ``MyPool``).
@type pool_name: str
@param dataset_name: Name of the dataset to which snapshot belongs to (e.g. ``CommonSet``).
@type dataset_name: str
@param snapshot_name: Name of the snapshot which was cloned (e.g. ``MySnapshot``).
@type snapshot_name: str
@param clone_name: Name of the clone (e.g. ``MyClone``).
@type clone_name: str
@return: Http code 204 on success.
{
"properties": {
"keep_shares": {
"type": "boolean"
}
}
}
Promote clone to the dataset.
N/A
Rollback dataset to given snapshot.
@param pool_name: Name of the pool.
@type pool_name: str
@param dataset_name: Name of dataset.
@type dataset_name: str
@param snapshot_name: Snapshot name.
@type snapshot_name: str
{
"properties": {
"keep_shares": {
"type": "boolean"
}
}
}
List all items (snapshots, clones) when rollback is executed.
N/A
List all datasets and it's snapshots.
@param pool_name: Name of the pool to which snapshots belongs to (e.g. ``MyPool``).
@type pool_name: str
Example JSON output::
{
"data":
[
{
"name": "MySnapshot",
"properties":
{
"creation": 1484835502
}
}
],
"error": null
}
@return: Http code 200 on success.
N/A
List full configuration of FC groups on given pool.
FC group gathers FC targets, initiators and volumes that are available on
given pool. When particular volume is added to FC group, it is available
to all initiators that are specified in group configuration through all
targets (ports) that are assigned to that group.
Each pool contains one specific group called "Default". This group allows
to access volumes that are present in that group by any initiator. Volumes
are available through assigned targets (ports). It is not possible to
assign any initiator to "Default" group. Also removal of this group is not
possible.
Example JSON output::
{
"data": [
{
"name": "Default",
"alias": "Default",
"is_default": true,
"active": true,
"fc_targets": [
{
"status": "OK",
"is_target_mode_enabled": true,
"is_hw_target": true,
"alias": "fc-tgt-01",
"node_assignment": {
"assignment_id": 2,
"target_mapping": [
{
"node_id": "a57452b2",
"wwn": "21:01:00:1b:32:25:fc:86"
}
],
"local_target": "21:01:00:1b:32:25:fc:86"
},
"parent_host": null,
"wwn": "21:01:00:1b:32:25:fc:86"
}
],
"luns": [
{
"prod_id": "JovianDSS",
"scsi_id": "81c42fd710050207",
"mode": "wt",
"volume_name": "fc-vol3",
"block_size": 512,
"lun": 0
}
]
},
{
"name": "GROUP0",
"alias": "GROUP0",
"is_default": false,
"active": true,
"fc_targets": [
{
"status": "OK",
"is_target_mode_enabled": true,
"is_hw_target": true,
"alias": "tgt0",
"node_assignment": {
"assignment_id": 1,
"target_mapping": [
{
"node_id": "00000001",
"wwn": "21:00:00:1b:32:05:fc:11"
},
{
"node_id": "a57452b2",
"wwn": "21:00:00:1b:32:05:fc:86"
}
],
"local_target": "21:00:00:1b:32:05:fc:86"
},
"parent_host": null,
"wwn": "21:00:00:1b:32:05:fc:86"
}
],
"luns": [
{
"prod_id": "JovianDSS",
"scsi_id": "dfa90de2800cb220",
"mode": "wt",
"volume_name": "fc-vol0",
"block_size": 512,
"lun": 0
}
],
"initiators": [
{
"alias": "ini0",
"wwn": "21:00:00:1b:32:05:fc:00"
}
]
}
],
"error": null
}
FC group fields description:
- "name" - Unique identifier of FC group. It is used to identify group
in REST API requests.
- "alias" - User friendly name for FC group.
- "is_default" - Flag that indicates if given group is a "Default"
group.
- "active" - Flag that indicates if group is active. If group is not
active it doesn't allow to access any assigned volumes. Inactive group
is simply a configuration that is not applied physically. Group may
become inactive due to conflicts with groups on other pools after
import. In general group cannot use targets that are used by other
pools and SCSI ID of volumes cannot be used by volumes on other pools.
- "fc_targets" - List with FC targets assigned to group. For detailed
description of target assigned to group representation please refer to
L{get_fc_group_targets}.
- "luns" - List with LUNs (volumes) assigned to group. For detailed
description of volumes assigned to FC group please refer to
L{get_fc_group_luns}.
- "initiators" - List with initiators assigned to group. For detailed
description of initiators please refer to L{get_pool_initiators}.
@param pool_name: Name of pool for which configuration of groups is listed.
@type pool_name: str
@return: Http code 200 on success and list with groups configured on pool.
N/A
Create new FC group on given pool.
During creation of FC group it is possible to set up custom alias. However
unique identifier of group is it's name which is generated for each new
group. On successful group creation JSON with group data is returned and
it contains information about group name.
Optional JSON keys:
- "alias" - User friendly name for FC group.
- "fc_targets" - Array with WWNs of FC targets that will be assigned
to newly created group.
- "initiators" - Array with WWNs of initiators that will be assigned
to newly created group.
- "luns" - Array with configurations of LUNs that will be assigned to
newly created group. Format of LUN configuration is the same as for
L{add_volume_to_fc_group} end-point.
Example JSON input::
{
"alias": "New-FC-Group",
"fc_targets": ["21:00:00:1b:32:05:fc:86"],
"initiators": [
"21:00:00:0e:1e:2a:ff:03",
"21:00:00:0e:1e:2a:ff:04"
],
"luns": [
{
"volume_name": "fc-vol0",
"scsi_id": "81c42fd710050207",
"lun": 0
}
]
}
@param pool_name: Name of pool where group is created.
@type pool_name: str
@return: Http code 200 on success and JSON representation of created group.
N/A
Fetch configuration of given group.
Example JSON output:
Output is in the same format as for L{get_fc_groups} except that only
single item is returned instead of list with all groups on pool.
@param pool_name: Name of pool where FC group is.
@type pool_name: str
@param group_name: Name of FC group to fetch.
@type group_name: str
@return: Http code 200 on success and JSON representation of selected
group.
N/A
Edit given FC group configuration.
Optional JSON keys:
- "alias" - User friendly name for FC group.
- "active" - Boolean flag that modify FC group active state. Flag set
to false deactivates group, flag set to true activates group.
Example JSON input::
{
"alias": "New-Alias"
}
@param pool_name: Name of pool where FC group is.
@type pool_name: str
@param group_name: Name of group configuration to edit.
@type group_name: str
@return: Http code 200 on success and JSON representation of modified
group.
{
"properties": {
"alias": {
"oneOf": [{
"type": "string"
}, {
"type": "null"
}]
},
"active": {
"type": "boolean"
}
},
"additionalProperties": false
}
Delete given group from pool.
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group to remove.
@type group_name: str
@return: Http code 204 on success.
N/A
List all initiators assigned to FC group.
Example JSON output:
Output is in the same format as for L{get_pool_initiators} except that
list with initiators contains only those items that are assiged to given
FC group.
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group from which initiators will be listed.
@type group_name: str
@return: Http code 200 on success adn list with initiators assigned to
group.
N/A
Assign initiator to FC group.
Initiator that is assigned to FC group, gives access to all targets and
volumes in same group to port that uses selected WWN.
Required JSON keys:
- "wwn" - WWN of initiator that will be assigned to group.
Example JSON input::
{
"wwn": "21:00:00:1b:32:05:fc:10"
}
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group where initiator will be assigned.
@type group_name: str
@return: Http code 204 on success.
{
"properties": {
"wwn": {
"type": "string"
}
},
"required": ["wwn"],
"additionalProperties": false
}
Fetch configuration of initiator assigned to FC group.
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group where initiator is assigned.
@type group_name: str
@param wwn: Unique identifier of initiator to fetch.
@type wwn: str
@return: Http code 200 on success and JSON representation of selected
initiator.
N/A
Remove initiator configuration from FC group.
When initiator is removed from group, FC port with specified WWN no longer
has access to targets and volumes in that group.
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group from which initiator will be removed.
@type group_name: str
@param wwn: WWN of initiator to remove.
@type wwn: str
@return: Http code 204 on success.
N/A
List volumes assigned to group.
Each volume on pool can be assigned to many FC groups. However when volume
is used by iSCSI target then it isn't allowed to use that volume in any
FC group.
Each assigned volume has it's SCSI ID identifier that describes virtual
device that is created for that volume. For each volume only one virtual
device can be created. If volume is assigned to more than one group then
in each of the groups virtual device configuration have to be the same.
By default unique SCSI ID is generated for particular volume and it doesn't
changes for given volume until it is removed from pool. It is recommended
to use default SCSI ID generated for volume.
Example JSON output::
{
"data": [
{
"volume_name": "fc-vol0",
"lun": 0,
"scsi_id": "dfa90de2800cb220",
"prod_id": "JovianDSS",
"mode": "wt",
"block_size": 512,
"device_handler": "vdisk_fileio",
"eui": "6466613930646532"
},
"error": null
}
LUNs are represented in similar way as in iSCSI module.
LUN fields description:
- "volume_name" - Name of volume that is assigned as LUN to group.
Resources on this volume are available through targets that are present
in same group.
- "lun" - "logical unit number" for assigned volume, number from range
0 - 255, it is good idea to have at least one volume that uses number
0 because otherwise some initiators might experience issues with
discovering other volumes.
- "scsi_id" - SCSI ID is a unique identifier of virtual device that is
created for assigned volume.
- "prod_id" - Product identifier of exported volume.
- "mode" - Access mode to volume:
- "wt" - write through mode,
- "wb" - write back mode,
- "ro" - read only access.
- "block_size" - Block size of virtual device for volume. Minimal value
for block size is 512 and block size value have to be power of 2.
- "device_handler" - Type of access to volume:
- "vdisk_fileio" - File I/O access type.
- "vdisk_blockio" - Block I/O access type, performs direct block
I/O access to volume.
- "eui" - Extended unique identifier of virtual device. It is a string
of 16 hexadecimal digits. Value is created by encoding first 8
characters of SCSI ID using hexadecimal digits.
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group from which volumes will be listed.
@type group_name: str
@return: Http code 200 and list with volumes assigned to group.
N/A
Assign volume to FC group.
Create virtual device with given configuration for selected volume and
assign it to FC group. After assignment it will be possible to access
volume though targets assigned to that group. If volume is already assigned
to other group, virtual device for that volume already exists and is used
for any other group where volume is added. It is necessary to not specify
virtual device configuration or to use exactly the same settings as for
already existing device. If settings for volume virtual device doesn't
match it simply isn't assigned to group - error is returned.
Required JSON keys:
- "volume_name" - Name of volume to assign to FC group.
Optional JSON keys:
- "scsi_id" - Unique identifier of virtual device created for assigned
volume. It have to be string 16 characters in length and only
alphanumeric characters are allowed. By default when this option is not
specified SCSI ID is generated using volume name.
- "lun" - logical unit number used by assigned volume
- "mode" - access mode used by virtual device:
- "wt" - read and write access
- "wb" - write back mode,
- "ro" - read only access
- "block_size" - block size used by virtual device
- "device_handler" - type of access to volume:
- "vdisk_blockio" - block I/O device, write back mode is not
available for this device hander
- "vdisk_fileio" - file I/O device
Example JSON input::
{
"volume_name": "fc-volume-01"
}
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group from where volume will be added.
@type group_name: str
@return: Http code 204 on success.
N/A
Fetch particular volume (virtual device) assigned to given group.
Virtual device configuration that is created for particular volume is
returned. It is necessary to specify virtual device SCSI ID because it is
used as unique identifier of volume assigned to group.
Example JSON output:
Output is in the same format as for L{get_fc_group_luns} except that only
single item is returned instead of list with all volumes in group.
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group from which volumes will be listed.
@type group_name: str
@param scsi_id: Unique identifier of virtual device assigned to group.
@type scsi_id: str
@return: Http code 200 on success and JSON representation of selected
volume (virtual device).
N/A
Modify configuration of LUN in FC Group.
Settings that are assigned to virtual device (SCSI ID, mode, block_size and
device_handler) will affect all groups where volume is assigned.
Modification of those settings for LUN in one group changes them for all
other groups where volume is used. LUN number on the other hand is assigned
only to given group.
Example JSON output:
Output is in the same format as for L{get_fc_group_luns} except that only
data about modified LUN is returned.
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group where LUN is assigned.
@type group_name: str
@param scsi_id: Unique identifier of virtual device assigned to group.
@type scsi_id: str
@return: Http code 200 on success and JSON representation of modified LUN.
{
"properties": {
"scsi_id": {
"type": "string"
},
"mode": {
"type": "string"
},
"block_size": {
"type": "integer"
},
"lun": {
"type": "integer"
},
"device_handler": {
"type": "string"
}
},
"additionalProperties": false
}
Remove volume from given group.
After removal of volume from FC group targets assigned to that group will
no longer give access to removed volume.
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group from which volumes will be removed.
@type group_name: str
@param scsi_id: Unique identifier of virtual device assigned to group.
@type scsi_id: str
@return: Http code 204 on success.
N/A
List configuration of targets assigned to given group.
FC targets from system can be assigned to FC group to access through them
assigned to group volumes. As those are system FC targets configuration is
similar to described in L{get_fc_targets} however there are some additional
fields. Because targets are local to particular machine and pool might be
imported on different machine, each target assignment is in fact kind of
box (mapping) of target on particular node. That is assignment of target
to group creates mapping on that group that maps assigned local target on
node where target was assigned. Moreover it is possible to configure this
assignment to work on other nodes where pool might be imported. This
information is exposed through additional field in target configuration
"node_assignment". More on this topic can be found in
L{get_target_node_assignments}.
Example JSON output::
{
"data": [
{
"status": "OK",
"is_target_mode_enabled": true,
"is_hw_target": true,
"alias": "tgt0",
"node_assignment": {
"assignment_id": 1,
"target_mapping": [
{
"node_id": "00000001",
"wwn": "21:00:00:1b:32:05:fc:11"
},
{
"node_id": "a57452b2",
"wwn": "21:00:00:1b:32:05:fc:86"
}
],
"local_target": "21:00:00:1b:32:05:fc:86"
},
"parent_host": null,
"wwn": "21:00:00:1b:32:05:fc:86"
}
],
"error": null
}
Target fields has identical meaning as in L{get_fc_targets} except that
additional field is present: "node_assignment". This field has sub fields
that describes assignment of FC target to nodes where pool might be
imported. Following fields are present in "node_assignment":
- "assignment_id" - Unique identifier of target to group assignment
that maps targets to particular nodes.
- "local_target" - WWN of target that is configured for local node. If
target isn't configured for node where pool is currently imported this
field will have null value - in that case it is necessary to configure
target mapping for local node in order to make it working in the group.
- "target_mapping" - List with mappings of targets to particular nodes.
Each item of list contains following fields:
- "node_id" - Unique identifier of node where pool may be imported.
- "wwn" - WWN of target that shall be used on given node when pool
is imported there.
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group from which targets will be fetched.
@type group_name: str
@return: Http code 200 on success and list with targets assigned to group.
N/A
Assign target to given group.
When target is added to group all volumes that are present to group will
be available on added target (port). It is possible to add same target to
many different groups on the same pool. In that case resources from each
group will be available through this target.
Required JSON keys:
- "wwn" - WWN of target that will be added to group.
Example JSON input::
{
"wwn": "21:00:00:1b:32:05:fc:10"
}
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group where target will be added.
@type group_name: str
@return: Http code 204 on success.
{
"properties": {
"wwn": {
"type": "string"
}
},
"required": ["wwn"],
"additionalProperties": false
}
Remove target assignment from given group.
Similar operation to L{remove_target_from_fc_group} is performed but target
is identified by target assignment instead of wwn. This allows to remove
targets from group that are not configured on local node.
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group where target is present.
@type group_name: str
@param assignment_id: Integer identifier of target assignment, that will
be removed from group.
@type assignment_id: int
@return: Http code 204 on success.
N/A
Remove target from given group.
When target is removed from group, volumes from group are no longer
available on removed target.
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group where target is present.
@type group_name: str
@param wwn: WWN of target that will be removed.
@type wwn: str
@return: Http code 204 on success.
N/A
Fetch single target configuration that is assigned to given group.
Example JSON output:
Output is in the same format as for L{get_fc_group_targets} except that
only single item is returned instead of list with all targets assigned
to group.
@param pool_name: Name of pool where group is.
@type pool_name: str
@param group_name: Name of group from which target will be fetched..
@type group_name: str
@param wwn: WWN of target to fetch.
@type wwn: str
@return: Http code 200 on success and JSON representation of selected
FC target group configuration.
N/A
List all initiators added to given pool.
Initiators that are present in pool configuration are available for
assignment in FC groups. Each pool has it's own list with initiators that
is independent from other pools. Configuration is available on pool no
matter on which machine it is imported.
Example JSON output::
{
"data": [
{
"alias": "test-ini-11",
"wwn": "21:00:00:1b:32:05:fc:11"
},
{
"alias": "test-ini-10",
"wwn": "21:00:00:1b:32:05:fc:10"
}
],
"error": null
}
Initiators fields description:
- "wwn" - WWN that is unique identifier of initiator, which is a FC
port that can be allowed to gain FC group access (by assignment to
group).
- "alias" - User friendly name for initiator.
@param pool_name: Name of pool for which configuration is listed.
@type pool_name: str
@return: Http code 200 on success and list with initiators configured on
pool.
N/A
Add new initiator configuration to given pool.
Required JSON keys:
- "wwn" - WWN of initiator that will be added to pool configuration.
Optional JSON keys:
- "alias" - User friendly name for initiator.
Example JSON input::
{
"wwn": "21:00:00:1b:32:05:fc:10",
"alias": "New-Initiator"
}
@param pool_name: Name of pool where initiator is added.
@type pool_name: str
@return: Http code 200 on success and JSON representation of created
initiator configuration.
{
"properties": {
"wwn": {
"type": "string"
},
"alias": {
"type": "string"
}
},
"required": ["wwn"],
"additionalProperties": false
}
Fetch configuration of initiator with given WWN from pool.
Example JSON output:
Output is in the same format as for L{get_pool_initiators} except that only
single item is returned instead of list with all initiators on pool.
@param pool_name: Name of pool where initiator configuration is.
@type pool_name: str
@param wwn: Unique identifier of initiator to fetch.
@type wwn: str
@return: Http code 200 on success and JSON representation of selected
initiator.
N/A
Edit given initiator configuration.
Optional JSON keys:
- "alias" - User friendly name for initiator.
Example JSON input::
{
"alias": "New-Alias"
}
@param pool_name: Name of pool where configuration of initiator is.
@type pool_name: str
@param wwn: Unique identifier of initiator to edit.
@type wwn: str
@return: Http code 200 on success and JSON representation of modified
initiator.
{
"properties": {
"alias": {
"oneOf": [{
"type": "string"
}, {
"type": "null"
}]
}
},
"additionalProperties": false
}
Delete given initiator from pool configuration.
@param pool_name: Name of pool where configuration of initiator is.
@type pool_name: str
@param wwn: Unique identifier of initiator that will be deleted.
@type wwn: str
@return: Http code 204 on success.
N/A
List all targets that are assigned to any group on pool.
List every target that is assigned to at least one group on given pool.
In fact listed are assignments of target to node along with data about
locally used target (if any is configured) is returned.
Example JSON output::
Output is in the same format as for L{get_fc_group_targets} except that
targets that are assigned to any group on pool are listed instead of
targets from one particular group.
@param pool_name: Name of pool for which assigned targets will be listed.
@type pool_name: str
@return: Code 200 on success and list with targets.
N/A
List all target to node assignments of targets on pool.
FC targets are local to particular machine. When target is assigned to
group on pool, automatically target assignment is created. This assignment
maps which target shall be used in group on which node where pool may be
imported. In fact from group perspective target assignment is added to
group and there is saved that selected target is used on local node in this
assignment.
There are cases when assignment exists but target is not present or not
configured for node where pool is currently imported. It is possible
to assign targets WWN to remote nodes or assign local target if it isn't
assigned. When pool is imported on new node it might turn out that
assignment of targets for this node is not configured. In that case it is
possible to select which targets shall be used. There is also special case
when target on local node is assigned but it isn't present - for example
due to removed FC adapter. In this special case it is possible to reassign
another target from local node but it cannot be already used in any target
assignment for local node.
Example JSON output::
{
"data": [
{
"assignment_id": 1,
"target_mapping": [
{
"node_id": "00000001",
"wwn": "21:00:00:1b:32:05:fc:11"
},
{
"node_id": "a57452b2",
"wwn": "21:00:00:1b:32:05:fc:86"
}
],
"local_target": "21:00:00:1b:32:05:fc:86"
}
],
"error": null
}
Node assignment fields description:
- "assignment_id" - Unique identifier of particular target to node
assignment. It is automatically generated when assignment is created
during target addition to group.
- "local_target" - Shows WWN of target that is used on local node. If
target is not configured for local node this value will be set to null.
It is required to assign local target in order to make assignment
working in the group.
- "target_mapping" - List with all configured nodes and targets that
are used on that nodes. Each item contains following fields:
- "node_id" - Unique identifier of node where pool may be imported.
- "wwn" - WWN of target that will be used on assigned node when
pool is imported there.
@param pool_name: Name of pool for which target assignments are listed.
@type pool_name: str
@return: Code 200 on success and list with target assignments.
N/A
Fetch configuration of target assignment with given ID.
Example JSON output::
Output is in the same format as for L{get_target_node_assignments} except
that only single item is returned instead of list with all target node
assignments.
@param pool_name: Name of pool where target assignment is.
@type pool_name: str
@param assignment_id: ID of target assignment to fetch.
@type assignment_id: int
@return: Code 200 on success and configuration of target assignment.
N/A
Configure target to be used on given node when pool is imported there.
Select target WWN that shall be used on particular node. When WWN from
foreign nodes is set no validation of target existence is performed. If
target that not really exist is selected, then after import on that node
target will be listed in assignment but won't be used because it is
missing.
Required JSON keys:
- "node_id" - ID of node for which target is assigned.
- "wwn" - WWN of target that will be used on selected node.
Example JSON input::
{
"node_id": "00000001",
"wwn": "21:00:00:1b:32:05:fc:11"
}
@param pool_name: Name of pool where target assignment is.
@type pool_name: str
@param assignment_id: ID of target assignment where new node to target
mapping will ge added.
@type assignment_id: int
@return: Http code 200 on success and JSON representation of created
assignment.
{
"properties": {
"node_id": {
"type": "string"
},
"wwn": {
"type": "string"
}
},
"required": ["node_id", "wwn"],
"additionalProperties": false
}
Remove target assignment from pool and remove target from all groups.
Removal of target assignment from pool causes that all data related to
assignment of target for given pool is removed. This also removes currently
used target from all groups where it is used.
Removal of target assignment is used instead of simpler removal of target
from pool because particular target may not be present or configured in
assignment. This is the case when pool is imported on different machine
for which assignment wasn't configured. In that case it is possible to
remove assignment from that pool. This operation will remove target
placeholder from each group. In case of assignment removal from machine
where it is configured, target that is present in groups will be removed
from each of those groups.
Basically this is simple way to remove target from configuration on pool
level instead of FC group level.
@param pool_name: Name of pool from which target assignment will be
removed.
@type pool_name: str
@param assignment_id: ID of target assignment that will be removed from
pool.
@type assignment_id: int
@return: Http code 204 on success.
N/A
Change mapping of target if it is not set or target is missing.
Target mapping can be modified for local node when it isn't configured
yet (mapping for local node is not present) or target is selected but
it is missing.
Example JSON input::
{
"wwn": "21:00:00:1b:32:05:fc:11"
}
@param pool_name: Name of pool where target assignment is.
@type pool_name: str
@param assignment_id: ID of target assignment where local node mapping will
be modified.
@type assignment_id: int
@return: Http code 200 on success and JSON representation of modified
target assignment.
{
"properties": {
"wwn": {
"type": "string"
}
},
"additionalProperties": false
}
Fetch assignment for selected node.
Example JSON output::
{
"data": {
"node_id": "00000001",
"wwn": "21:00:00:1b:32:05:fc:11"
},
"error": null
}
Meaning of JSON fields is the same as described in
L{get_target_node_assignments}.
@param pool_name: Name of pool where target assignment is.
@type pool_name: str
@param assignment_id: ID of target assignment to fetch.
@type assignment_id: int
@param node_id: ID of node for which fetch target assignment.
@type node_id: str
@return: Code 200 on success and selected target node assignment.
N/A
Remove mapping for given node from target assignment.
It is possible to remove unneeded mappings for nodes where pool is not
going to be imported.
@param pool_name: Name of pool where target assignment is.
@type pool_name: str
@param assignment_id: ID of target assignment where mapping will be
removed.
@type assignment_id: int
@param node_id: ID of node for which mapping will be removed.
@type node_id: str
@return: Http code 204 on success.
N/A
List all Virtual IPs on given pool.
Example JSON output:
- Single node::
{
"data":
[
{
"name": "vip2",
"address": "192.168.25.150",
"netmask": "255.255.255.0",
"interface": "eth2",
"active": true,
},
{
"name": "vip1",
"address": "192.168.18.150",
"netmask": "255.255.255.0",
"interface": "eth1",
"active": true,
}
],
"error" : null
}
- Two nodes are bound::
{
"data":
[
{
"name": "vip1",
"address": "192.168.22.150",
"netmask": "255.255.255.0",
"interface": "eth1",
"active": true,
"remote_interface": [
{
"interface" : "eth2",
"node_id" : "236ef571"
}
]
}
],
"error" : null
}
@param pool_name: Name of pool for which virtual IPs will be listed.
@type pool_name: str
@return: Http code 200 on success.
N/A
Add new Virtual IP on given pool.
Required JSON keys:
- "name" - String with name of virtual IP. Maximum name length is 8
characters, allowed characters are: A-Z, a-z, 0-9, _ and -.
- "address" - String with IP address.
- "netmask" - String with netmask for virtual IP.
- "interface" - Name of interface on which virtual IP will be set.
- "remote_interface" - This field should be supplied only if there is
other node bound. If virtual IP is created on single node machine this
field is not allowed and shouldn't be present in JSON request. For case
when another nodes are bound this field must contain array with data
about interfaces assigned for this virtual IP on every remote node.
Every item of array must contain following keys:
- "node_id" - ID of remote node where interface for virtual IP will
be assigned.
- "interface" - Name of interface on remote node.
Optional JSON keys:
- "active" - Boolean flag that indicates if virtual IP is enabled. If
not specified it defaults to true - virtual IP is active.
Example JSON input:
- Create virtual IP for single node::
{
"name": "vip1",
"address": "192.168.120.50",
"netmask": "255.255.255.0",
"interface": "eth1"
}
- Create virtual IP when other node is bound::
{
"name": "vip2",
"address": "192.168.140.60",
"netmask": "255.255.255.0",
"interface": "eth1",
"remote_interface": [
{
"node_id": "abcdef123",
"interface": "eth7"
}
]
}
@param pool_name: Name of pool where virtual IP will be added.
@type pool_name: str
@return: Http code 201 on success.
{
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "string"
},
"netmask": {
"type": "string"
},
"interface": {
"type": "string"
},
"active": {
"type": "boolean"
},
"remote_interface": {
"type": "array",
"items": {
"properties": {
"nodeid": {
"type": "string"
},
"interface": {
"type": "string"
}
},
"required": ["node_id", "interface"]
}
}
},
"required": ["name", "address", "netmask", "interface"],
"additionalProperties": false
}
Get interface that is set as default gateway.
Example JSON output::
{
"vip_name": "VIP0",
"gateway": "192.168.0.1",
"ip": "192.168.0.5",
"netmask": "255.255.255.255"
}
N/A
Set given interface as default gateway.
Required JSON keys:
- "vip_name" - Name of VIP interface.
- "ip" - IP address of the destination.
- "netmask" - Netmask address of the destination.
Optional JSON keys:
- "gateway" - IP address of the gateway.
Example JSON input::
{
"vip_name": "VIP0",
"gateway": "192.168.0.1",
"ip": "192.168.0.5",
"netmask": "255.255.255.255"
}
@return: Http code 201 on success.
{
"properties": {
"vip_name": {
"type": "string"
},
"ip": {
"type": "string",
"format": "ipv4"
},
"netmask": {
"type": "string",
"format": "ipv4"
},
"gateway": {
"oneOf": [{
"type": "string",
"format": "ipv4"
}, {
"type": "null"
}, {
"type": "string",
"maxLength": 0
}]
}
},
"required": ["vip_name", "ip", "netmask"],
"additionalProperties": false
}
Deletes routing entry.
{
"properties": {
"ip": {
"type": "string",
"format": "ipv4"
},
"netmask": {
"type": "string",
"format": "ipv4"
}
},
"required": ["ip", "netmask"]
}
Get specified Virtual IP data.
Example JSON output:
Data format is the same as in L{get_vips_from_pool} except that single
object is returned instead of list of virtual IPs.
@param pool_name: Name of pool where virtual IP belongs to.
@type pool_name: str
@param vip_name: Name of virtual IP to list.
@type vip_name: str
@return: Http code 200 on success.
N/A
Delete given virtual IP.
@param pool_name: Name of pool where virtual IP belongs to.
@type pool_name: str
@param vip_name: Name of virtual IP that will be deleted.
@type vip_name: str
@return: Http code 204 on success.
N/A
Edit given Virtual IP.
Optional JSON keys:
All fields are the same as in L{add_vip} except that all are optional. Only
values supplied in request will be modified. If remote_interface will be
specified then whole array with interfaces will be overridden - it is
necessary to specify all remote nodes and interfaces on each modification.
Example JSON input::
{
"address": "192.168.45.65"
}
{
"name": "Vip-A",
"interface": "eth8"
}
@param pool_name: Name of pool where virtual IP belongs to.
@type pool_name: str
@param vip_name: Name of virtual IP that will be modified.
@type vip_name: str
@return: Http code 201 on success.
{
"properties": {
"name": {
"type": "string"
},
"address": {
"type": "string"
},
"netmask": {
"type": "string"
},
"interface": {
"type": "string"
},
"active": {
"type": "boolean"
},
"remote_interface": {
"type": "array",
"items": {
"properties": {
"node_id": {
"type": "string"
},
"interface": {
"type": "string"
}
},
"required": ["node_id", "interface"]
}
}
},
"additionalProperties": false
}
Lists all properties of given snapshot.
@param pool_name: Name of the zpool (e.g. "Pool-0")
@type pool_name: str
@param volume_name: Name of the volume (e.g. "v1")
@type volume_name: str
@param snapshot_name: Name of the snapshot (e.g. "MySnapshot")
@type snapshot_name: str
Example JSON output::
{
"data":
{
"referenced": "65536",
"defer_destroy": "off",
"userrefs": "0",
"primarycache": "all",
"type": "snapshot",
"creation": "2015-5-27 16:8:35",
"refcompressratio": "1.00x",
"compressratio": "1.00x",
"written": "65536",
"used": "0",
"clones": "",
"mlslabel": "none",
"secondarycache": "all"
},
"error": null
}
@return: Http code 200 on success.
N/A
Lists all volumes in pool with it's snapshots.
@param poolname: Name of the zpool (e.g. "Pool-0").
@type poolname: str
Example of JSON output::
{
"data":
[
{
"volume": "by_req",
"snapshots":
[
]
},
{
"volume": "v1",
"snapshots":
[
{
"name": "v1@MySnapshot",
"properties":
{
"creation": 1484835502
}
}
]
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Get data about given pool.
Example JSON output:
Returned JSON is in the same format as for L{get_all_pools} except that
single pool object is returned instead of array with all pools.
@param poolname: Name of pool for which data will be retrieved.
@type poolname: str
@return: Http code 200 on success.
N/A
Destroy pool with given name.
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of active pool that will be destroyed.
@type poolname: str
@return: On successful destroy http code 204 is returned.
N/A
Clear devices errors in pool.
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool where errors will be cleared.
@type poolname: str
@return: On successful clear http code 201 is returned.
N/A
List all disks in given pool.
Example JSON output::
{
"data": [
{
"name": "sdb",
"id" : "scsi-0QEMU_QEMU_HARDDISK_drive-scsi0-0-1",
"model" : "QEMU HARDDISK ",
"sn" : "",
"path" : "pci-0000:00:06.0-scsi-0:0:1:0",
"size" : 10737418240
"led": null,
"iostats": {"read": "0", "write": "0", "chksum": "0"},
"health" : "ONLINE"
}
],
"error" : null
}
Disk fields description:
- "iostats" - object containing number of read, write and checksum
errors, this value is obtained from zfs
- "health" - disk status obtained from zfs
- rest of disk fields has same meaning as described in
get_all_disks_from_system
@param poolname: Name of pool for which disks will be listed.
@type poolname: str
@return: Http code 200 on success.
N/A
Get disk with given ID from pool with given name.
Example JSON output:
Single disk object that has the same format as disks returned from
L{get_all_disks_from_pool}
@param poolname: Name of pool for which disks will be listed.
@type poolname: str
@param disk_id: ID of disk that will be listed. Disk with this ID have to
belong to given pool otherwise http code 404 will be returned.
@type disk_id: str
@return: Http code 200 on success.
N/A
Remove given disk from pool.
Only spare, single log and cache disks can be removed from pool.
@param poolname: Name of pool where disk belongs to.
@type poolname: str
@param disk_id: ID of disk that will be removed from pool.
@type disk_id: str
@return: Http code 204 on success.
N/A
Attach another disk to specified one in given pool.
Disk that will be attached is provided in JSON request.
Required JSON keys:
- "disk_to_attach" - ID of disk that will be attached.
Example JSON input::
{
"disk_to_attach": "scsi-0QEMU_QEMU_HARDDISK_drive-scsi0-0-5"
}
@param poolname: Name of pool where disk belongs to.
@type poolname: str
@param disk_id: ID of disk to which new disk will be attached. Even if disk
is attached to mirror vdev ID of one of disks need to be provided in order
to attach new disk.
@type disk_id: str
@return: Http code 201 on success.
{
"properties": {
"disk_to_attach": {
"type": "string"
}
},
"required": ["disk_to_attach"]
}
Clear error count on given disk.
@param poolname: Name of pool where disk belongs to.
@type poolname: str
@param disk_id: ID of disk that error count will be cleared.
@type disk_id: str
@return: Http code 201 on success.
N/A
Detach given disk from vdev in pool.
Disk can be detached only if it belongs to mirror vdev. Otherwise this
operation will fail.
@param poolname: Name of pool where disk belongs to.
@type poolname: str
@param disk_id: ID of disk that will be detached from vdev.
@type disk_id: str
@return: Http code 201 on success.
N/A
Offline disk in given pool.
@param poolname: Name of pool where disk belongs to.
@type poolname: str
@param disk_id: ID of disk that will be bring offline.
@type disk_id: str
@return: Http code 201 on success.
N/A
Online disk in given pool.
@param poolname: Name of pool where disk belongs to.
@type poolname: str
@param disk_id: ID of disk that will be bring online.
@type disk_id: str
@return: Http code 201 on success.
N/A
Replace given disk with another one given in JSON request.
Disk that will be used to replace is send in JSON request.
Required JSON keys:
- "new_disk" - ID of disk that will be used as replacement.
Example JSON input::
{
"new_disk": "scsi-0QEMU_QEMU_HARDDISK_drive-scsi0-0-5"
}
@param poolname: Name of pool where disk belongs to.
@type poolname: str
@param disk_id: ID of disk that will be replaced with new disk.
@type disk_id: str
@return: Http code 201 on success.
{
"properties": {
"new_disk": {
"type": "string"
}
},
"required": ["new_disk"]
}
Expand the pool to use all new available space (for example after replacing both drives in a mirror).
Example JSON output:
End-point doesn't return any data.
@return: HTTP code 201 on success
N/A
Export pool with given name.
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool to export.
@type poolname: str
@return: On successful pool export http code 201 is returned.
N/A
Mount given pool.
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool to mount.
@type poolname: str
@return: On successful pool mount http code 201 is returned.
N/A
Return list with all iSCSI targets available in given pool.
End-point return array with information about all iSCSI targets in given pool.
Example JSON output::
{
"data": [
{
"incoming_users_active": true,
"name": "iqn.2015-05:dss.target0",
"allow_ip": [
"192.168.2.30/0",
"192.168.3.45"
],
"outgoing_user": {
"password": "11223344556677"
},
"active": true,
"conflicted": false,
"deny_ip": [
"0.0.0.0/0"
]
},
{
"incoming_users_active": false,
"name": "iqn.2015-05:dss.target1",
"allow_ip": [],
"outgoing_user": null,
"active": false,
"conflicted": false,
"deny_ip": []
}
],
"error": null
}
@param poolname: Name of pool
@type poolname: str
@return: On successful HTTP code 200 is returned.
N/A
Create new iSCSI target in given pool.
Configuration of iSCSI target is provided in JSON formatted data.
Required JSON keys:
- "name" - String with name of iSCSI target. String can contain
up to 255 characters. Regular expression for validation names is
"^\w([a-z0-9\.:\-]*\w)?$"
Optional JSON keys:
- "active" - Boolean value that indicates if iSCSI target should be
activated after creating.
- "incoming_users_active" - Boolean value that indicates if CHAP users
authentication functionality should be enabled. If any user will not be
created using end-point (POST):
/pools//san/iscsi/targets//incoming-users
access to iSCSI target will not be allowed.
- "outgoing_user": - Object containing name and password for
mutual/outgoing CHAP user.
Regular expression for validation names is '^\w([a-zA-Z0-9-_]*\w)?$'.
Password must consist of at least 12 characters and cannot contain
whitespace characters.
Regular expression for validation password is '^[a-zA-Z0-9-_!@%()+?.:;]+$'.
Please make sure that mutual CHAP user name is different than any other
CHAP user.
- "allow_ip" - Array with network classes or specify individual IP addresses
that are permitted to access the target from iSCSI initiator.
Each item of array contains IP string.
Allowed network addresses field (allow_ip) has higher priority than
denied network addresses field (deny_ip).
- "deny_ip" - Array with network classes or specify individual IP addresses
that are denied to access the target from iSCSI initiator.
Each item of array contains network classes or IP string.
Allowed network addresses field (allow_ip) has higher priority than
denied network addresses field (deny_ip).
In order to completely block access, set address 0.0.0.0/0.
Example JSON input::
{
"name": "iqn.2015-05:dss.target2",
"active": true,
"incoming_users_active": true,
"outgoing_user": {
"password": "zxcasdqwe123",
"name": "mutual_user"
},
"allow_ip": [
"192.168.2.30/0",
"192.168.3.45"
],
"deny_ip": [
"0.0.0.0/0"
]
}
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool
@type poolname: str
@return: On successful iSCSI target creation HTTP code 201 is returned.
{
"properties": {
"name": {
"type": "string"
},
"active": {
"type": "boolean"
},
"incoming_users_active": {
"type": "boolean"
},
"allow_ip": {
"type": "array",
"items": {
"type": "string"
}
},
"deny_ip": {
"type": "array",
"items": {
"type": "string"
}
},
"outgoing_user": {
"properties": {
"name": {
"type": "string"
},
"password": {
"type": "string"
}
},
"additionalProperties": false,
"required": ["name", "password"]
}
},
"additionalProperties": false,
"required": ["name"]
}
Return information about iSCSI target in given pool.
End-point return information about iSCSI target in given pool.
Example JSON output::
{
"data": {
"incoming_users_active": true,
"name": "iqn.2015-05:dss.target0",
"allow_ip": [
"192.168.2.30/0",
"192.168.3.45"
],
"outgoing_user": {
"password": "11223344556677",
"name": "outuser"
},
"active": true,
"conflicted": false,
"deny_ip": [
"0.0.0.0/0"
]
},
"error": null
}
@param poolname: Name of pool
@type poolname: str
@param target_name: Name of iSCSI target.
@type target_name: str
@return: On successful HTTP code 200 is returned.
N/A
Remove existing iSCSI target in given pool.
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool
@type poolname: str
@param target_name: Name of iSCSI target.
@type target_name: str
@return: On successful remove HTTP code 204 is returned.
N/A
Modify existing iSCSI target in given pool.
Configuration of iSCSI target is provided in JSON formatted data.
Optional JSON keys:
- "name" - String with new name of iSCSI target. String can contain
up to 255 characters. Regular expression for validation names is
"^\w([a-z0-9\.:\-]*\w)?$"
- "active" - Boolean value that indicates if iSCSI target should be
activated.
- "incoming_users_active" - Boolean value that indicates if CHAP users
authentication functionality should be enabled. If none user will be
created using end-point (POST):
/pools//san/iscsi/targets//incoming-users
access to iSCSI target will not be allowed.
- "outgoing_user": - Object containing name and password for
mutual/outgoing CHAP user.
Regular expression for validation names is '^\w([a-zA-Z0-9-_]*\w)?$'.
Password must consist of at least 12 characters and cannot contain
whitespace characters.
Regular expression for validation password is '^[a-zA-Z0-9-_!@%()+?.:;]+$'.
Please make sure that mutual CHAP user name is different than any other
CHAP user.
- "allow_ip" - Array with network classes or specify individual IP addresses
that are permitted to access the target from iSCSI initiator.
Each item of array contains IP string.
Allowed network addresses field (allow_ip) has higher priority than
denied network addresses field (deny_ip).
- "deny_ip" - Array with network classes or specify individual IP addresses
that are denied to access the target from iSCSI initiator.
Each item of array contains network classes or IP string.
Allowed network addresses field (allow_ip) has higher priority than
denied network addresses field (deny_ip).
In order to completely block access, set address 0.0.0.0/0.
Example JSON input::
{
"name": "iqn.2015-05:dss.target2",
"active": true,
"incoming_users_active": true,
"outgoing_user": {
"password": "zxcasdqwe123",
"name": "mutual_user"
},
"allow_ip": [
"192.168.2.30/0",
"192.168.3.45"
],
"deny_ip": [
"0.0.0.0/0"
]
}
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool
@type poolname: str
@param target_name: Name of iSCSI target to modify.
@type target_name: str
@return: On successful iSCSI target modification HTTP code 200 is returned.
{
"properties": {
"name": {
"type": "string"
},
"active": {
"type": "boolean"
},
"incoming_users_active": {
"type": "boolean"
},
"allow_ip": {
"type": "array",
"items": {
"type": "string"
}
},
"deny_ip": {
"type": "array",
"items": {
"type": "string"
}
},
"outgoing_user": {
"properties": {
"name": {
"type": "string"
},
"password": {
"type": "string"
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Return list with all CHAP users which can connect to given iSCSI target.
End-point return array with all CHAP users which can connect
to given iSCSI target.
Example JSON output::
{
"data": [
{
"name": "user2"
},
{
"name": "user1"
}
],
"error": null
}
@param poolname: Name of pool
@type poolname: str
@param target_name: Name of iSCSI target.
@type target_name: str
@return: On successful HTTP code 200 is returned.
N/A
Create new CHAP user for given iSCSI target in given pool.
Configuration of new CHAP user is provided in JSON formatted data.
Required JSON keys:
- "name" - String with name of CHAP user.
Regular expression for validation names is '^\w([a-zA-Z0-9-_]*\w)?$'.
- "password" - String with password/target secret for CHAP user.
Password must consist of at least 12 characters and cannot contain
whitespace characters.
Regular expression for validation password is '^[a-zA-Z0-9-_!@%()+?.:;]+$'.
Example JSON input::
{
"name": "target_user",
"password": "3e21ewqdsacxz"
}
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool
@type poolname: str
@param target_name: Name of iSCSI target.
@type target_name: str
@return: On successful CHAP user creation HTTP code 201 is returned.
{
"properties": {
"name": {
"type": "string"
},
"password": {
"type": "string"
}
},
"required": ["name", "password"],
"additionalProperties": false
}
Modify existing CHAP user in given iSCSI target in given pool.
Configuration for modifying CHAP user is provided in JSON formatted data.
Required JSON keys:
- "name" - String with name of CHAP user.
Regular expression for validation names is '^\w([a-zA-Z0-9-_]*\w)?$'.
- "password" - String with password/target secret for CHAP user.
Password must consist of at least 12 characters and cannot contain
whitespace characters.
Regular expression for validation password is '^[a-zA-Z0-9-_!@%()+?.:;]+$'.
Example JSON input::
{
"name": "target_user",
"password": "3e21ewqdsacxz"
}
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool
@type poolname: str
@param target_name: Name of iSCSI target.
@type target_name: str
@param user_name: Name of CHAP user that will be modified.
@type user_name: str
@return: On successful CHAP user modification HTTP code 201 is returned.
{
"properties": {
"name": {
"type": "string"
},
"password": {
"type": "string"
}
},
"additionalProperties": false
}
Remove existing CHAP user from iSCSI target in given pool.
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool.
@type poolname: str
@param target_name: Name of iSCSI target where CHAP user exists.
@type target_name: str
@param user_name: Name of CHAP user.
@type user_name: str
@return: On successful remove user HTTP code 204 is returned.
N/A
Return list LUN's assigned to given iSCSI target.
End-point return array with all information about all zvols/LUNs in
given iSCSI target. Every item of an array is a dictionary with data
about particular LUN.
Example JSON output::
{
"data": [
{
"name": "zvol1",
"block_size": 512,
"mode": "wt",
"scsi_id": "BScDoXmbe5v6g7wL",
"lun": 1,
"eui": "425363446f586d62"
},
{
"name": "zvol2",
"block_size": 512,
"mode": "wt",
"scsi_id": "1111111111111111",
"lun": 0,
"eui": "3131313131313131"
}
],
"error": null
}
@param poolname: Name of pool
@type poolname: str
@param target_name: Name of iSCSI target.
@type target_name: str
@return: On successful HTTP code 200 is returned.
N/A
Attach existing zvol to given iSCSI target.
Configuration of iSCSI target is provided in JSON formatted data.
Required JSON keys:
- "name" - String with name of existing zvol.
Optional JSON keys:
- "scsi_id" - String with SCSI ID which will be set when zvol is
attached to iSCSI target.
Regular expression for validation SCSI ID is '[a-zA-Z0-9]{16}$'.
SCSI ID is T10 vendor specific identifier for Device Identification
VPD page (0x83) of INQUIRY data.
Note: some initiators, e.g. VMware's ESXi or MS Hyper-V, only looks
at the first eight characters of SCSI ID. You have to make sure
that these first eight characters are unique or VMware will consider
these devices as identical.
- "lun" - LUN number which will be set when zvol is attached to iSCSI
target.
Please note that in order to access iSCSI-enabled data from an
initiator, the target needs to have a LUN 0, otherwise the data in all
other LUNs will be inaccessible.
- "mode" - Type of access mode to volume:
- "wt" - write through
- "wb" - write back
- "ro" - read only
- "block_size" - Block size information which will be set for LUN.
The block size must be power of 2 and >= 512 bytes. Default is 512.
- "device_handler" - Type of I/O access to volume:
- "vdisk_fileio" - File I/O access type.
- "vdisk_blockio" - Block I/O access type, performs direct block
I/O access to volume.
Example JSON input::
{
"name": "zvol1",
"scsi_id": "1234567890123456",
"lun": 0,
"mode": "ro",
"block_size" : 512
}
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool
@type poolname: str
@param target_name: Name of iSCSI target.
@type target_name: str
@return: On successful LUN attach HTTP code 200 is returned.
{
"properties": {
"name": {
"type": "string"
},
"scsi_id": {
"type": "string"
},
"lun": {
"type": "integer"
},
"mode": {
"type": "string"
},
"block_size": {
"type": "integer"
},
"device_handler": {
"type": "string"
}
},
"required": ["name"],
"additionalProperties": false
}
Return information about zvol.
End-point return all information about zvol in given iSCSI target.
Example JSON output::
{
"data": {
"name": "volume4",
"block_size": 512,
"mode": "ro",
"scsi_id": "6778da4b1cb60221",
"lun": 1
},
"error": null
}
@param poolname: Name of pool
@type poolname: str
@param target_name: Name of iSCSI target.
@type target_name: str
@param zvol: Zvol name/SCST device_name.
@type zvol: str
@return: On successful HTTP code 200 is returned.
N/A
Detach zvol/LUN from given iSCSI target.
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool
@type poolname: str
@param target_name: Name of iSCSI target.
@type target_name: str
@param zvol: Zvol name/SCST device_name.
@type zvol: str
@return: On successful zvol detach HTTP code 204 is returned.
N/A
Modify existing LUN/zvol in given iSCSI target.
Modification sends INQUIRY DATA HAS CHANGED Unit Attention so
iSCSI initiator do not break the connection - it applies only for modification
zvol name, scsi_id, mode and block size.
Configuration of LUN is provided in JSON formatted data.
Required JSON keys:
- "lun" - LUN number which is set for zvol.
If you want to modify LUN number you need to detach and attach zvol
again with new number. Dynamic modify of LUN number is not possible.
Optional JSON keys:
- "scsi_id" - String with SCSI ID which will be set.
Regular expression for validation SCSI ID is '[a-zA-Z0-9]{16}$'.
SCSI ID is T10 vendor specific identifier for Device Identification
VPD page (0x83) of INQUIRY data.
Note: some initiators, e.g. VMware's ESXi or MS Hyper-V, only looks
at the first eight characters of SCSI ID. You have to make sure
that these first eight characters are unique or VMware will consider
these devices as identical.
- "mode" - Type of access mode to volume:
- "wt" - write through
- "wb" - write back
- "ro" - read only
- "block_size" - Block size information which should be set for LUN.
The block size must be power of 2 and >= 512 bytes. Default is 512.
- "device_handler" - Type of I/O access to volume:
- "vdisk_fileio" - File I/O access type.
- "vdisk_blockio" - Block I/O access type, performs direct block
I/O access to volume.
Example JSON input::
{
"scsi_id": "aabbcc4433221144",
"lun": 1,
"mode": "ro",
"block_size" : 1024
}
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool
@type poolname: str
@param target_name: Name of iSCSI target.
@type target_name: str
@param zvol: LUN/zvol name to modify.
@type zvol: str
@return: On successful LUN modify HTTP code 200 is returned.
{
"properties": {
"lun": {
"type": "integer"
},
"mode": {
"type": "string"
},
"scsi_id": {
"type": "string"
},
"block_size": {
"type": "integer"
},
"device_handler": {
"type": "string"
}
},
"additionalProperties": false
}
Start or stop scrub scan on given pool.
Required JSON keys:
- "action" - Indicates if scrub should be started or stoppend on given
pool. Only following values are allowed: "start", "stop".
Example JSON output:
End-point doesn't return any data.
@return: On successful scrub run http code 201 is returned.
{
"properties": {
"action": {
"type": "string"
}
}
}
Return scrub scheduler for given pool.
Example JSON output::
{
"data": [
{
"day_of_the_month" : "*/2",
"hour" : "6",
"last_time_started" : "N/A",
"month_of_the_year" : "*",
"day_of_the_week" : "*",
"minute" : "15"
}
],
"error" : null
}
@param poolname: Name of pool for which scheduler will be returned.
@type poolname: str
@return: Http code 200 on success.
N/A
Set scheduler for scrub on given pool.
Example JSON input::
{
"day_of_the_week": "*",
"month_of_the_year": "*",
"day_of_the_month": "*",
"hour": "*",
"minute": "*"
}
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool for which scheduler will be set.
@type poolname: str
@return: Http code 200 on success.
{
"properties": {
"day_of_the_month": {
"type": "string"
},
"day_of_the_week": {
"type": "string"
},
"month_of_the_year": {
"type": "string"
},
"hour": {
"type": "string"
},
"minute": {
"type": "string"
}
},
"required": ["day_of_the_month", "day_of_the_week", "month_of_the_year", "hour", "minute"]
}
Remove scrub scheduler for given pool.
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool for which scheduler will be removed.
@type poolname: str
@return: Http code 204 on success.
N/A
None
N/A
Provides information about system volume
upgrade status:
- 'not_needed' : System volume is up to date
- 'needed' : System volume is outdated and needs an upgrade
- 'ready' : System volume is outdated, and will be upgraded
when the pool is exported
- 'interrupted': System volume is outdated, previous upgrade was interrupted
- 'out_of_space': System volume is outdated, but there is not enough space
on the pool for an upgrade
- 'name_taken': System volume is outdated, but upgrade cannot be performed
because of a zvol name conflict
- 'backup_name_taken': System volume is outdated, but upgrade cannot be performed
because of a zvol name conflict
- 'no_sysvol': System volume is not available
Example JSON output:
{
"status": "ready"
}
@param poolname: Name of pool on which system volume should be checked
@type poolname: str
@return: Http code 200 on success.
N/A
Initialize pools system volume upgrade process.
On pool export/move the upgrade will be finalized.
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool to upgrade.
@type poolname: str
@return: When successful http code 201 is returned.
N/A
Unmount given pool.
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool to unmount.
@type poolname: str
@return: On successful pool unmount http code 201 is returned.
N/A
Upgrade given pool.
Example JSON output:
End-point doesn't return any data.
@param poolname: Name of pool to upgrade.
@type poolname: str
@return: On successful pool unmount http code 201 is returned.
N/A
Gets all or specified vdevs for a pool.
N/A
Adds vdev to the pool.
{
"properties": {
"vdevs": {
"type": "array",
"items": {
"properties": {
"type": {
"type": "string",
"enum": ["", "mirror", "raidz1", "raidz2", "raidz3", "log", "log mirror", "spare", "cache", "special", "special mirror", "dedup", "dedup mirror"]
},
"disks": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": ["type", "disks"]
}
}
},
"required": ["vdevs"]
}
Remove given vdev from zpool
N/A
Gets all or specified vdevs for a pool.
N/A
Gets all or specified vdevs for a pool.
N/A
None
N/A
Lists all volumes of given pool.
@param poolname: Name of the zpool (e.g. "Pool-0").
@type poolname: str
Example JSON output (success)::
{
"data":
[
{
"origin": null,
"referenced": "65536",
"primarycache": "all",
"logbias": "latency",
"creation": "1432730973",
"sync": "always",
"is_clone": false,
"dedup": "off",
"used": "1076101120",
"full_name": "Pool-0/v1",
"type": "volume",
"written": "65536",
"usedbyrefreservation": "1076035584",
"compression": "lz4",
"usedbysnapshots": "0",
"copies": "1",
"compressratio": "1.00x",
"readonly": "off",
"mlslabel": "none",
"secondarycache": "all",
"available": "976432164864",
"resource_name": "Pool-0/v1",
"volblocksize": "131072",
"refcompressratio": "1.00x",
"snapdev": "hidden",
"volsize": "1073741824",
"reservation": "0",
"usedbychildren": "0",
"usedbydataset": "65536",
"name": "v1",
"checksum": "on",
"refreservation": "1076101120"
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Creates volume on given pool with provided properties.
@param poolname: Name of the zpool (e.g. "Pool-0").
@type poolname: str
Required JSON keys:
- "name" - string with name of the new volume.
- "size" - integer which is the size of new volume in bytes.
Optional JSON keys:
- "blocksize" - integer or string indicating block size of new volume (by default 131072).
- "create_parents" - boolean indicating if all non-existing parent datasets should be created
(default false).
- "sparse" - boolean taht if set to true creates a sparse volume with no reservation
(default false)
- "properties" - object containing values for properties like:
- "compression" - ('off', 'on', 'lzjb', 'gzip', 'gzip-1', 'gzip-2', 'gzip-3', 'gzip-4',
'gzip-5', 'gzip-6', 'gzip-7', 'gzip-8', 'gzip-9', 'zle', 'lz4')
- "primarycache" - ('all', 'none', 'metadata')
- "secondarycache" - same as primary
- "logbias" - ('latency', 'throughput')
- "sync" - ('always', 'standard', 'disabled')
- "dedup" - ('off', 'on', 'verify', 'sha256', 'sha256,verify')
- "copies" - (1, 2, 3)
Example JSON input::
{
"name": "by_req",
"size": "1000000"
}
Example JSON output::
{
"data":
{
"origin": null,
"is_clone": false,
"full_name": "Pool-0/by_req",
"name": "by_req"
},
"error": null
}
@return: Http code 201 on success.
{
"properties": {
"name": {
"type": "string"
},
"size": {
"type": "string"
},
"blocksize": {
"oneOf": [{
"type": "string"
}, {
"type": "integer"
}]
},
"create_parents": {
"type": "boolean"
},
"sparse": {
"type": "boolean"
},
"properties": {
"type": "object"
}
},
"required": ["name", "size"]
}
Returns data of single volume which belongs to given pool.
@param poolname: Name of the zpool (e.g. "Pool-0").
@type poolname: str
@param volumename: Name of the volume (e.g. "v1").
@type volumename: str
Example JSON output::
{
"data":
{
"origin": null,
"referenced": "65536",
"primarycache": "all",
"logbias": "latency",
"creation": "1432730973",
"sync": "always",
"is_clone": false,
"dedup": "off",
"used": "1076101120",
"full_name": "Pool-0/v1",
"type": "volume",
"written": "65536",
"usedbyrefreservation": "1076035584",
"compression": "lz4",
"usedbysnapshots": "0",
"copies": "1",
"compressratio": "1.00x",
"readonly": "off",
"mlslabel": "none",
"secondarycache": "all",
"available": "976432152576",
"resource_name": "Pool-0/v1",
"volblocksize": "131072",
"refcompressratio": "1.00x",
"snapdev": "hidden",
"volsize": "1073741824",
"reservation": "0",
"usedbychildren": "0",
"usedbydataset": "65536",
"name": "v1",
"checksum": "on",
"refreservation": "1076101120"
},
"error": null
}
@return: Http code 200 on success.
N/A
Modify volume property specified in request.
@param poolname: Name of the zpool (e.g. "Pool-0").
@type poolname: str
@param volumename: Name of the volume (e.g. "v1").
@type volumename: str
Required JSON keys:
- any, at least one
Optional JSON keys:
- "name" - string with new name of the volume.
- "size" - integer which is the new size of volume in bytes.
- "provisioning" - string describing type of the volume provisioning ('thin', 'thick').
Example JSON input::
{
"name": "newName"
}
Example JSON output::
{
"data": null,
"error": null
}
@return: Http code 201 on success.
{
"oneOf": [{
"properties": {
"name": {
"type": "string"
}
},
"required": ["name"]
}, {
"properties": {
"size": {
"type": "string"
}
},
"required": ["size"]
}, {
"properties": {
"provisioning": {
"type": "string",
"enum": ["thin", "thick"]
}
},
"required": ["provisioning"]
}]
}
Deletes given volume.
@param poolname: Name of the zpool (e.g. "Pool-0").
@type poolname: str
@param volumename: Name of the volume (e.g. "v1").
@type volumename: str
Optional JSON keys:
- "recursively_children" - boolean indicating if zfs should recursively destroy all children of resource,
in case of snapshot remove all snapshots in descendant file system (default false).
- "recursively_dependents" - boolean indicating if zfs should recursively destroy all dependents,
including cloned file systems outside the target hierarchy (default false).
- "force_umount" - boolean indicating if volume should be forced to umount (defualt false).
Example of JSON input::
{
"force_umount": true
}
@return: Http code 204 on success.
{
"properties": {
"recursively_children": {
"type": "boolean"
},
"recursively_dependents": {
"type": "boolean"
},
"force_umount": {
"type": "boolean"
},
"check_snapshot_clones": {
"type": "boolean"
}
}
}
Clone volume.
@param poolname: Name of the zpool (e.g. "Pool-0")
@type poolname: str
@param volumename: Name of the volume (e.g. "v1")
@type volumename: str
Required JSON keys:
- "name" - string with the name that will be assigned to clone.
- "snapshot" - string name of the snapshot that clone will be created from.
Optional JSON keys:
- "create_parents" - boolean, if positive creates all non existing parents of dataset where snapshot will be
cloned. Parent datasets must exist to successfully create snapshot clone (default false).
- "properties" - object with properties for the new clone.
Example of JSON input::
{
"name": "MyClone",
"snapshot": "MySnapshot"
}
Example of JSON output::
{
"data":
{
"origin": "Pool-0/v1@MySnapshot",
"is_clone": true,
"full_name": "Pool-0/MyClone",
"name": "MyClone"
},
"error": null
}
@return: Http code 200 on success.
{
"properties": {
"snapshot": {
"type": "string"
},
"name": {
"type": "string"
},
"create_parents": {
"type": "boolean"
},
"properties": {
"type": "object"
}
},
"required": ["snapshot", "name"]
}
Gets all properties of the given volume.
@param poolname: Name of the zpool (e.g. "Pool-0")
@type poolname: str
@param volumename: Name of the volume (e.g. "v1")
@type volumename: str
Example of JSON output::
{
"data":
[
{
"owner": "Pool-0/v1",
"name": "checksum",
"value": "on"
},
{
"owner": "Pool-0/v1",
"name": "usedbyrefreservation",
"value": "1076101120"
},
{
"owner": "Pool-0/v1",
"name": "creation",
"value": "1432730973"
},
{
"owner": "Pool-0/v1",
"name": "mlslabel",
"value": "none"
},
{
"owner": "Pool-0/v1",
"name": "reservation",
"value": "0"
},
{
"owner": "Pool-0/v1",
"name": "referenced",
"value": "65536"
},
{
"owner": "Pool-0/v1",
"name": "written",
"value": "0"
},
{
"owner": "Pool-0/v1",
"name": "volsize",
"value": "1073741824"
},
{
"owner": "Pool-0/v1",
"name": "primarycache",
"value": "all"
},
{
"owner": "Pool-0/v1",
"name": "snapdev",
"value": "visible"
},
{
"owner": "Pool-0/v1",
"name": "usedbydataset",
"value": "65536"
},
{
"owner": "Pool-0/v1",
"name": "refcompressratio",
"value": "1.00x"
},
{
"owner": "Pool-0/v1",
"name": "compression",
"value": "lz4"
},
{
"owner": "Pool-0/v1",
"name": "volblocksize",
"value": "131072"
},
{
"owner": "Pool-0/v1",
"name": "available",
"value": "976430936064"
},
{
"owner": "Pool-0/v1",
"name": "type",
"value": "volume"
},
{
"owner": "Pool-0/v1",
"name": "sync",
"value": "always"
},
{
"owner": "Pool-0/v1",
"name": "usedbychildren",
"value": "0"
},
{
"owner": "Pool-0/v1",
"name": "secondarycache",
"value": "all"
},
{
"owner": "Pool-0/v1",
"name": "copies",
"value": "1"
},
{
"owner": "Pool-0/v1",
"name": "origin",
"value": null
},
{
"owner": "Pool-0/v1",
"name": "refreservation",
"value": "1076101120"
},
{
"owner": "Pool-0/v1",
"name": "logbias",
"value": "latency"
},
{
"owner": "Pool-0/v1",
"name": "resource_name",
"value": "Pool-0/v1"
},
{
"owner": "Pool-0/v1",
"name": "dedup",
"value": "off"
},
{
"owner": "Pool-0/v1",
"name": "readonly",
"value": "off"
},
{
"owner": "Pool-0/v1",
"name": "used",
"value": "1076166656"
},
{
"owner": "Pool-0/v1",
"name": "usedbysnapshots",
"value": "0"
},
{
"owner": "Pool-0/v1",
"name": "compressratio",
"value": "1.00x"
}
],
"error": null
}
@return: Http code 204 on success.
N/A
Modifies volume properties.
@param poolname: Name of the zpool (e.g. "Pool-0")
@type poolname: str
@param volumename: Name of the volume (e.g. "v1")
@type volumename: str
Required JSON keys:
- "property_name" - string with name of the property.
- "property_value" - New value of the property.
Example JSON input::
{
"property_name": "copies",
"property_value": "2"
}
@return: Http code 201 on success.
{
"property_name": {
"type": "string"
},
"property_value": {
"type": "string"
}
}
Creates snapshot.
@param poolname: Name of the zpool (e.g. "Pool-0")
@type poolname: str
@param volumename: Name of the volume (e.g. "v1")
@type volumename: str
Required JSON keys:
- "snapshot_name" - string with name of the new snapshot.
Optional JSON keys:
- "recursive" - boolean indicating if recursively create snapshots of all descendant datasets.
- "properties" - object containing properties of new snapshot.
Example of JSON input::
{
"snapshot_name": "QuiteNice"
}
@return: Http code 200 on success.
{
"properties": {
"snapshot_name": {
"type": "string"
},
"recursive": {
"type": "boolean"
},
"properties": {
"type": "object"
}
},
"required": ["snapshot_name"]
}
Lists all snapshots of the given volume.
@param poolname: Name of the zpool (e.g. "Pool-0")
@type poolname: str
@param volumename: Name of the volume (e.g. "v1")
@type volumename: str
Example of JSON output::
{
"data":
[
{
"referenced": "65536",
"name": "MySnapshot",
"defer_destroy": "off",
"userrefs": "0",
"primarycache": "all",
"type": "snapshot",
"creation": "2015-5-27 16:8:35",
"refcompressratio": "1.00x",
"compressratio": "1.00x",
"written": "65536",
"used": "0",
"clones": "",
"mlslabel": "none",
"secondarycache": "all"
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Deletes given snapshot.
@param poolname: Name of the zpool (e.g. "Pool-0")
@type poolname: str
@param volumename: Name of the volume (e.g. "v1")
@type volumename: str
@param snapshotname: Name of the snapshot (e.g. "MySnapshot")
@type snapshotname: str
Optional JSON keys:
- "recursively_children" - boolean indicating if zfs should recursively destroy all children of resource,
in case of snapshot remove all snapshots in descendant file system (default false).
- "recursively_dependents" - boolean indicating if zfs should recursively destroy all dependents,
including cloned file systems outside the target hierarchy (default false).
- "force_umount" - boolean indicating if volume should be forced to umount (defualt false).
Example of JSON input::
{
"recursively_dependents": false
}
@return: Http code 204 on success.
{
"properties": {
"recursively_children": {
"type": "boolean"
},
"recursively_dependents": {
"type": "boolean"
},
"force_umount": {
"type": "boolean"
}
}
}
Lists all clones of given snapshot.
@param poolname: Name of the zpool (e.g. "Pool-0")
@type poolname: str
@param volumename: Name of the volume (e.g. "v1")
@type volumename: str
@param snapshotname: Name of the snapshot (e.g. "MySnapshot")
@type snapshotname: str
Example of JSON output::
{
"data":
[
{
"origin": "Pool-0/v1@MySnapshot",
"is_clone": true,
"full_name": "Pool-0/MyClone",
"name": "MyClone"
},
{
"origin": "Pool-0/v1@MySnapshot",
"is_clone": true,
"full_name": "Pool-0/MyClone",
"name": "MyClone"
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Return description of a given clone.
@param poolname: Name of the zpool (e.g. "Pool-0").
@type poolname: str
@param volumename: Name of the volume (e.g. "v1").
@type volumename: str
@param snapshotname: Name of the snapshot (e.g. "MySnapshot").
@type snapshotname: str
@param clonename: Name of the clone (e.g. "MyClone").
@type clonename: str
Example of JSON output::
{
"data":
{
"origin": "Pool-0/v1@MySnapshot",
"is_clone": true,
"full_name": "Pool-0/MyClone",
"name": "MyClone"
},
"error": null
}
@return: Http code 200 on success.
N/A
Deletes given clone.
@param poolname: Name of the zpool (e.g. "Pool-0").
@type poolname: str
@param volumename: Name of the volume (e.g. "v1").
@type volumename: str
@param snapshotname: Name of the snapshot (e.g. "MySnapshot").
@type snapshotname: str
@param clonename: Name of the clone (e.g. "MyClone").
@type clonename: str
Optional JSON keys:
- "recursively_children" - boolean indicating if zfs should recursively destroy all children of resource,
in case of snapshot remove all snapshots in descendant file system (default false).
- "recursively_dependents" - boolean indicating if zfs should recursively destroy all dependents,
including cloned file systems outside the target hierarchy (default false).
- "force_umount" - boolean indicating if volume should be forced to umount (defualt false).
Example of JSON input::
{
"umount": true
}
@return: Http code 204 on success.
{
"properties": {
"recursively_children": {
"type": "boolean"
},
"recursively_dependents": {
"type": "boolean"
},
"force_umount": {
"type": "boolean"
}
}
}
Promote clone to dataset.
@param poolname: Name of the zpool (e.g. "Pool-0").
@type poolname: str
@param volumename: Name of the volume (e.g. "v1").
@type volumename: str
@param snapshotname: Name of the snapshot (e.g. "MySnapshot").
@type snapshotname: str
@param clonename: Name of the clone (e.g. "MyClone").
@type clonename: str
@return: Http code 200 on success
N/A
Rollback to given snapshot name.
@param pool_name: Name of pool.
@type pool_name: str
@param volume_name: Name of volume.
@type volume_name: str
@param snapshot_name: Name of snapshot.
@type snapshot_name: str
N/A
List item to be deleted before rollback is executed.
N/A
List all pools available for import.
End-point return array with data about all pools available for import.
Example JSON output::
{
"data": [
{
"name": "Pool-0",
"id": "11637266618494361322",
"status": 24,
"health" : "ONLINE",
"size": "249108103168",
"operation": {"operation": "none"},
"vdevs": [
{
"name": "mirror-0",
"type" : "mirror",
"health" : "ONLINE",
"iostats": {"read" : null, "write" : null, "chksum" : null},
"disks": [
{
"name": "sdb",
"id": "wwn-0x5000c5001c11581c",
"sn": "5VP1YAQQ",
"model": "ST31000528AS ",
"path": null,
"health": "ONLINE",
"size": 1000204886016,
"iostats": {"read": null, "write": null, "chksum": null},
"led": null
},
{
"name": "sdc",
"id": "ata-ST3250310AS_9RY03FX0",
"sn": "9RY03FX0",
"model": "ST3250310AS ",
"path": null,
"health": "ONLINE",
"size": 250059350016,
"iostats": {"read": null, "write": null, "chksum": null},
"led": null,
}
],
"vdev_replacings": [ ],
"vdev_spares": [ ]
}
]
}
],
"error" : null
}
@return: Http code 200 on success.
N/A
Import pool selected in JSON request data.
URL parameters:
- "as_task" - 0 or 1. If its set to 1, the REST endpoint responds
immediately, and the operation will be done in the background,
otherwise response will be sent after the operation is finished.
Defaults to 0.
Required JSON keys:
- "id" - String with ID of pool that will be imported. It identifies
particular exported pool even if there are more than one exported pool
with the same name.
- "name" - String with name of pool that will be imported. If it is set
to different value than current pool name then it will be used to
rename pool during import.
Optional JSON keys:
- "force" - Boolean value that indicates if pool should be imported
with force switch. In that case zfs try to import pool even if it seems
to be used on different machine etc.
- "omit_missing" - Boolean value that indicates if pool should be
imported without LOG group.
- "ignore_unfinished_resilver" - Boolean flag used to ignore validation
if pool resilver has finished. Import of pool with unfinished resilver
when disks with more recent data are unavailable or may become
unavailable may lead to data corruption.
- "as_task" - If true, the REST endpoint responds immediately, and
pool import will be done in the background, otherwise response
will be received after pool is imported.
Example JSON input::
{
"id": "123456789abc",
"name": "TestPool",
"force": true,
"omit_missing": true,
"ignore_unfinished_resilver" true,
}
Example JSON output when run as background task:
{
"data": {
"task": {
"id": "0f21fedd-9d1c-4b90-8c5a-14b056135157",
"links": {
"delete": {
"href": "/api/v3/tasks/0f21fedd-9d1c-4b90-8c5a-14b056135157"
},
"response": {
"href": "/api/v3/tasks/0f21fedd-9d1c-4b90-8c5a-14b056135157/response"
},
"request": {
"href": "/api/v3/tasks/0f21fedd-9d1c-4b90-8c5a-14b056135157/request"
},
"self": {
"href": "/api/v3/tasks/0f21fedd-9d1c-4b90-8c5a-14b056135157"
}
}
}
},
"error": null
}
When running in the foreground, there is no output.
@return: On successful pool import http code 201 is returned. If run
as a background task, http code 202 is returned
{
"properties": {
"id": {
"type": "string"
},
"name": {
"type": "string"
},
"force": {
"type": "boolean"
},
"omit_missing": {
"type": "boolean"
},
"recovery_import": {
"type": "boolean"
},
"ignore_unfinished_resilver": {
"type": "boolean"
}
},
"required": ["id"]
}
Destroy pool that is exported by clearing it's disks labels.
Exported pool will be destroyed by clearing labels on all disks that
contains label with information about pool id.
Example JSON output:
End-point doesn't return any data.
@param pool_id: Id of pool that will be destroyed.
@type pool_id: str
@return: On successful destroy of exported pool http code 204 is returned.
N/A
Get total size of all pools.
Example JSON output::
{
"data" : 249108103168,
"error" : null
}
@return: Http code 200 on success.
N/A
Return information if I/O is suspended and for which pool.
Example JSON output::
{
"data" : {
"is_suspended" : false,
"pool" : null
},
"error" : null
}
Fields description:
- "is_suspended" - Boolean flag that indicates if I/O is suspended.
- "pool" - If I/O is suspended this field has name of pool for which
I/O is suspended.
@return: Http code 200 on success.
N/A
Return information if kernel had bug or oops.
Example JSON output::
{
"data" : {
"is_kernel_bug" : false
},
"error" : null
}
Fields description:
- "is_kernel_bug" - Boolean flag that indicates
any system had kernel bug or oops.
@return: Http code 200 on success.
N/A
Return information if kernel had out of memory state.
Example JSON output::
{
"data" : {
"is_out_of_memory" : false,
"process_name" : null
},
"error" : null
}
Fields description:
- "is_out_of_memory" - Boolean flag that indicates
any system process caused out of memory state.
- "process_name" - If any system process caused out of memory
this field has name of process.
@return: Http code 200 on success.
N/A
Reboot system, if I/O is suspended or any system process freezes
do emergency reboot.
Emergency reboot will cause immediate hard system reboot.
{
"properties": {
"force": {
"type": "boolean"
}
}
}
Gets the list of pools that are not being resilvered.
Required for reboot endpoint.
N/A
Shutdown system, if I/O is suspended or any system process freezes
do emergency shutdown
Emergency shout down will cause only emergency reboot - it is not possible
to shutdown system in any way when I/O is suspended or any system process freezes.
{
"properties": {
"force": {
"type": "boolean"
}
}
}
Gets the list of pools that are not being resilvered.
Required for reboot endpoint.
N/A
Prevent automatic reboot of system.
If system is set to reboot system automatically when I/O suspended
it is possible to stop this reboot.
N/A
Prevent automatic reboot of system.
If system is set to reboot system automatically if system had
kernel oops or bug it is possible to stop this reboot.
N/A
Prevent automatic reboot of system.
If system is set to reboot system automatically when if system has
out of memory state it is possible to stop this reboot.
N/A
Prevent automatic reboot of system.
If system is set to reboot system automatically if any system
process is unresponsive it is possible to stop this reboot.
N/A
Return information if any system process is unresponsive (has D state).
Example JSON output::
{
"data" : {
"is_process_freeze" : false,
"process_name" : null
},
"error" : null
}
Fields description:
- "is_process_freeze" - Boolean flag that indicates
any system process is unresponsive.
- "process_name" - If any system process is unresponsive
this field has name of process with D state.
@return: Http code 200 on success.
N/A
Return UPS status.
Example JSON output:
- For case when APC UPS is present::
{
"data": {
"manufacturer": "APC",
"type": "",
"mode": "",
"status": "",
"charge": ""
},
error: null
}
- If UPS is not set then output is empty::
{
"data": {},
"error": null
}
@return: Http code 200 on success.
N/A
Return basic information about currently running product.
Example JSON output::
{
"data": {
"activation_expiration_date": "2015-05-21",
"storage_capacity" : 81363860455424,
"name": "Open-E JovianDSS",
"server_name": "dss",
"pool_mountpoint": "/Pools",
"support": "N/A",
"up": "05",
"server_description": "Open-E JovianDSS",
"version_name": "1.0up05.1501.FRESNO",
"storage_capacity_exceeded": false,
"host_name": "dssJ0000099",
"version": "1.0",
"up": "27",
"release_date": "2018-03-28",
"serial_number : "J0000099",
"build": "FRESNO",
"oem_brand": "Newtech",
"oem_type": "full",
"help_link": "http://base.url.to.oem.product.helps",
"support_info": "For technical support please inquire",
"support_email": "support@arxys.com",
"cert_email": "support@arxys.com",
"vandor_name": "Arxys Inc.",
"redundant_boot_medium": true,
"default_odp_src_plan": "1hour=>5minutes,3days=>15minutes,2weeks=>1hour",
"default_odp_dst_plan": "12hours=>5minutes,1week=>15minutes,3weeks=>1hour,3months=>12hours",
"zfs_version_type": "experimental"
},
"error" : null
}
@return: Http code 200 on success.
N/A
Modify product settings.
Optional JSON keys:
- "host_name" - Set host name of server.
- "server_description" - Set server description.
- "server_name" - Set server name.
Example JSON input::
{
"host_name": "testname",
"server_name": "test",
"server_description": "Test Server"
}
@return: Http code 201 on success.
{
"properties": {
"server_name": {
"type": "string"
},
"server_description": {
"type": "string"
},
"host_name": {
"type": "string"
}
},
"additionalProperties": false
}
Gets activation messages from activation.xml file.
End-point will return error if it will be executed before product
activation.
Example JSON output::
{
"data" : "Activation successful!",
"error" : null
}
Product before activation:
@return: Http code 200 on success.
N/A
Perform product activation.
There are two activation methods on-line and off-line. On-line activation
requires server to have internet connection. Off-line activation doesn't
require internet connection it is performed by upload of activation file.
In order to activate product on-line just send empty request without any
additional data. For off-line activation valid activation file must be send.
File should be send in form data, content-type header have to be set to
"multipart/form-data" and file must be stored in field called
"activation_file".
N/A
Download file with pre-activation data.
File will be send directly to client that send request. Web-browser will
just pop up window with file download. Pre-activation file is used to
generate activation file that allows to perform off-line activation.
N/A
Returns product life time state and time informations.
Example JSON output::
{
"data" : {
"pk_type" : 1,
"life_time_days" : 29,
"life_time_state" : 3
},
"error" : null
}
Fields description:
- "pk_type" - Type of product key:
- 0 - trial key,
- 1 - full product key.
- "life_time_days" - Number of days until activation time expires.
- "life_time_state" - State of product activation:
- 0 - product key has not been provided yet, or some unexpected
error occured
- 1 - not activated trial,
- 2 - activated trial,
- 3 - full product key not acativated,
- 4 - full product key that that activation must be periodically
refreshed in time periods described by subscription agreement,
- 5 - activated full product key.
@return: Http code 200 on success.
N/A
List all FC targets (ports) available in the system.
FC ports are local to particular system. Those ports are physical FC ports
on adapters directly attached to machine or virtual WWNs that are created
on those ports.
Example JSON output::
{
"data": [
{
"status": "OK",
"is_target_mode_enabled": true,
"is_hw_target": true,
"alias": "fc-tgt-01",
"parent_host": null,
"wwn": "21:01:00:1b:32:25:fc:86"
},
{
"status": "OK",
"is_target_mode_enabled": true,
"is_hw_target": false,
"alias": "tgt0",
"parent_host": "21:01:00:1b:32:25:fc:86",
"wwn": "21:00:00:1b:32:05:fc:86"
},
{
"status": "Missing",
"is_target_mode_enabled": true,
"is_hw_target": false,
"alias": "tgt-002",
"parent_host": null,
"wwn": "21:02:00:1b:32:25:fc:86"
}
],
"error": null
}
Target fields description:
- "wwn": Unique identifier of port, it is also used as identifier in
REST API and have to be used every time when particular port is
referred.
- "alias": User friendly name for port.
- "status": Status that indicates if port is available in the system
or not:
- "OK" - port is available.
- "Missing" - port is not available in the system, physical adapter
is removed or parent host is missing.
- "is_target_mode_enabled": Boolean flag that indicates if target mode
is enabled on given port. When flag is set to false it means that port
is working in initiator mode. Flag set to true indicates that port is
working in target mode.
- "is_hw_target": Flag that indicates if target is a physical port or
virtual WWN.
- "parent_host": WWN of physical port on which virtual one is created.
For physical ports this value is set to null as those ports doesn't
have parent host.
@return: Http code 200 on success and list with all FC ports.
N/A
Create virtual port on existing physical FC port.
Operation is possible only if physical FC port is connected to FC switch
due to way how FC network operates. If port that is not connected is used,
operation ends with server error.
New port inherits target mode from it's parent host. When parent host is
in target mode then virtual port will be also configured with target mode
enabled. When parent host is in initiator mode, virtual port is also
configured using initiator mode. This behavior is present because target
mode must be set to the same value for parent host and all virtual ports
that are created on it.
Required JSON keys:
- "parent_host" - WWN of physical FC port on which virtual one will be
created.
- "wwn": WWN identifier of newly created virtual port. It have to be
unique.
Optional JSON keys:
- "alias" - User friendly name for created virtual port.
Example JSON input::
{
"parent_host": "21:01:00:1b:32:25:fc:86",
"wwn": "21:01:00:1b:32:25:fc:01",
"alias": "New-FC-Port"
}
@return: Http code 200 on success and JSON representation of created port.
{
"properties": {
"parent_host": {
"type": "string"
},
"wwn": {
"type": "string"
},
"alias": {
"type": "string"
}
},
"required": ["parent_host", "wwn"],
"additionalProperties": false
}
Fetch target (port) with given WWN from the system.
Example JSON output:
Output is in the same format as for L{get_fc_targets} except that only
single item is returned instead of a list with all ports.
@param wwn: WWN of port to fetch.
@type wwn: str
@return: Http code 200 on success and JSON representation of selected port.
N/A
Edit given target (port) configuration.
Optional JSON keys:
- "alias" - Modification of port user friendly name.
- "is_target_mode_enabled" - Boolean flag that controls port mode.
Setting flag to true enables target mode on port, setting flag to false
disables target mode and leaves port in initiator mode. This setting
is available only for physical ports, it isn't possible to change
target mode on virtual ports. When target mode is changed on physical
port all virtual targets created on that port will be modified to use
the same setting.
Example JSON input::
{
"alias": "New-Alias",
"is_target_mode_enabled": true
}
@param wwn: WWN (unique identifier) of port that will be modified.
@type wwn: str
@return: Http code 200 on success and JSON representation of modified port.
{
"properties": {
"alias": {
"oneOf": [{
"type": "string"
}, {
"type": "null"
}]
},
"is_target_mode_enabled": {
"type": "boolean"
}
},
"additionalProperties": false
}
Delete given port from system configuration.
It is possible to delete only virtual ports or configurations of missing
ports.
@param wwn: WWN (unique identifier) of port that will be deleted.
@type wwn: str
@return: Http code 204 on success.
N/A
Issue LIP on given target.
Sending LIP causes that configuration of target is refreshed by initiators.
However it may break connection to initiators that are currently connected
to target.
@param wwn: WWN of port for which LIP will be send.
@type wwn: str
@return: Http code 204 on success.
N/A
Disable discovery CHAP user access authentication functionality.
Example JSON output:
End-point doesn't return any data.
@return: On successful disable HTTP code 201 is returned.
N/A
Add/create new discovery CHAP user which will connect to iSCSI portal.
Configuration of new discovery CHAP user is provided in JSON formatted data.
Required JSON keys:
- "name" - String with name of discovery CHAP user.
Regular expression for validation names is '^\w([a-zA-Z0-9-_]*\w)?$'.
- "password" - String with password for CHAP user.
Password must consist of at least 12 characters and cannot contain
whitespace characters.
Regular expression for validation password is '^[a-zA-Z0-9-_!@%()+?.:;]+$'.
Example JSON input::
{
"name": "disc_user",
"password": "3e21ewqdsacxz"
}
Example JSON output:
End-point doesn't return any data.
@return: On successful discovery CHAP user creation HTTP code 201 is returned.
{
"properties": {
"name": {
"type": "string"
},
"password": {
"type": "string"
}
},
"required": ["name", "password"],
"additionalProperties": false
}
Return list with all discovery CHAP users that can connect to iSCSI portal.
End-point return array with information about all discovery CHAP users
that can connect to iSCSI portal.
Example JSON output::
{
"data": {
"user1disc": "123qweasdzxc",
"user2disc": "321ewqdsacxz"
},
"error": null
}
@return: On successful HTTP code 200 is returned.
N/A
Remove existing discovery CHAP user.
Example JSON output:
End-point doesn't return any data.
@param user_name: Name of CHAP user.
@type user_name: str
@return: On successful remove user HTTP code 204 is returned.
N/A
Enable discovery CHAP user access authentication functionality.
Example JSON output:
End-point doesn't return any data.
@return: On successful enable HTTP code 201 is returned.
N/A
Return list with all iSCSI LUNs that match search criteria.
Search criteria are provided as url arguments using following syntax:
?where=
For example:
?where=eui==3139336438363737
Those arguments will be used to search iSCSI LUNs with eui
3139336438363737.
If search criteria are not specified all iSCSI LUNs will be returned. It
is important to note that list with results is always returned even for
queries that suppose to return only one item, like queries for LUN with
specific eui of SCSI ID. It is like that because it is possible to have
multiple LUNs with the same SCSI ID in configuration where only one LUN is
assigned to active target. Other LUNs may have SCSI ID conflict after
import of the pool from the foreign system and are assigned to inactive
iSCSI targets. Each item in output list contains information if target
where LUN is assigned is active.
Example JSON output::
{
"data": [
{
"iscsi_target": {
"active": true,
"name": "iqn.2020-04.iscsi:node-f1b41ee9.target0"
},
"pool": "Pool-0",
"lun": {
"scsi_id": "193d86773f7222b3",
"eui": "3139336438363737",
"name": "vol0",
"lun": 0
}
}
],
"error": null
}
@return: Http code 200 on success and list with iSCSI LUNs that match
search criteria.
N/A
Return list with all iSCSI LUNs that match search criteria.
Search criteria are provided as url arguments using following syntax:
?where=
For example:
?where=eui==3139336438363737
Those arguments will be used to search iSCSI LUNs with eui
3139336438363737.
If search criteria are not specified all iSCSI LUNs will be returned. It
is important to note that list with results is always returned even for
queries that suppose to return only one item, like queries for LUN with
specific eui of SCSI ID. It is like that because it is possible to have
multiple LUNs with the same SCSI ID in configuration where only one LUN is
assigned to active target. Other LUNs may have SCSI ID conflict after
import of the pool from the foreign system and are assigned to inactive
iSCSI targets. Each item in output list contains information if target
where LUN is assigned is active.
Example JSON output::
{
"data": [
{
"iscsi_target": {
"active": true,
"name": "iqn.2020-04.iscsi:node-f1b41ee9.target0"
},
"pool": "Pool-0",
"lun": {
"scsi_id": "193d86773f7222b3",
"eui": "3139336438363737",
"name": "vol0",
"lun": 0
}
}
],
"error": null
}
@return: Http code 200 on success and list with iSCSI LUNs that match
search criteria.
N/A
Return if discovery CHAP user access authentication is enabled or disabled.
End-point return boolean state with information if discovery CHAP user
access authentication is enabled or disabled.
Example JSON output::
{
"data": true,
"error": null
}
@return: On successful HTTP code 200 is returned.
N/A
Returns iSCSI targets cache
Example JSON output::
{
"data": {
"Pool-0": [
{
"active": true,
"luns": [
{
"blocksize": "512",
"lun": "0",
"lun_path": "/dev/Pool-0/zv",
"mode": "wt",
"scsiid": "bZPyX5ofQewAac3n"
}
],
"name": "iqn.2016-01:dss.target0",
"rel_tgt_id": "1529"
}
]
},
"error": null
}
@return: Http code 200 on success.
N/A
Configure password used by all SEDs.
New password replaces any previously set password. It will be used for
unlocking SED disks and it will be used when locking is enabled for given
disk. It will not change currently used password for any disk that for
which locking is already enabled.
Example JSON input:
- Set password for the first time::
{
"new_password": "123456789qwertyu"
}
- Change password that was already configured::
{
"new_password": "123456789qwertyu"
"old_password": "000056789qwertyu"
}
@return: Http code 201 on success
{
"properties": {
"new_password": {
"type": "string"
},
"old_password": {
"type": "string"
}
},
"required": ["new_password"]
}
Get configuration of the selected service, e.g.:
GET:/api/v2/services/service_name
Example JSON output (success)::
{
"data": {
"enabled": true
},
"error": null
}
@return: Http code 200 on success.
N/A
Sets configuration of the selected service, e.g.:
PUT:/api/v1/services/service_name
Example JSON input::
{
"data": {
"enabled": true
},
"error": null
}
@return Http code 204 on success.
N/A
Sets configuration of the admember (Active Directory Member) service e.g.:
PUT:/api/v2/services/admember
Example JSON input:
{
"enabled": true,
"user" : "Administrator",
"password" : "SecretPassword",
"realm" : "DOMAIN.LOCAL",
"computer_ou": "computer/subcomputer"
}
@return Http code 204 on success.
{
"oneOf": [{
"properties": {
"enabled": {
"type": "boolean"
}
},
"required": ["enabled"],
"additionalProperties": false
}, {
"properties": {
"enabled": {
"type": "boolean"
},
"realm": {
"type": "string"
},
"user": {
"type": "string"
},
"password": {
"type": "string"
},
"computer_ou": {
"type": "string"
},
"scan_trusted_domains": {
"type": "boolean"
}
},
"required": ["enabled", "realm", "user", "password"],
"additionalProperties": false
}]
}
Get configuration of the admember (Active Directory Member) service e.g.:
GET:/api/v2/services/admember
Example JSON output:
{
"enabled": true,
"user" : "Administrator",
"realm" : "DOMAIN.LOCAL",
"computer_ou": "computer/subcomputer",
"connected": true,
"database": {
"status": "ok"
"last_updated": 1470119640
}
}
@return Http code 200 on success.
N/A
Update users/groups database.
POST:/api/v2/services/admember/update
Example JSON output::
{
"data": null,
"error": null
}
@return: Http code 200 on success.
{
"properties": {
"clear_share_assignments": {
"type": "boolean"
}
}
}
Sets configuration of the cli service e.g.:
PUT:/api/v3/services/cli
Example JSON input:
{
"enabled": true,
"password": "password",
"allow_ip": ["192.168.0.1"],
"port": 22223
}
@return Http code 204 on success.
{
"properties": {
"enabled": {
"type": "boolean"
},
"password": {
"type": "string"
},
"allow_ip": {
"type": "array"
},
"port": {
"type": "integer"
}
},
"additionalProperties": false
}
Get configuration of the cli service e.g.:
GET:/api/v3/services/cli
Example JSON output:
{
"enabled": true,
"password": "password",
"allow_ip": ["192.168.0.1"],
"port": 22223,
"ssh_key": ""
}
@return Http code 200 on success.
N/A
Generate SSH Key.
POST:/api/v3/services/cli/sshkey
N/A
Sets settings of the LDAP service e.g.:
PUT:/api/v3/services/ldap
Example JSON input:
{
"enabled": true,
"domain_type": "internal",
"domain": "LocalDomain",
"password": "123456"
},
{
"enabled": true,
"domain_type": "external",
"profile": "JovianDSS",
"server": "192.168.10.1",
"encryption_type": "TLS",
"port": 389,
"base_dn": "dc=internal,dc=lan",
"users_dn": "ou=users,dc=internal,dc=lan",
"groups_dn": "ou=groups,dc=internal,dc=lan",
"anonymous_access": false,
"admin_dn": "cn=admin,dc=internal,dc=lan",
"admin_password": "123456"
}
@return Http code 204 on success.
N/A
Get settings of the LDAP service e.g.:
GET:/api/v3/services/ldap
Example JSON input:
{
"status": true,
"enabled": true,
"domain": "LocalDomain",
"default_gid": 513,
}
@return Http code 200 on success.
N/A
Get LDAP cache info e.g.:
GET:/api/v3/services/ldap/cache
Example JSON input:
{
"users": 0,
"groups": 1
}
@return Http code 200 on success.
N/A
Get configuration of the LDAP database e.g.:
GET:/api/v3/services/ldap/database
Example JSON input:
{
"csn": "XYZ",
"initialized": true
}
@return Http code 200 on success.
N/A
Dump LDAP database and configuration file
N/A
Set internal LDAP factory default configuration.
@return Http code 200 on success.
N/A
None
N/A
Get replication info of the LDAP database e.g.:
GET:/api/v3/services/ldap/replication
Example JSON input:
{
"method": null
}
@return Http code 200 on success.
N/A
None
N/A
None
N/A
None
N/A
None
N/A
None
{
"properties": {
"enabled": {
"type": "boolean"
}
},
"required": ["enabled"],
"additionalProperties": false
}
None
{
"properties": {
"disabled": {
"type": "boolean"
}
},
"required": ["disabled"],
"additionalProperties": false
}
None
{
"properties": {
"suspended": {
"type": "boolean"
}
},
"required": ["suspended"],
"additionalProperties": false
}
Try connecting to external LDAP database.
If connecting is not possible, an error will
be returned with the reason for why this happens. E. g.:
GET:/api/v3/services/ldap/test_connection
@return Http code 200 on success.
N/A
Sets configuration of the NFS service e.g.:
PUT:/api/v3/services/nfs
Example JSON input:
{
"enabled": true,
}
@return Http code 204 on success.
{
"properties": {
"enabled": {
"type": "boolean"
},
"thread_count": {
"type": "integer"
},
"versions": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
Get configuration of the NFS service e.g.:
GET:/api/v2/services/nfs
Example JSON input:
{
"enabled": true,
}
@return Http code 200 on success.
N/A
Add redfish service
Example JSON input:
{
"alias": "alias1",
"address": "192.168.10.1",
"port": "443",
"user": "user1",
"password": "password1"
}
@return: Http code 201 on success.
{
"properties": {
"alias": {
"type": "string"
},
"address": {
"type": "string"
},
"port": {
"type": "integer"
},
"user": {
"type": "string"
},
"password": {
"type": "string"
}
},
"required": ["alias", "address", "port", "user", "password"],
"additionalProperties": false
}
Get list of redfish services
Example JSON output:
{
"data": [
{
"address": "192.168.10.1",
"alias": "alias2",
"manufacturer": "VORTEX SHELF",
"password": "password2",
"port": 443,
"ssdp": false,
"user": "user2"
},
{
"address": "192.168.10.2",
"alias": "alias1",
"manufacturer": "VORTEX SHELF",
"password": "password1",
"port": 443,
"ssdp": false,
"user": "user1"
}
],
"error": null
}
N/A
Set redfish service
Example JSON input:
{
"alias": "alias1",
"address": "192.168.10.1",
"port": "443",
"user": "user1",
"password": "password1"
}
@return: Http code 201 on success.
{
"properties": {
"alias": {
"type": "string"
},
"address": {
"type": "string"
},
"port": {
"type": "integer"
},
"user": {
"type": "string"
},
"password": {
"type": "string"
}
},
"additionalProperties": false
}
Get redfish service for given alias
Example JSON output:
{
"data":
{
"address": "192.168.10.1",
"alias": "alias1",
"manufacturer": "VORTEX SHELF",
"password": "password1",
"port": 443,
"ssdp": false,
"user": "user1"
},
"error": null
}
N/A
Deletes redfish service from given alias.
@return: Http code 204 on success.
N/A
None
{
"properties": {
"enabled": {
"type": "boolean"
},
"ip_address": {
"type": "string",
"format": "ipv4"
},
"port": {
"type": "number"
},
"protocol": {
"type": "string",
"enum": ["tcp", "udp"]
}
}
}
None
N/A
Sets settings of the Remote Consola Access service:
PUT:/api/v2/services/remote_console
Example JSON input:
{
"enabled": true,
"port": 82,
"passwd": admin
"allowed_access_ip": ["192.168.0.1", "192.168.1.1"]
}
@return Http code 204 on success.
N/A
Get settings of the Remote Console Access service:
GET:/api/v2/services/remote_console
Example JSON input:
{
"enabled": true,
"port": 82,
"allowed_access_ip": ["192.168.0.1", "192.168.1.1"]
}
@return Http code 200 on success.
N/A
Sets settings of the REST service e.g.:
PUT:/api/v2/services/rest
Example JSON input:
{
"enabled": true,
"port": 82,
"user": admin,
"passwd": admin
}
@return Http code 204 on success.
N/A
Get settings of the REST service e.g.:
GET:/api/v2/services/rest
Example JSON input:
{
"enabled": true,
"port": 82,
"user": admin
}
@return Http code 200 on success.
N/A
Sets configuration of the RSYNC service e.g.:
PUT:/api/v3/services/rsync
Example JSON input:
{
"enabled": true,
"user": "admin",
"password": "password"
}
@return Http code 204 on success.
N/A
Get configuration of the RSYNC service e.g.:
GET:/api/v2/services/rsync
Example JSON input:
{
"enabled": true,
"user": "admin"
}
@return Http code 200 on success.
N/A
Sets configuration of the SMB service e.g.:
PUT:/api/v2/services/smb
Example JSON input:
{
"enabled": true,
}
@return Http code 204 on success.
{
"properties": {
"enabled": {
"type": "boolean"
},
"wins_server": {
"type": "string"
},
"workgroup": {
"oneOf": [{
"type": "string"
}, {
"type": "null"
}]
},
"hide_special_folders": {
"type": "boolean"
},
"unix_extensions": {
"type": "boolean"
},
"dos_attributes": {
"type": "boolean"
},
"admin_users": {
"type": "array"
},
"sid": {
"type": "string"
},
"oplocks": {
"type": "boolean"
},
"kernel_oplocks": {
"type": "boolean"
},
"level2_oplocks": {
"type": "boolean"
},
"smb2_leases": {
"type": "boolean"
},
"fruit": {
"type": "boolean"
}
},
"additionalProperties": false
}
Get configuration of the SMB service e.g.:
GET:/api/v2/services/smb
Example JSON output::
{
"smb2_leases": true,
"admin_users": [],
"workgroup": "WORKGROUP",
"enabled": true,
"wins_server": "",
"unix_extensions": false,
"fruit": true,
"oplocks": true,
"sid": "S-1-5-21-2893658096-2769335802-4101685516",
"level2_oplocks": true,
"hide_special_folders": true,
"kernel_oplocks": false
}
@return Http code 200 on success.
N/A
Restart smb service.
@return: Http code 204 on success.
N/A
Example JSON output::
{
"data": {
"results": 3,
"entries": [
{
"id": 0,
"name": "test1"
},
{
"id": 1,
"name": "test2"
},
{
"id": 2,
"name": "test3"
}
]
},
"error": null
}
@return: Http code 200 on success.
N/A
Example JSON input::
{
"data":[
{
"id" : 1,
"name" : "Administrator",
"allow_access": true,
},
{
"id" : 2,
"name" : "user1",
"allow_access": false,
}]
"error":null
}
@return: Http code 204 on success.
{
"type": "array"
}
Get tracker service configuration.
Example JSON output::
{
"enabled": true,
"status": true
}
Fields description:
- "enabled" - Boolean flag that indicates if service is enabled.
- "status" - Boolean flag that indicates if service is currently
running or not.
@return: Http code 200 on sucess.
N/A
Set tracker service configuration.
Optional JSON keys:
- "enabled" - Boolean flag used to enable or disable the service.
Example JSON input::
{
"enabled": true
}
@return: Http code 204 on success.
{
"properties": {
"enabled": {
"type": "boolean"
}
},
"additionalProperties": false
}
Get name of the pool used by tracker
Example JSON output::
{
"data": "Pool-0",
"error": null
}
Fields description:
- "data" - String containing name of the pool used by tracker --
if it's enabled, or null if it's disabled.
@return: Http code 200 on success.
N/A
Sets settings of the Zeroconf service e.g.:
PUT:/api/v3/services/zeroconf
Example JSON input:
{
"enabled": true,
"timemachine": false
}
@return Http code 204 on success.
{
"properties": {
"enabled": {
"type": "boolean"
},
"timemachine": {
"type": "boolean"
},
"smb": {
"type": "boolean"
}
},
"additionalProperties": false
}
Get settings of the Zeroconf service e.g.:
GET:/api/v3/services/zeroconf
Example JSON output:
{
"enabled": true,
"timemachine": false
}
@return Http code 200 on success.
N/A
Return list of saved settings.
Example JSON output::
{
"data":
[
{
"date": "2015-06-12 15:25:05",
"path": "/mnt/system/settings/settings_2015-06-12_15-25-05.cnf",
"saved_settings":
[
"system"
],
"file": "settings_2015-06-12_15-25-05.cnf",
"mtime": "1434115505"
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Deletes given settings file.
@param filename: File name where are settings to be deleted (e.g. ``settings_2015-06-12_15-25-05.cnf``).
@type filename: str
@return: Http code 200 on success.
N/A
Downloads given settings file.
@param filename: File name where are settings to be downloaded (e.g. ``settings_2015-06-12_15-25-05.cnf``).
@type filename: str
Response data is a binary content of a settings file.
@return: Http code 200 on success.
N/A
Restores settings from file.
@param filename: File name where are settings to be restored (e.g. ``settings_2015-06-12_15-25-05.cnf``).
@type filename: str
Required JSON keys:
- "system" - bool indicating if system settings should be saved.
- "storage" - bool indicating if storage settings should be saved.
Example JSON input::
{
"system": true,
"storage": false
}
@return: Http code 200 on success.
{
"properties": {
"system": {
"type": "boolean"
},
"storage": {
"type": "boolean"
}
}
}
Saves previously uploaded file (by PHP) in settings directory.
@param filename: File name of the settings that were uploaded (e.g. ``settings_2015-06-12_15-25-05.cnf``).
@type filename: str
N/A
Saves current settings to a file (which name is generated automatically from date).
Required JSON keys:
- "system" - bool indicating if system settings should be saved.
- "storage" - bool indicating if storage settings should be saved.
Example JSON input::
{
"system": true,
"storage": false
}
Example JSON output::
{
"data": "settings_2015-06-12_15-25-05.cnf",
"error": null
}
@return: Http code 200 on success.
{
"properties": {
"system": {
"type": "boolean"
},
"storage": {
"type": "boolean"
}
}
}
Return size of saved settings.
Example JSON output::
{
"data":
[
{
"current_size": 1235421,
"max_size": 2 * 1024 ** 3,
"size_exceeded": false
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Uploads a settings file.
To upload settings file it have to be added as form data under key "file".
@return: Http code 204 on success.
N/A
Lists all shares.
Example endpoint:
GET: /api/v3/shares?page=0&per_page=10&where=path==Pool-0/Dataset-0
GET: /api/v3/shares?page=0&per_page=10&where=path@like=Pool-0/Dataset-0/%
Example of JSON output::
{
"data":
[
{
"comment": "",
"name": "MyShare",
"real_path": "/Pools/Pool-0/MyDataSet/MyShareDir",
"nfs":
{
"no_root_squash": false,
"allow_write_ip":
[
],
"all_squash": false,
"enabled": false,
"insecure_connections": false,
"synchronous_data_record": false,
"insecure_lock_requests": false,
"allow_access_ip":
[
]
},
"smb": {
"enabled": false,
"read_only": false,
"visible": true,
"handling_large_dirs": false,
"default_case": "lower",
"inherit_owner": false,
"inherit_perms": true,
"access_mode": "guest",
"timemachine": false
},
"active": true,
"path": "Pool-0/MyDataSet/MyShareDir",
"conflicted": false
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Creates share with given parameters.
Required JSON keys:
- "name" - string with name of the new share.
- "path" - string with path where share will be placed.
Optional JSON keys:
- "comment" - string with a comment.
- "active" - boolean indicating if share should be active.
- "nfs" - object describing NFS functionality, the key might be:
- "enabled" - boolean indicating if NFS functionality should be enabled (default false).
- "allow_access_ip" - array with IP addresses which are allowed to read (default empty).
- "allow_write_ip" - array with IP addresses which are allowed to write (default empty).
- "insecure_connections" - boolean indicating if not secured connections are allowed (default false).
- "synchronous_data_record" - boolean indicating if reply to requests should be sent only after requested
changes have been committed to stable storage (comparing to asynchronous mode
it has less performance, but it's more safety) (default false).
- "insecure_lock_requests" - boolean indicating if credentials of user that performs locking request should
not be remembered, and not confirmed on access to a file (default false).
- "all_squash" - boolean indicating if all UIDs and GIDs should be mapped to anonymous user
(useful for FTP) (default false).
- "no_root_squash" - boolean indicate if root squashing should be disabled (useful for diskless
clients) (default false).
- "smb" - object describing SMB functionality, the key might be:
- "enabled" - (type: boolean) Indicating if SMB functionality should be enabled (default false).
- "read_only" - (type: boolean) (default false).
- "visible" - (type: boolean) (default false).
- "handling_large_dirs" - (type: boolean) This option allows you to significantly speed up file listing (default false).
The prerequisite is to convert all file and directory names to lower or upper case exclusively.
Please select your preferred choice below.
Note
You will need to convert your existing file and directory names to lower or upper case
before selecting this option, as otherwise they will become inaccessible.
Note
Please note that due to case sensitivity issues, the operations above may have
a negative impact on Unix-like systems.
Please prepare accordingly beforehand. Windows is not affected
- "default_case" - (type: string) (default "lower") This option works with enabled "handling_large_dirs"
and it will convert all names passed by client to that case.
- "inherit_owner" - (type: boolean) The ownership of new files and directories is normally governed
by effective uid of the connected user.
If this option value is true, the ownership for new files and directories is taken
from the ownership of the parent directory.
Common scenarios where this behavior is useful is in implementing drop-boxes where users
can create and edit files but not delete them (default false).
- "inherit_perms" - (type: boolean) If this option value is true, new directories inherit the mode of the parent directory
and new files inherit their read/write permissions from the parent directory.
This option can be particularly useful on large systems with many users
to allow a single [homes] share to be used flexibly by each user (default false).
- "access_mode" - (type: string) (default false).
- "spotlight" - (type: boolean) flag that enables spotlight support for this smb share
- "timemachine" - (type: boolean) flag that enables Time Machine support for this smb share
Example JSON input::
{
"name": "NewShare",
"path": "Pool-0/MyDataSet/NewShare",
"comment": "It's just example.",
"nfs": {
"all_squash": true
}
}
@return: Http code 201 on success.
{
"properties": {
"name": {
"type": "string"
},
"path": {
"type": "string",
"pattern": ".+/.+"
},
"comment": {
"type": "string"
},
"active": {
"type": "boolean"
},
"nfs": {
"properties": {
"enabled": {
"type": "boolean"
},
"allow_access_ip": {
"type": "array"
},
"allow_write_ip": {
"type": "array"
},
"insecure_connections": {
"type": "boolean"
},
"synchronous_data_record": {
"type": "boolean"
},
"insecure_lock_requests": {
"type": "boolean"
},
"all_squash": {
"type": "boolean"
},
"no_root_squash": {
"type": "boolean"
}
},
"additionalProperties": false
},
"smb": {
"properties": {
"enabled": {
"type": "boolean"
},
"read_only": {
"type": "boolean"
},
"visible": {
"type": "boolean"
},
"handling_large_dirs": {
"type": "boolean"
},
"default_case": {
"enum": ["lower", "upper"]
},
"inherit_owner": {
"type": "boolean"
},
"inherit_perms": {
"type": "boolean"
},
"access_mode": {
"enum": ["guest", "user"]
},
"spotlight": {
"type": "boolean"
},
"timemachine": {
"type": "boolean"
},
"ip_restrictions": {
"properties": {
"restriction_type": {
"type": "string"
},
"ip_list": {
"type": "array"
},
"except_list": {
"type": "array"
}
}
}
},
"additionalProperties": false
}
},
"required": ["name", "path"],
"additionalProperties": false
}
Returns data about concrete, given share.
@param share_name: Name of share.
@type share_name: str
Example JSON output 1 (success)::
{
"data":
{
"comment": "",
"name": "MyShare",
"real_path": "/Pools/Pool-0/MyDataSet/MyShareDir",
"nfs":
{
"no_root_squash": false,
"allow_write_ip":
[
],
"all_squash": false,
"enabled": false,
"insecure_connections": false,
"synchronous_data_record": false,
"insecure_lock_requests": false,
"allow_access_ip":
[
]
},
"smb": {
"enabled": false,
"read_only": false,
"visible": true,
"handling_large_dirs": false,
"default_case": "lower",
"inherit_owner": false,
"inherit_perms": true,
"access_mode": "guest",
"timemachine": false
},
"active": true,
"path": "Pool-0/MyDataSet/MyShareDir",
"conflicted": false
},
"error": null
}
Example of JSON output 2 (fail)::
{
"data": null,
"error":
{
"class": "werkzeug.exceptions.NotFound",
"message": "Share whatever not exists."
}
}
@return: Http code 200 on success.
N/A
Modifies parameters of given share.
@param share_name: Name of share.
@type share_name: str
Optional JSON keys:
- "path" - string with path where share is placed (this is the first identifier of share, if not provided
parameter ``share_name`` will be used).
- "comment" - string with a comment.
- "active" - boolean indicating if share should be active.
- "nfs" - object describing NFS functionality, the key might be:
- "enabled" - boolean indicating if NFS functionality should be enabled (default false).
- "allow_access_ip" - array with IP addresses which are allowed to read (default empty).
- "allow_write_ip" - array with IP addresses which are allowed to write (default empty).
- "insecure_connections" - boolean indicating if not secured connections are allowed (default false).
- "synchronous_data_record" - boolean indicating if reply to requests should be sent only after requested
changes have been committed to stable storage (comparing to asynchronous mode
it has less performance, but it's more safety) (default false).
- "insecure_lock_requests" - boolean indicating if credentials of user that performs locking request should
not be remembered, and not confirmed on access to a file (default false).
- "all_squash" - boolean indicating if all UIDs and GIDs should be mapped to anonymous user
(useful for FTP) (default false).
- "no_root_squash" - boolean indicate if root squashing should be disabled (useful for diskless
clients) (default false).
Example JSON input::
{
"nfs": {
"all_squash": false
}
}
@return: Http code 200 on success.
{
"properties": {
"name": {
"type": "string"
},
"path": {
"type": "string",
"pattern": ".+/.+"
},
"comment": {
"type": "string"
},
"active": {
"type": "boolean"
},
"nfs": {
"properties": {
"enabled": {
"type": "boolean"
},
"allow_access_ip": {
"type": "array"
},
"allow_write_ip": {
"type": "array"
},
"insecure_connections": {
"type": "boolean"
},
"synchronous_data_record": {
"type": "boolean"
},
"insecure_lock_requests": {
"type": "boolean"
},
"all_squash": {
"type": "boolean"
},
"no_root_squash": {
"type": "boolean"
}
},
"additionalProperties": false
},
"smb": {
"properties": {
"enabled": {
"type": "boolean"
},
"read_only": {
"type": "boolean"
},
"visible": {
"type": "boolean"
},
"handling_large_dirs": {
"type": "boolean"
},
"default_case": {
"enum": ["lower", "upper"]
},
"inherit_owner": {
"type": "boolean"
},
"inherit_perms": {
"type": "boolean"
},
"access_mode": {
"enum": ["guest", "user"]
},
"spotlight": {
"type": "boolean"
},
"timemachine": {
"type": "boolean"
},
"ip_restrictions": {
"properties": {
"restriction_type": {
"type": "string"
},
"ip_list": {
"type": "array"
},
"except_list": {
"type": "array"
}
}
}
},
"additionalProperties": false
}
},
"additionalProperties": false
}
Deletes share with given name.
@param share_name: Name of share.
@type share_name: str
@return: Http code 204 on success.
N/A
Lists all groups for given share.
@param share_name: Name of share.
@type share_name: str
Example of JSON output::
{
"data": {
"entries": [
{
"id": 1,
"name": "DEV+devgroup2"
},
{
"id": 0,
"name": "DEV+devgroup1"
}
],
"results": 2
},
"error": null
}
@return: Http code 200 on success.
N/A
Adds groups to given share.
@param share_name: Name of share.
@type share_name: str
@return: Http code 201 on success.
{
"type": "array"
}
Removes groups from given share.
@param share_name: Name of share.
@type share_name: str
@return: Http code 204 on success.
{
"type": "array"
}
Lists all users for given share.
@param share_name: Name of share.
@type share_name: str
Example of JSON output::
{
"data": {
"entries": [
{
"id": 1,
"name": "DEV+devuser2"
},
{
"id": 0,
"name": "DEV+devuser1"
}
],
"results": 2
},
"error": null
}
@return: Http code 200 on success.
N/A
Adds users to given share.
@param share_name: Name of share.
@type share_name: str
@return: Http code 201 on success.
{
"type": "array"
}
Removes users from given share.
@param share_name: Name of share.
@type share_name: str
@return: Http code 204 on success.
{
"type": "array"
}
None
N/A
None
{
"properties": {
"source_resource": {
"type": ["string", "null"]
},
"source_snapshot_range": {
"type": ["string", "null"]
},
"destination_resource": {
"type": "string"
},
"source_ip": {
"type": ["string", "null"]
},
"destination_ip": {
"type": ["string", "null"]
},
"force_rollback_on_destination": {
"type": ["boolean", "null"]
},
"generate_replication_stream_package": {
"type": ["boolean", "null"]
},
"generate_deduplicated_stream": {
"type": ["boolean", "null"]
},
"include_properties": {
"type": ["boolean", "null"]
},
"bandwidth_limit": {
"type": ["string", "null"]
}
},
"anyOf": [{
"required": ["source_resource"]
}, {
"required": ["source_snapshot_range"]
}]
}
None
N/A
None
N/A
None
N/A
None
N/A
Fetch data about active boot medium.
Example JSON output::
{
"data": {
"state": "healthy",
"progress": null,
"target_disk_count": 2
},
"error": null
}
Fields description:
- "state" - state of boot medium:
- "healthy" - boot medium is working correctly without issues
- "recovering" - boot medium is rebuilding one of redundancy disks
- "degraded" - boot medium is working using only one disk
- "progress" - integer with percentage of boot medium rebuild, if this
operation is not running then it is set to null (it is null when state
is healthy or degraded).
- "target_disk_count" - Number of disks that should be active in boot
medium in order to keep it in healthy state. In most cases those are
two disks but it is possible to install system on one disk if user
need it and then target disk count is 1 and boot medium is in healthy
state with just one disk.
@return: Http code 200 on success.
N/A
Fetch list of disks that belong to boot medium.
Example JSON output::
{
"data": [
{
"id": "DISK_ID",
"type": "disk",
"state": "healthy"
}
]
"error": null
}
Fields description:
- "id" - id of disk
- "type" - type of disks describes it's role in boot medium:
- "disk" - active disk in mirrored boot medium
- "spare" - inactive disk used as spare that can be used to replace
faulty disks
- "state" - state of boot medium disk:
- "healthy" - disk is working correctly
- "rebuild" - spare disk is being replaced and rebuild of boot
medium is in progress
- "failed" - disk has been marked as failed
- null - spare disks that are not used (not being rebuilt) doesn't
have any state
@return: Http code 200 on success.
N/A
Add new disk to boot medium.
If boot medium contains only one disk then newly added one will be
immediately added as active disk and it will be rebuilt. If boot medium
already contains two active disks then newly added one will be added as
spare disk.
Required JSON keys:
- "id" - ID of disk that will be added to boot medium.
Example JSON input::
{
"id": "DISK_ID"
}
@return Http code 201 on success.
{
"properties": {
"id": {
"type": "string"
}
},
"required": ["id"],
"additionalProperties": false
}
Fetch details about given disk that belongs to boot medium.
Example JSON output:
Output is in the same format as for L{get_disks} except that only single
item is returned instead of an array with boot medium disks.
@param disk_id: Id of boot medium disk to get.
@type disk_id: str
@return: Http code 200 on success.
N/A
Remove given disk from boot medium.
Selected disk will be removed from boot medium but if removed one is an
active disk and boot medium contains spares then it will automatically
replace removed disk. Obviously it is an error to remove last available
disk from boot medium.
@param disk_id: Id of boot medium disk to remove.
@type disk_id: str
@return: Http code 204 on success.
N/A
Mark given disk as failed.
Failed disk won't be used any more by boot medium and if any spare disk is
available it will replace failed disk.
@param disk_id: Id of boot medium disk to be marked as failed.
@type disk_id: str
@return: Http code 204 on success.
N/A
Get list with boot medium jobs.
Example JSON output::
{
data: [
{
"id": "boot-medium-check",
"type": "boot-medium-check"
},
],
error: null
}
N/A
Get status of boot medium integrity check job.
Example JSON output::
{
"data": {
"id": "boot-medium-check",
"type": "boot-medium-check",
"is_running": true,
"progress": 78.8,
"time_left": 125,
"rate": 23891968,
"last_run": 1469716542
},
"error": null
}
Fields description:
- "id" - unique identifier of job, it is connected with scheduler task
- "type" - type of job, it is connected with scheduler task
- "is_running" - boolean flag that indicates if job is running or not
- "progress" - float value that describes what percent of job is
finished, if this value is not available null is returned
- "time_left" - estimated time to finish scan in seconds
- "rate" - current scanning rate in bytes per second
- "last_run" - date at which last check was started, it is given as
UTC timestamp (number of seconds since 1970-01-01)
@return: Http code 200 on success.
N/A
Manually start boot medium integrity check.
@return: Http code 204 on success.
N/A
Manually stop boot medium integrity check.
@return: Http code 204 on success.
N/A
Fetch boot medium additional settings.
Example JSON output::
{
"data": {
"progress_messages_enabled": true
},
"error": null
}
Fields description:
- "progress_messages_enabled" - Flag that indicates if boot medium
progress messages will be issued or not. Setting this flag to False
disables all percentage messages that boot medium generates - only
start and finish message is sent in that case.
return: Http code 200 on success
N/A
Change additional settings for boot medium.
Optional JSON keys:
"progress_messages_enabled" - Flag that controls if boot medium
progress messages are generated.
Example JSON input::
{
"progress_messages_enabled": false
}
return: Http code 200 on success.
{
"properties": {
"progress_messages_enabled": {
"type": "boolean"
}
}
}
Get configuration of the certificate.
Example JSON output::
{
"data": {
"certificate_type": "self-signed",
"expiration_date": 1580399982,
"issuer_common_name": "Open-E JovianDSS",
"subject_common_name": "Open-E JovianDSS"
},
"error": null
}
Fields description:
- "certificate_type" - type of used certificate:
- "self-signed" - automatically generated self-signed certificate
- "custom" - certificate uploaded by the user
- "expiration_date" - timestamp with certificate expiration date
- "issuer_common_name" - common name of certificate issuer
- "subject_common_name" - common name of certificate subject
N/A
Configure type of certificate used by the system for https connections.
It is possible to select between an auto generated self-signed certificate
or a custom certificate that is uploaded along with a private key.
To use the custom certificate is is required to send request with
a multipart/form-data content type with containing key and certificate
files.
Form need to provide the following fields:
- key_file - file with private key in pem format
- cert_file - file with certificate in pem format
To use self-signed certificate (it is a default setting) it is required
to send a request with an application/json conntent type and set
self-signed certificate type in JSON data.
Example JSON input::
{
"certificate_type": "self-signed"
}
{
"properties": {
"certificate_type": {
"type": "string"
}
},
"required": ["certificate_type"],
"additionalProperties": false
}
Check if hpessad is enabled.
Example JSON output::
{
"enabled": true
}
Fields description:
- "enabled" - true when hpessad tool is running and fale otherwise
@return: Http code 200 on success.
N/A
Enable or disable hpessad tool.
Required JSON keys:
- "enabled" - true to enable the tool, false to disable it.
Example JSON input::
{
"enabled": true
}
@return Http code 204 on success.
{
"properties": {
"enabled": {
"type": "boolean"
}
},
"required": ["enabled"]
}
Returns logs package stream.
N/A
Get response policy for critical system errors:
Reboot mechanism can be triggered for:
ZFS pool I/O suspend
System processs freeze (after 300sec)
Kernel oops or BUG
Out-of-memory error
Fields description:
- "io_suspend_policy" - Policy used when I/O suspended state occurs in
zfs.
- "system_process_freeze_policy" - Policy used when system process
is unresponsive for longer than 300 seconds
- "kernel_bug_policy" - Policy used when kernel oops or bug occurs in
Linux kernel.
- "out_of_memory_policy" - Policy used when kernel has out of
memory state
Value description:
- "manual-reboot" - indicates that user will be prompted for manual
reboot.
- "automatic-reboot" - system will automatically reboot after
30 seconds, it is possible to stop this reboot within 30 seconds
time frame.
- "immediate-reboot" - system will reboot immediately any of issue
is detected.
Example JSON output::
{
data: {
"io_suspend_policy": "manual-reboot",
"system_process_freeze_policy": "automatic-reboot",
"kernel_bug_policy": "immediate-reboot",
"out_of_memory_policy": "manual-reboot",
},
error: null
}
@return: Http code 200 on success.
N/A
Set policy applied for critical system errors:
Reboot mechanism can be triggered for:
ZFS pool I/O suspend
System processs freeze (after 300sec)
Kernel oops or BUG
Out-of-memory error
Required JSON keys:
- "io_suspend_policy" - Policy used when I/O suspended state occurs in
zfs.
- "system_process_freeze_policy" - Policy used when system process
is unresponsive for longer than 300 seconds
- "kernel_bug_policy" - Policy used when kernel oops or bug occurs in
Linux kernel.
- "out_of_memory_policy" - Policy used when kernel has out of
memory state
Value description:
- "manual-reboot" - indicates that user will be prompted for manual
reboot.
- "automatic-reboot" - system will automatically reboot after
30 seconds, it is possible to stop this reboot within 30 seconds
time frame.
- "immediate-reboot" - system will reboot immediately any of issue
is detected.
Example JSON input::
{
"io_suspend_policy": "manual-reboot",
"system_process_freeze_policy": "automatic-reboot",
"kernel_bug_policy": "immediate-reboot",
"out_of_memory_policy": "manual-reboot",
}
@return: Http code 200 on success.
{
"properties": {
"io_suspend_policy": {
"type": "string"
},
"system_process_freeze_policy": {
"type": "string"
},
"kernel_bug_policy": {
"type": "string"
},
"out_of_memory_policy": {
"type": "string"
}
},
"required": ["io_suspend_policy", "system_process_freeze_policy", "kernel_bug_policy", "out_of_memory_policy"]
}
Get current state of I/O fencing policy
Example JSON output::
{
data: {
"enabled": True
},
error: null
}
Fields description:
- "enabled" - True if I/O fencing is enabled, False
otherwise
@return: Http code 200 on success.
N/A
Set state of I/O fencing policy
Required JSON keys:
- "enabled" - True if I/O fencing should be enabled,
False otherwise
Example JSON input::
{
"enabled": True
}
@return: Http code 200 on success.
N/A
Get policy applied when I/O suspended state occurs in zfs.
Example JSON output::
{
data: {
"io_suspend_policy": "manual-reboot"
},
error: null
}
Fields description:
- "io_suspend_policy" - Policy used when I/O suspended state occurs in
zfs.
- "manual-reboot" - indicates that user will be prompted for manual
reboot when I/O suspended state occurs.
- "automatic-reboot" - indicates that when I/O suspended state
occur then system will automatically reboot after 30 seconds, it is
possible to stop this reboot within 30 seconds time frame
- "immediate-reboot" - system will reboot immediately when I/O
suspended state occurs.
@return: Http code 200 on success.
N/A
Set policy applied when I/O suspended state occurs.
Required JSON keys:
- "io_suspend_policy" - Policy to set, description of available
policies is available in {get_io_suspend_policy}.
Example JSON input::
{
"io_suspend_policy": "immediate-reboot"
}
@return: Http code 200 on success.
{
"properties": {
"io_suspend_policy": {
"type": "string"
}
},
"required": ["io_suspend_policy"]
}
Fetch all tasks registered in scheduler.
Scheduler runs tasks according to it's configuration. Each task can be
configured to run in particular time intervals.
Example JSON output::
{
"data": [
{
"id": "SCHEDULER_TASK_ID",
"job_id": "boot-medium-check",
"schedule": "weekly",
"minute": 15,
"hour": 7,
"day_of_month": null,
"month": null,
"day_of_week": [1, 2, 3, 4, 5],
"is_running": true,
"progress": 48.7,
"last_time_started": null
}
],
"error": null
}
Fields description:
- "id" - ID of particular scheduler task
- "job_id" - ID of job that is assigned to task, there are predefined
IDs for some jobs:
- "boot-medium-check" - job that performs integrity check of boot
medium
- "schedule" - type of schedule:
- "daily" - task is executed by specified in days interval that is
set using day_of_month field
- "weekly" - task is executed each week on specified days of week
- "monthly" - task is executed each month on specified days of month
- "yearly" - task is executed each year on specified months with
specified days of month
- "minute" - minute when task is executed
- "hour" - hour when task is executed
- "day_of_month" - day of month when task is executed specified as
number in range 1-31, for monthly and yearly schedule this can be array
that contains multiple items, in case of daily schedule this is array
with single item specifying day interval
- "month" - array with months when task will be executed, months are
specified as numbers in range 1-12
- "day_of_week" - array with days of week when schedule will be
executed, days are expressed as numbers: 1 is monday, 7 is sunday
- "last_time_started" - value that indicates when task was started for
the last time, if task have not been started yet then this has null
value
@return: Http code 200 on success.
N/A
Create new scheduler task.
Required JSON keys:
- "job_id"
- "schedule"
- "day_of_month" - required only for daily, monthly or yearly schedule
- "month" - required only for yearly schedule
- "day_of_week" - required only for weekly schedule
Optional JSON keys:
- "hour"
- "minute"
Example JSON input::
{
"job_id": "boot-medium-check",
"schedule": "daily",
"minute": 45,
"hour": 11,
"day_of_month": [3]
}
For detailed fields description take a look at L{get_scheduler_tasks}.
@return: Http code 201 on success.
{
"properties": {
"job_id": {
"type": "string"
},
"schedule": {
"type": "string"
},
"minute": {
"type": "integer"
},
"hour": {
"type": "integer"
},
"day_of_month": {
"oneOf": [{
"type": "array",
"items": {
"type": "integer"
}
}, {
"type": "integer"
}]
},
"month": {
"oneOf": [{
"type": "array",
"items": {
"type": "integer"
}
}, {
"type": "integer"
}]
},
"day_of_week": {
"oneOf": [{
"type": "array",
"items": {
"type": "integer"
}
}, {
"type": "integer"
}]
}
},
"required": ["job_id", "schedule"],
"additionalProperties": false
}
Fetch scheduler task with given id.
Example JSON output::
{
"data": {
"id": "task_id",
"job_id": "boot-medium-check",
"schedule": "yearly",
"minute": 5,
"hour": 3,
"day_of_month": [3, 10, 17, 24],
"month": [1, 8, 9],
"day_of_week": null
},
"error": null
}
For detailed fields description take a look at L{get_scheduler_tasks}.
@param task_id: ID of scheduler task to fetch.
@type task_id: str
@return: Http code 200 on success.
N/A
Modify given scheduler task.
Method accepts the same set of JSON keys as L{create_scheduler_task} except
that all are optional. Given values will be edited in scheduler task but
bear in mind that some fields depends on the others for more details read
description for L{get_scheduler_tasks}. Some of the fields accept null
value in order to be able to reset particular field. Some schedules
requires that some fields are set to null. If schedule is modified it might
be required to set some fields to null value.
Example JSON input::
{
"day_of_month": [10, 20]
}
@param task_id: ID of scheduler task to modify.
@type task_id: str
@return: Http code 200 on success.
{
"properties": {
"schedule": {
"type": "string"
},
"minute": {
"type": "integer"
},
"hour": {
"type": "integer"
},
"day_of_month": {
"oneOf": [{
"type": "array",
"items": {
"type": "integer"
}
}, {
"type": "integer"
}, {
"type": "null"
}]
},
"month": {
"oneOf": [{
"type": "array",
"items": {
"type": "integer"
}
}, {
"type": "integer"
}, {
"type": "null"
}]
},
"day_of_week": {
"oneOf": [{
"type": "array",
"items": {
"type": "integer"
}
}, {
"type": "integer"
}, {
"type": "null"
}]
}
},
"additionalProperties": false
}
Delete given scheduler task.
@param task_id: ID of scheduler task to delete.
@type task_id: str
@return: Http code 204 on success.
N/A
Fetch scrub pause scheduler settings.
Output data has the same format as input data with scrub pause scheduler
configuration. Input data is described in
L{configure_scrub_pause_scheduler}.
@return: Http code 200 on success.
N/A
Enable scrub pause scheduler.
Configure schedule for scrub pause. Two types of schedules are available:
daily and weekly. For daily schedule it is required to provide time
configuration that includes time of scrub pause and time of scrub resume.
In weekly schedule global time is optional and is applied to any day for
which time settings are not specified. It is an error to not configure
default time settings in weekly schedule, if there is at least one day
without configured time schedule. If each day contains time configuration
it is not necessary to provide default one, in this case it won't be saved
or used.
Weekly schedule that mixes default time settings and settings for
individual days, applies default time settings into individual days that do
not provide time configuration. This means that in mixed configuration
time settings are always interpreted as configured for individual days and
will be presented this way when fetched. The only case where default time
settings are not saved directly into individual days is when each day do
not provide time settings.
Days of the week are provided as day number:
- 0: sunday
- 1: monday
- 2: tuesday
- 3: wednesday
- 4: thursday
- 5: friday
- 6: saturday
Time settings are described by time of "scrub_pause" and time of
"scrub_resume". Each object requires to provide "hour" and "minute" fields.
Hours and minutes are provided as integers, 24 hour clock format is used
in configuration. Detailed input format is presented below, each type of
schedule has separate example.
Example JSON input:
- Daily schedule::
{
"schedule_type": "daily",
"time": {
"scrub_pause": {
"hour": 10,
"minute": 0
},
"scrub_resume": {
"hour": 16,
"minute": 30
}
}
}
- Weekly schedule with default time::
{
"schedule_type": "weekly",
"time": {
"scrub_pause": {
"hour": 10,
"minute": 0
},
"scrub_resume": {
"hour": 16,
"minute": 30
}
},
"days": [
{"day_number": 1},
{"day_number": 2},
{"day_number": 3},
{"day_number": 4},
{"day_number": 5}
]
}
- Weekly schedule with custom time for each day::
{
"schedule_type": "weekly",
"days": [
{
"day_number": 1,
"time": {
"scrub_pause": {
"hour": 8,
"minute": 0
},
"scrub_resume": {
"hour": 14,
"minute": 15
}
}
},
{
"day_number": 2,
"time": {
"scrub_pause": {
"hour": 10,
"minute": 0
},
"scrub_resume": {
"hour": 16,
"minute": 20
}
}
}
]
}
- Weekly schedule with scrub pause that spans multiple days::
{
"schedule_type": "weekly",
"days": [
{
"day_number": 1,
"time": {
"scrub_pause": {
"hour": 8,
"minute": 0
}
}
},
{
"day_number": 3,
"time": {
"scrub_resume": {
"hour": 16,
"minute": 20
}
}
},
{
"day_number": 5,
"time": {
"scrub_pause": {
"hour": 11,
"minute": 15
}
}
},
{
"day_number": 6,
"time": {
"scrub_resume": {
"hour": 14,
"minute": 15
}
}
}
]
}
@return: Http code 200 on success along with updated configuration of the
scrub pause scheduler.
N/A
Disable scrub pause scheduler and remove configuration.
@return: Http code 204 on success.
N/A
Returns tasks. Uses paging by default.
URL parameters:
- page: Determines which page to fetch. Default: 0
- per_page: Determines the amount of results per page. Default: 20
- sort_by: Decides by which key the results will be sorted by. Default: "start_time".
- order: Decides how to sort the results: "asc" for ascending order, "desc" for descending. Default: "asc"
- query: A query that determines which entries should be deleted.
If no query is specified returns all the tasks. Syntax documented under /doc/query REST endpoint.
Example: GET: .../tasks?query={"name": "VersionChange", "start_time": {"$gt": 1619525186}}
Example JSON output:
{
"data": [
{
"status": "failed",
"resource": {
"type": "Update",
"id": "b42804"
},
"name": "VersionChange",
"links": {
"self": {
"href": "/api/v3/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6"
},
"request": {
"href": "/api/v3/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6/request"
},
"response": {
"href": "/api/v3/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6/response"
},
"delete": {
"href": "/api/v3/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6"
}
},
"start_time": 1619525186.992631,
"uri": "/api/v3/updates/b42804/defaultboot",
"id": "e1163fca-00d3-47ac-9e8a-a95886dc3ad6",
"end_time": 1619525217.041519,
"method": "POST"
}
],
"error": null
}
@return http code 200 on success
N/A
Delete task for given query
URL parameters:
- query: A query that determines which entries should be deleted. Syntax documented under /doc/query REST endpoint.
Example: DELETE: .../tasks?query={"name": "VersionChange", "start_time": {"$gt": 1619525186}}
Example JSON output:
{
"data": {
"deleted_count": 1
},
"error": null
}
@return: Http code 200 on success.
N/A
Returns status of a task identified by 'task_id'
@param task_id: ID for the task
@type task_id: str
Example JSON output:
{
"data": {
"status": "failed",
"resource": {
"type": "Update",
"id": "b42804"
},
"name": "VersionChange",
"links": {
"self": {
"href": "/api/v3/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6"
},
"request": {
"href": "/api/v3/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6/request"
},
"response": {
"href": "/api/v3/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6/response"
},
"delete": {
"href": "/api/v3/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6"
}
},
"start_time": 1619525186.992631,
"uri": "/api/v3/updates/b42804/defaultboot",
"id": "e1163fca-00d3-47ac-9e8a-a95886dc3ad6",
"end_time": 1619525217.041519,
"method": "POST"
},
"error": null
}
@return http code 200 on success
N/A
Delete task with a given ID. Cannot delete tasks in progress.
@return: Http code 204 on success.
N/A
Returns request JSON for the task.
@param task_id: ID for the task
@type task_id: str
JSON output is task-dependant. Parameters that are part of the URL are added as additional fields.
For example for this endpoint there would be:
{
"data": {
"task_id": "1234-5678-9101-1121",
... // Remaining JSON request parameters
},
"error": null
}
@return http code 200 on success
N/A
Returns an identical response that would have appeared if the operations
done by the task identified by 'task_id' were done synchronically.
@param task_id: ID for the task
@type task_id: str
JSON output and http code are task-dependant.
N/A
Return configuration of system time.
Example JSON output::
{
"data":
{
"timezone": "Europe/Berlin",
"timestamp": 1437126007228,
"daemon": false,
"sync_at_boot": false,
"servers":
[
"0.europe.pool.ntp.org"
]
},
"error": null
}
@return: Http code 200 on success.
N/A
Sets configuration of system time.
Example JSON input 1::
{
"timezone": "Europe/Amsterdam"
}
Example JSON input 2::
{
"sync_at_boot": true,
"daemon": false
}
Example JSON output 1 (success)::
{
"data": null,
"error": null
}
Example JSON output 2 (fail)::
{
"data": null,
"error": {
"class": "jsonschema.exceptions.ValidationError",
"message": "You have to specify at least one property."
}
}
Required JSON keys:
- any property, at least one is required
Optional JSON keys:
- "timestamp" - Miliseconds since epoch (int).
- "timezone" - Available timezone name (str).
- "sync_at_boot" - Should time be synchronized once via NTP at system boot (bool).
- "daemon" - Should be NTP service running (bool).
- "servers" - Addresses of NTPs used both by sync on demand and daemon (str).
@return: Http code 200 on success.
{
"properties": {
"timestamp": {
"type": "number"
},
"timezone": {
"type": "string"
},
"sync_at_boot": {
"type": "boolean"
},
"daemon": {
"type": "boolean"
},
"servers": {
"type": "array"
}
}
}
Synchronizes system time with NTP servers from configuration.
Example JSON output 1 (success)::
{
"data": null,
"error": null
}
@return: Http code 200 on success.
N/A
Returns all available in system timezones.
There is almost 600 items.
Example JSON output (shortened)::
{
"data":
[
"Europe/Amsterdam",
"Europe/Andorra",
"Europe/Athens",
"Europe/Belfast",
"Europe/Belgrade"
],
"error": null
}
@return: Http code 200 on success.
N/A
Returns information about products versions, builds etc. and applied small updates.
Example JSON output::
{
"data":
[
{
"product": "1.0",
"product_name": "EDSS",
"up": "05",
"currently_running": 1,
"installation_date": "2015-05-26 12:18",
"version": "1.0",
"relnotes":
[
"Release notes are available online. Go to release notes webpage."
],
"build": "FRESNO",
"code_name": "FRESNO",
"date": "2015-05-26",
"default_boot": 0,
"small_update":
[
],
"id": "EDSS",
"size": 0
},
{
"product": "1.0",
"product_name": "EDSS",
"up": "05",
"currently_running": 0,
"installation_date": "2015-05-26 14:42",
"version": "1.0",
"relnotes":
[
"Release notes are available online. Go to release notes webpage."
],
"build": "16286",
"code_name": "FRESNO",
"date": "2015-05-26",
"default_boot": 1,
"small_update":
[
],
"id": "b16286",
"size": 4608358112
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Adds update image file so it will be able to be chosen and running.
Image file is uploaded separately (by PHP).
Required JSON keys:
- "path" - string, file path to image file.
Example JSON input::
{
"path": "/tmp/upload/upd_90014-EDSS.upd"
}
Example JSON output 1 (success)::
{
"data": null,
"error": null
}
Example JSON output 2 (fail)::
{
"data": null,
"error":
{
"class": "opene.maintenance.update.UpdateError",
"errno": 100,
"message": "Wrong parameter."
}
}
Example JSON output 3 (fail)::
{
"data": null,
"error":
{
"class": "opene.maintenance.update.full.FullUpdateError",
"errno": 1,
"message": "File not found."
}
}
@return: Http code 200 on success.
{
"properties": {
"path": {
"type": "string"
}
}
}
Returns information about given version.
@param update_name: Version ID (e.g. "b16286.1").
@type update_name: str
Example JSON output 1 (success)::
{
"data":
{
"product": "1.0",
"product_name": "EDSS",
"up": "05",
"currently_running": 0,
"installation_date": "2015-05-26 14:54",
"version": "1.0",
"relnotes":
[
"Release notes are available online. Go to release notes webpage."
],
"build": "16286",
"code_name": "FRESNO",
"date": "2015-05-26",
"default_boot": 0,
"small_update":
[
],
"id": "b16286.1",
"size": 4608251535
},
"error": null
}
@return: Http code 200 on success.
N/A
Deletes given product version.
@param update_name: Version ID (e.g. "b16286.1").
@type update_name: str
Example JSON output 1 (success)::
{
"data": null,
"error": null
}
Example JSON output 2 (fail)::
{
"data": null,
"error":
{
"class": "opene.maintenance.update.full.FullUpdateError",
"errno": 10,
"message": "Version currently used."
}
}
@return: Http code 200 on success.
N/A
Change version to be used at boot.
@param update_name: Version ID (e.g. "b16286.1").
@type update_name: str
URL parameters:
- "as_task" - 0 or 1. If its set to 1, the REST endpoint responds
immediately, and the operation will be done in the background,
otherwise response will be sent after the operation is finished.
Defaults to 0.
Optional JSON keys:
- "reboot" - indicates if system should be restarted now.
Example JSON input::
{
"reboot": true
}
Example JSON output 1 (success)::
{
"data": null,
"error": null
}
Example JSON output 2 (fail)::
{
"data": null,
"error":
{
"class": "opene.maintenance.update.full.FullUpdateError",
"errno": 9,
"message": "Update does not exist."
}
}
Example JSON output 3 (when run as a background task)::
{
"data": {
"task": {
"id": "0f21fedd-9d1c-4b90-8c5a-14b056135157",
"links": {
"delete": {
"href": "/api/v3/tasks/0f21fedd-9d1c-4b90-8c5a-14b056135157"
},
"response": {
"href": "/api/v3/tasks/0f21fedd-9d1c-4b90-8c5a-14b056135157/response"
},
"request": {
"href": "/api/v3/tasks/0f21fedd-9d1c-4b90-8c5a-14b056135157/request"
},
"self": {
"href": "/api/v3/tasks/0f21fedd-9d1c-4b90-8c5a-14b056135157"
}
}
}
},
"error": null
}
@return: Http code 200 on success. If run
as a background task, http code 202 is returned.
{
"properties": {
"reboot": {
"type": "boolean"
}
}
}
Adds small_update to the given version.
@param update_name: Version ID (e.g. "b16286.1").
@type update_name: str
Required JSON keys:
- "path" - string, file path to image file.
Example JSON input::
{
"path": "/tmp/upload/upd_90014-EDSS.upd"
}
@return: Http code 200 on success.
{
"properties": {
"path": {
"type": "string"
}
}
}
Returns data about small updates of given version.
@param update_name: Version ID (e.g. "b16286.1").
@type update_name: str
Example JSON output 1 (success)::
{
"data":
[
{
"installed": 0,
"installation_date": "2015-05-26 15:40",
"restart_needed": 0,
"release_notes":
[
"FIXED: Reordered NICs."
],
"id": "upd_90015-EDSS",
"size": 8192
}
],
"error": null
}
Example JSON output 2 (fail)::
{
"data": null,
"error":
{
"class": "opene.maintenance.update.small.SmallUpdateError",
"errno": 6,
"message": "Product does not exist."
}
}
@return: Http code 200 on success.
N/A
Deletes small_update of given version.
@param update_name: Version ID (e.g. "b16286.1").
@type update_name: str
@param small_update_name: Small update ID (e.g. "upd_90015-EDSS").
@type small_update_name: str
Optional JSON keys:
- "reboot" - indicates if system should be restarted now.
Example JSON input::
{
"reboot": true
}
Example JSON output 1 (success)::
{
"data": null,
"error": null
}
Example JSON output 2 (fail)::
{
"data": null,
"error":
{
"class": "opene.maintenance.update.small.SmallUpdateError",
"errno": 1,
"message": "Small Update does not exist."
}
}
@return: Http code 200 on success.
{
"properties": {
"reboot": {
"type": "boolean"
}
}
}
Apply small update to version.
@param update_name: Version ID (e.g. "b16286.1").
@type update_name: str
@param small_update_name: Small update ID (e.g. "upd_90015-EDSS").
@type small_update_name: str
Optional JSON keys:
- "reboot" - indicates if system should be restarted now.
Example JSON input::
{
"reboot": true
}
Example JSON output 1 (success)::
{
"data": null,
"error": null
}
@return: Http code 200 on success.
{
"properties": {
"reboot": {
"type": "boolean"
}
}
}
Creates user in given backend.
Example JSON input:
{
"name": "user",
"password": "password",
"backend_name": "AD"
}
Fields:
- 'name' - user name
- 'password' - password to set
- 'backend_name' - authentication backend to use
@return: Http code 201 on success.
{
"properties": {
"name": {
"type": "string"
},
"password": {
"type": "string"
},
"backend_name": {
"type": "string"
}
},
"required": ["name", "password", "backend_name"],
"additionalProperties": false
}
Example JSON output::
{
"data":{
results : 2,
entries : [
{
"uid" : 1000,
"gid": 1000,
"name" : "Administrator",
"backend" : "LDAP"
},
{
"uid" : 1001,
"gid" : 1000,
"name" : "User",
"backend" : "LDAP"
}
]
},
"error":null
}
@return: Http code 200 on success.
N/A
Example JSON output::
{
"data":{
"uid" : 1000,
"gid": 1000,
"name" : "Administrator",
"backend" : "LDAP"
},
"error":null
}
@return: Http code 200 on success.
N/A
Deletes user from given backend.
@return: Http code 204 on success.
N/A
Example JSON output::
@return: Http code 200 on success.
N/A
Example JSON input::
{
"groups": ["group1", "group2"],
"backend_name": "LDAP"
}
Fields:
- 'groups' - list of groups where user will be attached
- 'backend_name' - authentication backend to use
@return: Http code 204 on success.
{
"properties": {
"groups": {
"type": "array"
},
"backend_name": {
"type": "string"
}
},
"required": ["groups", "backend_name"],
"additionalProperties": false
}
Example JSON input::
{
"groups": ["group1", "group2"],
"backend_name": "LDAP"
}
Fields:
- 'groups' - list of groups from where user will be detached
- 'backend_name' - authentication backend to use
@return: Http code 204 on success.
{
"properties": {
"groups": {
"type": "array"
},
"backend_name": {
"type": "string"
}
},
"required": ["groups", "backend_name"],
"additionalProperties": false
}
Updates user in given backend.
Example JSON input:
{
"name": "name",
}
Fields:
- 'new_name' - user new name
@return: Http code 204 on success.
{
"properties": {
"name": {
"type": "string"
}
},
"required": ["name"]
}
Updates user in given backend.
Example JSON input:
{
"password": "password"
}
Fields:
- 'name' - new user name
- 'password' - new password to set
@return: Http code 204 on success.
{
"properties": {
"password": {
"type": "string"
}
},
"required": ["password"]
}
Example JSON input::
{
"primary_group": "Group",
"backend_name": "LDAP"
}
Fields:
- 'primary_group' - new primary group name
- 'backend_name' - authentication backend to use
@return: Http code 200 on success.
{
"properties": {
"primary_group": {
"type": "string"
},
"backend_name": {
"type": "string"
}
},
"required": ["primary_group", "backend_name"],
"additionalProperties": false
}
Check if given path is an existing directory of dataset or snapshot.
@param path: Directory path of dataset or snapshot (e.g. "Pool-0/MyDataSet/SomeShare")
@type path: str
@return: Http code 204 on success (exists).
N/A
Returns all available Vdev types.
N/A