doc/jsonrpc: add doc for iscsi target (d2e7441e) · Commits · Public Repositories / spdk

doc/jsonrpc.md

+798 −0

Original line number	Diff line number	Diff line
		@@ -1710,6 +1710,804 @@ Example response:
		}
		~~~

		# iSCSI Target {#jsonrpc_components_iscsi_tgt}

		## set_iscsi_options method {#rpc_set_iscsi_options}

		Set global parameters for iSCSI targets.

		This RPC may only be called before SPDK subsystems have been initialized. This RPC can be called only once.

		### Parameters

		Name \| Type \| Description
		--------------------------- \| --------\| -----------
		auth_file \| string \| Path to CHAP shared secret file for discovery session (default: "/usr/local/etc/spdk/auth.conf")
		node_base \| string \| Prefix of the name of iSCSI target node (default: "iqn.2016-06.io.spdk")
		nop_timeout \| number \| Timeout in seconds to nop-in request to the initiator (default: 60)
		nop_in_interval \| number \| Time interval in secs between nop-in requests by the target (default: 30)
		no_discovery_auth \| boolean \| CHAP for discovery session should be disabled (default: `false`)
		req_discovery_auth \| boolean \| CHAP for discovery session should be required (default: `false`)
		req_discovery_auth_mutual \| boolean \| CHAP for discovery session should be unidirectional (`false`) or bidirectional (`true`) (default: `false`)
		discovery_auth_group \| number \| CHAP group ID for discovery session (default: 0)
		max_sessions \| number \| Maximum number of sessions in the host (default: 128)
		max_queue_depth \| number \| Maximum number of outstanding I/Os per queue (default: 64)
		max_connections_per_session \| number \| Session specific parameter, MaxConnections (default: 2)
		default_time2wait \| number \| Session specific parameter, DefaultTime2Wait (default: 2)
		default_time2retain \| number \| Session specific parameter, DefaultTime2Retain (default: 20)
		immediate_data \| boolean \| Session specific parameter, ImmediateData (default: `true`)
		error_recovery_level \| number \| Session specific parameter, ErrorRecoveryLevel (default: 0)
		allow_duplicated_isid \| boolean \| Allow duplicated initiator session ID (default: `false`)
		min_connections_per_core \| number \| Allocation unit of connections per core (default: 4)

		Parameters `no_discovery_auth` and `req_discovery_auth` are mutually exclusive.

		### Example

		Example request:

		~~~
		{
		"params": {
		"allow_duplicated_isid": true,
		"default_time2retain": 60,
		"immediate_data": true,
		"node_base": "iqn.2016-06.io.spdk",
		"max_sessions": 128,
		"nop_timeout": 30,
		"nop_in_interval": 30,
		"auth_file": "/usr/local/etc/spdk/auth.conf",
		"no_discovery_auth": true,
		"default_time2wait": 2
		},
		"jsonrpc": "2.0",
		"method": "set_iscsi_options",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": true
		}
		~~~

		## get_iscsi_global_params method {#rpc_get_iscsi_global_params}

		Show global parameters of iSCSI targets.

		### Parameters

		This method has no parameters.

		### Example

		Example request:

		~~~
		request:
		{
		"jsonrpc": "2.0",
		"method": "get_iscsi_global_params",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": {
		"allow_duplicated_isid": true,
		"default_time2retain": 60,
		"immediate_data": true,
		"node_base": "iqn.2016-06.io.spdk",
		"req_discovery_auth_mutual": false,
		"nop_in_interval": 30,
		"discovery_auth_group": 0,
		"max_connections_per_session": 2,
		"max_queue_depth": 64,
		"nop_timeout": 30,
		"max_sessions": 128,
		"error_recovery_level": 0,
		"auth_file": "/usr/local/etc/spdk/auth.conf",
		"min_connections_per_core": 4,
		"no_discovery_auth": true,
		"default_time2wait": 2,
		"req_discovery_auth": false
		}
		}
		~~~

		## get_initiator_groups method {#rpc_get_initiator_groups}

		Show information about all available initiator groups.

		### Parameters

		This method has no parameters.

		### Result

		Array of objects describing initiator groups.

		Name \| Type \| Description
		--------------------------- \| --------\| -----------
		tag \| number \| Initiator group tag
		initiators \| array \| Array of initiator hostnames or IP addresses
		netmasks \| array \| Array of initiator netmasks

		### Example

		Example request:

		~~~
		{
		"jsonrpc": "2.0",
		"method": "get_initiator_groups",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": [
		{
		"initiators": [
		"iqn.2016-06.io.spdk:host1",
		"iqn.2016-06.io.spdk:host2"
		],
		"tag": 1,
		"netmasks": [
		"192.168.1.0/24"
		]
		}
		]
		}
		~~~

		## add_initiator_group method {#rpc_add_initiator_group}

		Add an initiator group.

		### Parameters

		Name \| Optional \| Type \| Description
		--------------------------- \| -------- \| --------\| -----------
		tag \| Required \| number \| Initiator group tag (unique, integer > 0)
		initiators \| Required \| array \| Not empty array of initiator hostnames or IP addresses
		netmasks \| Required \| array \| Not empty array of initiator netmasks

		### Example

		Example request:

		~~~
		{
		"params": {
		"initiators": [
		"iqn.2016-06.io.spdk:host1",
		"iqn.2016-06.io.spdk:host2"
		],
		"tag": 1,
		"netmasks": [
		"192.168.1.0/24"
		]
		},
		"jsonrpc": "2.0",
		"method": "add_initiator_group",
		"id": 1
		}
		~~~

		Example response:

		~~~
		response:
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": true
		}
		~~~

		## delete_initiator_group method {#rpc_delete_initiator_group}

		Delete an existing initiator group.

		### Parameters

		Name \| Optional \| Type \| Description
		--------------------------- \| -------- \| --------\| -----------
		tag \| Required \| number \| Initiator group tag (unique, integer > 0)

		### Example

		Example request:

		~~~
		{
		"params": {
		"tag": 1
		},
		"jsonrpc": "2.0",
		"method": "delete_initiator_group",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": true
		}
		~~~

		## add_initiators_to_initiator_group method {#rpc_add_initiators_to_initiator_group}

		Add initiators to an existing initiator group.

		### Parameters

		Name \| Optional \| Type \| Description
		--------------------------- \| -------- \| --------\| -----------
		tag \| Required \| number \| Existing initiator group tag.
		initiators \| Optional \| array \| Array of initiator hostnames or IP addresses
		netmasks \| Optional \| array \| Array of initiator netmasks

		### Example

		Example request:

		~~~
		request:
		{
		"params": {
		"initiators": [
		"iqn.2016-06.io.spdk:host3"
		],
		"tag": 1,
		"netmasks": [
		"255.255.255.1"
		]
		},
		"jsonrpc": "2.0",
		"method": "add_initiators_to_initiator_group",
		"id": 1
		}
		~~~

		Example response:

		~~~
		response:
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": true
		}
		~~~

		## get_target_nodes method {#rpc_get_target_nodes}

		Show information about all available iSCSI target nodes.

		### Parameters

		This method has no parameters.

		### Result

		Array of objects describing target node.

		Name \| Type \| Description
		--------------------------- \| --------\| -----------
		name \| string \| Target node name (ASCII)
		alias_name \| string \| Target node alias name (ASCII)
		pg_ig_maps \| array \| Array of Portal_Group_Tag:Initiator_Group_Tag mappings
		luns \| array \| Array of Bdev names to LUN ID mappings
		queue_depth \| number \| Target queue depth
		disable_chap \| boolean \| CHAP authentication should be disabled for this target
		require_chap \| boolean \| CHAP authentication should be required for this target
		mutual_chap \| boolean \| CHAP authentication should be bidirectional (`true`) or unidirectional (`false`)
		chap_group \| number \| Authentication group ID for this target node
		header_digest \| boolean \| Header Digest should be required for this target node
		data_digest \| boolean \| Data Digest should be required for this target node

		### Example

		Example request:

		~~~
		{
		"jsonrpc": "2.0",
		"method": "get_target_nodes",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": [
		{
		"luns": [
		{
		"lun_id": 0,
		"bdev_name": "Nvme0n1"
		}
		],
		"mutual_chap": false,
		"name": "iqn.2016-06.io.spdk:target1",
		"alias_name": "iscsi-target1-alias",
		"require_chap": false,
		"chap_group": 0,
		"pg_ig_maps": [
		{
		"ig_tag": 1,
		"pg_tag": 1
		}
		],
		"data_digest": false,
		"disable_chap": false,
		"header_digest": false,
		"queue_depth": 64
		}
		]
		}
		~~~

		## construct_target_node method {#rpc_construct_target_node}

		Add a iSCSI target node.

		### Parameters

		Name \| Optional \| Type \| Description
		--------------------------- \| -------- \| --------\| -----------
		name \| Required \| string \| Target node name (ASCII)
		alias_name \| Required \| string \| Target node alias name (ASCII)
		pg_ig_maps \| Required \| array \| Array of (Portal_Group_Tag:Initiator_Group_Tag) mappings
		luns \| Required \| array \| Array of Bdev names to LUN ID mappings
		queue_depth \| Required \| number \| Target queue depth
		disable_chap \| Optional \| boolean \| CHAP authentication should be disabled for this target
		require_chap \| Optional \| boolean \| CHAP authentication should be required for this target
		mutual_chap \| Optional \| boolean \| CHAP authentication should be bidirectional (`true`) or unidirectional (`false`)
		chap_group \| Optional \| number \| Authentication group ID for this target node
		header_digest \| Optional \| boolean \| Header Digest should be required for this target node
		data_digest \| Optional \| boolean \| Data Digest should be required for this target node

		### Example

		Example request:

		~~~
		{
		"params": {
		"luns": [
		{
		"lun_id": 0,
		"bdev_name": "Nvme0n1"
		}
		],
		"mutual_chap": true,
		"name": "target2",
		"alias_name": "iscsi-target2-alias",
		"pg_ig_maps": [
		{
		"ig_tag": 1,
		"pg_tag": 1
		},
		{
		"ig_tag": 2,
		"pg_tag": 2
		}
		],
		"data_digest": true,
		"disable_chap": true,
		"header_digest": true,
		"queue_depth": 24
		},
		"jsonrpc": "2.0",
		"method": "construct_target_node",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": true
		}
		~~~

		## add_pg_ig_maps method {#rpc_add_pg_ig_maps}

		Add initiator group to portal group mappings to an existing iSCSI target node.

		### Parameters

		Name \| Optional \| Type \| Description
		--------------------------- \| -------- \| --------\| -----------
		name \| Required \| string \| Target node name (ASCII)
		pg_ig_maps \| Required \| array \| Not empty array of initiator to portal group mappings objects

		Portal to Initiator group mappings object:

		Name \| Optional \| Type \| Description
		--------------------------- \| -------- \| --------\| -----------
		ig_tag \| Required \| number \| Existing initiator group tag
		pg_tag \| Required \| number \| Existing portal group tag

		### Example

		Example request:

		~~~
		{
		"params": {
		"pg_ig_maps": [
		{
		"ig_tag": 1,
		"pg_tag": 1
		},
		{
		"ig_tag": 2,
		"pg_tag": 2
		},
		{
		"ig_tag": 3,
		"pg_tag": 3
		}
		],
		"name": "iqn.2016-06.io.spdk:target3"
		},
		"jsonrpc": "2.0",
		"method": "add_pg_ig_maps",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": true
		}
		~~~

		## delete_pg_ig_maps method {#rpc_delete_pg_ig_maps}

		Delete initiator group to portal group mappings from an existing iSCSI target node.

		### Parameters

		Name \| Optional \| Type \| Description
		--------------------------- \| -------- \| --------\| -----------
		name \| Required \| string \| Target node name (ASCII)
		pg_ig_maps \| Required \| array \| Not empty array of Portal to Initiator group mappings objects

		Portal to Initiator group mappings object:

		Name \| Optional \| Type \| Description
		--------------------------- \| -------- \| --------\| -----------
		ig_tag \| Required \| number \| Existing initiator group tag
		pg_tag \| Required \| number \| Existing portal group tag

		### Example

		Example request:

		~~~
		{
		"params": {
		"pg_ig_maps": [
		{
		"ig_tag": 1,
		"pg_tag": 1
		},
		{
		"ig_tag": 2,
		"pg_tag": 2
		},
		{
		"ig_tag": 3,
		"pg_tag": 3
		}
		],
		"name": "iqn.2016-06.io.spdk:target3"
		},
		"jsonrpc": "2.0",
		"method": "delete_pg_ig_maps",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": true
		}
		~~~

		## delete_target_node method {#rpc_delete_target_node}

		Delete a iSCSI target node.

		### Parameters

		Name \| Optional \| Type \| Description
		--------------------------- \| -------- \| --------\| -----------
		name \| Required \| string \| Target node name (ASCII)

		### Example

		Example request:

		~~~
		{
		"params": {
		"name": "iqn.2016-06.io.spdk:target1"
		},
		"jsonrpc": "2.0",
		"method": "delete_target_node",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": true
		}
		~~~

		## get_portal_groups method {#rpc_get_portal_groups}

		Show information about all available portal groups.

		### Parameters

		This method has no parameters.

		### Example

		Example request:

		~~~
		request:
		{
		"jsonrpc": "2.0",
		"method": "get_portal_groups",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": [
		{
		"portals": [
		{
		"cpumask": "0x2",
		"host": "127.0.0.1",
		"port": "3260"
		}
		],
		"tag": 1
		}
		]
		}
		~~~

		## add_portal_group method {#rpc_add_portal_group}

		Add a portal group.

		### Parameters

		Name \| Optional \| Type \| Description
		--------------------------- \| -------- \| --------\| -----------
		tag \| Required \| number \| Portal group tag
		portals \| Required \| array \| Not empty array of portals

		Portal object

		Name \| Optional \| Type \| Description
		--------------------------- \| -------- \| --------\| -----------
		host \| Required \| string \| Hostname or IP address
		port \| Required \| string \| Port number

		### Example

		Example request:

		~~~
		{
		"params": {
		"portals": [
		{
		"host": "127.0.0.1",
		"port": "3260"
		}
		],
		"tag": 1
		},
		"jsonrpc": "2.0",
		"method": "add_portal_group",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": true
		}
		~~~

		## delete_portal_group method {#rpc_delete_portal_group}

		Delete an existing portal group.

		### Parameters

		Name \| Optional \| Type \| Description
		--------------------------- \| -------- \| --------\| -----------
		tag \| Required \| number \| Existing portal group tag

		### Example

		Example request:

		~~~
		{
		"params": {
		"tag": 1
		},
		"jsonrpc": "2.0",
		"method": "delete_portal_group",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": true
		}
		~~~

		## get_iscsi_connections method {#rpc_get_iscsi_connections}

		Show information about all active connections.

		### Parameters

		This method has no parameters.

		### Results

		Array of objects describing iSCSI connection.

		Name \| Type \| Description
		--------------------------- \| --------\| -----------
		id \| number \| Index (used for TTT - Target Transfer Tag)
		cid \| number \| CID (Connection ID)
		tsih \| number \| TSIH (Target Session Identifying Handle)
		lcore_id \| number \| Core number on which the iSCSI connection runs
		initiator_addr \| string \| Initiator address
		target_addr \| string \| Target address
		target_node_name \| string \| Target node name (ASCII) without prefix

		### Example

		Example request:

		~~~
		{
		"jsonrpc": "2.0",
		"method": "get_iscsi_connections",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": [
		{
		"tsih": 4,
		"cid": 0,
		"target_node_name": "target1",
		"lcore_id": 0,
		"initiator_addr": "10.0.0.2",
		"target_addr": "10.0.0.1",
		"id": 0
		}
		]
		}
		~~~

		## target_node_add_lun method {#rpc_target_node_add_lun}

		Add an LUN to an existing iSCSI target node.

		### Parameters

		Name \| Optional \| Type \| Description
		--------------------------- \| -------- \| --------\| -----------
		name \| Required \| string \| Target node name (ASCII)
		bdev_name \| Required \| string \| bdev name to be added as a LUN
		lun_id \| Optional \| number \| LUN ID (default: first free ID)

		### Example

		Example request:

		~~~
		{
		"params": {
		"lun_id": 2,
		"name": "iqn.2016-06.io.spdk:target1",
		"bdev_name": "Malloc0"
		},
		"jsonrpc": "2.0",
		"method": "target_node_add_lun",
		"id": 1
		}
		~~~

		Example response:

		~~~
		{
		"jsonrpc": "2.0",
		"id": 1,
		"result": true
		}
		~~~

		# NVMe-oF Target {#jsonrpc_components_nvmf_tgt}

		## get_nvmf_subsystems method {#rpc_get_nvmf_subsystems}