Validates credentials for a user or the administrator account and returns
a list of permissions associated with that account.
Path parameters:
- "user": Optional user name for domain authentication. When omitted, administrator authentication is used.
Example JSON input:
{
"password": "supersecret"
}
Example JSON output:
{
"data":
{
"authenticated": true,
"permissions": ["webgui_read", "webgui_write"]
}
}
Required request fields:
- 'password' - Password for the LDAP, Active Directory user or for the admin account
@return HTTP code 200 on success.
@return HTTP code 400 when JSON input is invalid.
{
"properties": {
"password": {
"type": "string"
}
},
"required": [
"password"
],
"additionalProperties": false
}
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"
]
}
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
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 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.
Required JSON keys:
- "address" - IP address of ping node to be monitored
(e.g. ``192.168.251.17``).
Example JSON input::
{
"address": "192.168.251.17"
}
@return: Http code 201 on success.
{
"properties": {
"address": {
"type": "string"
}
},
"required": [
"address"
]
}
None
N/A
Sets "Lost connection response policy".
Required JSON keys:
- "policy" - policy name used when ping node connection is lost:
- "export" - export pools
- "reboot" - reboot cluster node
Example JSON input::
{
"policy": "policy_name"
}
@return: Http code 204 on success.
{
"properties": {
"policy": {
"type": "string"
}
},
"required": [
"policy"
]
}
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
None
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:
- "interfaces" - array of exactly two path members (one per node),
- "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:
- "interfaces" - array of ring members,
two items are required in the array, each item is an object with fields:
- "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
Adds SCST handler for SCSI-3 Persistent Reservation Synchronization.
Required JSON keys:
- "device_name" - SCST device name.
- "lun_path" - path to backend LUN device.
- "options" - object with handler options:
- "blocksize" - block size for exposed device.
Optional JSON keys:
- "prod_id" - product identifier exposed by target.
- "device_handler" - SCST device handler type. Defaults to BLOCKIO.
- "options.read_only" - integer flag for read-only mode (1 enables
read-only).
- "options.write_through" - integer flag for write-through mode.
- "options.filesize" - integer size for file-based handler.
- "options.thin_provisioned" - integer flag for thin provisioning.
@return: Http code 200 on success.
{
"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
Removes SCST handlers from SCSI-3 Persistent Reservation Synchronization.
Required JSON keys:
- "handers_list" - array of SCST handler names to remove.
@return: Http code 204 on success.
{
"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).
Optional JSON keys:
- "force" - bool flag used only with "cluster" mode to force cluster
start, this flag is needed foce cluster start when separated cluster
state is set on both cluster nodes..
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"
]
}
Diagnostic connection test to the REST API.
Returns simple text "OK" on successful connection to the REST API.
Example JSON output:
{
"data": "OK",
"error": null
}
@return: Http code 200 on success.
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,
"missing": false,
"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,
"missing": 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,
"missing": false,
"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
- "missing" - bool that indicates if disk is missing
- "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.
Required JSON keys:
- "led" - Indicates if disk identification or fault indication should
be enabled or disabled. Type: object.
- "locate" - Controls identify/locate LED state. Type: boolean.
- "fault" - Controls fault LED state. Type: boolean.
Optional JSON keys:
- None.
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
Enable password protection for specified disk.
@param disk_id: ID of the disk for which password protection will be
enabled.
@type disk_id: str
@return: Http code 201 on success.
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.
Required JSON keys:
- None.
Optional JSON keys:
- "discard_zdb_labels" - List of disk IDs for which ZDB labels should
be discarded during reread, or null. Type: array[string] or null.
- "clear_zdb_labels" - List of disk IDs for which ZDB labels should be
cleared during reread, or null. Type: array[string] or null.
@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
S.M.A.R.T. status summary for all disks in the system.
List of disks in the system with status of the S.M.A.R.T. test. True value
indicates that disk passed the test, False value indicates that disk failed
the test.
Example JSON output::
{
"data": {
{
"smart_test_passed": true,
"id": "wwn-0x5000039fdadcc2f6",
"name": "sda"
},
{
"smart_test_passed": true,
"id": "wwn-0x5000c5002a388201",
"name": "sdb"
}
},
"error": null
}
@return: Http code 200 on success.
N/A
Detailed disk S.M.A.R.T. data.
JSON Output description:
- "device_name" - Disk name in the system.
- "smart_available" - Flag that indicates if disk supports S.M.A.R.T.
If it is set to false, data returned for the disk is limited and might
not be reliable as disk does not support S.M.A.R.T.
- "smart_enabled" - Flag that indicates if S.M.A.R.T. is enabled on
given disk. If it is set to false, disk has disabled S.M.A.R.T.
support. In order to correctly read S.M.A.R.T. data it is required to
enable it on the disk.
- "device_information" - Object containing detailed device information.
- "device" - Object with device type data:
- "type" - Type of device: "sat" (SATA), "nvme", "scsi" etc.
- "protocol" - Communication protocol used by the disk:
"ATA", "NVMe", "SCSI" etc.
- "model_family" - Disk model family (product line), this field may
be empty (null) if disk is not present in smartctl database.
- "model_name" - Model of the disk.
- "serial_number" - Disk serial number.
- "firmware_version" - String indicating version of the firmware
used by the disk.
- "user_capacity" - Object with data describing space that can be
used on the disk.
- "bytes" - Size of the available space in bytes.
- "blocks" - Size of the available space in blocks.
- "logical_block_size" - Logical block size.
- "physical_block_size" - Physical block size.
- "rotation_rate" - Number with rate at which mechanical hard drive
rotates plates. For SSDs it may be a string describing that this
device is a solid state disk. In some cases (for example NVMe
disks) this field is empty (set to null) - which indicates that it
does not apply to given device.
- "form_factor" - Object describing physical dimensions of the
device. This field may be empty (set to null) if device is not
present in smartctl database or if this field does not apply to
particular device.
- "ata_value" - Vendor specific value describing device size.
- "name" - String with human readable description of a device
size like "3.5 inches".
- "in_smartctl_database" - Flag describing if device is present in
smartctl database.
- "ata_version" - Object with ATA version description. This field
may be empty (set to null) if device does not use ATA standard
(for example NVMe devices).
- "major_value" - Integer with major value.
- "minor_value" - Integer with minor value.
- "string" - String with name of ATA version.
- "sata_version" - Object with SATA version description. This field
may be empty (set to null) if device does not use SATA interface
(for example NVMe devices).
- "value" - Integer with version number.
- "string" - Human readable name of SATA version for example:
"SATA 3.0"
- "nvme_data" - Data specific to NVMe devices. This field is empty
for non NVMe devices (set to null).
- "nvme_pci_vendor" - Object describing PCI vendor.
- "id" - Integer
- "subsystem_id" - Integer
- "nvme_ieee_oui_identifier" - Integer
- "nvme_total_capacity" - Integer value describing total disk
capacity in bytes.
- "nvme_unallocated_capacity" - Integer value describing amount
of space that is currently not allocated by the device.
- "nvme_controller_id" - Integer
- "nvme_number_of_namespaces" - Integer value describing count
of items in nvme_namespaces list.
- "nvme_namespaces" - List with objects describing additional
device properties.
- "smart_data" - Object containing detailed S.M.A.R.T. data for the
disk.
- "smart_status" - Flag indicating if disk passed S.M.A.R.T. test.
- "ata_smart_attributes" - List of disk attributes. Those
attributes are available for ATA disks only, NVMe devices will
have this field set to null. Attributes are vendor specific and
quite often their meaning is not documented. Attributes shall be
presented to the user as is and it is up to the user to obtain any
information about their meaning if necessary. Each attribute is
presented as object with following fields:
- "name" - Name of the attribute with spaces replaced by
undersocres "_".
- "value" - Normalized value of the attribute which ranges
from 1 to 253. Most commonly initial default value is set to
100 which means that particular property is at the level in
which disk left the factory. However default value is dependent
on disk manufacturer and usage of 100 as default value may
vary between vendors. Usually higher value means better
property while lover worser property. But this is also up to
the manufacturer of the disk and is dependent on the type of
the property. For some properties lower value might mean better
value while for other the opposite.
- "threshold" - Threshold beyond which value shall not be
exceeded during normal operation. Be aware that interpretation
of the value vary between manufactures and between types of
properties itself. This means that it is not known if threshold
have to be added or substracted from initial value to know if
value exceeds it. Also initial value not necessary have to
be 100 as it also depends on manufacturer and is most commonly
undocumented.
- "worst" - Worst registered value for the property.
- "when_failed" - Field indicating if value exceeded or
currently exceeds the threshold. This field can be used to
check if particular property indicates that there may be issues
with the disk. Field can use following values:
- "" - Empty string indicates that property does not report
any issues, its status is OK.
- "now" - Means that property is currently indicating
issues with the disk, threshold is currently exceeded.
- "past" - Means that property was exceeded in the past
but currently is within threshold. This could also indicate
issues with the disk as property reported in the past value
that exceeds the threshold.
- If none of the above values is found in "when_failed"
field, value that is returned by smartctl will be directly
used however it rather shall not happen.
- "prefailure" - Flag that tells if given property can be
used as indicator of coming disk failure when it exceeds
the threshold. If it is set to true and property indicates
issue in "when_failed" field, it means that disk failure is
expected in the future. When flag is set to false it means
that this property is related to disk "age". In that case
if "when_failed" field indicates issue, it simply means that
disk can be considered as worn out by manufacturers
standards but it not necessarily indicates that disk is
going to suddenly fail.
- "raw" - Object with raw value. It contains direct value
returned by the disk that is not normalized. This value
could be actually anything like number of bytes, some
voltage that represents temperature or anything else. It is
completely manufacturer dependent. Object contains two
fields:
- "value" - Integer with direct property value, units
or meaning is manufacturer dependent.
- "string" - In some cases much more human readable
representation of the raw value. In many cases it is
simply integer from "value" field as string but
sometimes it is a helpfull text. For example in case of
temperature it could be text such as:
"27 (Min/Max 21/32)" - which clearly explains meaning
of property value.
- "nvme_smart_health_information_log" - Object containing
S.M.A.R.T. information specific to NVMe devices. Its content is
dependent on manufacturer. Below are presented some common fields
that are always present but if particular field was not returned
by the device its value will be empty (set to null). There could
be other fields present depending on what device returned. Because
meaning, units and presense of the fields is manufacturer dependant
and usually undocumented, below descriptions are a general
guideline only. Some of the fields may overlap with fields
available for all kind of devices but it is not certain if
particular device will report the same field in both places. Due to
that reason repeated fields may be available in NVMe section and in
general section.
- "available_spare" - Percentage of spare flash that is
available on this device.
- "temperature" - Current temperature of the device.
Some devices have more than one temperature sensor and also
return list of temperatures in field "temperature_sensors".
However it is not guaranteed that this field is present in
the output.
- "percentage_used" - Device worn out percentage.
- "data_units_read" - Number of 512 byte units multiplied by
1000 read from flash.
- "data_units_written" - Number of 512 byte units written
to flash.
- "host_reads" - Number of requested reads on the device.
- "host_writes" - Number of requested writes on the device.
- "power_cycles" - Number of device power cycles.
- "power_on_hors" - Total count of hours the device was
powered on.
- "unsafe_shutdowns" - Number of device shutdowns by suddenly
cutting the power to the device.
- "power_on_time" - Number of hours device was powered on.
- "power_cycle_count" - Number of device power cycles.
- "temperature" - Object with temperature data of the device. It
contains following fields:
- "current" - Current temperature reading.
- "drive_trip" - Critical temperature at which disk "trips" -
shuts down to prevent damage. This field is usually available
only for SCSI disks.
- "scsi_grown_defect_list" - Counter of defects for SCSI disks.
- "scsi_percentage_used_endurance_indicator" - Percentage of used
disk endurance. This field is usually available for SCSI SSD disks.
- "scsi_error_counter_log" - Log with error counters of SCSI disks.
Log contains three entries: "read", "write", "verify". Not every
SCSI disk contains all entries. If particular entry is missing it
is set to null. Each entry contains following fields with error
counters:
- "errors_corrected_by_eccfast" - Integer
- "errors_corrected_by_eccdelayed" - Integer
- "errors_corrected_by_rereads_rewrites" - Integer
- "total_errors_corrected" - Integer
- "correction_algorithm_invocations" - Integer
- "gigabytes_processed" - String that contains floating point
number of gigabytes.
- "total_uncorrected_errors" - Integer
- "error_log" - List with lines from device error log. This is
presented as list of lines as devices return error log in form of a
text that is not standardized. Log is supposed to be human readable
at least if log format is understood by the reader.
@param disk_id: ID of the disk from which S.M.A.R.T. data will be obtained.
@type disk_id: str
@return: Http code 200 on success.
N/A
Status of disk self test.
JSON Output description:
- "test_status" - Status of disk self test. It uses string value to
describe the status, following values are used:
- COMPLETED_WITHOUT_ERROR - self test ended and it have not
detected any issues with the disk
- ABORTED_BY_HOST - self test was aborted
- INTERRUPTED_HOST_RESET
- FATAL_OR_UNKNOWN_ERROR
- COMPLETED_UNKNOWN_FAILURE
- COMPLETED_ELECTRICAL_FAILURE
- COMPLETED_SERVO_SEEK_FAILURE
- COMPLETED_READ_FAILURE
- COMPLETED_HANDLING_DAMAGE
- SELF_TEST_IN_PROGRESS - self test is currently running,
"remaining_percent" indicates how much of the test has left
- "remaining_percent" - When test is in progres it indicates how much
percent of the test left until finish. If test is not running this
value is set to null.
- "passed" - Boolean flag indicating if last self test has passed.
- "is_running" - Boolean flag indicating if self test is currently in
progress.
- "self_tests_supported" - Boolean flag that indicates if disk supports
S.M.A.R.T. self tests.
@param disk_id: ID of the disk from which S.M.A.R.T. self test status will
be obtained.
@type disk_id: str
@return: Http code 200 on success.
N/A
Get list with statuses of self tests executed on the disk.
List with self test log entries is returned. Each entry describes self
test that was executed on the disk or is currently being executed
(currently running self test is present as first item of the list).
JSON Output description of each log entry:
- "self_test_type" - Type of self test that the entry describes.
Following values are available:
- "SHORT_OFFLINE" - short self test
- "EXTENDED_OFFLINE" - long self test
- "CONVEYANCE_OFFLINE" - conveyance self test
- "SELECTIVE_OFFLINE" - selective self test
- "remaining_percent" - This field has different meaning depending on
test status. For test that is being in progress it describes how much
percent of the test has left until finish. For the test that was
aborted or has failed it shows how much percent of the test has left
before it was aborted or before it failed.
- "passed" - Boolean flag indicating if given test passed.
- "is_running" - Boolean flag indicating if given test is currently in
progress.
- "self_test_status": Status of given self test. It uses the same
values as disk self test status:
- COMPLETED_WITHOUT_ERROR - self test ended and it have not
detected any issues with the disk
- ABORTED_BY_HOST - self test was aborted
- INTERRUPTED_HOST_RESET
- FATAL_OR_UNKNOWN_ERROR
- COMPLETED_UNKNOWN_FAILURE
- COMPLETED_ELECTRICAL_FAILURE
- COMPLETED_SERVO_SEEK_FAILURE
- COMPLETED_READ_FAILURE
- COMPLETED_HANDLING_DAMAGE
- SELF_TEST_IN_PROGRESS - self test is currently running,
"remaining_percent" indicates how much of the test has left
- "lifetime_hours" - The time at which the test took place, measured in
hours of disk life time.
@param disk_id: ID of the disk from which S.M.A.R.T. self test log will be
obtained.
@type disk_id: str
@return: Http code 200 on success.
N/A
Start S.M.A.R.T. self test on given disk.
By default if not specified, short self test is started on the disk. Test
type can be selected in by providing JSON configuration.
Required JSON keys:
- None.
Optional JSON keys:
- "test_type" - Selects type of the self test that will be executed on
the disk. Following values are allowed:
- "short" - short offline self test
- "long" - long offline self test
- "conveyance" - conveyance offline self test, this value is
supported only by ATA devices
- "selective" - selective self test that is executed only on
particular part of the disk denoted by starting and ending
Logical Block Address. To run this test on given part of the disk
it is required to provide "start_lba" and "end_lba" arguments.
Type: string.
- "start_lba" - Miningfull only for selective self test. It configures
Logical Block Address of the disk where test will start its scan. If
this argument is not specified and "selective" self test is used, value
defaults to 0 - start of the disk. Type: integer or null.
- "end_lba" - Miningfull only for selective self test. It configures
Logical Block Address where test will stop its scan. If this argument
is not specified and "selective" self test is used, value defaults to
end of the disk. Type: integer or null.
Note for selective self test. If this type of test is selected without
providing start and stop LBAs, it will run selective self test for whole
disk which is similar to running long self test for the whole disk.
@param disk_id: ID of the disk on which self test will be started.
@type disk_id: str
@return: Http code 201 on success.
{
"properties": {
"test_type": {
"type": "string"
},
"start_lba": {
"oneOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
},
"end_lba": {
"oneOf": [
{
"type": "integer"
},
{
"type": "null"
}
]
}
}
}
Stop any S.M.A.R.T. self test that is running on given disk.
If no self test is running on the disk at the moment, operation will do
nothing.
@param disk_id: ID of the disk on which self test will be aborted.
@type disk_id: str
@return: Http code 201 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
Fetch data about connected to the server enclosures.
Exampl JSON output::
{
"data": [
{
"model": "H4060-J",
"vendor": "HGST",
"name": "sg9"
},
],
"error": null
}
@return: Http code 200 on success.
N/A
Fetch all sensor readings for specified enclosure.
To read sensors enclosure have to be supported by the software. Supported
enclosures have configuration file that describes available sensors. In
case of not supported enclosure, empty list is returned.
Example JSON output::
{
"data": {
"temp": {
"name": "Temperature",
"sensors": [
{
"individual_index": 0,
"type_header_index": 4,
"name": "TEMP SLOT 00",
"value": 36.0,
"offset": 20
}
]
},
"voltage": {
"name": "Voltage",
"sensors": [
{
"individual_index": 0,
"type_header_index": 8,
"name": "VOLT PSU A AC",
"value": 23475.0
}
]
},
"current": {
"name": "Current",
"sensors": [
{
"individual_index": 0,
"type_header_index": 9,
"name": "CURR PSU A IN",
"value": 46.0
}
]
},
"speed_act": {
"name": "Fan speed",
"sensors": [
{
"individual_index": 0,
"type_header_index": 3,
"name": "FAN ENCL 1",
"value": 415.0
}
]
}
},
error: null
}
@param enclosure_name: SCSI generic name of enclosure in the system. It is
provided in "name" field for listed enclosures in the system.
@type enclosure_name: str
@return: Http code 200 on success.
N/A
Map enclosure bays to disks that are present there.
Example JSON output::
{
"exitcode": 0,
"exception": {
"class": null,
"message": null,
"errno": null,
"traceback": null
},
"data": {
"enclosure": {
"vendor": "SEAGATE",
"model": "SP-3212A-E12EBD",
"serial_number": "SGFGD2006517A0B",
"name": "sg25",
"connections": [
{
"name": "sg25",
"scsi_address": "0:0:25:0"
},
{
"name": "sg51",
"scsi_address": "0:0:51:0"
}
]
},
"bays": [
{
"bay_number": 0,
"bay_status": "OK",
"disk": {
"dev_name": "sdak",
"disk_id": "wwn-0x5000c500d70645db",
"vendor": "SEAGATE",
"model": "ST16000NM002G",
"serial_number": "ZL2H9AWC0000C139AJCP"
}
},
{
"bay_number": 1,
"bay_status": "OK",
"disk": {
"dev_name": "sdal",
"disk_id": "wwn-0x5000c500cb8535bf",
"vendor": "SEAGATE",
"model": "ST16000NM002G",
"serial_number": "ZL2DFDS30000C128M248"
}
},
{
"bay_number": 2,
"bay_status": "OK",
"disk": {
"dev_name": "sdam",
"disk_id": "wwn-0x5000c500cb7cfe0f",
"vendor": "SEAGATE",
"model": "ST16000NM002G",
"serial_number": "ZL2E194T0000C128AEUF"
}
}
]
}
}
@param enclosure_name: SCSI generic name of enclosure in the system. It is
provided in "name" field for listed enclosures in the system.
@type enclosure_name: str
@return: Http code 200 on success.
N/A
Map enclosure bays to disks that are present there for all enclosures.
Example JSON output::
{
"exitcode": 0,
"exception": {
"class": null,
"message": null,
"errno": null,
"traceback": null
},
"data": [
{
"enclosure": {
"vendor": "SEAGATE",
"model": "SP-3212A-E12EBD",
"serial_number": "SGFGD2006517A0B",
"name": "sg25",
"connections": [
{
"name": "sg25",
"scsi_address": "0:0:25:0"
},
{
"name": "sg51",
"scsi_address": "0:0:51:0"
}
]
},
"bays": [
{
"bay_number": 0,
"bay_status": "OK",
"disk": {
"dev_name": "sdak",
"disk_id": "wwn-0x5000c500d70645db",
"vendor": "SEAGATE",
"model": "ST16000NM002G",
"serial_number": "ZL2H9AWC0000C139AJCP"
}
},
{
"bay_number": 1,
"bay_status": "OK",
"disk": {
"dev_name": "sdal",
"disk_id": "wwn-0x5000c500cb8535bf",
"vendor": "SEAGATE",
"model": "ST16000NM002G",
"serial_number": "ZL2DFDS30000C128M248"
}
}
]
}
]
}
@return: Http code 200 on success.
N/A
Get groups list e.g.:
GET:/api/v4/groups
Query params:
- 'page', 'per_page', 'sort_by', 'order', 'search', 'search_by'
Example JSON output::
{
"data": {
"results": 2,
"entries": [
{
"gid": 1000,
"name": "Administrators",
"backend": "LDAP"
},
{
"gid": 1001,
"name": "Users",
"backend": "LDAP"
}
]
},
"error": null
}
@return: Http code 200 on success.
N/A
Creates group in given backend e.g.:
POST:/api/v4/groups
Example JSON input:
{
"name": "newgroup",
"backend_name": "AD"
}
Fields:
- 'name' - group name
- 'backend_name' - authentication backend to use
@return: Http code 200 on success.
{
"properties": {
"name": {
"type": "string"
},
"backend_name": {
"type": "string"
}
},
"required": [
"name",
"backend_name"
],
"additionalProperties": false
}
Get group details e.g.:
GET:/api/v4/groups/
Fields:
- 'group' - group name from path
Example JSON output::
{
"data": {
"gid": 1000,
"name": "Administrators",
"backend": "LDAP"
},
"error": null
}
@return: Http code 200 on success.
N/A
Deletes group from given backend e.g.:
DELETE:/api/v4/groups/
Fields:
- 'group' - group name from path
@return: Http code 204 on success.
N/A
Get users assigned to group e.g.:
GET:/api/v4/groups//users
Fields:
- 'group' - group name from path
Query params:
- 'page', 'per_page', 'sort_by', 'order', 'search', 'search_by', 'where', 'ordering'
Example JSON output::
{
"data": {
"results": 2,
"entries": [
{
"uid": 1000,
"gid": 1000,
"name": "Administrator",
"backend": "LDAP",
"primary": true
},
{
"uid": 1001,
"gid": 1000,
"name": "User",
"backend": "LDAP",
"primary": false
}
]
},
"error": null
}
@return: Http code 200 on success.
N/A
Add users to group e.g.:
POST:/api/v4/groups//users
Example JSON input::
{
"users": ["user1", "user2"],
"backend_name": "LDAP"
}
Fields:
- 'group' - group name from path
- 'users' - list of users to add
- 'backend_name' - authentication backend to use
@return: Http code 200 on success.
{
"properties": {
"users": {
"type": "array"
},
"backend_name": {
"type": "string"
}
},
"required": [
"users",
"backend_name"
],
"additionalProperties": false
}
Remove users from group e.g.:
DELETE:/api/v4/groups//users
Example JSON input::
{
"users": ["user1", "user2"],
"backend_name": "LDAP"
}
Fields:
- 'group' - group name from path
- 'users' - list of users to remove
- 'backend_name' - authentication backend to use
@return: Http code 204 on success.
{
"properties": {
"users": {
"type": "array"
},
"backend_name": {
"type": "string"
}
},
"required": [
"users",
"backend_name"
],
"additionalProperties": false
}
Get HTML output from "inspect" diagnostic tool.
Output is returned as string in JSON field "data". URL argument
"body_only" can be used to control type of the output:
- body_only=0 - Data field contains full HTML. It is the default and is
returned also when URL argument is not provided.
- body_only=1 - Data field contains only body part of HTML with inspect
output.
@return: HTTP code 200 on success.
N/A
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.
Required JSON keys:
- "key" - extension key to apply.
{
"properties": {
"key": {
"type": "string"
}
},
"required": [
"key"
]
}
Validate if given extension key is correct.
Required JSON keys:
- "key" - extension key to validate.
- "pk" - product key used to validate extension key compatibility.
{
"properties": {
"key": {
"type": "string"
},
"pk": {
"type": "string"
}
},
"required": [
"key",
"pk"
]
}
Returns already used product key.
N/A
Apply given product key in product.
Required JSON keys:
- "key" - product key to apply.
{
"properties": {
"key": {
"type": "string"
}
},
"required": [
"key"
]
}
Validate if given product key is correct.
Required JSON keys:
- "key" - product key to validate.
{
"properties": {
"key": {
"type": "string"
}
},
"required": [
"key"
]
}
Returns a list of notifications - informations, warnings and errors.
Query parameters:
- filter: Search for specified string in the notification messages and
return only those messages.
- limit: Limit the results to the latest N messages, where N is a positive
integer.
- start: Skip the first N messages, where N is a positive integer.
- errors: If set to '0' or 'false' error messages won't be returned.
Defaults to '1'.
- warnings: If set to '0' or 'false' warning messages won't be returned.
Defaults to '1'.
- info: If set to '0' or 'false' information messages won't be returned.
Defaults to '1'.
- start_datetime: Only the messages that were reported after the specified date
and time will be returned.
Format of date and time: "YYYY-mm-dd HH:MM:SS".
- end_datetime: Only the messages that were reported before the specified date
and time will be returned.
Format of date and time: "YYYY-mm-dd HH:MM:SS".
@return HTTP code 200 on success.
@return HTTP code 500 in case of malformed filters.
N/A
Delete events
@param group: ID of event group to delete.
@return: Http code 200 on success.
N/A
Mark elements as read
Required JSON keys:
- "is_read" - boolean flag that sets read status for all events in
selected group.
Example JSON input:
{
"is_read": true
}
@param group: ID of event group to mark as read.
@return: Http code 200 on success.
{
"properties": {
"is_read": {
"type": "boolean"
}
},
"required": [
"is_read"
]
}
Delete all events
@return: Http code 200 on success.
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.
Required JSON keys:
- "state" - Requested service state. Allowed values: "start", "stop".
Type: string.
Optional JSON keys:
- None.
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/v4/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/v4/snmp/monitoring/cpu
Required JSON keys:
- "state" - Requested sensor state. Allowed values: "start", "stop".
Type: string.
Optional JSON keys:
- None.
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/v4/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.
Type: string.
Optional JSON keys:
- "path_grouping_policy" - Path grouping policy for multipath. Type:
string.
- "path_selector" - Path selection algorithm used to choose next active
path. Type: string.
- "prio" - Priority algorithm used to rank paths/path groups. Type:
string.
- "failback" - Failback behavior for returning traffic to preferred
paths after recovery. Type: string or integer.
- "rr_min_io_rq" - Number of I/O requests before switching path in
round-robin modes. Type: integer.
- "rr_weight" - Round-robin weighting mode. Type: string.
- "flush_on_last_del" - Controls queue flush behavior when last path is
deleted. Type: string.
- "no_path_retry" - Retry behavior when no path is available. Type:
string or integer.
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_grouping_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.
Required JSON keys:
- None.
Optional JSON keys:
- "path_grouping_policy" - Path grouping policy for multipath. Type:
string or null.
- "path_selector" - Path selection algorithm used to choose next active
path. Type: string or null.
- "prio" - Priority algorithm used to rank paths/path groups. Type:
string or null.
- "failback" - Failback behavior for returning traffic to preferred
paths after recovery. Type: string, integer or null.
- "rr_min_io_rq" - Number of I/O requests before switching path in
round-robin modes. Type: integer or null.
- "rr_weight" - Round-robin weighting mode. Type: string or null.
- "flush_on_last_del" - Controls queue flush behavior when last path is
deleted. Type: string or null.
- "no_path_retry" - Retry behavior when no path is available. Type:
string, integer or null.
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.
Required JSON keys:
- None.
Optional JSON keys:
- "path_grouping_policy" - Default path grouping policy for multipath
devices. Type: string.
- "path_selector" - Default path selection algorithm. Type: string.
- "prio" - Default priority algorithm for paths/path groups. Type:
string.
- "failback" - Default failback behavior after path recovery. Type:
string or integer.
- "rr_min_io_rq" - Default number of I/O requests before switching path
in round-robin modes. Type: integer.
- "rr_weight" - Default round-robin weighting mode. Type: string.
- "flush_on_last_del" - Default queue flush behavior when last path is
deleted. Type: string.
- "no_path_retry" - Default retry behavior when no path is available.
Type: string or integer.
- "path_checker" - Default path checker used to verify path health.
Type: string.
- "checker_timeout" - Default timeout used by path checker. Type:
integer or null. Setting null restores device default.
Refer to multipath documentation for detailed information.
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.
Required JSON keys:
- None.
Optional JSON keys:
- "enabled" - Boolean flag that controls if multipath service is
enabled or dissabled. Type: boolean.
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)",
"sr_iov_active": null,
"sr_iov_model": null
}
],
"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.
- "sr_iov_active" - This is a flag that informs if SR-IOV is active
for given virtual NIC in virtualized environment. When it is active,
flag is set to true, null is used otherwise. This flag is usefull only
for instances of the system that run within virtual machine to indicate
if virtualized NIC has SR-IOV enabled. On real hardware this flag is
always set to null regardless of SR-IOV support on physical NIC.
- "sr_iov_model" - As in case of the sr_iov_active field this one is
meaningfull only for instance of the system running within virtual
machine. It contains model of virtual function (NIC virtual function
used for SR-IOV) that is used when SR-IOV is active on virtual NIC.
Physical NICs and virtual NICs with disabled SR-IOV has this field
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/v4/network/interfaces/bond0"
},
"error": null
}
{
"data": {
"url" : "/api/v4/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.
- "primary_interface" - Name of interface that will be used as primary
interface in bonding, 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" - 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.
Required JSON keys:
- "ip" - IP address of routing to delete.
- "netmask" - Netmask of routing to delete.
{
"properties": {
"ip": {
"type": "string",
"format": "ipv4"
},
"netmask": {
"type": "string",
"format": "ipv4"
}
},
"required": [
"ip",
"netmask"
]
}
Return reserved size for new zvol
Required JSON keys:
- "pool_name" - name of the ZFS pool where zvol will be created.
- "volsize" - requested zvol size in GiB, provided as string.
- "volblocksize" - zvol block size in bytes, provided as string.
Optional JSON keys:
- "copies" - number of zvol copies, provided as string; defaults to 1.
Example JSON input:
{
"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, max value of volsize is 17 179 869 183 GiB
@return: Http code 200 on success.
{
"properties": {
"pool_name": {
"type": "string"
},
"volsize": {
"type": "string"
},
"volblocksize": {
"type": "string"
},
"copies": {
"type": "string"
}
},
"required": [
"pool_name",
"volsize",
"volblocksize"
]
}
Get status of ODP service.
Example JSON output::
{
"data": {
"backend_version": "0.14",
"running": true,
"last_logs": ""
},
"error": null
}
@return: Http code 200 on success.
N/A
Get debug log output for given task.
Required JSON keys:
- "name" - Name of ODP task to diagnose.
Example JSON input::
{
"name": "Pool-0/vol0"
}
@return: Http code 200 on success.
{
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
}
Disable all ODP tasks.
@return: Http code 204 on success.
N/A
Disable selected ODP tasks.
Required JSON keys:
- "odp_tasks" - Array with names of ODP tasks to disable.
Example JSON input::
{
"odp_tasks": [
"Pool-0/volume-00"
"Pool-1/dataset-01"
]
}
@return: Http code 204 on success.
{
"properties": {
"odp_tasks": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"odp_tasks"
]
}
Disable odps task.
Required JSON keys:
- "name" - Name of ODP task to disable.
Example JSON input::
{
"name": "Pool-0/MyDataset"
}
@return: Http code 200 on success.
{
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
}
Enable all ODP tasks.
@return: Http code 204 on success.
N/A
Enable selected ODP tasks.
Required JSON keys:
- "odp_tasks" - Array with names of ODP tasks to enable.
Example JSON input::
{
"odp_tasks": [
"Pool-0/volume-00"
"Pool-1/dataset-01"
]
}
@return: Http code 204 on success.
{
"properties": {
"odp_tasks": {
"type": "array",
"items": {
"type": "string"
}
}
},
"required": [
"odp_tasks"
]
}
Enable odps task.
Required JSON keys:
- "name" - Name of ODP task to enable.
Example JSON input::
{
"name": "Pool-0/MyDataset"
}
@return: Http code 200 on success.
{
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
}
List attached ESX servers.
Example JSON output::
{
"data": [
{
"address": "172.25.100.11",
"user": "admin"
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Attach ESC server.
Required JSON keys:
- "address" - ESX server address or hostname.
- "user" - Username used to authenticate to ESX server.
- "password" - Password used to authenticate to ESX server.
Example JSON input::
{
"address": "172.25.100.11",
"user": "admin",
"password": "admin"
}
@return: Http code 200 on success.
{
"properties": {
"address": {
"type": "string"
},
"user": {
"type": "string"
},
"password": {
"type": "string"
}
},
"required": [
"address",
"user",
"password"
],
"additionalProperties": false
}
Detach given ESX server.
N/A
Get ESX datacenters.
N/A
List ESX virtual machines.
N/A
List NAS volumes that can be used by ODP.
Output data contains information if volume is suitable for backup source
or destination. Data is in the same format as for volumes, the only
difference is that datasets are listed.
@return: Http code 200 on success.
N/A
Modify odp resource.
Optional JSON keys:
- "odp_src_data" - object with ODP source state fields:
- "paused" - boolean flag that pauses (`true`) or resumes
(`false`) backup sending for given resource.
Example JSON input::
{
"odp_src_data": {
"paused": true
}
}
{
"properties": {
"odp_src_data": {
"type": "object",
"properties": {
"paused": {
"type": "boolean"
}
}
}
},
"additionalProperties": false
}
Detach given NAS volume from ODP destination.
After detaching NAS volume from ODP, sending backups to that volume will
no longer be possible from source.
N/A
Set destination flag on nas volume.
N/A
List all attached backup nodes.
Example JSON output::
{
"data": [
{
"address": "192.168.184.28:40000",
"description": "Example backup server."
}
],
"error": null
}
@return: Http code 200 on success.
N/A
Attach new backup node.
Required JSON keys:
- "address" - IP address of backup node.
- "password" - Administrator password of backup node.
Optional JSON keys:
- "description" - Description for given backup node.
Example JSON input::
{
"address": "192.168.184.10",
"password": "admin",
"description": "Example backup server."
}
@return: Http code 200 on success.
{
"properties": {
"address": {
"type": "string"
},
"password": {
"type": "string"
},
"description": {
"type": "string"
}
},
"required": [
"address",
"password"
],
"additionalProperties": false
}
Remove given backup node from attached nodes.
@return: Http code 204 on success.
N/A
List NAS volumes that can be used by ODP.
Output data contains information if volume is suitable for backup source
or destination. Data is in the same format as for volumes, the only
difference is that datasets are listed.
@return: Http code 200 on success.
N/A
List volumes that can be used by ODP.
Output data contains information if volume is suitable for backup source
or destination.
Example JSON output::
"data": {
"entries": [
{
"available": false,
"is_clone": false,
"name": "Pool-0/vol0-bac",
"odp_destination_flag": true,
"odp_src_data": null,
"odp_src_hostname": null,
"odp_src_name": null,
"reason": "destination-flag-enabled"
},
{
"available": true,
"is_clone": false,
"name": "Pool-0/vol1-bac",
"odp_destination_flag": false,
"odp_src_data": null,
"odp_src_hostname": null,
"odp_src_name": null,
"reason": "available-for-source-role"
}
],
"results": 2
},
"error": null
}
@return: Http code 200 on success.
N/A
Disallow given source node to send backups to this machine.
Given source backup node will no longer be able to send backups to machine
where this end-point is executed.
@return: Http code 204 on success.
N/A
List source nodes that are authorized to send backups to this node.
List host names of source backup nodes that can send backup data to node
where this end-point is executed.
Example JSON output::
{
"data": [
"node-71e98245"
],
"error": null
}
@return: Http code 200 on success.
N/A
Restart all ODP tasks.
N/A
Get default settings for ODP tasks.
Default settings are used when given value is not provided during
configuration of the task.
Example JSON output::
{
"data": {
"plan": "1h=>5min,3d=>15min,2w=>1h",
"dst_plan": "12h=>5min,1w=>15min,3w=>1h,3m=>12h"
},
"error": null
}
Fields description:
- "plan" - Default source retention plan in znapzend format:
"=>" entries separated by
commas.
- "dst_plan" - Default destination retention plan in the same format
as "plan".
@return: Http code 200 on success.
N/A
Set default settings for ODP tasks.
Default settings are used when given value is not provided during
configuration of the task.
Optional JSON keys:
- "plan" - Default source retention plan in znapzend format:
- "=>" entries separated by
commas.
- Example: "1h=>5min,3d=>15min,2w=>1h".
- Supported unit aliases:
- second: second, sec, s
- minute: minute, min
- hour: hour, h
- day: day, d
- week: week, w
- month: month, mon, m
- year: year, y
- "dest_plan" - Default destination retention plan in the same format
as "plan" (for example "12h=>5min,1w=>15min,3w=>1h,3m=>12h").
Example JSON input::
{
"plan": "1h=>5min,3d=>15min,2w=>1h",
"dst_plan": "12h=>5min,1w=>15min,3w=>1h,3m=>12h"
}
@return: Http code 200 on success.
{
"properties": {
"plan": {
"type": [
"string",
"null"
]
},
"dest_plan": {
"type": [
"string",
"null"
]
}
},
"additionalProperties": false
}
List all configured ODP tasks.
Example JSON output::
{
"data": {
"entries": [
{
"dedup": "off",
"description": "",
"destinations": [
{
"dataset": "192.168.184.28:40000/Pool-0/ds0-bac",
"plan": "12hours=>5minutes,1week=>15minutes,3weeks=>1hour,3months=>12hours"
}
],
"enabled": "on",
"esx_datastore": null,
"granular_resync": "on",
"mbuffer": "off",
"mbuffer_size": "1000M",
"name": "Pool-0/ds0",
"plan": "1hour=>5minutes,3days=>15minutes,2weeks=>1hour",
"rate_limit": "100M",
"send_unchanged_data": "off",
"tsformat": "autosnap_%Y-%m-%d-%H%M%S",
"type": "filesystem"
},
{
"dedup": "off",
"description": "",
"destinations": [
{
"dataset": "192.168.184.28:40000/Pool-0/vol0-bac",
"plan": "12hours=>5minutes,1week=>15minutes,3weeks=>1hour,3months=>12hours"
}
],
"enabled": "on",
"esx_datastore": null,
"granular_resync": "on",
"mbuffer": "off",
"mbuffer_size": "1000M",
"name": "Pool-0/vol0",
"plan": "1hour=>5minutes,3days=>15minutes,2weeks=>1hour",
"rate_limit": "100M",
"send_unchanged_data": "on",
"tsformat": "autosnap_%Y-%m-%d-%H%M%S",
"type": "volume"
}
],
"results": 2
},
"error": null
}
Fields description:
- "plan" - Source retention plan in znapzend format:
- "=>" entries separated by
commas.
- Example: "1h=>5min,3d=>15min,2w=>1h".
- Meaning: keep snapshots from last 1 hour every 5 minutes, from
last 3 days every 15 minutes, from last 2 weeks every 1 hour.
- Supported unit aliases:
- second: second, sec, s
- minute: minute, min
- hour: hour, h
- day: day, d
- week: week, w
- month: month, mon, m
- year: year, y
- "destinations[].plan" - Retention plan for given destination in the
same format as "plan".
@return: Http code 200 on success.
N/A
Add new ODP task.
Required JSON keys:
- "name" - Source dataset or volume name for the ODP task.
Optional JSON keys:
- "plan" - Source retention plan in znapzend format:
- "=>" entries separated by
commas.
- Example: "1h=>5min,3d=>15min,2w=>1h".
- Supported unit aliases:
- second: second, sec, s
- minute: minute, min
- hour: hour, h
- day: day, d
- week: week, w
- month: month, mon, m
- year: year, y
- "description" - Description of the task.
- "dedup" - Flag enabling deduplication on destination.
- "granular_resync" - Flag enabling granular resynchronization.
- "mbuffer" - Flag enabling mbuffer.
- "mbuffersize" - mbuffer size string (for example "1G").
- "rate_limit" - Replication bandwidth limit.
- "tsformat" - Snapshot name format used by ODP.
- "esx_datastore" - ESX datastore identifier.
- "destinations" - List of destination definitions:
- "dataset" - Destination dataset or remote dataset path.
- "plan" - Optional destination retention plan in the same format
as "plan".
- "send_encrypted" - Flag that enables send compressed data directly,
without decompression. This makes the file transfer faster and uses
less network bandwidth.
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"
}
],
"send_encrypted": false
}
@return: Http code 200 on success.
{
"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"
]
}
},
"send_encrypted": {
"type": "boolean"
}
},
"required": [
"name"
],
"additionalProperties": false
}
Delete specified ODP task.
Required JSON keys:
- "name" - Name of ODP task to delete.
Example JSON input::
{
"name": "Pool-0/MyDataset"
}
{
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
],
"additionalProperties": false
}
Get configuration of specified ODP task.
Example JSON output::
{
"data": {
"name": "Pool-0/vol0",
"type": "volume",
"mbuffer": "off",
"mbuffer_size": "1G",
"plan": "1hour=>5minutes,3days=>15minutes,2weeks=>1hour",
"tsformat": "autosnap_%Y-%m-%d-%H%M%S",
"description": "",
"destinations": [
{
"dataset": "192.168.184.28:40000/Pool-0/vol0-bac",
"plan": "12hours=>5minutes,1week=>15minutes,3weeks=>1hour,3months=>12hours"
}
],
"esx_datastore": null,
"dedup": "off",
"granular_resync": "on",
"rate_limit": "off",
"enabled": "on",
"send_unchanged_data": "off"
},
"error": null
}
Fields description:
- "plan" - Source retention plan in znapzend format:
- "=>" entries separated by
commas.
- Example: "1h=>5min,3d=>15min,2w=>1h".
- "destinations[].plan" - Destination retention plan in the same
format as "plan".
@return: Http code 200 on success.
N/A
Modify existing ODP task.
Optional JSON keys:
- "plan" - Source retention plan in znapzend format:
- "=>" entries separated by
commas.
- Example: "1h=>5min,3d=>15min,2w=>1h".
- Supported unit aliases:
- second: second, sec, s
- minute: minute, min
- hour: hour, h
- day: day, d
- week: week, w
- month: month, mon, m
- year: year, y
- "description" - Description of the task.
- "dedup" - Flag enabling deduplication on destination.
- "granular_resync" - Flag enabling granular resynchronization.
- "mbuffer" - Flag enabling mbuffer.
- "mbuffersize" - mbuffer size string (for example "1G").
- "rate_limit" - Replication bandwidth limit.
- "tsformat" - Snapshot name format used by ODP.
- "esx_datastore" - ESX datastore identifier; empty string removes
current datastore assignment.
- "destinations" - List of destination definitions:
- "dataset" - Destination dataset or remote dataset path.
- "plan" - Optional destination retention plan in the same format
as "plan".
- "send_encrypted" - Flag that enables send compressed data directly,
without decompression. This makes the file transfer faster and uses
less network bandwidth.
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"
}
],
send_encrypted": false
}
@param task_name: ODP task to modify provided as path to resource that
includes pool name (for example PoolName/DatasetName)
@return: Http code 200 on success.
{
"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"
]
}
},
"send_encrypted": {
"type": "boolean"
}
},
"additionalProperties": false
}
Get ESX server datastore for given task.
N/A
List volumes that can be used by ODP.
Output data contains information if volume is suitable for backup source
or destination.
Example JSON output::
"data": {
"entries": [
{
"available": false,
"is_clone": false,
"name": "Pool-0/vol0-bac",
"odp_destination_flag": true,
"odp_src_data": null,
"odp_src_hostname": null,
"odp_src_name": null,
"reason": "destination-flag-enabled"
},
{
"available": true,
"is_clone": false,
"name": "Pool-0/vol1-bac",
"odp_destination_flag": false,
"odp_src_data": null,
"odp_src_hostname": null,
"odp_src_name": null,
"reason": "available-for-source-role"
}
],
"results": 2
},
"error": null
}
@return: Http code 200 on success.
N/A
Modify odp resource.
Optional JSON keys:
- "odp_src_data" - object with ODP source state fields:
- "paused" - boolean flag that pauses (`true`) or resumes
(`false`) backup sending for given resource.
Example JSON input::
{
"odp_src_data": {
"paused": true
}
}
{
"properties": {
"odp_src_data": {
"type": "object",
"properties": {
"paused": {
"type": "boolean"
}
}
}
},
"additionalProperties": false
}
Detach given volume from ODP destination.
After detaching volume from ODP, sending backups to that volume will no
longer be possible from source.
N/A
Set destination flag on volume.
N/A
List all pools in system.
End-point return array containing configurations of all pools in system.
Output fields description:
- "disks" objects (vdev items):
- "disk_dev_name" - Device name of the disk to which vdev item
belongs to. If vdev item is a disk itself this field has the same
value as "name" filed. For partitions this field contains name of
the disk on which partition is created.
- "trim_data" - Object that contains data about trim operation.
Following fields are present in this object:
- "trim_time" - Timestamp of operation described by "status"
field. This field can be set to null if time data is not
applicable to current status - for example when trim has never
been executed on the disk.
- "progress" - Integer with progress percentage of trim
operation. This field may be set to null when value is not
applicable to current trim status.
- "status" - Current status of the trim operation:
- "trim_unsupported" - This device does not support trim
operation.
- "untrimmed" - Trim has never been ran on this disk
since it is member of the pool.
- "active" - Trim is currently running on this disk,
progress field shows percentage of the operation. Field
"trim_time" describes when trim was started.
- "suspended" - Trim has been suspended, "progress" field
indicates how much of the trim operation completed before
it was suspended. Field "trim_time" describes when
trim was started initially.
- "completed" - Trim operation has finished successfully,
field "trim_time" describes when trim finished.
- "is_pool_encryption_password_configured" - Flag that describes if
pool encryption password has been configured for given pool.
Example JSON output:
Pool with one mirror vdev that uses two disks::
{
"data": [
{
"name": "Pool-0",
"status": 24,
"health" : "ONLINE",
"scan": null,
"operation" : "none",
"encryption": {"enabled": False, "format": "passphrase", "method": "aes-256-ccm"},
"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",
"trim_data": {
"status": "active",
"trim_time": "1584019036",
"percent": 76
}
},
{
"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",
"trim_data": {
"status": "active",
"trim_time": "1584019036",
"percent": 76
}
}
],
"vdev_replacings": [],
"vdev_spares": []
}
],
"is_pool_encryption_password_configured": false
}
],
"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.
- "encryption" - Array with objects that describe encryption. Allowed fields:
- "enabled" - boolean
- "format" - string with type of password (e.g. passphrase)
- "password" - string that represents password
- "method" - encryption method
- "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", "special", "special mirror",
"dedup", "dedup mirror", "" (empty string is used to indicate
single type of vdev, one disk)
- "disks" - array with ids of disks that form particular vdev,
array is used even if particular vdev requires only one disk
Optional JSON keys:
- "autoreplace" - Boolean flag that controls automatic replacement of
failed devices in the pool.
- "autotrim" - Boolean flag that controls if auto trim is enabled
- "special_small_blocks" - Configures block size used by special
allocation classes. It can be provided as integer number of bytes or
string with suffix such as "16K".
Example JSON input::
{
"name": "TestPool",
"encryption": False,
"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"
},
"autoreplace": {
"type": "boolean"
},
"autotrim": {
"type": "boolean"
},
"special_small_blocks": {
"type": [
"string",
"number",
"null"
]
},
"encryption": {
"oneOf": [
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"enum": [
true
]
},
"format": {
"type": "string"
},
"password": {
"type": "string"
},
"method": {
"type": "string"
}
},
"required": [
"enabled",
"format",
"password",
"method"
],
"additionalProperties": false
},
{
"type": "object",
"properties": {
"enabled": {
"type": "boolean",
"enum": [
false
]
}
},
"required": [
"enabled"
],
"additionalProperties": false
}
]
},
"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 for a given pool.
Path parameters:
- "pool_name": Name of the pool
Query parameters:
- "page": Page number for paginated response (optional).
- "per_page": Number of entries per page for paginated response (optional).
- "sort_by": Field name used to sort entries (optional).
- "order": Sort direction, "asc" or "desc" (optional, default: "asc").
- "search": Case-insensitive filter value (optional).
- "search_by": Field name used with "search" (optional, default: "name").
- "ordering": Sorting mode, use "natural" for natural sort (optional).
Example JSON output:
{
"data": {
"results": 1,
"entries": [
{
"name": "Dataset-A0",
"full_name": "Pool-A/Dataset-A0",
"origin": null,
"quota": null,
"refquota": null,
"dedup": "off",
"compression": "off",
"sync": "always",
"logbias": "latency",
"primarycache": "all",
"secondarycache": "all",
"atime": "on",
"copies": "1",
"reservation": null,
"refreservation": null,
"recordsize": "131072",
"used": "131072",
"special_small_blocks": "0",
"available": "11656462336",
"usedbysnapshots": "0",
"usedbydataset": "131072",
"usedbychildren": "0",
"logicalused": "55808",
"logicalreferenced": "55808",
"snapshot_count": 0,
"clones": null,
"creation": "1770904774",
"readonly": "off",
"canmount": "on",
"direct": "standard",
"property_source": {
"special_small_blocks": {
"is_local": false,
"inherited_from": null
}
},
"encryption": {
"enabled": false,
"method": null,
"keystatus": null
},
"receive_resume_token": null
}
]
},
"error": null
}
Response fields:
- "data":
- "entries": Single page of entries.
- "encryption": Object describing encryption configuration for dataset.
- "enabled": Flag indicating if encryption is enabled for given dataset.
- "method": Encryption method used for the dataset, set to null
when encryption is disabled.
- "keystatus": Availability of the encryption key, set to null when encryption
is disabled. When encryption is enabled it indicates
if the encryption key is available for the dataset:
- "available" - Encryption key is available, dataset is active.
- "unavailable" - Encryption key is not available, dataset is inactive.
- "results": Total number of entries matching the search criteria.
@return HTTP code 200 on success.
@return HTTP code 500 when pool doesn't exist.
N/A
Create a dataset in a given pool.
Path parameters:
- "pool_name": Name of the pool to which dataset will belong.
Example JSON input:
{
"name": "NewDataset",
"sync": "always",
"special_small_blocks": "16K",
"encryption": {
"enabled": true,
"method": "aes-256-gcm"
}
}
@return: Http code 201 on success.
Required request fields:
- "name": string with name of the dataset to be created
Optional request fields:
- "special_small_blocks":
Configures block size used by special
allocation classes. It can be provided as integer number of bytes or
string with suffix such as "16K".
- "encryption": Optional object with encryption configuration, by
default encryption is disabled. Encryption configuration object has
following fields:
- enabled: Flag that toggles encryption for dataset. Encryption
can be enabled only during creation of the dataset and cannot be
changed.
- method: Encryption method that will be used. If not specified
default one will be used.
- "quota": Hard limit on space used by a dataset, its snapshots and clones.
Choices: (string "null" OR a size string, e.g. "10G")
- "reservation": Space guranteed to a dataset, its snapshots and clones.
Choices: (string "null" OR a size string, e.g. "10G")
- "refreservation": Space guaranteed only to a dataset, not including its snapshots and clones.
Choices: (string "null" OR a size string, e.g. "10G")
- "refquota": Hard limit on space used only by a dataset, not including its snapshots and clones.
Choices: (string "null" OR a size string, e.g. "10G")
- "recordsize": Suggested block size for files.
Choices: (4096, 8192, 16384, 32768, 65536, 131072, 262144, 524288,
1048576, 2097152, 4194304, 8388608, 16777216)
- "copies": Copies of data stored.
` Choices: (1, 2, 3)
- "compression": Compression algorithm.
Choices: ('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": Controls what is stored in ARC.
Choices: ('all', 'none', 'metadata')
- "logbias": Hint for handling synchronous writes.
Choices: ('latency', 'throughput')
- "atime": Controls whether the access time for files is updated when they are read.
Choices: ('on', 'off')
- "dedup": Configures deduplication for a dataset.
Choices: ('on', 'off', 'verify', 'sha256', 'sha256,verify')
- "secondarycache": Controls what is stored in L2ARC.
Choices: ('all', 'none', 'metadata')
- "sync": Controls the behavior of synchronous requests.
Choices: ('standard', 'always', 'disabled')
- "direct": Controls the behavior of Direct I/O requests.
Choices: ('standard', 'disabled', 'always')
@return HTTP code 201 on success.
@return HTTP code 400 when JSON input is invalid
@return HTTP code 500 when pool or dataset doesn't exist.
{
"properties": {
"name": {
"type": "string"
},
"encryption": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"method": {
"type": "string"
}
}
},
"dedup": {
"type": "string",
"enum": [
"on",
"off",
"verify",
"sha256",
"sha256,verify"
]
},
"compression": {
"type": "string",
"enum": [
"on",
"off",
"lzjb",
"gzip",
"gzip-1",
"gzip-2",
"gzip-3",
"gzip-4",
"gzip-5",
"gzip-6",
"gzip-7",
"gzip-8",
"gzip-9",
"zle",
"lz4"
]
},
"sync": {
"type": "string",
"enum": [
"standard",
"always",
"disabled"
]
},
"logbias": {
"type": "string",
"enum": [
"latency",
"throughput"
]
},
"primarycache": {
"type": "string",
"enum": [
"all",
"none",
"metadata"
]
},
"secondarycache": {
"type": "string",
"enum": [
"all",
"none",
"metadata"
]
},
"atime": {
"type": "string",
"enum": [
"on",
"off"
]
},
"copies": {
"type": "number",
"enum": [
1,
2,
3
]
},
"quota": {
"type": [
"string",
"null"
],
"pattern": "^(?P\\d+([.,]\\d+)?(e\\+\\d+)?)\\s*(?P[BKMGT]i?B?)?$"
},
"reservation": {
"type": [
"string",
"null"
],
"pattern": "^(?P\\d+([.,]\\d+)?(e\\+\\d+)?)\\s*(?P[BKMGT]i?B?)?$"
},
"refreservation": {
"type": [
"string",
"null"
],
"pattern": "^(?P\\d+([.,]\\d+)?(e\\+\\d+)?)\\s*(?P[BKMGT]i?B?)?$"
},
"refquota": {
"type": [
"string",
"null"
],
"pattern": "^(?P\\d+([.,]\\d+)?(e\\+\\d+)?)\\s*(?P[BKMGT]i?B?)?$"
},
"recordsize": {
"type": "number",
"enum": [
4096,
8192,
16384,
32768,
65536,
131072,
262144,
524288,
1048576,
2097152,
4194304,
8388608,
16777216
]
},
"special_small_blocks": {
"type": [
"string",
"number",
"null"
]
}
},
"additionalProperties": false,
"required": [
"name"
]
}
Get details for a specific dataset.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset.
Example JSON output:
{
"data": {
"name": "Dataset-0",
"full_name": "Pool-0/Dataset-0",
"origin": null,
"quota": null,
"refquota": null,
"dedup": "off",
"compression": "off",
"sync": "always",
"logbias": "latency",
"primarycache": "all",
"secondarycache": "all",
"atime": "on",
"copies": "1",
"reservation": null,
"refreservation": null,
"recordsize": "131072",
"used": "98304",
"special_small_blocks": "0",
"available": "11656900608",
"usedbysnapshots": "0",
"usedbydataset": "98304",
"usedbychildren": "0",
"logicalused": "43008",
"logicalreferenced": "43008",
"snapshot_count": 0,
"clones": null,
"creation": "1772453971",
"readonly": "off",
"canmount": "on",
"direct": "standard",
"property_source": {
"special_small_blocks": {
"is_local": false,
"inherited_from": null
}
},
"encryption": {
"enabled": false,
"method": null,
"keystatus": null
},
"receive_resume_token": null
},
"error": null
}
Fields description:
- data:
- "encryption": Object describing encryption configuration for dataset
- "enabled": Flag indicating if encryption is enabled for given dataset.
- "method": Encryption method used for the dataset, set to null
when encryption is disabled.
- "keystatus": Availability of the encryption key, set to null when encryption
is disabled. When encryption is enabled it indicates
if the encryption key is available for the dataset:
- "available" - Encryption key is available, dataset is active.
- "unavailable" - Encryption key is not available, dataset is inactive.
@return HTTP code 200 on success.
@return HTTP code 500 when pool doesn't exist.
N/A
Modify properties of a specific dataset.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset.
Example JSON input:
{
"sync": "always",
"inherit": ["special_small_blocks"]
}
@return: Http code 201 on success.
Required request fields:
--
Optional request fields:
- "name": String with the new name for a dataset.
- "special_small_blocks":
Configures block size used by special
allocation classes. It can be provided as integer number of bytes or
string with suffix such as "16K".
- "quota": Hard limit on space used by a dataset, its snapshots and clones.
Choices: (string "null" OR a size string, e.g. "10G")
- "reservation": Space guranteed to a dataset, its snapshots and clones.
Choices: (string "null" OR a size string, e.g. "10G")
- "refreservation": Space guaranteed only to a dataset, not including its snapshots and clones.
Choices: (string "null" OR a size string, e.g. "10G")
- "refquota": Hard limit on space used only by a dataset, not including its snapshots and clones.
Choices: (string "null" OR a size string, e.g. "10G")
- "recordsize": Suggested block size for files.
Choices: (4096, 8192, 16384, 32768, 65536, 131072, 262144, 524288,
1048576, 2097152, 4194304, 8388608, 16777216)
- "copies": Copies of data stored.
` Choices: (1, 2, 3)
- "compression": Compression algorithm.
Choices: ('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": Controls what is stored in ARC.
Choices: ('all', 'none', 'metadata')
- "logbias": Hint for handling synchronous writes.
Choices: ('latency', 'throughput')
- "atime": Controls whether the access time for files is updated when they are read.
Choices: ('on', 'off')
- "dedup": Configures deduplication for a dataset.
Choices: ('on', 'off', 'verify', 'sha256', 'sha256,verify')
- "secondarycache": Controls what is stored in L2ARC.
Choices: ('all', 'none', 'metadata')
- "sync": Controls the behavior of synchronous requests.
Choices: ('standard', 'always', 'disabled')
- "direct": Controls the behavior of Direct I/O requests.
Choices: ('standard', 'disabled', 'always')
- "inherit" - Array with property names for witch values will be
inherited from parent dataset. Inherited value is the same as value in
parent dataset and will change if parent dataset changes its value.
@return HTTP code 201 on success.
@return HTTP code 400 when JSON input is invalid
@return HTTP code 500 when pool or dataset doesn't exist.
{
"properties": {
"name": {
"type": "string"
},
"inherit": {
"type": "array",
"items": {
"type": "string"
}
},
"dedup": {
"type": "string",
"enum": [
"on",
"off",
"verify",
"sha256",
"sha256,verify"
]
},
"compression": {
"type": "string",
"enum": [
"on",
"off",
"lzjb",
"gzip",
"gzip-1",
"gzip-2",
"gzip-3",
"gzip-4",
"gzip-5",
"gzip-6",
"gzip-7",
"gzip-8",
"gzip-9",
"zle",
"lz4"
]
},
"sync": {
"type": "string",
"enum": [
"standard",
"always",
"disabled"
]
},
"logbias": {
"type": "string",
"enum": [
"latency",
"throughput"
]
},
"primarycache": {
"type": "string",
"enum": [
"all",
"none",
"metadata"
]
},
"secondarycache": {
"type": "string",
"enum": [
"all",
"none",
"metadata"
]
},
"atime": {
"type": "string",
"enum": [
"on",
"off"
]
},
"copies": {
"type": "number",
"enum": [
1,
2,
3
]
},
"quota": {
"type": [
"string",
"null"
],
"pattern": "^(?P\\d+([.,]\\d+)?(e\\+\\d+)?)\\s*(?P[BKMGT]i?B?)?$"
},
"reservation": {
"type": [
"string",
"null"
],
"pattern": "^(?P\\d+([.,]\\d+)?(e\\+\\d+)?)\\s*(?P[BKMGT]i?B?)?$"
},
"refreservation": {
"type": [
"string",
"null"
],
"pattern": "^(?P\\d+([.,]\\d+)?(e\\+\\d+)?)\\s*(?P[BKMGT]i?B?)?$"
},
"refquota": {
"type": [
"string",
"null"
],
"pattern": "^(?P\\d+([.,]\\d+)?(e\\+\\d+)?)\\s*(?P[BKMGT]i?B?)?$"
},
"recordsize": {
"type": "number",
"enum": [
4096,
8192,
16384,
32768,
65536,
131072,
262144,
524288,
1048576,
2097152,
4194304,
8388608,
16777216
]
},
"special_small_blocks": {
"type": [
"string",
"number",
"null"
]
}
},
"additionalProperties": false
}
Delete a specific dataset.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset.
Example JSON input:
{
"keep_shares": false,
"check_snapshot_clones": false
}
Required request fields:
--
Optional request fields:
- "keep_shares": Keep existing shares after deleting dataset.
- "check_snapshot_clones": Check for dataset clones and delete them before deleting dataset.
@return HTTP code 204 on success.
@return HTTP code 400 when JSON input is invalid
@return HTTP code 500 when pool or dataset doesn't exist.
{
"properties": {
"keep_shares": {
"type": "boolean"
},
"check_snapshot_clones": {
"type": "boolean"
}
}
}
Lists snapshots of a given dataset.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset.
Example JSON output:
{
"data": {
"results": 1,
"entries": [
{
"parent": {
"name": "Dataset-0",
"type": 1,
"properties": {
"guid": "3703559446787864766"
}
},
"name": "Snapshot-0",
"properties": {
"guid": "2643609450871167356",
"creation": 1772463614
}
}
]
},
"error": null
}
Fields description:
- "data":
- "entries": Single page of entries.
- "name": Snapshot name.
- "properties":
- "guid": Unique, 64-bit identifier of a resource.
- "creation": Snapshot creation timestamp.
- "parent": Parent dataset information.
- "name": Parent dataset name.
- "type": Resource type (1 - filesystem, 4 - volume).
- "properties":
- "guid": Unique, 64-bit identifier of a resource.
- "creation": Creation timestamp.
- "results": Total number of entries matching the filters.
@return HTTP code 200 on success.
@return HTTP code 500 when pool or dataset doesn't exist.
N/A
Create snapshot of a specific dataset.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset.
Example JSON input:
{
"name": "NewSnapshot"
}
Required request fields:
- "name": String with name of the snapshot to be created
@return HTTP code 201 on success.
@return HTTP code 400 when JSON input is invalid
@return HTTP code 500 when pool or dataset doesn't exist.
{
"properties": {
"name": {
"type": "string"
}
},
"required": [
"name"
]
}
Get details for a specific dataset snapshot.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset to which snapshot belongs.
- "snapshot_name": Name of the snapshot.
Example JSON output:
{
"data": {
"name": "Snapshot-0",
"compressratio": "1.00",
"createtxg": "9325",
"creation": "2026-03-02 16:00:14",
"defer_destroy": "off",
"guid": "2643609450871167356",
"logicalreferenced": "43008",
"refcompressratio": "1.00",
"referenced": "98304",
"type": "snapshot",
"used": "0",
"userrefs": "0",
"written": "98304",
"acltype": "posix",
"casesensitivity": "sensitive",
"context": "none",
"defcontext": "none",
"devices": "on",
"encryption": "off",
"exec": "on",
"mlslabel": "none",
"nbmand": "off",
"normalization": "none",
"primarycache": "all",
"rootcontext": "none",
"secondarycache": "all",
"setuid": "on",
"utf8only": "off",
"version": "5",
"xattr": "on",
"objsetid": "161",
"fscontext": "none",
"prefetch": "all"
},
"error": null
}
@return HTTP code 200 on success.
@return HTTP code 500 when pool, dataset, or snapshot doesn't exist.
N/A
Delete a specific dataset snapshot.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset to which snapshot belongs.
- "snapshot_name": Name of the snapshot to be deleted.
Example JSON input:
{
"keep_shares": false
}
Required request fields:
--
Optional request fields:
- "keep_shares": Keep share configurations associated with this snapshots clones.
They will stay deactivated.
@return HTTP code 204 on success.
@return HTTP code 400 when JSON input is invalid.
@return HTTP code 500 when pool, dataset, or snapshot does not exist.
{
"properties": {
"keep_shares": {
"type": "boolean"
}
}
}
Get all clones of a dataset snapshot.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset to which snapshot belongs.
- "snapshot_name": Name of the snapshot for which clones are listed.
Example JSON output:
{
"data": [
{
"name": "Clone-0"
}
],
"error": null
}
@return HTTP code 200 on success.
@return HTTP code 500 when pool, dataset, or snapshot does not exist.
N/A
Creates clone of a dataset from snapshot.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset to which snapshot belongs.
- "snapshot_name": Name of the snapshot to be cloned.
Example JSON input:
{
"name": "MyClone",
"dedup": "sha256,verify"
}
Required request fields:
- "name": String with name of the dataset clone to be created.
Optional request fields:
- "special_small_blocks":
Configures block size used by special
allocation classes. It can be provided as integer number of bytes or
string with suffix such as "16K".
- "quota": Hard limit on space used by a dataset, its snapshots and clones.
Choices: (string "null" OR a size string, e.g. "10G")
- "reservation": Space guranteed to a dataset, its snapshots and clones.
Choices: (string "null" OR a size string, e.g. "10G")
- "refreservation": Space guaranteed only to a dataset, not including its snapshots and clones.
Choices: (string "null" OR a size string, e.g. "10G")
- "refquota": Hard limit on space used only by a dataset, not including its snapshots and clones.
Choices: (string "null" OR a size string, e.g. "10G")
- "recordsize": Suggested block size for files.
Choices: (4096, 8192, 16384, 32768, 65536, 131072, 262144, 524288,
1048576, 2097152, 4194304, 8388608, 16777216)
- "copies": Copies of data stored.
` Choices: (1, 2, 3)
- "compression": Compression algorithm.
Choices: ('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": Controls what is stored in ARC.
Choices: ('all', 'none', 'metadata')
- "logbias": Hint for handling synchronous writes.
Choices: ('latency', 'throughput')
- "atime": Controls whether the access time for files is updated when they are read.
Choices: ('on', 'off')
- "dedup": Configures deduplication for a dataset.
Choices: ('on', 'off', 'verify', 'sha256', 'sha256,verify')
- "secondarycache": Controls what is stored in L2ARC.
Choices: ('all', 'none', 'metadata')
- "sync": Controls the behavior of synchronous requests.
Choices: ('standard', 'always', 'disabled')
- "direct": Controls the behavior of Direct I/O requests.
Choices: ('standard', 'disabled', 'always')
@return HTTP code 200 on success.
@return HTTP code 400 when JSON input is invalid.
@return HTTP code 500 when pool, dataset, or snapshot does not exist.
{
"properties": {
"name": {
"type": "string"
},
"dedup": {
"type": "string",
"enum": [
"on",
"off",
"verify",
"sha256",
"sha256,verify"
]
},
"compression": {
"type": "string",
"enum": [
"on",
"off",
"lzjb",
"gzip",
"gzip-1",
"gzip-2",
"gzip-3",
"gzip-4",
"gzip-5",
"gzip-6",
"gzip-7",
"gzip-8",
"gzip-9",
"zle",
"lz4"
]
},
"sync": {
"type": "string",
"enum": [
"standard",
"always",
"disabled"
]
},
"logbias": {
"type": "string",
"enum": [
"latency",
"throughput"
]
},
"primarycache": {
"type": "string",
"enum": [
"all",
"none",
"metadata"
]
},
"secondarycache": {
"type": "string",
"enum": [
"all",
"none",
"metadata"
]
},
"atime": {
"type": "string",
"enum": [
"on",
"off"
]
},
"copies": {
"type": "number",
"enum": [
1,
2,
3
]
},
"quota": {
"type": [
"string",
"null"
],
"pattern": "^(?P\\d+([.,]\\d+)?(e\\+\\d+)?)\\s*(?P[BKMGT]i?B?)?$"
},
"reservation": {
"type": [
"string",
"null"
],
"pattern": "^(?P\\d+([.,]\\d+)?(e\\+\\d+)?)\\s*(?P[BKMGT]i?B?)?$"
},
"refreservation": {
"type": [
"string",
"null"
],
"pattern": "^(?P\\d+([.,]\\d+)?(e\\+\\d+)?)\\s*(?P[BKMGT]i?B?)?$"
},
"refquota": {
"type": [
"string",
"null"
],
"pattern": "^(?P\\d+([.,]\\d+)?(e\\+\\d+)?)\\s*(?P[BKMGT]i?B?)?$"
},
"recordsize": {
"type": "number",
"enum": [
4096,
8192,
16384,
32768,
65536,
131072,
262144,
524288,
1048576,
2097152,
4194304,
8388608,
16777216
]
},
"special_small_blocks": {
"type": [
"string",
"number",
"null"
]
}
},
"additionalProperties": false,
"required": [
"name"
]
}
Get clone of dataset created from a given snapshot.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset to which snapshot belongs.
- "snapshot_name": Name of the snapshot from which clone was created.
- "clone_name": Name of the clone.
Example JSON output:
{
"data": {
"name": "Clone-0",
"full_name": "Pool-0/Clone-0",
"origin": "Pool-0/Dataset-0@Snapshot-0",
"quota": null,
"refquota": null,
"dedup": "off",
"compression": "off",
"sync": "standard",
"logbias": "latency",
"primarycache": "all",
"secondarycache": "all",
"atime": "on",
"copies": "1",
"reservation": null,
"refreservation": null,
"recordsize": "131072",
"used": "8192",
"special_small_blocks": "0",
"available": "11656712192",
"usedbysnapshots": "0",
"usedbydataset": "8192",
"usedbychildren": "0",
"logicalused": "4096",
"logicalreferenced": "43008",
"snapshot_count": 0,
"clones": null,
"creation": "1772527940",
"readonly": "off",
"canmount": "on",
"direct": "standard",
"property_source": {
"special_small_blocks": {
"is_local": false,
"inherited_from": null
}
},
"encryption": {
"enabled": false,
"method": null,
"keystatus": null
},
"receive_resume_token": null
},
"error": null
}
@return HTTP code 200 on success.
@return HTTP code 404 when clone does not exist.
@return HTTP code 500 when pool, dataset, or snapshot does not exist.
N/A
Delete a specific dataset clone.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset to which snapshot belongs.
- "snapshot_name": Name of the snapshot from which clone was created.
- "clone_name": Name of the clone to be deleted.
Example JSON input:
{
"keep_shares": false
}
Required request fields:
--
Optional request fields:
- "keep_shares": Keep share configurations associated with this clone.
They will stay deactivated.
@return HTTP code 204 on success.
@return HTTP code 400 when JSON input is invalid.
@return HTTP code 404 when clone does not exist.
@return HTTP code 500 when pool, dataset, or snapshot does not exist.
{
"properties": {
"keep_shares": {
"type": "boolean"
}
}
}
Promote clone to a regular dataset.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset to which snapshot belongs.
- "snapshot_name": Name of the snapshot from which clone was created.
- "clone_name": Name of the clone to be promoted.
@return HTTP code 200 on success.
@return HTTP code 500 when pool does not exist.
N/A
Get clone and share counts for a specific snapshot.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset to which snapshot belongs.
- "snapshot_name": Name of the snapshot for which counts are calculated.
Example JSON output:
{
"data": {
"clones": 2,
"shares": 1
},
"error": null
}
Fields description:
- "clones": Number of dataset clones created from this snapshot.
- "shares": Number of shares configured for those dataset clones.
@return HTTP code 200 on success.
@return HTTP code 500 when pool, dataset, or snapshot does not exist.
N/A
Get counts of items that would be removed during rollback.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset to be rolled back.
- "snapshot_name": Target snapshot for rollback.
Example JSON output:
{
"data": {
"snapshots": 3,
"clones": 2,
"shares": 1
},
"error": null
}
Fields description:
- "snapshots": Number of newer snapshots that would be deleted.
- "clones": Number of clones depending on those snapshots.
- "shares": Number of shares assigned to those clones.
@return HTTP code 200 on success.
@return HTTP code 500 when pool, dataset, or snapshot does not exist.
N/A
Roll back a dataset to a specific snapshot.
Path parameters:
- "pool_name": Name of the pool to which dataset belongs.
- "dataset_name": Name of the dataset to roll back.
- "snapshot_name": Name of the snapshot to roll back to.
Example JSON input:
{
"keep_shares": false
}
Required request fields:
--
Optional request fields:
- "keep_shares": Keep share configurations associated with clones
removed by rollback.
@return HTTP code 200 on success.
@return HTTP code 400 when JSON input is invalid.
@return HTTP code 500 when pool, dataset, or snapshot does not exist.
{
"properties": {
"keep_shares": {
"type": "boolean"
}
}
}
List all dataset snapshots for a pool.
Path parameters:
- "pool_name": Name of the pool for which snapshots are listed.
Example JSON output:
{
"data": {
"entries": [
{
"parent": {
"name": "Dataset-0",
"type": 1,
"properties": {
"guid": "3703559446787864766"
}
},
"name": "Snapshot-0",
"properties": {
"guid": "2643609450871167356",
"creation": 1772463614
}
}
],
"results": 1
},
"error": null
}
Fields description:
- "data":
- "entries": Single page of entries.
- "name": Snapshot name.
- "properties":
- "guid": Unique, 64-bit identifier of a resource.
- "creation": Snapshot creation timestamp.
- "parent": Parent dataset information.
- "name": Parent dataset name.
- "type": Resource type (1 - filesystem, 4 - volume).
- "properties":
- "guid": Unique, 64-bit identifier of a resource.
- "results": Total number of entries matching the filters.
@return HTTP code 200 on success.
@return HTTP code 500 when pool does not exist.
N/A
Get NVMe target configuration for given pool.
List configured and active NVMe targets on given pool. Returned data is
a NVMe target configuration object for given pool:
- "nvme_subsystems" - list of configured subsystems, each zvol is
configured on separate subsystem:
- "subsystem_name" - NQN used by the subsystem.
- "subsystem_serial" - Serial number of the subsystem.
- "nvmet_zvols" - List of zvol names used by the subsystem. Every
zvol is configured on separate subsystem and this list has always
one item.
- "vips" - List of assigned Virtual IPs to given NVMe target. Given
target is available only through assigned Virtual IPs that are
active. Each configuration object has following fields:
- "vip_name" - Name of Virtual IP.
- "transmission_type" - Transmission type that will be used
by the port configured for this Virtual IP. Available values
are: tcp, rdma (tcp is default).
- "namespaces" - List of namespaces present on the subsystem. As
one only one zvol is assigned to subsystem this list has one item.
Each namespace item has available following fields:
- "number" - Namespace number, this field is available only if
subsystem is active.
- "uuid" - Namespace UUID.
- "nguid" - Namespace NGUID.
- "block_size" - Block size used by namespace.
- "zvol_name" - Zvol used in the namespace.
Example JSON output::
{
"data": {
"nvmet_subsystems": [
{
"subsystem_name": "nqn.2014-08.org.nvmexpress:subsystem:disk0",
"subsystem_serial": "56976d51abdfc65fea8d",
"active": true,
"nvmet_zvols": [
"nvme-vol0"
],
"vips": [
{
"vip_name": "vip1",
"transmission_type": "tcp"
}
],
"namespaces": [
{
"number": 1,
"uuid": "c3fcaae8-b3e2-fd63-663b-7a6f24471dae",
"nguid": "C3FCAAE8B3E2FD63663B7A6F24471DAE",
"block_size": 512,
"zvol_name": "nvme-vol0"
}
]
},
{
"subsystem_name": "nqn.2014-08.org.nvmexpress:subsystem:disk1",
"subsystem_serial": "94f38985125482a2538d",
"active": true,
"nvmet_zvols": [
"nvme-vol1"
],
"vips": [
{
"vip_name": "vip1",
"transmission_type": "tcp"
}
],
"namespaces": [
{
"number": 1,
"uuid": "x3fcaae8-b3e2-fd63-663b-7a6f24471dae",
"nguid": "X3FCAAE8B3E2FD63663B7A6F24471DAE",
"block_size": 512,
"zvol_name": "nvme-vol1"
}
]
}
]
},
"error": null
}
@param pool_name: Name of the pool for which configured NVMe targets will
be listed.
@type pool_name: str
@return: HTTP code 200 on success.
N/A
Create NVMe target for given volume on pool.
Every volume configured in NVMe target uses separate subsystem with only
one name space. Configured subsystems are available through ports created
on all active virtual IPs from given pool.
Required JSON keys:
- "volume_name" - Name of the volume that will be configured as NVMe
target.
- "vips" - List of assigned to NVMe target virtual IPs. This field
is actually optional but if not specified during configuration of NVMe
target, it will not be available on any port. List consists of Virtual
IP configuration objects with following fields:
- "vip_name" - Name of virtual IP.
- "transmission_type" - Transmission type used by the port
configured for this Virtual IP: tcp or rdma (default is tcp and
this field is optional).
Optional JSON keys:
- "subsystem_name" - Name of the subsystem to create. It is
automatically generated if not provided based on pool and volume name.
The generated name will not be descriptive and it is advised to
manually give appropriate name for the subsystem.
- "subsystem_serial" - Serial number for the subsystem. If not provided
it will be generated based on subsystem name.
Example JSON input::
{
"volume_name": "vol-01",
"subsystem_name": "nvme-disk1"
}
@param pool_name: Name of the pool.
@type pool_name: str
@return: HTTP code 201 on success.
{
"properties": {
"volume_name": {
"type": "string"
},
"subsystem_name": {
"type": "string"
},
"subsystem_serial": {
"type": "string"
},
"vips": {
"type": "array",
"items": {
"properties": {
"vip_name": {
"type": "string"
},
"transmission_type": {
"type": "string"
}
},
"required": [
"vip_name"
]
}
},
"active": {
"type": "boolean"
},
"block_size": {
"type": "integer"
}
},
"required": [
"volume_name"
]
}
Fetch NVMe target configuration for given volume.
Get single NVMe target configuration for selected volume. The output format
is the same as for listing NVMe target configuration for whole pool except
that single item is returned.
@param pool_name: Name of the pool for which configured NVMe target will
be fetched.
@type pool_name: str
@param volume_name: Name of volume for which configured NVMe target will be
fetched.
@type volume_name: str
@return: HTTP code 200 on success.
N/A
Modify configuration of selected NVMe target.
Change configuration of NVMe target. In case of subsystem name and serial
modification, it is required to recreate target configuration on system
level. This will cause that any connected initiator will lose its
connection and it will be required to reconnect the target.
Optional JSON keys:
- "subsystem_name" - Modified name for the subsystem.
- "subsystem_serial" - Modified serial number of the subsystem.
- "active" - Boolean flag that indicates if given subsystem is active.
Inactive subsystem is present only in configuration and is not
configured on the system level
- "vips" - List of assigned Virtual IPs. It overwrites currently set
list of Virtual IPs. List consists of Virtual IP configuration objects
with fields:
- "vip_name" - Name of the Virtual IP.
- "transmission_type" - Transmission type used by the port
configured for this Virtual IP: tcp or rdma.
@param pool_name: Name of the pool where NVMe target is configured.
@type pool_name: str
@param volume_name: Name of volume where NVMe target is configured.
@type volume_name: str
@return: HTTP code 200 on success. Updated configuration of modified
target is returned, it uses the same format as used by fetching single NVMe
target configuration.
{
"properties": {
"subsystem_name": {
"type": "string"
},
"subsystem_serial": {
"type": "string"
},
"vips": {
"type": "array",
"items": {
"properties": {
"vip_name": {
"type": "string"
},
"transmission_type": {
"type": "string"
}
},
"required": [
"vip_name"
]
}
},
"active": {
"type": "boolean"
}
}
}
Delete NVMe subsystem for given volume.
Subsystem will be deleted and given volume will not be available as NVMe
target.
@param pool_name: Name of the pool.
@type pool_name: str
@param volume_name: Name of the volume.
@type volume_name: str
@return: HTTP code 204 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.
{
"properties": {
"alias": {
"type": "string"
},
"fc_targets": {
"type": "array",
"items": {
"type": "string"
}
},
"initiators": {
"type": "array",
"items": {
"type": "string"
}
},
"luns": {
"type": "array",
"items": {
"properties": {
"volume_name": {
"type": "string"
},
"scsi_id": {
"type": "string"
},
"lun": {
"type": "integer"
},
"mode": {
"type": "string"
},
"block_size": {
"type": "integer"
},
"device_handler": {
"type": "string"
},
"thin_provisioned": {
"type": "boolean"
}
},
"required": [
"volume_name"
],
"additionalProperties": false
}
}
},
"additionalProperties": false
}
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"
},
"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.
@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
- "thin_provisioned" - Boolean describing if virtual device will use
thin provisioned setting or not. When not specified this value is set
to the same setting as zfs volume uses. Enable thin provisioning allows
the trim to work thus it might be suitable to use thin provisioned
virtual device even if zvol uses thick provisioning.
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.
Required JSON keys:
- None.
Optional JSON keys:
- "scsi_id" - Unique identifier of virtual device assigned to group.
Type: string.
- "mode" - Access mode used by virtual device. Type: string.
- "block_size" - Block size used by virtual device. Type: integer.
- "lun" - Logical unit number used by assigned volume. Type: integer.
- "device_handler" - Type of access to volume. Type: string.
- "thin_provisioned" - Boolean describing if virtual device will use
thin provisioned setting or not. Type: boolean.
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"
},
"thin_provisioned": {
"type": "boolean"
}
},
"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
}
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.
Required JSON keys:
- None.
Optional JSON keys:
- "wwn" - WWN of target that will be assigned for local node mapping.
Type: string.
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
}
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
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.
Required JSON keys:
- "ip" - IP address of the destination.
- "netmask" - Netmask address of the destination.
{
"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
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
}
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
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
Return pool volumes using pagination format and filtering capabilities.
Returned volumes contain all the fields that are present in end-point for
listing all pool volumes with additional fields describing volume
assignment. Additional fields are:
- "used" - Boolean field that indicates if volumes is in use by any
service
- "assignment" - Field describes service where volume is used:
unassigned, iscsi, fc, nvmet
- "iscsi_target" - Name of iSCSI target if volume is attached there as
a LUN or null.
- "fc_groups" - List of FC group names where volume is added. List is
empty if volume is not used by any FC group.
- "nvmet_subsystem" - Name of nvmet subsystem if volume is available as
NVMe target or null if it is not used by nvmet.
- "is_backup_source" - Boolean field that indicates if volume is used
as a backup source.
- "is_backup_destination" - Boolean field that indicates if volume is
used as backup destination. It describes if this volume is used to save
any backups.
- "backup_source" - Full path to source of the backup.
- "backup_destinations" - List of backup destinations. List is empty
if volume is not backup source or volume is used as local backup only.
Volumes can be filtered using "where" url argument, for example:
?where=assignment==fc. Filtering can be performed for all described above
fields except fc_groups field for which it works slightly differently.
Volume can be assigned to multiptle fc_groups hence fc_grouips field is a
list. It is possible to filter volumes by FC groups using two operators and
two keywords:
- "fc_group==" - return only volumes added to given group, volume may
be added also to other groups
example: where=fc_group==GROUP0
- "fc_groups==" - coma delimited list of groups where volume is added,
it will return only those volumes that are added to given set of groups,
volume have to be present in all described groups and all of them have
to be provided in the query
example: where=fc_groups==GROUP0,GROUP1,GROUP2
- "fc_group!=" - return only volumes that are not added to given group
example: where=fc_group!=Default
- "fc_groups!=" - coma delimited list of groups where volume is not
added, it will return only those volumes that are not added to given
set of groups, volume cannot be present in any described group that are
provided in the query
example: where=fc_groups!=GROUP1,GROUP2
Multiple filter arguments can be supplied by dividing them with semicolon
";" character. Those arguments will act as logical conjuction.
Example: where=fc_group!=GROUP0;assignment!=iscsi;is_clone==false
@param pool_name: Name of the pool.
@type pool_name: str
@return: HTTP code 200 on success.
N/A
Lists all snapshots on a pool.
@param pool_name: Name of the pool to which snapshots belongs to (e.g. ``MyPool``).
Example JSON output:
{
"data": {
"results": 1,
"entries": [
{
"parent": {
"name": "dataset1",
"type": 1,
"properties": {
"guid": "11780918867444959491"
}
},
"name": "autosnap_2025-12-11-094900",
"properties": {
"guid": "5380658664087013896",
"creation": 1765442940
}
}
]
},
"error": null
}
guid - unique, 64-bit identifier of a resource
type - resource type (1 - filesystem, 4 - volume)
creation - snapshot creation timestamp
@return: Http code 200 on success.
N/A
Set pool encryption password for given pool.
When password field is provided, pool encryption password is set for given
pool and will be used for all datasets and zvols created with enabled
encryption option. If password is already configured it will be changed to
the new one. Any dataset or zvol for which key is not available and pool
encryption password is used (set as key), will attempt to load new password
and activate given resource if key loads succesfully.
It is possible to modify other encryption settings through this endpoint
without chnanging the password. Password is modified only if password field
is provided.
Optonal JSON keys:
- "password" - New encryption password.
- "encryption_method" - Default encryption method that will be used by
datasets and zvols with enabled encryption when method is not specified
during creation.
Example JSON input:
{
"password": "new-password"
}
@param pool_name: Name of pool on which encryption password will be changed.
@type pool_name: str
@return: Http code 204 on success.
{
"properties": {
"password": {
"type": "string"
},
"encryption_method": {
"type": "string"
}
}
}
Get configuration of pool encryption.
Fields description:
- "encryption_method" - Default encryption method that will be used
for encryption on dataste or zvol when method is not specified during
encryption configuration.
Example JSON output::
{
"data": {
"encryption_method": "aes-256-ccm"
},
"error": null
}
@return: Http code 200 on success.
N/A
Manage zpool initialize operation.
This endpoint allows to start, cancel or suspend zpool initialize on
selected pool. Optionally it is possible to provide list of devices for
which action will be applied.
Optional JSON keys:
- "action" - Used to control which action will be executed:
- "start" - Start zpool initialization - this is the default and it
is used if the key is not provided in the request.
- "cancel" - Cancel zpool initialization.
- "suspend" - Suspend zpool initialization.
- "devices" - List of pool device IDs for which selected action will be
applied - it is possible to for example initialize only selected disks
within the pool.
@param pool_name: Name of the pool for which zpool initialize will be
executed.
@type pool_name: str
@return: Http code 204 on success.
{
"properties": {
"action": {
"type": "string"
},
"devices": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
Fetch iSCSI target sessions for a target on given pool.
Example JSON output:
{
"data": [
{
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target0",
"cid": "0",
"ip": "192.168.188.9",
"sid": "10300003d0200",
"initiator_name": "JovianDSS"
}
],
"error": null
}
@param pool_name: Name of the pool.
@param target_name: Name of iSCSI target.
@return: Http code 200 on success and list of iSCSI target sessions for
target located on given pool.
N/A
Fetch session data for selected target located on given pool.
Example JSON output::
{
"data": {
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target1",
"cid": "0",
"ip": "192.168.188.9",
"sid": "20400003d0200",
"initiator_name": "JovianDSS"
},
"error": null
}
@param pool_name: Name of the pool.
@param target_name: Name of the iSCSI target.
@param session_id: ID of session to fetch (sid).
@return: Http code 200 on success and session data.
N/A
List all iSCSI target sessions for targets that belong to given pool.
Example JSON output::
{
"data": [
{
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target0",
"cid": "0",
"ip": "192.168.188.9",
"sid": "10300003d0200",
"initiator_name": "JovianDSS"
},
{
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target1",
"cid": "0",
"ip": "15.15.15.8",
"sid": "30500003d0200",
"initiator_name": "JovianDSS"
},
{
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target1",
"cid": "0",
"ip": "192.168.188.9",
"sid": "20400003d0200",
"initiator_name": "JovianDSS"
}
],
"error": null
}
@param pool_name: Name of the pool.
@return: Http code 200 on success and list of iSCSI target sessions for
targets that belong to selected pool.
N/A
Fetch iSCSI target session from given pool.
Example JSON output::
{
"data": {
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target1",
"cid": "0",
"ip": "192.168.188.9",
"sid": "20400003d0200",
"initiator_name": "JovianDSS"
},
"error": null
}
@param pool_name: Name of the pool.
@param session_id: ID of session to fetch (sid).
@return: Http code 200 on success and session data.
N/A
Manage trim operation on the pool.
This endpoint allows to start, stop or suspend trim on given pool.
Optionally it is possible to provide device within pool to which trim will
be applied.
Optional JSON keys:
- "action" - Used to control what action will be executed:
- "start" - (default if key is not provided) - start trim process
- "stop" - stop trim process
- "suspend" - suspend trim process, by starting it on this pool it
will be resumed from the point where it was suspended
- "device" - Request to trim only given device on the pool instead of
running trim on all devices. By default if this key is not provided
trim is executed on all devices in the pool.
@param pool_name: Name of the pool on which trim will be executed.
@type pool_name: str
@return: Http code 201 on success.
{
"properties": {
"action": {
"type": "string"
},
"device": {
"type": "string"
}
}
}
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
Modify pool properties.
Configuration of pool is provided in JSON formatted data.
JSON keys:
- "autoreplace" - Boolean value that controls disk auto replace
property.
- "autotrim" - Boolean value that controls auto trim property.
- "special_small_blocks" - Configures block size used by special
allocation classes. It can be provided as integer number of bytes or
string with suffix such as "16K".
Example JSON input:
{
"autoreplace": true
}
Example JSON output:
End-point doesn't return any data.
@return: Http code 200 on success.
{
"properties": {
"autoreplace": {
"type": "boolean"
},
"autotrim": {
"type": "boolean"
},
"special_small_blocks": {
"type": [
"string",
"number"
]
}
}
}
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. Type: string.
Optional JSON keys:
- None.
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. Type:
string.
Optional JSON keys:
- None.
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"
],
"vip_allowed_portals": {
"enabled": true,
"assigned_vips": ["vip0", "vip1"]
}
},
{
"incoming_users_active": false,
"name": "iqn.2015-05:dss.target1",
"allow_ip": [],
"outgoing_user": null,
"active": false,
"conflicted": false,
"deny_ip": [],
"vip_allowed_portals": {
"enabled": false,
"assigned_vips": []
}
}
],
"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.
- "vip_allowed_portals" - Configuration of iSCSI target access through
virtual IPs.
- "enabled" - Boolean flag that indicates if access to iSCSI target
through virtual IPs is enabled. When it is enabled, iSCSI target is
available only through assigned virtual IPs.
- "assigned_vips" - List of virtual IP names that are assigned to
the target. Only virtual IPs that are configured on the same pool
where iSCSI target is present can be assigned.
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"
],
"vip_allowed_portals": {
"enabled": true,
"assigned_vips": ["vip0", "vip1"]
}
}
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"
]
},
"vip_allowed_portals": {
"properties": {
"enabled": {
"type": "boolean"
},
"assigned_vips": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"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"
],
"vip_allowed_portals": {
"enabled": true,
"assigned_vips": ["vip0", "vip1"]
}
},
"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
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.
- "vip_allowed_portals" - Configuration of iSCSI target access through
virtual IPs.
- "enabled" - Boolean flag that indicates if access to iSCSI target
through virtual IPs is enabled. When it is enabled, iSCSI target is
available only through assigned virtual IPs.
- "assigned_vips" - List of virtual IP names that are assigned to
the target. Only virtual IPs that are configured on the same pool
where iSCSI target is present can be assigned.
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"
],
"vip_allowed_portals": {
"enabled": false,
"assigned_vips": []
}
}
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
},
"vip_allowed_portals": {
"properties": {
"enabled": {
"type": "boolean"
},
"assigned_vips": {
"type": "array",
"items": {
"type": "string"
}
}
}
}
},
"additionalProperties": false
}
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
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:
- None.
Optional 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,
"thin_provisioned": true
},
{
"name": "zvol2",
"block_size": 512,
"mode": "wt",
"scsi_id": "1111111111111111",
"lun": 0,
"thin_provisioned": true
}
],
"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.
- "thin_provisioned" - Boolean describing if virtual device will use
thin provisioned setting or not. When not specified this value is set
to the same setting as zfs volume uses. Enable thin provisioning allows
the trim to work thus it might be suitable to use thin provisioned
virtual device even if zvol uses thick provisioning.
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"
},
"thin_provisioned": {
"type": "boolean"
}
},
"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
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.
- "thin_provisioned" - Boolean describing if virtual device will use
thin provisioned setting or not.
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"
},
"thin_provisioned": {
"type": "boolean"
}
},
"additionalProperties": false
}
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
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.
Required JSON keys:
- "day_of_the_week" - Cron-like day-of-week expression.
- "month_of_the_year" - Cron-like month expression.
- "day_of_the_month" - Cron-like day-of-month expression.
- "hour" - Cron-like hour expression.
- "minute" - Cron-like minute expression.
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
Lists all snapshots on a pool.
@param poolname: Name of the pool to which snapshots belongs to (e.g. ``MyPool``).
Example JSON output:
{
"data": {
"results": 1,
"entries": [
{
"parent": {
"name": "dataset1",
"type": 1,
"properties": {
"guid": "11780918867444959491"
}
},
"name": "autosnap_2025-12-11-094900",
"properties": {
"guid": "5380658664087013896",
"creation": 1765442940
}
}
]
},
"error": null
}
guid - unique, 64-bit identifier of a resource
type - resource type (1 - filesystem, 4 - volume)
creation - snapshot creation timestamp
@return: Http code 200 on success.
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.
@return Http code 200 on success.
N/A
Adds vdev to the pool.
Required JSON keys:
- "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", "special", "special mirror",
"dedup", "dedup mirror", "" (empty string is used to indicate
single type of vdev, one disk)
- "disks" - array with ids of disks that form particular vdev,
array is used even if particular vdev requires only one disk
@return Http code 201 on success.
{
"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"
]
}
Gets all or specified vdevs for a pool.
@return Http code 200 on success.
N/A
Remove given vdev from zpool.
@return Http code 204 on success.
N/A
Get disks from specified pool vdev.
@return Http code 200 on success.
N/A
Get disk from pool vdev.
@return Http code 200 on success.
N/A
Lists all volumes of given pool.
Fields description:
- "encryption" - Object describing encryption configuration for zvol:
- "enabled" - Flag indicating if encryption is enabled for given
zvol.
- "method" - Encryption method that is used for the zvol. It is
set to null when encryption is disabled.
- "keystatus" - Availability of encryption key, it is set to null
when encryption is disabled. When encryption is enabled it indicates
if encryption key is available for the zvol.
- "available" - Encryption key is available, zvol is active
- "unavailable" - Encryption key is not available, zvol is
inactive.
@param poolname: Name of the zpool (e.g. "Pool-0").
@type poolname: str
Example JSON output (success)::
{
"data": {
"entries": [
{
"aclinherit": null,
"acltype": null,
"atime": null,
"available": "7493398528",
"canmount": null,
"casesensitivity": null,
"checksum": "on",
"clones": null,
"compression": "lz4",
"compressratio": "1.00",
"context": "none",
"copies": "1",
"createtxg": "159046",
"creation": "1621581891",
"dedup": "off",
"default_scsi_id": "1fb0d778ec515d83",
"defcontext": "none",
"defer_destroy": null,
"devices": null,
"dnodesize": null,
"encryption": "off",
"encryptionroot": null,
"exec": null,
"filesystem_count": null,
"filesystem_limit": null,
"fscontext": "none",
"full_name": "Pool-0/Volume-0",
"guid": "13633669279800403888",
"is_clone": false,
"keyformat": "none",
"keylocation": "none",
"keystatus": null,
"logbias": "latency",
"logicalreferenced": "28672",
"logicalused": "28672",
"mlslabel": "none",
"mounted": null,
"mountpoint": null,
"name": "z1",
"nbmand": null,
"normalization": null,
"objsetid": "292",
"origin": null,
"overlay": null,
"pbkdf2iters": "0",
"primarycache": "all",
"quota": null,
"readonly": "off",
"receive_resume_token": null,
"recordsize": null,
"redundant_metadata": "all",
"refcompressratio": "1.00",
"referenced": "57344",
"refquota": null,
"refreservation": "0",
"relatime": null,
"reservation": "0",
"rootcontext": "none",
"san:volume_id": "1fb0d778ec515d83bdbbf14a5603ec78b6fdf6bf",
"scontext": null,
"secondarycache": "all",
"setuid": null,
"sharenfs": null,
"sharesmb": null,
"snapdev": "hidden",
"snapdir": null,
"snapshot_count": "18446744073709551615",
"snapshot_limit": "18446744073709551615",
"sync": "always",
"type": "volume",
"used": "57344",
"usedbychildren": "0",
"usedbydataset": "57344",
"usedbyrefreservation": "0",
"usedbysnapshots": "0",
"userrefs": null,
"utf8only": null,
"version": null,
"volblocksize": "65536",
"volmode": "default",
"volsize": "524288000",
"vscan": null,
"written": "57344",
"xattr": null,
"zoned": null,
"encryption": {
"enabled": false,
"method": null,
"keystatus": null
}
},
{
"aclinherit": null,
"acltype": null,
"atime": null,
"available": "7493398528",
"canmount": null,
"casesensitivity": null,
"checksum": "on",
"clones": null,
"compression": "lz4",
"compressratio": "1.00",
"context": "none",
"copies": "1",
"createtxg": "159083",
"creation": "1621581955",
"dedup": "off",
"default_scsi_id": "3fb971ed8f0cbbc3",
"defcontext": "none",
"defer_destroy": null,
"devices": null,
"dnodesize": null,
"encryption": "off",
"encryptionroot": null,
"exec": null,
"filesystem_count": null,
"filesystem_limit": null,
"fscontext": "none",
"full_name": "Pool-0/Volume-1",
"guid": "12059659473553087171",
"is_clone": false,
"keyformat": "none",
"keylocation": "none",
"keystatus": null,
"logbias": "latency",
"logicalreferenced": "28672",
"logicalused": "28672",
"mlslabel": "none",
"mounted": null,
"mountpoint": null,
"name": "z10",
"nbmand": null,
"normalization": null,
"objsetid": "439",
"origin": null,
"overlay": null,
"pbkdf2iters": "0",
"primarycache": "all",
"quota": null,
"readonly": "off",
"receive_resume_token": null,
"recordsize": null,
"redundant_metadata": "all",
"refcompressratio": "1.00",
"referenced": "57344",
"refquota": null,
"refreservation": "0",
"relatime": null,
"reservation": "0",
"rootcontext": "none",
"san:volume_id": "3fb971ed8f0cbbc3e680c17170c7edd1072b8953",
"scontext": null,
"secondarycache": "all",
"setuid": null,
"sharenfs": null,
"sharesmb": null,
"snapdev": "hidden",
"snapdir": null,
"snapshot_count": "18446744073709551615",
"snapshot_limit": "18446744073709551615",
"sync": "always",
"type": "volume",
"used": "57344",
"usedbychildren": "0",
"usedbydataset": "57344",
"usedbyrefreservation": "0",
"usedbysnapshots": "0",
"userrefs": null,
"utf8only": null,
"version": null,
"volblocksize": "65536",
"volmode": "default",
"volsize": "536870912000",
"vscan": null,
"written": "57344",
"xattr": null,
"zoned": null,
"encryption": {
"enabled": false,
"method": null,
"keystatus": null
}
}
],
"results": 2
},
"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)
- "encryption" - Optional object with encryption configuration, by
default encryption is disabled. Encryption configuration object has
following fields:
- "enabled" - Flag that toggles encryption for zvol. Encryption
can be enabled only during creation of the zvol and cannot be
changed.
- "method" - Encryption method that will be used. If not specified
default one will be used.
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"
},
"encryption": {
"type": "object",
"properties": {
"enabled": {
"type": "boolean"
},
"method": {
"type": "string"
}
}
}
},
"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:
End-point support modification of only one value at a time. Only one
of optional JSON keys can be supplied to perform given modification.
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).
- "check_snapshot_clones" - boolean flag that enables clone checks for
snapshots related to the volume before deletion.
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.
- "provisioning" - string describing type of the volume provisioning ('thin', 'thick').
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"
},
"provisioning": {
"type": "string",
"enum": [
"thin",
"thick"
]
},
"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"
}
}
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": {
"results": 1,
"entries": [
{
"parent": {
"name": "volume1",
"type": 4,
"properties": {
"guid": "9881280794906017901"
}
},
"name": "volume1snapshot",
"properties": {
"guid": "1990758647405663064",
"creation": 1767186792
}
}
]
},
"error": null
}
guid - unique, 64-bit identifier of a resource
type - resource type (1 - filesystem, 4 - volume)
creation - snapshot creation timestamp
@return: Http code 200 on success.
N/A
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"
]
}
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
List item to be deleted before rollback is executed.
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 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.
- "recovery_import" - Boolean flag used to perform recovery-oriented
import mode for problematic pools.
- "encryption_password" - Password used to import encrypted pool.
- "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/v4/tasks/0f21fedd-9d1c-4b90-8c5a-14b056135157"
},
"response": {
"href": "/api/v4/tasks/0f21fedd-9d1c-4b90-8c5a-14b056135157/response"
},
"request": {
"href": "/api/v4/tasks/0f21fedd-9d1c-4b90-8c5a-14b056135157/request"
},
"self": {
"href": "/api/v4/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"
},
"encryption_password": {
"type": "string"
}
},
"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
None
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
Gets the list of pools that are not being resilvered.
Required for reboot endpoint.
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.
Optional JSON keys:
- "force" - Boolean flag; when set to true forces emergency 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.
Optional JSON keys:
- "force" - Boolean flag; when set to true forces emergency reboot
instead of graceful shutdown.
{
"properties": {
"force": {
"type": "boolean"
}
}
}
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
Prevent automatic reboot of system.
If system is set to reboot system automatically if system had
ZFS panic 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 information if ZFS panic occured.
Example JSON output::
{
"data" : {
"is_zfs_panic" : false
},
"error" : null
}
Fields description:
- "is_zfs_panic" - Boolean flag that indicates
any system had ZFS panic.
@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.
Required JSON keys:
- None.
Optional JSON keys:
- "host_name" - Set host name of server. Type: string.
- "server_description" - Set server description. Type: string.
- "server_name" - Set server name. Type: string.
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".
HTTP codes:
200 - activation succeeded
400 - In case of offline activation with an activation file - the file was invalid or contained
incorrect information which does not allow for activation.
422 - In case of online activation - there was a problem communicating with the activation
server or the activation server did not permit the activation.
N/A
Downloads a preactivation file based on the specified message type.
This endpoint generates and downloads a pre-activation file, which is necessary for activating
the product or refreshing activation information (including information about support plans)
off-line.
URL arguments:
- message: Specifies the type of operation to perform. It can either be 'activation'
or 'refresh'. The default value is 'activation'. This argument informs the server whether
to generate a file for product activation or to refresh the information about support plans.
HTTP codes:
- 200: The preactivation file was successfully generated.
- 400: BadRequest error if the 'message' URL parameter is not one of the allowed values ('activation' or 'refresh').
The response is an attachment containing the generated preactivation file.
N/A
Download updated activation file from the activation server. Similarly
to the /activate-product endpoint there are two refresh methods: on-line and off-line.
- For on-line refresh send an empty request. Activation file will be downloaded and the product
will be activated.
- For off-line refresh send an activation file. File should be sent in form data,
content-type header have to be set to "multipart/form-data" and file must be stored
in a field called "activation_file". If the file is valid the product will be activated.
HTTP codes:
200 - activation succeeded
400 - In case of offline activation with an activation file - the file was invalid or contained
incorrect information which does not allow for activation.
422 - In case of online activation - there was a problem communicating with the activation
server or the activation server did not permit the refresh.
N/A
Get text of license agreement.
Example JSON output::
{
"data": "License text content",
"error": null
}
@return: Http code 200 on success
N/A
Get status of license agreement.
Example JSON output::
{
"data": {
"license_accepted": true
},
"error": null
}
@return: Http code 200 on success.
N/A
Accept license agreement.
Required JSON keys:
- "accepted" - Controls license agreement state. Set to true to accept
and false to decline. Type: boolean.
Optional JSON keys:
- None.
@return: Http code 204 on success.
{
"properties": {
"accepted": {
"type": "boolean"
}
},
"required": [
"accepted"
],
"additionalProperties": false
}
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
Gets the list of support plans that were retrieved during the latests synchronization
with the activation server.
Example JSON output:
{
"data" : {
"entries": [
{
"plan_id": "1234"
"name": "example.name",
"start": 1710160642,
"end": 1773232642,
"active": true,
"provider": "example.provider",
"email": "example@example.com",
"phone": "123 345 678",
"www": "example.website.com"
}
],
"results": 1
},
"error" : null
}
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
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
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
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
}
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 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
List iSCSI target sessions for given target.
Fields returned for each session can be configured using url arguments
which are described in L{_iscsi_sessions_view_configuration}.
Example JSON output::
{
"data": [
{
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target0",
"cid": "0",
"ip": "192.168.188.9",
"sid": "10300003d0200",
"initiator_name": "JovianDSS"
}
],
"error": null
}
@param target_name: Name of iSCSI target.
@return: Http code 200 on success and list of iSCSI tartet sessions for
given target.
N/A
Fetch selected session data that belongs to the target.
Example JSON output::
{
"data": {
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target0",
"cid": "0",
"ip": "192.168.188.9",
"sid": "10300003d0200",
"initiator_name": "JovianDSS"
},
"error": null
}
@param target_name: Name of iSCSI target
@param session_id: ID of session to fetch (sid)
@return: Http code 200 on success and session data.
N/A
List all iSCSI target sessions.
Fields returned for each session can be configured using url arguments
which are described in L{_iscsi_sessions_view_configuration}.
Example JSON output::
{
"data": [
{
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target1",
"cid": "0",
"ip": "15.15.15.8",
"sid": "30500003d0200",
"initiator_name": "JovianDSS"
},
{
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target1",
"cid": "0",
"ip": "192.168.188.9",
"sid": "20400003d0200",
"initiator_name": "JovianDSS"
},
{
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target0",
"cid": "0",
"ip": "192.168.188.9",
"sid": "10300003d0200",
"initiator_name": "JovianDSS"
}
],
"error": null
}
@return: Http code 200 on success and list with iSCSI targets sessions.
N/A
Fetch session data of the session with given ID.
Example JSON output::
{
"data": {
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target0",
"cid": "0",
"ip": "192.168.188.9",
"sid": "10300003d0200",
"initiator_name": "JovianDSS"
},
"error": null
}
@param session_id: ID of session to fetch (sid)
@return: Http code 200 on success and session data.
N/A
List all iSCSI target sessions grouped by initiator name.
Fields returned for each session can be configured using url arguments
which are described in L{_iscsi_sessions_view_configuration}.
Example JSON output::
{
"data": {
"JovianDSS": [
{
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target1",
"cid": "0",
"ip": "15.15.15.8",
"sid": "30500003d0200"
},
{
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target1",
"cid": "0",
"ip": "192.168.188.9",
"sid": "20400003d0200"
},
{
"target_name": "iqn.2022-04.iscsi:node-f05b1068.target0",
"cid": "0",
"ip": "192.168.188.9",
"sid": "10300003d0200"
}
]
},
"error": null
}
@return: Http code 200 on success and list with iSCSI targets sessions
grouped by initiator name
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"
]
}
Fetch internal SED cache with disks and unlock times.
This cache is read only and for internal use.
N/A
Get configuration of the selected service, e.g.:
GET:/api/v4/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/v4/services/service_name
Example JSON input::
{
"data": {
"enabled": true
},
"error": null
}
@return Http code 204 on success.
N/A
Get configuration of the admember (Active Directory Member) service e.g.:
GET:/api/v4/services/admember
Example JSON output:
{
"enabled": true,
"user": "Administrator",
"realm": "DOMAIN.LOCAL",
"computer_ou": "Computers",
"idmap_profile": "tdb+rid",
"default_idmap": "tdb",
"idmap_settings": {
"autorid": {
"min_id": 1000000,
"max_id": 19999999,
"rangesize": 1000000
},
"tdb": {
"min_id": 1000000,
"max_id": 19000000
}
},
"trust_policy": true,
"trusted": [
{
"domain": "EXAMPLE.1"
},
{
"domain": "EXAMPLE.2"
}
],
"status": true,
"connected": true,
"database": {
"status": "ok",
"last_updated": 1470119640
},
"last_password_change": 1595254144
}
@return Http code 200 on success.
N/A
Sets configuration of the admember (Active Directory Member) service e.g.:
PUT:/api/v4/services/admember
Example JSON input:
{
"enabled": true,
"user": "MyUser",
"password": "SecretPass",
"realm": "realm.lan",
"computer_ou": "Computers",
"idmap_profile": "autorid",
"default_idmap": "autorid",
"idmap_settings": {
"autorid": {
"min_id": 1800000,
"max_id": 29999999,
"rangesize": 5000
},
"tdb": {
"min_id": 23000000,
"max_id": 30000000
}
},
"trust_policy": true,
"scan_trusted_domains": true
}
Example JSON input (toggle only):
{
"enabled": false
}
@return Http code 204 on success.
@raise 400 when request body does not match schema.
@raise 422 when Active Directory/authentication validation fails.
{
"oneOf": [
{
"properties": {
"enabled": {
"type": "boolean"
},
"realm": {
"type": "string"
},
"user": {
"type": "string"
},
"password": {
"type": "string"
},
"computer_ou": {
"type": "string"
},
"trust_policy": {
"type": "boolean"
},
"idmap_profile": {
"type": "string",
"enum": [
"autorid",
"tdb+rid",
"tdb+ad"
]
},
"default_idmap": {
"type": "string",
"enum": [
"autorid",
"tdb"
]
},
"idmap_settings": {
"properties": {
"autorid": {
"type": "object",
"properties": {
"min_id": {
"type": "integer"
},
"max_id": {
"type": "integer"
},
"rangesize": {
"type": "integer"
}
},
"required": [
"min_id",
"max_id",
"rangesize"
],
"additionalProperties": false
},
"tdb": {
"type": "object",
"properties": {
"min_id": {
"type": "integer"
},
"max_id": {
"type": "integer"
}
},
"required": [
"min_id",
"max_id"
],
"additionalProperties": false
}
},
"additionalProperties": false
},
"scan_trusted_domains": {
"type": "boolean"
}
},
"required": [
"enabled",
"realm",
"user",
"password",
"computer_ou",
"trust_policy",
"idmap_profile",
"scan_trusted_domains"
],
"additionalProperties": false
},
{
"properties": {
"enabled": {
"type": "boolean"
}
},
"required": [
"enabled"
],
"additionalProperties": false
}
]
}
Update configuration of the admember (Active Directory Member) service e.g.:
PATCH:/api/v4/services/admember
Example JSON input:
{
"password": "SecretPassword"
}
@return Http code 204 on success.
@raise 400 when request body does not match schema.
@raise 422 when password validation fails.
{
"properties": {
"password": {
"type": "string"
}
},
"additionalProperties": false
}
Checks if ID ranges for domains using the autorid backend are consistent within the cluster.
GET:/api/v4/services/admember/autorid-consistent-in-cluster
Example JSON output:
{
"data": {
"consistent": true
},
"error": null
}
@return Http code 200
N/A
Gets the configuration for already configured trusted domains, together with
default configuration for domains that haven't been configured, but are listed
by the primary domain as trusted.
GET:/api/v4/services/admember/trusted/all
Example JSON output:
[
{
"active": true,
"domain": "DOMAIN1.LAN",
"enabled": false,
"id_mapping": "autorid",
"idmap_settings": {
"autorid": {
"min_id": 1000000,
"max_id": 19999999,
"rangesize": 1000000
},
"ad": {
"scheme": "rfc2307",
"min_id": 1000,
"primary_group": true,
"max_id": 10000
},
"rid": {
"min_id": 20000,
"max_id": 40000
}
}
},
{
"active": true,
"domain": "DOMAIN2.LAN",
"enabled": false,
"id_mapping": "autorid",
"idmap_settings": {
"autorid": {
"min_id": 1000000,
"max_id": 19999999,
"rangesize": 1000000
},
"ad": {
"scheme": "sfu20",
"min_id": 20000,
"primary_group": true,
"max_id": 40000
},
"rid": {
"min_id": 20000,
"max_id": 40000
}
}
}
]
@return Http code 200 on success.
N/A
Gets all of the assigned trusted domains
along with their online status.
GET:/api/v4/services/admember/trusted/assigned
Example JSON output:
[
{
"domain": "DOMAIN.LAN",
"active": true,
"enabled": true,
"id_mapping": "default",
"idmap_settings":
{
"autorid": {
"min_id": 1000000,
"max_id": 19999999,
"rangesize": 1000000
},
"ad": {
"scheme": "sfu20",
"primary_group": false,
"min_id": 200000,
"max_id": 299999
},
"rid": {
"min_id": 200000,
"max_id": 299999
}
}
},
{
"domain": "DOMAIN2.LAN",
"active": false,
"enabled": false,
"id_mapping": "ad",
"idmap_settings":
{
"autorid": {
"min_id": 1000000,
"max_id": 19999999,
"rangesize": 1000000
},
"ad": {
"scheme": "rfc2307",
"primary_group": true,
"min_id": 100000,
"max_id": 199999
},
"rid": {
"min_id": 100000,
"max_id": 199999
}
}
}
]
@return Http code 200 on success.
N/A
Adds configuration for multiple trusted domains.
POST:/api/v4/services/admember/trusted/assigned
Example JSON input:
[
{
"domain": "DOMAIN.LAN",
"enabled": true,
"id_mapping": "default"
},
{
"domain": "DOMAIN2.LAN",
"enabled": false,
"id_mapping": "ad",
"idmap_settings": {
"ad": {
"scheme": "rfc2307",
"primary_group": true,
"min_id": 100000,
"max_id": 199999
},
"rid": {
"min_id": 20000,
"max_id": 40000
}
}
}
]
@return Http code 201 on success.
@raise 400 when request body or trusted domain data is invalid.
@raise 422 when trusted domains validation fails.
@raise 409 when a trusted domain already exists.
{
"type": "array",
"items": {
"properties": {
"domain": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"id_mapping": {
"type": "string",
"enum": [
"default",
"ad",
"rid"
]
},
"idmap_settings": {
"properties": {
"ad": {
"properties": {
"scheme": {
"type": "string",
"enum": [
"rfc2307",
"sfu",
"sfu20"
]
},
"primary_group": {
"type": "boolean"
},
"min_id": {
"type": "integer"
},
"max_id": {
"type": "integer"
}
},
"required": [
"scheme",
"primary_group",
"min_id",
"max_id"
],
"additionalProperties": false
},
"rid": {
"properties": {
"min_id": {
"type": "integer"
},
"max_id": {
"type": "integer"
}
},
"required": [
"min_id",
"max_id"
],
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"required": [
"domain",
"enabled",
"id_mapping"
],
"additionalProperties": false
}
}
Replaces the list of assigned trusted domains with new configuration.
PUT:/api/v4/services/admember/trusted/assigned
Example JSON input:
[
{
"domain": "DOMAIN.LAN",
"enabled": true,
"id_mapping": "default"
},
{
"domain": "DOMAIN2.LAN",
"enabled": false,
"id_mapping": "ad",
"idmap_settings": {
"ad": {
"scheme": "rfc2307",
"primary_group": true,
"min_id": 100000,
"max_id": 199999
},
"rid": {
"min_id": 20000,
"max_id": 40000
}
}
}
]
@return Http code 204 on success.
@raise 400 when request body or trusted domain data is invalid.
@raise 409 when the request contains duplicate domains.
{
"type": "array",
"items": {
"properties": {
"domain": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"id_mapping": {
"type": "string",
"enum": [
"default",
"ad",
"rid"
]
},
"idmap_settings": {
"properties": {
"ad": {
"properties": {
"scheme": {
"type": "string",
"enum": [
"rfc2307",
"sfu",
"sfu20"
]
},
"primary_group": {
"type": "boolean"
},
"min_id": {
"type": "integer"
},
"max_id": {
"type": "integer"
}
},
"required": [
"scheme",
"primary_group",
"min_id",
"max_id"
],
"additionalProperties": false
},
"rid": {
"properties": {
"min_id": {
"type": "integer"
},
"max_id": {
"type": "integer"
}
},
"required": [
"min_id",
"max_id"
],
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"required": [
"domain",
"enabled",
"id_mapping"
],
"additionalProperties": false
}
}
Removes multiple AD Domains from the list of assigned trusted domains.
DELETE:/api/v4/services/admember/trusted/assigned
Example JSON input:
[
"DOMAIN1.LAN",
"DOMAIN2.LAN"
]
@return Http code 204 on success.
@raise 400 when request body is invalid.
@raise 422 when trusted domains validation fails.
@raise 404 when one of the domains is not assigned.
{
"type": "array",
"items": {
"type": "string"
}
}
Gets the domains listed by the primary domain as trusted with default configuration
and online status.
GET:/api/v4/services/admember/trusted/unassigned
Example JSON output:
[
{
"active": true,
"domain": "DOMAIN1.LAN",
"enabled": false,
"id_mapping": "autorid",
"idmap_settings": {
"autorid": {
"min_id": 1000000,
"max_id": 19999999,
"rangesize": 1000000
},
"ad": {
"scheme": "rfc2307",
"min_id": 1000,
"primary_group": true,
"max_id": 10000
},
"rid": {
"min_id": 20000,
"max_id": 40000
}
}
},
{
"active": true,
"domain": "DOMAIN2.LAN",
"enabled": false,
"id_mapping": "autorid",
"idmap_settings": {
"autorid": {
"min_id": 1000000,
"max_id": 19999999,
"rangesize": 1000000
},
"ad": {
"scheme": "sfu20",
"min_id": 20000,
"primary_group": true,
"max_id": 40000
},
"rid": {
"min_id": 20000,
"max_id": 40000
}
}
}
]
@return Http code 200 on success.
N/A
Validates configuration for a list of trusted domains. Does not commit the configuration
even in the case it is correct.
PUT:/api/v4/services/admember/trusted/validate
Example JSON input:
[
{
"domain": "DOMAIN1.LAN",
"enabled": false,
"id_mapping": "autorid"
},
{
"domain": "DOMAIN2.LAN",
"enabled": true,
"id_mapping": "ad",
"idmap_settings": {
"ad": {
"scheme": "sfu20",
"primary_group": true,
"min_id": 20000,
"max_id": 40000
},
"rid": {
"min_id": 20000,
"max_id": 40000
}
}
}
]
@return Http code 204 on success.
@raise 400 when request body or trusted domain data is invalid.
@raise 422 when trusted domains validation fails.
@raise 409 when the request contains duplicate domains.
{
"type": "array",
"items": {
"properties": {
"domain": {
"type": "string"
},
"enabled": {
"type": "boolean"
},
"id_mapping": {
"type": "string",
"enum": [
"default",
"ad",
"rid"
]
},
"idmap_settings": {
"properties": {
"ad": {
"properties": {
"scheme": {
"type": "string",
"enum": [
"rfc2307",
"sfu",
"sfu20"
]
},
"primary_group": {
"type": "boolean"
},
"min_id": {
"type": "integer"
},
"max_id": {
"type": "integer"
}
},
"required": [
"scheme",
"primary_group",
"min_id",
"max_id"
],
"additionalProperties": false
},
"rid": {
"properties": {
"min_id": {
"type": "integer"
},
"max_id": {
"type": "integer"
}
},
"required": [
"min_id",
"max_id"
],
"additionalProperties": false
}
},
"additionalProperties": false
}
},
"required": [
"domain",
"enabled",
"id_mapping"
],
"additionalProperties": false
}
}
Update users/groups database.
POST:/api/v4/services/admember/update
Example JSON input:
{
"clear_share_assignments": false
}
Example JSON output:
{
"data": null,
"error": null
}
@return Http code 200 on success.
@raise 400 when request body does not match schema.
{
"properties": {
"clear_share_assignments": {
"type": "boolean"
}
}
}
Get configuration of the cli service e.g.:
GET:/api/v4/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
Sets configuration of the cli service e.g.:
PUT:/api/v4/services/cli
Optional JSON keys:
- "enabled" - Boolean flag that starts or stops CLI service.
- "password" - CLI password configuration value.
- "allow_ip" - Array with IP addresses allowed to connect to CLI.
- "port" - TCP port used by CLI service.
Note:
- "password", "allow_ip", and "port" are applied together only when
all three keys are present in request JSON.
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
}
Generate SSH Key.
POST:/api/v4/services/cli/sshkey
N/A
Get settings of the LDAP service e.g.:
GET:/api/v4/services/ldap
Example JSON output:
{
"status": true,
"enabled": true,
"domain_type": "internal",
"internal": {
"domain": "LocalDomain",
"default_gid": 513
},
"external": {
"profile": "standard",
"anonymous_access": false,
"admin_dn": "admin",
"connection": {
"192.168.123.123": "connected"
},
"database": {
"status": "updating",
"last_updated": 123456789
},
"encryption_type": "plain",
"users_dn": "users",
"servers": ["127.0.0.1", "127.0.0.2"],
"base_dn": "dc=external",
"groups_dn": "groups",
"computers_dn": "groups",
"port": 401
}
}
@return Http code 200 on success.
N/A
Sets settings of the LDAP service e.g.:
PUT:/api/v4/services/ldap
Example JSON input:
{
"enabled": true,
"domain_type": "internal",
"domain": "LocalDomain",
"password": "123456"
}
@return Http code 200 on success.
@raise Http code 400 on JSON schema validation errors.
@raise Http code 403 when operation is forbidden.
@raise Http code 422 on LDAP service/runtime errors.
{
"oneOf": [
{
"properties": {
"enabled": {
"type": "boolean"
},
"domain_type": {
"type": "string",
"pattern": "^internal$"
},
"domain": {
"type": "string"
},
"password": {
"type": "string"
}
},
"additionalProperties": false
}
]
}
Get configuration of the LDAP database e.g.:
GET:/api/v4/services/ldap/database
Example JSON output:
{
"csn": "XYZ",
"initialized": true,
"id": "db-id"
}
@return Http code 200 on success.
N/A
Set internal LDAP factory default configuration.
@return Http code 200 on success.
N/A
Get configuration of the NFS service e.g.:
GET:/api/v4/services/nfs
Example JSON output:
{
"data": {
"thread_count": 256,
"versions": ["2", "3"],
"enabled": true,
"status": true
},
"error": null
}
@return Http code 200 on success.
N/A
Sets configuration of the NFS service e.g.:
PUT:/api/v4/services/nfs
Optional JSON input fields:
- "enabled" - boolean
- "thread_count" - integer (supported values: 8, 16, 32, 64, 96, 128, 256)
- "versions" - array of strings, supported values: "2", "3"
Example JSON input:
{
"enabled": true,
"thread_count": 64,
"versions": ["2", "3"]
}
@return Http code 204 on success.
@return Http code 400 on invalid JSON schema or invalid NFS configuration values.
@return Http code 500 on internal service start/stop/restart failure.
{
"properties": {
"enabled": {
"type": "boolean"
},
"thread_count": {
"type": "integer"
}
},
"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
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 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
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
}
Deletes redfish service from given alias.
@return: Http code 204 on success.
N/A
Get remote logging configuration.
Example JSON output:
{
"data": {
"enabled": false,
"ip_address": "",
"port": 514,
"protocol": ""
},
"error": null
}
@return: Http code 200 on success.
N/A
Set remote logging configuration.
Optional JSON keys:
- "enabled" - Boolean flag that enables or disables remote logging.
- "ip_address" - IPv4 address of remote syslog server.
- "port" - Port number used to send remote logs.
- "protocol" - Transport protocol used for remote logging:
- "tcp"
- "udp"
@return: Http code 200 on success.
{
"properties": {
"enabled": {
"type": "boolean"
},
"ip_address": {
"type": "string",
"format": "ipv4"
},
"port": {
"type": "number"
},
"protocol": {
"type": "string",
"enum": [
"tcp",
"udp"
]
}
}
}
Get settings of the Remote Console Access service:
GET:/api/v4/services/remote_console
Example JSON output:
{
"data": {
"port": 22222,
"allowed_access_ip": [],
"enabled": false,
"status": null
},
"error": null
}
@return Http code 200 on success.
N/A
Sets settings of the Remote Consola Access service:
PUT:/api/v4/services/remote_console
Optional JSON keys:
- "enabled" - Boolean flag that starts or stops
Remote Console Access service.
- "port" - TCP port used by Remote Console Access service.
- "passwd" - Password used to access remote console.
- "allowed_access_ip" - Array with IP addresses allowed to connect.
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.
{
"properties": {
"enabled": {
"type": "boolean"
},
"port": {
"type": "integer"
},
"passwd": {
"type": "string"
},
"allowed_access_ip": {
"type": "array"
}
},
"additionalProperties": false
}
Get settings of the REST service e.g.:
GET:/api/v4/services/rest
Example JSON output:
{
"enabled": true,
"status": true,
"port": 82,
"user": "admin",
"allowed_methods": ["GET", "POST"]
}
@return Http code 200 on success.
N/A
Sets settings of the REST service e.g.:
PUT:/api/v4/services/rest
Example JSON input:
{
"enabled": true,
"port": 82,
"user": "admin",
"passwd": "admin",
"allowed_methods": ["GET", "HEAD", "OPTIONS", "TRACE"]
}
Allowed value for all methods: "allowed_methods": ["*"]
Allowed fields: enabled, port, user, passwd, allowed_methods
Additional properties are rejected.
@return Http code 204 on success.
@return Http code 400 on invalid JSON schema or invalid configuration values.
{
"properties": {
"enabled": {
"type": "boolean"
},
"port": {
"type": "integer"
},
"user": {
"type": "string"
},
"passwd": {
"type": "string"
},
"allowed_methods": {
"type": "array",
"items": {
"type": "string"
}
}
},
"additionalProperties": false
}
Get configuration of the RSYNC service e.g.:
GET:/api/v4/services/rsync
Example JSON input:
{
"enabled": true,
"user": "admin"
}
@return Http code 200 on success.
N/A
Sets configuration of the RSYNC service e.g.:
PUT:/api/v4/services/rsync
Optional JSON keys:
- "enabled" - Boolean flag that starts or stops RSYNC service.
- "user" - Username used by RSYNC service.
- "password" - Password used by RSYNC service.
Note:
- If either "user" or "password" is provided, both values are written;
missing one is treated as empty string.
Example JSON input:
{
"enabled": true,
"user": "admin",
"password": "password"
}
@return Http code 204 on success.
{
"properties": {
"enabled": {
"type": "boolean"
},
"user": {
"type": "string"
},
"password": {
"type": "string"
}
},
"additionalProperties": false
}
Get configuration of the SMB service e.g.:
GET:/api/v4/services/smb
Example JSON output:
{
"data": {
"smb2_leases": true,
"admin_users": [],
"workgroup": "WORKGROUP",
"enabled": true,
"status": 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,
"dos_attributes": false
},
"error": null
}
@return Http code 200 on success.
N/A
Sets configuration of the SMB service e.g.:
PUT:/api/v4/services/smb
Optional JSON input fields:
- "enabled" - enables/disables SMB service (register/start or unregister/stop)
- "wins_server" - WINS server address used for NetBIOS name resolution
- "workgroup" - SMB workgroup name; also updates default workgroup
- "hide_special_folders" - hides special SMB shares/folders
- "unix_extensions" - enables UNIX SMB extensions
- "dos_attributes" - enables DOS attributes support
- "admin_users" - list of SMB administrator usernames
- "sid" - SMB domain/server SID
- "oplocks" - enables/disables opportunistic locking
- "kernel_oplocks" - enables/disables kernel oplocks support
- "level2_oplocks" - enables/disables level2 oplocks
- "smb2_leases" - enables/disables SMB2 leases
- "fruit" - enables/disables Apple SMB extensions (vfs_fruit)
Example JSON input:
{
"enabled": true,
"wins_server": "192.168.1.10",
"workgroup": "WORKGROUP",
"hide_special_folders": true,
"unix_extensions": false,
"dos_attributes": false,
"admin_users": ["Administrator"],
"sid": "S-1-5-21-2893658096-2769335802-4101685516",
"oplocks": true,
"kernel_oplocks": false,
"level2_oplocks": true,
"smb2_leases": false,
"fruit": false
}
Note:
- All fields are optional.
- Additional properties are not allowed.
@return Http code 204 on success.
@return Http code 400 on invalid JSON payload or validation error.
{
"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
}
List users connected to samba e.g.:
GET:/api/v4/services/smb/connected-users
This end point supports pagination and search through Pagination and Where
utilities. Arguments for pagination and search are provided through URL
arguments. For details refer to the documentation of those utilities.
Example JSON output:
{
"data": {
"results": 2,
"entries": [
{
"pid": "17961",
"uid": 1000,
"username": "user3",
"gid": 100,
"machine": "192.168.176.44",
"ip_address_type": "ipv4",
"ip_address": "192.168.176.44",
"port": 41000,
"protocol_version": "SMB3_02"
},
{
"pid": "15596",
"uid": 1001,
"username": "user2",
"gid": 100,
"machine": "192.168.176.21",
"ip_address_type": "ipv4",
"ip_address": "192.168.176.21",
"port": 37066,
"protocol_version": "SMB3_02"
}
]
},
"error": null
}
@return: Http code 200 on success and list of connected users.
@return: Http code 400 on invalid where/search query arguments.
N/A
List all SMB share connections for given user e.g.:
GET:/api/v4/services/smb/connected-users//connections
This end point supports pagination and search through Pagination and Where
utilities. Arguments for pagination and search are provided through URL
arguments. For details refer to the documentation of those utilities.
Example JSON output:
{
"data": {
"results": 1,
"entries": [
{
"service": "share-03",
"pid": "17961",
"machine": "192.168.176.44",
"connected_at": "Mon Jan 25 09:25:51 2021 CET",
"dataset": "pool1/dataset1"
}
]
},
"error": null
}
@param user_name: Name of the user for which connections will be listed.
@type user_name: str.
@return: Http code 200 on success and list of share connections.
@return: Http code 400 on invalid where/search query arguments.
N/A
Restart smb service e.g.:
POST:/api/v4/services/smb/restart
@return: Http code 204 on success.
N/A
Get SMB admin users list e.g.:
GET:/api/v4/services/smb/superusers
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
Set SMB admin users list e.g.:
PUT:/api/v4/services/smb/superusers
Example JSON input:
[
{
"id": 1,
"name": "Administrator",
"allow_access": true
},
{
"id": 2,
"name": "user1",
"allow_access": false
}
]
@return: Http code 204 on success.
@return: Http code 400 when request body is not a JSON array.
{
"type": "array"
}
Get SNMP configuration.
Example JSON output::
{
"data": {
"enabled": true,
"snmp_type": "SNMP_v2",
"snmp_v2": {
"contact": "test",
"location": "test",
"community": "public"
},
"snmp_v3": {
"contact": "test",
"location": "test",
"username": "admin"
}
},
"error": null
}
@return: HTTP code 200 on success.
N/A
Edit SNMP configuration.
Optional JSON keys:
- "enabled" - Boolean flag that controls if SNMP is enabled.
- "snmp_type" - Version of SNMP, one of:
- "SNMP_v2" - SNMP version 2.
- "SNMP_v3" - SNMP version 3.
- "snmp_v2" - Configuration for SNMP version 2 - it will be used when
this version is selected.
- "contact" - SNMP version 2 configuration field.
- "location" - SNMP version 2 configuration field.
- "community" - SNMP version 2 configuration field.
- "snmp_v3" - Configuration for SNMP version 3 - it will be used when
this version is selected.
- "contact" - SNMP version 3 configuration field.
- "location" - SNMP version 3 configuration field.
- "username" - User name for authentication.
- "password" - Password for authentication.
@return: HTTP code 200 on success.
{
"properties": {
"enabled": {
"type": "boolean"
},
"snmp_type": {
"type": "string"
},
"snmp_v2": {
"properties": {
"contact": {
"type": "string"
},
"location": {
"type": "string"
},
"community": {
"type": "string"
}
}
},
"snmp_v3": {
"properties": {
"contact": {
"type": "string"
},
"location": {
"type": "string"
},
"username": {
"type": "string"
},
"password": {
"type": "string"
}
}
}
}
}
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
Get settings of the VAAI NAS service e.g.:
GET:/api/v4/services/vaai/nas
Example JSON output:
{
"data": {
"enabled": true,
"status": true
},
"error": null
}
@return Http code 200 on success.
N/A
Sets settings of the VAAI NAS service e.g.:
PUT:/api/v4/services/vaai/nas
JSON keys:
- "enabled" - Boolean flag used to enable or disable the service.
Example JSON input:
{
"enabled": true
}
@return Http code 200 on success.
@return Http code 400 on schema validation error.
{
"properties": {
"enabled": {
"type": "boolean"
}
},
"additionalProperties": false
}
Get settings of the WebGUI service e.g.:
GET:/api/v4/services/webgui
Example JSON output:
{
"data": {
"port": 443,
"allowed_ips": [
"192.168.23.4",
"1.2.3.4/12",
"2.3.4.5/24"
],
"allowed_methods": ["*"],
"domain_login": false,
"enabled": true,
"status": true
},
"error": null
}
@return Http code 200 on success.
@return Http code 500 on internal error.
N/A
Sets settings of the WebGUI service e.g.:
PUT:/api/v4/services/webgui
Optional JSON input fields:
- "enabled" - boolean
- "domain_login" - boolean
- "port" - integer (range: 1-65535)
- "allowed_ips" - array of strings (IPv4 address or IPv4 network in CIDR)
- "password" - string (must not be empty)
Example JSON input:
{
"enabled": true
}
Example JSON input:
{
"enabled": true,
"domain_login": true,
"port": 443,
"allowed_ips": ["192.168.1.1", "192.168.0.0/24"],
"password": "secret"
}
@type enabled: bool
@param enabled: Enable/disable the WebGUI service.
@type domain_login: bool
@param domain_login: Enable/disable domain-based authentication to the WebGUI.
@type port: int
@param port: HTTPS port for WebGUI.
@type allowed_ips: list[str]
@param allowed_ips: List of IPv4 addresses or IPv4 networks allowed to access the WebGUI.
@type password: str
@param password: WebGUI admin password (empty string is rejected).
@return Http code 204 on success.
@return Http code 400 on invalid JSON schema or invalid field values.
@return Http code 500 on internal service operation failure.
{
"properties": {
"enabled": {
"type": "boolean"
},
"domain_login": {
"type": "boolean"
},
"port": {
"type": "integer"
},
"allowed_ips": {
"type": "array",
"items": {
"type": "string"
}
},
"password": {
"type": "string"
}
},
"additionalProperties": false
}
Get settings of the Zeroconf service e.g.:
GET:/api/v4/services/zeroconf
Example JSON output:
{
"data": {
"enabled": true,
"status": true,
"timemachine": false,
"smb": true
},
"error": null
}
@return Http code 200 on success.
N/A
Sets settings of the Zeroconf service e.g.:
PUT:/api/v4/services/zeroconf
Example JSON input:
{
"enabled": true,
"timemachine": false,
"smb": true
}
@return Http code 200 on success.
@return Http code 400 when JSON schema validation fails.
{
"properties": {
"enabled": {
"type": "boolean"
},
"timemachine": {
"type": "boolean"
},
"smb": {
"type": "boolean"
}
},
"additionalProperties": false
}
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
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
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
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/v4/shares?page=0&per_page=10&where=path==Pool-0/Dataset-0
GET: /api/v4/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,
"extra_features": false,
"xattr": false,
"fruit": false,
"recycle": false,
"recycle_name": "RecycleName"
},
"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
- "extra_features" - (type: boolean) Enable additional Virtual File System (VFS) features for this Samba share
- "xattr" - (type: boolean) Advanced access control via ACL (acl_xattr)
- "fruit" - (type: boolean) macOS file sharing features and legacy Netatalk compatibility (fruit)
- "recycle" - (type: boolean) Recycle bin (recycle) Moves deleted files to a temporary folder instead of deleting them permanently.
- "recycle_name" - (type: string) Name of recycle bin
- "ip_restrictions" - (type: object) SMB access restrictions by
client IP:
- "restriction_type" - Restriction mode:
- "disabled" - IP-based restrictions are disabled.
- "allow" - Only addresses from "ip_list" are allowed
(except addresses from "except_list").
- "deny" - Addresses from "ip_list" are denied
(except addresses from "except_list").
- "ip_list" - List of explicitly allowed or blocked IP
addresses (depending on restriction mode). This list must be
non-empty when restriction type is "allow" or "deny".
- "except_list" - List of exception IP addresses.
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"
},
"extra_features": {
"type": "boolean"
},
"xattr": {
"type": "boolean"
},
"fruit": {
"type": "boolean"
},
"recycle": {
"type": "boolean"
},
"recycle_name": {
"type": "string"
},
"hide_unreadable": {
"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,
"extra_features": false,
"xattr": false,
"fruit": false,
"recycle": false,
"recycle_name": "RecycleName",
},
"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:
- "name" - string with new share name.
- "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).
- "smb" - object describing SMB functionality, allowed keys are
the same as for L{create_share}, including
"ip_restrictions".
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"
},
"extra_features": {
"type": "boolean"
},
"xattr": {
"type": "boolean"
},
"fruit": {
"type": "boolean"
},
"recycle": {
"type": "boolean"
},
"recycle_name": {
"type": "string"
},
"hide_unreadable": {
"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": [
{
"gid": 1,
"name": "DEV+devgroup2",
"readonly": true
},
{
"gid": 0,
"name": "DEV+devgroup1",
"readonly": false
}
],
"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
Required JSON keys:
- Request body is an array of objects:
- "name" - Group name to add to share.
- "readonly" - Boolean flag indicating read-only access.
Example JSON input:
[
{
"name": "DEV+devgroup1",
"readonly": true
},
{
"name": "DEV+devgroup2",
"readonly": false
}
]
@return: Http code 201 on success.
{
"type": "array",
"items": {
"properties": {
"name": {
"type": "string"
},
"readonly": {
"type": "boolean"
}
}
},
"additionalProperties": false
}
Removes groups from given share.
Required JSON keys:
- Request body is an array with group names to remove from share.
Example JSON input::
["groupG1", "groupG2"]
@param share_name: Name of share.
@type share_name: str
@return: Http code 204 on success.
{
"type": "array"
}
Empties SMB recycly bin by removing its directory. When a file gets removed
it will be re-created with the file inside
DELETE:/api/v4/shares//recycle
@return: Http code 200 on success
N/A
Lists all users for given share.
@param share_name: Name of share.
@type share_name: str
Example of JSON output::
{
"data": {
"entries": [
{
"uid": 1,
"name": "DEV+devuser2",
"readonly": true
},
{
"uid": 0,
"name": "DEV+devuser1",
"readonly": false
}
],
"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
Required JSON keys:
- Request body is an array of objects:
- "name" - User name to add to share.
- "readonly" - Boolean flag indicating read-only access.
Example JSON input:
[
{
"name": "DEV+devuser2",
"readonly": true
},
{
"name": "DEV+devuser1",
"readonly": false
}
]
@return: Http code 201 on success.
{
"type": "array",
"items": {
"properties": {
"name": {
"type": "string"
},
"readonly": {
"type": "boolean"
}
}
},
"additionalProperties": false
}
Removes users from given share.
@param share_name: Name of share.
@type share_name: str
Required JSON keys:
- Request body is an array with user names to remove from share.
Example JSON input::
["userA1", "userA2"]
@return: Http code 204 on success.
{
"type": "array"
}
Restore system administrator settings to factory defaults.
Return list of service names that factory defaults were restored to factory
defaults.
@return: Http code 200 on success.
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 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 content type and set
self-signed certificate type in JSON data.
Required JSON keys (for application/json requests):
- "certificate_type" - type of certificate to use. Supported value:
"self-signed".
Example JSON input::
{
"certificate_type": "self-signed"
}
N/A
Fetch current e-mail notification settings.
Example JSON output::
{
"data": {
"enabled": false,
"source_email": "test@notifications.example.com",
"destination_email": [
"example.user@example.com"
],
"smtp_server": "smtp.example.com",
"port": 25,
"account_name": "",
"use_ssl_encryption": false,
"message_types_to_send": [
"info",
"warning",
"error"
],
"destination_email_type": "alternative"
},
"error": null
}
Configuration fields description:
- "enabled" - Flag that tells if e-mail notification is enabled.
- "source_email" - E-mail address from which notifications will be
send.
- "destination_email" - List of e-mail addresses where notifications
will be send.
- "smtp_server" - SMTP server used to send e-mail notifications.
- "port" - Port on SMTP server used to send e-mail notifications.
- "account_name" - Optional login to e-mail accout. It is set when
e-mail account requires authentication in order to send e-mails.
- "use_ssl_encryption" - Flag that enables or disables usage of SSL
encryption during connection with SMTP server.
- "message_types_to_send" - List with types of messages that will be
send through e-mail notifications. Only message types specified on this
list will be send thorugh e-mail notification, any combination of
available types is possible. Following message types can be configured:
- "info" - messages with information level,
- "warning" - messages with warning level,
- "error" - messages with error level
- "destination_email_type" - Type of destination e-mail used:
- "default" - Destination e-mail is set to one address that is the
same as source e-mail.
- "alternative" - Destination e-mail is set to different address
than the source e-mail or there are multiple recipients specified.
@return: Http code 200 on success.
N/A
Modify configuration of e-mail notification.
Required JSON keys: All settings are optional, not specified options remain
unchanged. Depending on configuration different fields may required
assigned value. Most basic configuration of enabled e-mail notifications
contains following fields:
- "enabled" - set to true to enable e-mail notification,
- "source_email" - e-mail address from which notifications will be
send,
- "smtp_server" - SMTP server name or IP address used to send e-mail
notifications,
- "message_types_to_send" - at least one type of message to be send
through e-mail notifications, available types: info, warning, error.
Optional JSON keys:
- "enabled" - Flag used to enable or disable e-mail notification.
- "source_email" - E-mail address from which notifications will be
send. This field have to be specified for enabled e-mail notification.
It is possible to set this field to empty string, if e-mail
notification is disabled.
- "destination_email" - List of destination e-mail addresses to which
notifications will be send. It is possible to specify this field as
string if only one address is needed. If this field is empty in
configuration and not specified during the request, it defaults to
source e-mail address (account sends notifications to itself). By
setting this field to empty string or empty list it will revert to
using source e-mail address.
- "smtp_server" - Host name or IP address of SMTP server used to send
e-mail notifications. This field have to be set up when e-mail
notification is enabled. When e-mail notification is disabled it is
possible to assign empty stiring to this field.
- "port" - Port on SMTP server used to send e-mail notifications, it
defaults to port 25.
- "account_name" - Login to e-mail account that can be set when
authentication to SMTP server is required. By setting this field and
"mail_password" field to empty string authentication is disabled.
- "mail_password" - Password to e-mail account that can be set when
authentication to SMTP server is required.
- "use_ssl_encryption" - Flag that sets if SSL encryption will be used
during communication with SMTP server.
- "message_types_to_send" - List of message types that will be send
through e-mail notification. When e-mail notification is enabled at
least one message type have to be specified. For disabled e-mail
notification it is possible to set this field to empty list. Available
message types are:
- "info" - messages with information level,
- "warning" - messages with warning level,
- "error" - messages with error level
{
"properties": {
"enabled": {
"type": "boolean"
},
"source_email": {
"type": "string"
},
"destination_email": {
"oneOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "string"
}
]
},
"port": {
"type": "integer"
},
"smtp_server": {
"type": "string"
},
"account_name": {
"type": "string"
},
"mail_password": {
"type": "string"
},
"use_ssl_encryption": {
"type": "boolean"
},
"message_types_to_send": {
"oneOf": [
{
"type": "array",
"items": {
"type": "string"
}
},
{
"type": "string"
}
]
}
}
}
None
N/A
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"
]
}
Delete archived logs.
@return: Http code 204 on success.
N/A
Returns logs package stream.
N/A
Get NVMe initiator configuration.
Example JSON output::
{
"data": {
"host_nqn": "nvme-initiator-name"
},
"error": null
}
@return: Http code 200 on success.
N/A
Edit NVMe initiator configuration.
Optional JSON keys:
- "host_nqn" - String with name of the initiator.
- "auto_rescan_interval" - Interval in minutes for automatic rescan
of configured NVMe-oF subsystems and attempt to reconnect any
disconnected subsystems or paths.
Example JSON input::
{
"host_nqn": "nvme-initiator-name"
}
{
"auto_rescan_interval": 20
}
@return: Http code 200 on success.
{
"properties": {
"host_nqn": {
"type": "string"
},
"auto_rescan_interval": {
"type": "integer"
}
}
}
List NVMe subsystems discovered on given port.
Required JSON keys:
- "traddr" - Transmission address, for example IP address of the port
where NVMe subsystems are available.
Optional JSON keys:
- "transmission_type" - Two values are available: tcp, rdma.
Default value is tcp.
- "trsvcid" - Transmission service ID provided as integer or string.
For example TCP/IP port number, by default it is 4420.
@return: HTTP code 200.
{
"properties": {
"traddr": {
"type": "string"
},
"transmission_type": {
"type": "string"
},
"trsvcid": {
"oneOf": [
{
"type": "string"
},
{
"type": "integer"
}
]
}
},
"required": [
"traddr"
]
}
List configured connections to NVMe targets.
Example JSON output::
{
"data": [
{
"subsystem_nqn": "nvme-disk0",
"state": "connected",
"controllers": [
{
"controller": "nvme1",
"transport": "tcp",
"traddr": "172.21.150.10",
"trsvcid": 4420,
"model": "Linux",
"serial_number": "711f141e2b9902091f12",
"namespaces": [
{
"namespace": "nvme1n1",
"nsid": 1,
"physical_size": "21474836480",
"sector_size": 512
}
]
},
{
"controller": "nvme0",
"transport": "tcp",
"traddr": "172.21.150.9",
"trsvcid": 4420,
"model": "Linux",
"serial_number": "711f141e2b9902091f12",
"namespaces": [
{
"namespace": "nvme0n1",
"nsid": 1,
"physical_size": "21474836480",
"sector_size": 512
}
]
}
],
"paths": [
{
"name": "nvme1",
"transport": "tcp",
"traddr": "172.21.150.10",
"trsvcid": 4420,
"state": "live"
},
{
"name": "nvme0",
"transport": "tcp",
"traddr": "172.21.150.9",
"trsvcid": 4420,
"state": "live"
}
]
},
{
"subsystem_nqn": "nvme-disk1",
"state": "connected",
"controllers": [
{
"controller": "nvme3",
"transport": "tcp",
"traddr": "172.21.150.10",
"trsvcid": 4420,
"model": "Linux",
"serial_number": "1b767a8c65d407899ab8",
"namespaces": [
{
"namespace": "nvme3n1",
"nsid": 1,
"physical_size": "21474836480",
"sector_size": 512
}
]
},
{
"controller": "nvme2",
"transport": "tcp",
"traddr": "172.21.150.9",
"trsvcid": 4420,
"model": "Linux",
"serial_number": "1b767a8c65d407899ab8",
"namespaces": [
{
"namespace": "nvme2n1",
"nsid": 1,
"physical_size": "21474836480",
"sector_size": 512
}
]
}
],
"paths": [
{
"name": "nvme3",
"transport": "tcp",
"traddr": "172.21.150.10",
"trsvcid": 4420,
"state": "live"
},
{
"name": "nvme2",
"transport": "tcp",
"traddr": "172.21.150.9",
"trsvcid": 4420,
"state": "live"
}
]
}
],
"error": null
}
Returned data is a list of configured NVMe subsystem connections. Each
item provides following data:
- "subsystem_nqn" - Name of NVMe subsystem.
- "state" - Connection state for given subsystem:
connected / disconnected
- "controllers" - List of NVMe controllers created for given subsystem.
Each connected path has controller created that refers to given
connection.
- "namespaces" - Each controller has list of namespaces that refer
to block devices available in the system.
- "paths" - List of configured paths. This list is always present even
when initiator failed to reconnect. In that case state of the path will
indicate that it is disconnected.
@return: Http code 200 on success.
N/A
Connect to NVMe subsystem.
Required JSON keys:
- "subsystem_name" - Name of subsystem to connect.
- "paths" - List of paths used for connection. Each path is configured
using following fields:
- "traddr" - Transmission address, for example IP address.
- "transmission_type" - Two values are available: tcp, rdma.
Default is tcp if field is not specified.
- "trsvcid" - Transmission service ID, for example TCP/IP port.
Default is 4420 if field is not specified.
- "nr_io_queues" - Optional number of I/O queues.
Example JSON input::
{
"subsystem_name": "nvme-disk0",
"paths": [
{
"traddr": "172.20.100.9",
"transmission_type": "tcp",
"trsvcid": 4420
},
{
"traddr": "172.20.100.10",
"transmission_type": "tcp",
"trsvcid": 4420
}
]
}
@return: Http code 201 on success.
{
"properties": {
"subsystem_name": {
"type": "string"
},
"paths": {
"type": "array",
"items": {
"properties": {
"traddr": {
"type": "string"
},
"transmission_type": {
"type": "string"
},
"trsvcid": {
"type": "integer"
},
"nr_io_queues": {
"type": "integer"
}
},
"required": [
"traddr"
]
}
}
},
"required": [
"subsystem_name",
"paths"
]
}
Disconnect provided paths to subsystem.
Note that if all paths will be provided given subsystem configuration will
be removed. It is equivalent to disconnecting from the whole subsystem.
Required JSON keys:
- "subsystem_name" - Name of subsystem to where paths will be
disconnected.
- "paths" - List of paths to disconnect. Path configurations are in
the same format as for connecting subsystem:
- "traddr" - Transmission address, for example IP address.
- "transmission_type" - Two values are available: tcp, rdma.
Default is tcp if field is not specified.
- "trsvcid" - Transmission service ID, for example TCP/IP port.
Default is 4420 if field is not specified.
- "nr_io_queues" - Optional number of I/O queues, this parameter
is not taken into account while identifying a path to disconnect.
Example JSON input::
{
"subsystem_name": "nvme-disk0",
"paths": [
{
"traddr": "172.20.100.10",
"transmission_type": "tcp",
"trsvcid": 4420
}
]
}
@return: Http code 204 on success.
{
"properties": {
"subsystem_name": {
"type": "string"
},
"paths": {
"type": "array",
"items": {
"properties": {
"traddr": {
"type": "string"
},
"transmission_type": {
"type": "string"
},
"trsvcid": {
"type": "integer"
},
"nr_io_queues": {
"type": "integer"
}
},
"required": [
"traddr"
]
}
}
},
"required": [
"subsystem_name",
"paths"
]
}
Disconnect from given NVMe subsystem.
It will disconnect from all connected paths and remove subsystem from
configuration.
@param subsystem_name: Name of the subsystem to disconnect.
@type subsystem_name: str
@return: Http code 204 on success.
N/A
List NVMe subsystems with its status of paths.
List all NVMe subsystems present in the system with the status that
includes:
- list of namespaces
- list of paths
- list of controllers
- count of active paths
- count of maximum registered paths to given subsystem
Counter with active paths and maximum registered paths can be used to
identify if given subsystem has not disconnect on any path that was
previously available.
Example JSON output::
{
"data": [
{
"subsystem_nqn": "nqn.2014-08.org.nvmexpress:subsystem:4ddd2fa00520c092",
"namespaces": [
{
"name_space": "nvme1n1",
"nsid": 1,
"physical_size": "10737418240",
"used_bytes": "10737418240",
"sector_size": 512
}
],
"paths": [
{
"address": "traddr=172.25.100.12,trsvcid=4420",
"name": "nvme1",
"transport": "tcp",
"state": "live"
}
],
"controllers": [
{
"controller": "nvme1",
"address": "traddr=172.25.100.12,trsvcid=4420",
"transport": "tcp",
"firmware": "24.09",
"model_number": "SPDK bdev Controller",
"serial_number": "c6a2fe49fd12e93f17e5"
}
],
"active_path_count": 1,
"max_registered_path_count": 1
}
]
}
@return: HTTP code 200 on success.
N/A
Reset counter with number of paths for NVMe subsystem.
Reset maximum registered number of paths to the number of currently active
paths on selected NVMe subsystem.
@param subsystem_nqn: NQN of subsystem where path count will be reset.
@type subsystem_nqn: str
@return: HTTP code 204 on success.
N/A
Get configuration of NVMe multipath.
Output fields description:
- "enabled" - Flag in configuration that controls if NVMe multipath
should be enabled in the system.
- "enabled_current_status" - Flag that describes current status of NVMe
multipath in the system. Application of configuration value requires
reboot, this is current status of NVMe multipath within the system.
When it differs from configuration value it means that reboot is
required to apply changes.
- "reboot_required" - Flag that indicates if system reboot is required
to apply changes in configuration. This flag informs if enabled status
requires reboot to apply changes.
- "io_policy" - Following values are available:
- "numa" - this is active-passive mode - one path is active, the
rest are in passive mode. If the active path stops working, the
next one takes over its role.
- "round-robin" - this is active-active mode - all paths are
available and distribute the load between them
- Settings affecting NVMe subsystems connected through NVMe initiator:
- "reconnect_delay" - if the connection to an NVMe target is lost,
the initiator will wait configured number of seconds before
attempting to reconnect.
- "ctrl_loss_tmo" - determines how long the NVMe driver waits
before considering a controller (path) permanently lost if
reconnection attempts fail.
- "fast_io_fail_tmo" - defines the timeout (in seconds) for I/O
operations on a specific path after the path is marked as degraded
or failed. This parameter determines how quickly the system stops
attempting I/O on a failing path and reroutes to an alternative
path in a multipath configuration.
Example JSON output::
{
"data": {
"enabled": true,
"enabled_current_status": true,
"reboot_required": false,
"io_policy": "round-robin",
"reconnect_delay": 20,
"ctrl_loss_tmo": 800,
"fast_io_fail_tmo": 80
},
"error": null
}
@return: HTTP code 200 on success.
N/A
Edit NVMe multipath configuration.
Configuration is applied to all NVMe subsystems and controllers present in
the system.
Example JSON input::
{
"enabled": true,
"io_policy": "round-robin",
"reconnect_delay": 20,
"ctrl_loss_tmo": 800,
"fast_io_fail_tmo": 80
}
Optional JSON keys:
- "enabled" - Flag in configuration that controls if NVMe multipath
should be enabled in the system.
- "io_policy" - I/O policy for path selection. Supported values:
"numa", "round-robin".
- "reconnect_delay" - Delay in seconds before reconnect attempt.
- "ctrl_loss_tmo" - Timeout in seconds before controller (path) is
considered permanently lost.
- "fast_io_fail_tmo" - Timeout in seconds after path degradation/fail
before failing and rerouting I/O.
@return: HTTP code 200 on success.
{
"properties": {
"enabled": {
"type": "boolean"
},
"io_policy": {
"type": "string"
},
"reconnect_delay": {
"type": "integer"
},
"ctrl_loss_tmo": {
"type": "integer"
},
"fast_io_fail_tmo": {
"type": "integer"
}
}
}
Get response policy for critical system errors:
Reboot mechanism can be triggered for:
ZFS pool I/O suspend
Kernel oops or BUG
Out-of-memory error
ZFS panic
Fields description:
- "io_suspend_policy" - Policy used when I/O suspended state occurs in
zfs.
- "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
- "zfs_panic_policy" - Policy used when ZFS panic occured.
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",
"kernel_bug_policy": "immediate-reboot",
"out_of_memory_policy": "manual-reboot",
"zfs_panic_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
Kernel oops or BUG
Out-of-memory error
ZFS panic
Required JSON keys:
- "io_suspend_policy" - Policy used when I/O suspended state occurs in
zfs.
- "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
- "zfs_panic_policy" - Policy used when ZFS panic occured.
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",
"kernel_bug_policy": "immediate-reboot",
"out_of_memory_policy": "manual-reboot",
"zfs_panic_policy": "manual-reboot",
}
@return: Http code 200 on success.
{
"properties": {
"io_suspend_policy": {
"type": "string"
},
"kernel_bug_policy": {
"type": "string"
},
"out_of_memory_policy": {
"type": "string"
},
"zfs_panic_policy": {
"type": "string"
}
},
"required": [
"io_suspend_policy",
"kernel_bug_policy",
"out_of_memory_policy"
]
}
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"
]
}
Get power button settings.
Fields description:
- "power_button_action" - Action executed by the system when power
button is pressed:
- shutdown
- reboot
- no_action - power button press is ignored
Example JSON output::
{
"data": {
"power_button_action": "reboot"
},
"error": null
}
@return: Http code 200 on success.
N/A
Modify power button action.
Optional JSON keys:
- "power_button_action" - Sets action executed when power button is
pressed:
- shutdown
- reboot
- no_action
Example JSON input::
{
"power_button_action": "no_action"
}
@return: Http code 200 on success.
{
"properties": {
"power_button_action": {
"type": "string"
}
}
}
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" - ID of job that should be executed by scheduler task.
- "schedule" - Type of schedule: daily, weekly, monthly, yearly.
- "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" - Hour when task is executed.
- "minute" - Minute when task is executed.
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
Required JSON keys:
- "schedule_type" - Type of scheduler configuration: daily or weekly.
Optional JSON keys:
- "time" - Default scrub pause/resume time settings:
- "scrub_pause" - Time when scrub should be paused:
- "hour" - Hour in 24-hour format.
- "minute" - Minute.
- "scrub_resume" - Time when scrub should be resumed:
- "hour" - Hour in 24-hour format.
- "minute" - Minute.
- "days" - Array with weekly schedule entries:
- "day_number" - Day of week number (0-6).
- "time" - Optional time settings for this day, in the same format
as the top-level "time".
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 returned.
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/v4/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6"
},
"request": {
"href": "/api/v4/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6/request"
},
"progress": {
"href": "/api/v4/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6/progress"
},
"response": {
"href": "/api/v4/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6/response"
},
"delete": {
"href": "/api/v4/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6"
}
},
"start_time": 1619525186.992631,
"uri": "/api/v4/updates/b42804/defaultboot",
"id": "e1163fca-00d3-47ac-9e8a-a95886dc3ad6",
"end_time": 1619525217.041519,
"method": "POST"
}
],
"error": null
}
@return http code 200 on success
@return http code 400 when 'query' is not a valid JSON object
N/A
Delete tasks for given query.
URL parameters:
- query: A query that determines which entries should be deleted. Syntax documented under /doc/query REST endpoint.
If no query is specified, deletes all finished tasks (succeeded or failed).
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.
@return: Http code 400 when 'query' is not a valid JSON object.
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": {
"id": "e1163fca-00d3-47ac-9e8a-a95886dc3ad6",
"name": "VersionChange",
"status": "failed",
"resource": {
"type": "Update",
"id": "b42804"
},
"links": {
"self": {
"href": "/api/v4/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6"
},
"request": {
"href": "/api/v4/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6/request"
},
"progress": {
"href": "/api/v4/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6/progress"
},
"response": {
"href": "/api/v4/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6/response"
},
"delete": {
"href": "/api/v4/tasks/e1163fca-00d3-47ac-9e8a-a95886dc3ad6"
}
},
"start_time": 1619525186.992631,
"end_time": 1619525217.041519,
"uri": "/api/v4/updates/b42804/defaultboot",
"method": "POST"
},
"error": null
}
@return http code 200 on success
@return http code 404 when task with given ID does not exist
N/A
Delete task with a given ID. Cannot delete tasks in progress.
@param task_id: ID for the task
@type task_id: str
@return: Http code 204 on success.
@return: Http code 403 when task exists but is still in progress.
@return: Http code 404 when task with given ID does not exist.
N/A
Returns progress JSON for the task.
@param task_id: ID for the task
@type task_id: str
@return http code 200 on success
@return http code 404 when task with given ID does not exist
N/A
Returns request JSON for the task.
@param task_id: ID for the task
@type task_id: str
JSON output is task-dependent. 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"
},
"error": null
}
@return http code 200 on success
@return http code 404 when task with given ID does not exist
N/A
Returns an identical response that would have appeared if the operations
done by the task identified by 'task_id' were done synchronously.
@param task_id: ID for the task
@type task_id: str
JSON output and http code are task-dependent.
- Success code is inherited from the original operation.
- Returns http code 404 when task does not exist or response is not available yet.
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
Adds update image file.
You can upload files with .iso or .upd extension to this endpoint.
Curl Example:
curl -i -X POST -H "Content-Type: multipart/form-data" -F file=@iso_or_upd_file http://ip_address:port/api/v4/update
Python Example:
import requests
with open('iso_or_upd_file', 'rb') as f:
requests.post('http://ip_addres:port/api/v4/update', files = {'file': f})
Please reboot this server for the changes to take effect.
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.
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.
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.
N/A
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.
- "copy_settings" - Boolean flag that indicates if settings should be
saved and transferred to switched version. It defaults to true (when
not specified in JSON) meaning by default settings are always saved.
Setting flag to false allows to switch version without transferring
settings.
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"
},
"copy_settings": {
"type": "boolean"
}
}
}
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
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.
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"
}
}
}
Get users list e.g.:
GET:/api/v4/users
Query params:
- 'page', 'per_page', 'sort_by', 'order', 'search', 'search_by'
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
Creates user in given backend e.g.:
POST:/api/v4/users
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 200 on success.
{
"properties": {
"name": {
"type": "string"
},
"password": {
"type": "string"
},
"backend_name": {
"type": "string"
}
},
"required": [
"name",
"password",
"backend_name"
],
"additionalProperties": false
}
Get user details e.g.:
GET:/api/v4/users/
Fields:
- 'user' - user name from path
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 e.g.:
DELETE:/api/v4/users/
Fields:
- 'user' - user name from path
@return: Http code 204 on success.
N/A
Get groups assigned to user e.g.:
GET:/api/v4/users//groups
Fields:
- 'user' - user name from path
Query params:
- 'page', 'per_page', 'sort_by', 'order', 'search', 'search_by', 'where', 'ordering'
Example JSON output::
{
"data": {
"results": 2,
"entries": [
{
"name": "Domain Users",
"gid": 1000,
"backend": "LDAP",
"primary": true
},
{
"name": "Administrators",
"gid": 1001,
"backend": "LDAP",
"primary": false
}
]
},
"error": null
}
@return: Http code 200 on success.
N/A
Add user to groups e.g.:
POST:/api/v4/users//groups
Example JSON input::
{
"groups": ["group1", "group2"],
"backend_name": "LDAP"
}
Fields:
- 'user' - user name from path
- 'groups' - list of groups where user will be attached
- 'backend_name' - authentication backend to use
@return: Http code 200 on success.
{
"properties": {
"groups": {
"type": "array"
},
"backend_name": {
"type": "string"
}
},
"required": [
"groups",
"backend_name"
],
"additionalProperties": false
}
Remove user from groups e.g.:
DELETE:/api/v4/users//groups
Example JSON input::
{
"groups": ["group1", "group2"],
"backend_name": "LDAP"
}
Fields:
- 'user' - user name from path
- '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 e.g.:
PUT:/api/v4/users//password
Example JSON input:
{
"password": "password"
}
Fields:
- 'user' - user name from path
- 'password' - new password to set
@return: Http code 200 on success.
{
"properties": {
"password": {
"type": "string"
}
},
"required": [
"password"
]
}
Change user primary group e.g.:
PUT:/api/v4/users//primary_group
Example JSON input::
{
"primary_group": "Group",
"backend_name": "LDAP"
}
Fields:
- 'user' - user name from path
- '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.
Path parameters:
path: Directory path of dataset or snapshot (e.g. "Pool-0/MyDataSet/SomeShare")
@return HTTP code 204 on success (path exists).
@return HTTP code 400 when the path argument is invalid
@return HTTP code 404 when the path doesn't exist.
N/A
Returns all available Vdev types.
Single vdev (single disk vdev) is represented by empty string "".
Example JSON output:
{
"data": {
"types": [
"",
"mirror",
"raidz1",
"raidz2",
"raidz3",
"log",
"log mirror",
"spare",
"cache",
"special",
"special mirror",
"dedup",
"dedup mirror"
]
},
"error": null
}
@return Http code 200 on success.
N/A