Commit c6eb4da6 authored by Darek Stojaczyk's avatar Darek Stojaczyk Committed by Jim Harris
Browse files

doc/bdev: document iSCSI bdev module 



Most to-do items in lib/bdev/iscsi/README have been
done a long time ago, leaving this file greatly outdated.
It is removed now and the iSCSI bdev description is
added to doc/bdev.md.

Since most of the to-do items have been done, this
patch also adds a CHANGELOG entry announcing that
iSCSI bdev is no longer in experimental state.

Change-Id: I186c9e1489547152655e1e036b27ab6bc17fcf11
Signed-off-by: default avatarDarek Stojaczyk <dariusz.stojaczyk@intel.com>
Reviewed-on: https://review.gerrithub.io/429896


Tested-by: default avatarSPDK CI Jenkins <sys_sgci@intel.com>
Chandler-Test-Pool: SPDK Automated Test System <sys_sgsw@intel.com>
Reviewed-by: default avatarJim Harris <james.r.harris@intel.com>
Reviewed-by: default avatarBen Walker <benjamin.walker@intel.com>
parent 2975822f

CHANGELOG.md

+7 −1
Original line number Diff line number Diff line
@@ -51,7 +51,7 @@ A new structure spdk_mem_map_ops has been introduced to hold memory map related 
callbacks. This structure is now passed as the second argument of spdk_mem_map_alloc

in lieu of the notify callback.



### iscsi

### iscsi target



Parameter names of `set_iscsi_options` and `get_iscsi_global_params` RPC

method for CHAP authentication in discovery sessions have been changed to
@@ -69,6 +69,12 @@ specified. This default has been removed. Users must now explicitly specify 
the location of this file to load CHAP shared secrets from a file, or use

the related iSCSI RPC methods to add them at runtime.



### iscsi initiator



The SPDK iSCSI initiator is no longer perceived experimental and becomes

a first-class citizen among bdev modules. The basic usage has been briefly

described in the bdev user guide: [iSCSI bdev](https://spdk.io/doc/bdev.html#bdev_config_iscsi)



### Miscellaneous



The ReactorMask config file parameter has been deprecated.  Users should

doc/bdev.md

+13 −0
Original line number Diff line number Diff line
@@ -198,6 +198,19 @@ rpc.py stop_nbd_disk /dev/nbd0 
# Nvme0n1p1 in SPDK applications.

~~~



# iSCSI bdev {#bdev_config_iscsi}



The SPDK iSCSI bdev driver depends on libiscsi and hence is not enabled by default.

In order to use it, build SPDK with an extra `--with-iscsi-initiator` configure option.



The following command creates an `iSCSI0` bdev from a single LUN exposed at given iSCSI URL

with `iqn.2016-06.io.spdk:init` as the reported initiator IQN.



`rpc.py construct_iscsi_bdev -b iSCSI0 -i iqn.2016-06.io.spdk:init --url iscsi://127.0.0.1/iqn.2016-06.io.spdk:disk1/0`



The URL is in the following format:

`iscsi://[<username>[%<password>]@]<host>[:<port>]/<target-iqn>/<lun>`



# Linux AIO bdev {#bdev_config_aio}



The SPDK AIO bdev driver provides SPDK block layer access to Linux kernel block

lib/bdev/iscsi/README

deleted100644 → 0
+0 −26
Original line number Diff line number Diff line 
This is a very rough initial cut at an SPDK iSCSI initiator bdev module.  It

only performs operations (connect, login, read cap, read/write).

But this passes basic verify tests with bdevperf and with fio.



Be sure to build SPDK using --with-iscsi-initiator configure option.



Configuration file for iSCSI initiator is in the following format.

Note that the "/0" at the end means "LUN 0".



[iSCSI_Initiator]

  URL iscsi://127.0.0.1/iqn.2016-06.io.spdk:disk1/0 iSCSI0



To Do Items

===========

1) Create RPCs.

2) Use asynchronous polling for connect/login/disconnect.  Read/write is already

   using libiscsi event framework.

3) Choose initiator name as part of RPC configuration.  Currently this is hardcoded

   with g_initiator string.

4) Implement reset path.

5) Implement unmap path.

6) Use REPORT_LUNS to dynamically find all of the block devices attached to the

   iSCSI target node instead of hard-coding LUN 0.  This will need some extra

   investigation in libiscsi.  Currently the full URL is used which includes the LUN.

   Not sure yet how we can login to target node and then submit IO to different

   LUNs.  Let's treat this as low priority for now.