From 93a729434c4d053226dbd8dd88e1c62d11c5e2a5 Mon Sep 17 00:00:00 2001 From: Christopher 'm4z' Holm Date: Wed, 1 Mar 2017 14:59:57 +0100 Subject: Unify README headings. --- README | 76 +++++++++++++++++++++++++++++++++++++++--------------------------- 1 file changed, 45 insertions(+), 31 deletions(-) (limited to 'README') diff --git a/README b/README index 278292b..153e1a0 100644 --- a/README +++ b/README @@ -31,15 +31,18 @@ http://www.open-iscsi.com For questions, comments, contributions send e-mail to: open-iscsi@googlegroups.com - 1.1. Features - - - highly optimized and very small-footprint data path; - - persistent configuration database; - - SendTargets discovery; - - CHAP; - - PDU header Digest; - - multiple sessions; - + +1.1. Features +============= + +- highly optimized and very small-footprint data path; +- persistent configuration database; +- SendTargets discovery; +- CHAP; +- PDU header Digest; +- multiple sessions; + + 2. Introduction =============== @@ -146,6 +149,7 @@ ib_iser module; you may get warnings related to mismatched symbols on this driver, in which case you'll be unable to load ib_iser and open-iscsi simultaneously. + 4. Open-iSCSI daemon ==================== @@ -169,7 +173,6 @@ Usage: iscsid [OPTION] -v, --version display version and exit - 5. Open-iSCSI Configuration Utility =================================== @@ -579,7 +582,6 @@ You should now skip to 5.1.3 to see how to log in using the iface and for some helpful management commands. - 5.1.2 Setting up an iface for an iSCSI offload card =================================================== @@ -677,7 +679,7 @@ Now, we can use this iface to login into targets, which is described in the next section. -5.1.3 Discoverying iSCSI targets/portals +5.1.3 Discoverying iSCSI targets/portals ======================================== Be aware that iscsiadm will use the default route to do discovery. It will @@ -731,10 +733,9 @@ To now log into targets it is the same as with software iscsi. See section 7 for how to get started. - - 5.2 iscsiadm examples ===================== + Usage examples using the one-letter options (see iscsiadm man page for long options): @@ -1095,6 +1096,7 @@ To now log into targets it is the same as with software iscsi. See section This will print the aggregate statistics on the host adapter port. This includes MAC, TCP/IP, ECC & iSCSI statistics. + 6. Configuration ================ @@ -1109,8 +1111,10 @@ The manpages for iscsid, iscsiadm are in the doc subdirectory and can be installed in the appropriate man page directories and need to be manually copied into e.g. /usr/local/share/man8. + 7. Getting Started ================== + There are three steps needed to set up a system to use iSCSI storage: 7.1. iSCSI startup using the init script or manual startup. 7.2. Discover targets. @@ -1126,7 +1130,7 @@ daemon and log into the targets manually. 7.1.1 iSCSI startup using the init script ------------------------------------------------ +========================================= Red Hat or Fedora: ----------------- @@ -1155,11 +1159,12 @@ gets installed with "make install" will usually get you started. -7.1.2 Manual Startup: ---------------------- +7.1.2 Manual Startup +==================== + +7.1.2.1 Starting up the iSCSI daemon (iscsid) and loading modules +================================================================= -7.1.2.1 Starting up the iSCSI daemon (iscsid) and loading modules: ------------------------------------------------------------------ If there is no initd script, you must start the tools by hand. First load the iscsi modules with: @@ -1174,8 +1179,10 @@ redirected to the current console: ./iscsid -d 8 -f & -7.1.2.2 Logging into Targets: ---------------------------- + +7.1.2.2 Logging into Targets +============================ + Use the configuration utility, iscsiadm, to add/remove/update Discovery records, iSCSI Node records or monitor active iSCSI sessions (see above or the iscsiadm man files and see section 7.2 below for how to discover targets). @@ -1227,8 +1234,10 @@ In this example we would run Note: drop the portal group tag from the "iscsiadm -m node" output. + 7.2. Discover Targets ---------------------- +===================== + Once the iSCSI service is running, you can perform discovery using SendTarget with: @@ -1283,8 +1292,10 @@ storage), it is better to automate the login to the nodes we need. If you wish to log into a target manually now, see section "7.1.2.2 Logging in targets" above. + 7.3. Automate Target Logins for Future System Statups ------------------------------------------------------ +===================================================== + Note: this may only work for distros with init scripts. To automate login to a node, use the following with the record ID @@ -1310,7 +1321,7 @@ be logged into autmotically. 7.4 Automatic Discovery and Login ------------------------------------ +================================= Instead of running the iscsiadm discovery command and editing the startup setting, iscsid can be configured so that every X seconds @@ -1397,7 +1408,7 @@ commands. ========================= 8.1 iSCSI settings for dm-multipath ------------------------------------ +=================================== When using dm-multipath, the iSCSI timers should be set so that commands are quickly failed to the dm-multipath layer. For dm-multipath you should @@ -1406,7 +1417,7 @@ queued if all paths are failed in the multipath layer. 8.1.1 iSCSI ping/Nop-Out settings ---------------------------------- +================================= To quickly detect problems in the network, the iSCSI layer will send iSCSI pings (iSCSI NOP-Out requests) to the target. If a NOP-Out times out the iSCSI layer will respond by failing running commands and asking the SCSI @@ -1437,7 +1448,8 @@ and workload, or you may need to check your network for possible problems. 8.1.2 replacement_timeout -------------------------- +========================= + The next iSCSI timer that will need to be tweaked is: node.session.timeo.replacement_timeout = X @@ -1451,7 +1463,8 @@ an application if multipath is not being used. 8.1.2.1 Running Commands, the SCSI Error Handler, and replacement_timeout -------------------------------------------------------------------------- +========================================================================= + Remember, from the Nop-out discussion that if a network problem is detected, the running commands are failed immediately. There is one exception to this and that is when the SCSI layer's error handler is running. To check if @@ -1487,7 +1500,8 @@ is normally 60 seconds. 8.1.2.2 Pending Commands and replacement_timeout ------------------------------------------------- +================================================ + Commonly, the SCSI/BLOCK layer will queue 256 commands, but the path can only take 32. When a network problem is detected, the 32 commands in flight will be sent back to the SCSI layer immediately and because @@ -1505,7 +1519,7 @@ dm-multipath. 8.1.3 Optimal replacement_timeout Value ---------------------------------------- +======================================= The default value for replacement_timeout is 120 seconds, but because multipath's queue_if_no_path and no_path_retry setting can prevent IO errors @@ -1518,7 +1532,7 @@ multipath.conf settings, instead of the iSCSI layer. 8.2 iSCSI settings for iSCSI root ---------------------------------- +================================= When accessing the root partition directly through an iSCSI disk, the iSCSI timers should be set so that iSCSI layer has several chances to try to -- cgit v1.2.1