From: Alex Aizman Documentation/scsi/iscsi.txt Signed-off-by: Alex Aizman Signed-off-by: Dmitry Yusupov Signed-off-by: Andrew Morton --- 25-akpm/Documentation/scsi/iscsi.txt | 279 +++++++++++++++++++++++++++++++++++ 1 files changed, 279 insertions(+) diff -puN /dev/null Documentation/scsi/iscsi.txt --- /dev/null 2003-09-15 06:40:47.000000000 -0700 +++ 25-akpm/Documentation/scsi/iscsi.txt 2005-03-07 21:56:52.000000000 -0800 @@ -0,0 +1,279 @@ +================================================================= + + Linux* Open-iSCSI + +================================================================= + + March 04, 2005 + +Contents +======== + +- 1. In This Release +- 2. Introduction +- 3. Installation +- 4. Open-iSCSI daemon +- 5. Open-iSCSI Configuration Utility +- 6. Configuration +- 7. Getting Started +- 8. TBD +- Appendix A. SendTargets snapshot. + + + +1. In This Release +================== + +This file describes the Linux* Open-iSCSI Initiator. + +The latest development release is available at: +http://www.open-iscsi.org + +For questions, comments, contributions send e-mail to: +open-iscsi@googlegroups.com + + 1.1. Features + + - highly optimized and very small-footprint data path; + - multiple outstanding R2Ts; + - persistent configuration database; + - SendTargets discovery; + - CHAP; + - PDU header Digest; + - multiple sessions; + - multi-connection sessions. + + For the most recent list of features please refer to: + http://www.open-iscsi.org/cgi-bin/wiki.pl/Roadmap + + + +2. Introduction +=============== + +Open-iSCSI project is a high-performance, transport independent, +multi-platform implementation of RFC3720 iSCSI. + +Open-iSCSI is partitioned into user and kernel parts. + +The kernel portion of Open-iSCSI is a from-scratch code +licensed under GPL. The kernel part implements iSCSI data path +(that is, iSCSI Read and iSCSI Write), and consists of two +loadable modules: iscsi_if.ko and iscsi_tcp.ko. + +User space contains the entire control plane: configuration +manager, iSCSI Discovery, Login and Logout processing, +connection-level error processing, Nop-In and Nop-Out handling, +and (in the future:) Text processing, iSNS, SLP, Radius, etc. + +The user space Open-iSCSI consists of a daemon process called +iscsid, and a management utility iscsiadm. + + +3. Installation +=============== + +You need to enable "Cryptographic API" under "Cryptographic options" +in the kernel config. You also need to enable "CRC32c CRC algorithm" if +you use header or data digests. They are the kernel options, +CONFIG_CRYPTO and CONFIG_CRYPTO_CRC32C, respectively. + + +4. Open-iSCSI daemon +==================== + +The daemon implements control path of iSCSI protocol, plus some management +facilities. For example, the daemon could be configured to automatically +re-start discovery at startup, based on the contents of persistent +iSCSI database (see next section). + +For help, run: + + ./iscsid --help + +Usage: iscsid [OPTION] + + -c, --config=[path] Execute in the config file (/etc/iscsid.conf). + -f, --foreground run iscsid in the foreground + -d, --debug debuglevel print debugging information + -u, --uid=uid run as uid, default is current user + -g, --gid=gid run as gid, default is current user group + -h, --help display this help and exit + -v, --version display version and exit + + + +5. Open-iSCSI Configuration Utility +=================================== + +Open-iSCSI persistent configuration is implemented as a DBM database +available on all Linux installations. + +The database contains two tables: + +- Discovery table (discovery.db); +- Node table (node.db). + +The regular place for iSCSI database files: /var/db/iscsi/*.db + +The iscsiadm utility is a command-line tool to manage (update, delete, +insert, query) the persistent database. + +The utility presents set of operations that a user can perform +on iSCSI nodes, sessions, connections, and discovery records. + +Note that some of the iSCSI Node and iSCSI Discovery operations +do not require iSCSI daemon (iscsid) loaded. + +For help, run: + + ./iscsiadm --help + +Usage: iscsiadm [OPTION] + + -m, --mode specify operational mode op = + -m discovery --type=[type] --portal=[ip:port] --login + perform [type] discovery for target portal with + ip-address [ip] and port [port]. Initiate Login for + each discovered target if --login is specified + -m discovery display all discovery records from internal + persistent discovery database + -m discovery --record=[id] --login + perform discovery based on record [id] in database + -m discovery --record=[id] --op=[op] [--name=[name] --value=[value]] + perform specific DB operation [op] for specific + discovery record with [id]. It could be one of: + [new], [delete], [update] or [show]. In case of + [update], you have to provide [name] and [value] + you wish to update + -m node display all discovered nodes from internal + persistent discovery database + -m node --record=[id] [--login|--logout] + -m node --record=[id] --op=[op] [--name=[name] --value=[value]] + perform specific DB operation [op] for specific + node with record [id]. It could be one of: + [new], [delete], [update] or [show]. In case of + [update], you have to provide [name] and [value] + you wish to update + -m session display all active sessions and connections + -m session --record=[id[:cid]] [--logout] + perform operation for specific session with + record [id] or display statistics if no operation + specified. Operation will affect one connection + only if [:cid] is specified + -d, --debug debuglevel print debugging information + -V, --version display version and exit + -h, --help display this help and exit + + + Usage Examples: + + 1) SendTargets iSCSI Discovery: + + ./iscsiadm -m discovery --type sendtargets --portal 192.168.1.1:3260 + + 2) iSCSI Login: + + ./iscsiadm -m node --record 0f23e4 --login + + 3) iSCSI Logout: + + ./iscsiadm -m node --record 0f23e4 --logout + + 4) Changing iSCSI parameter: + + ./iscsiadm -m node --record 0f23e4 --op update \ + -n node.cnx[0].iscsi.MaxRecvDataSegmentLength -v 65536 + + 5) Adding custom iSCSI Node: + + ./iscsiadm -m node --op new --portal 192.168.0.1:3260 + new iSCSI node record added: [0a45f8] + + 6) Removing iSCSI Node: + + ./iscsiadm -m node --op delete --record 0a45f8 + + 7) Display iSCSI Node configuration: + + ./iscsiadm -m node --record 0a45f8 + + or + + ./iscsiadm -m node --op show --record 0a45f8 + + +6. Configuration +================ + +The default configuration file is /etc/iscsid.conf. This file contains +only configuration that could be overwritten by iSCSI Discovery, +or manualy updated via iscsiadm utility. + +See the man page and the example file for the current syntax. +(no man page yet...) + + +7. Getting Started +================== + +Right now there is no installation script. Just load the module with +command: + + insmod iscsi_if.ko + insmod iscsi_tcp.ko + +after that start iSCSI daemon process: + + ./iscsid + +or alternatively, start it with debug enabled and with output +redirected to the current console: + + ./iscsid -d8 -f & + +and use configuration utility to add/remove/update Discovery records, +iSCSI Node records or monitor active iSCSI sessions: + + ./iscsiadm + + +To login: + + ./iscsiadm -m node --record --login + +where is the record of a discovered or manually +added iSCSI Target Node (for iscsiadm usage examples see +previous sections). + + +8. TBD +====== + +To be completed: + + - Kernel tracing and Troubleshooting + - Immediate and not-so-immediate plans + - Useful scripts + - White paper on Open-iSCSI design + + +Appendix A. SendTargets iSCSI Discovery session snapshot. +========================================================= + +-bash-2.05b# ./iscsiadm -m discovery -tst -p 10.16.16.223:3260 +[02f611] 10.16.16.223:3260,1 iqn.2002-07.com.ttechnologies.target.a +[01acd1] 17.1.1.223:3260,1 iqn.2002-07.com.ttechnologies.target.a +-bash-2.05b# +-bash-2.05b# ./iscsiadm -m node +[02f611] 10.16.16.223:3260,1 iqn.2002-07.com.ttechnologies.target.a +[01acd1] 17.1.1.223:3260,1 iqn.2002-07.com.ttechnologies.target.a +-bash-2.05b# +-bash-2.05b# ./iscsiadm -m discovery -tst -p 10.16.16.227:3260 +[02fb91] 10.16.16.227:3260,1 iqn.2001-04.com.example:storage.disk2.sys1.xyz +-bash-2.05b# +-bash-2.05b# ./iscsiadm -m node +[02f611] 10.16.16.223:3260,1 iqn.2002-07.com.ttechnologies.target.a +[02fb91] 10.16.16.227:3260,1 iqn.2001-04.com.example:storage.disk2.sys1.xyz +[01acd1] 17.1.1.223:3260,1 iqn.2002-07.com.ttechnologies.target.a + _