From f0e177fa3d8807cfa6ae17f8a0dc759a045623f9 Mon Sep 17 00:00:00 2001 From: Aron Gunn Date: Thu, 6 Jul 2017 12:31:39 -0500 Subject: [PATCH] doc/rbd: Added the iSCSI initiators, RHEL, Windows, and ESX docs Fixes: http://tracker.ceph.com/issues/20437 Signed-off-by: Aron Gunn --- doc/rbd/iscsi-initiator-esx.rst | 33 ++++++++++ doc/rbd/iscsi-initiator-rhel.rst | 89 +++++++++++++++++++++++++++ doc/rbd/iscsi-initiator-win.rst | 100 +++++++++++++++++++++++++++++++ doc/rbd/iscsi-initiators.rst | 10 ++++ 4 files changed, 232 insertions(+) create mode 100644 doc/rbd/iscsi-initiator-esx.rst create mode 100644 doc/rbd/iscsi-initiator-rhel.rst create mode 100644 doc/rbd/iscsi-initiator-win.rst create mode 100644 doc/rbd/iscsi-initiators.rst diff --git a/doc/rbd/iscsi-initiator-esx.rst b/doc/rbd/iscsi-initiator-esx.rst new file mode 100644 index 0000000000000..faa0c5470bbe9 --- /dev/null +++ b/doc/rbd/iscsi-initiator-esx.rst @@ -0,0 +1,33 @@ +---------------------------------- +The iSCSI Initiator for VMware ESX +---------------------------------- + +**Prerequisite:** + +- VMware ESX 6.0 or later + +**iSCSI Discovery and Multipath Device Setup:** + +1. From vSphere, open the Storage Adapters, on the Configuration tab. Right click + on the iSCSI Software Adapter and select Properties. + +2. If CHAP was setup on the iSCSI gateway, in the General tab click the "CHAP…​" + button. If CHAP is not being used, skip to step 4. + +3. On the CHAP Credentials windows, select “Do not use CHAP unless required by target”, + and enter the "Name" and "Secret" values used on the initial setup for the iSCSI + gateway, then click on the "OK" button. + +4. On the Dynamic Discovery tab, click the "Add…​" button, and enter the IP address + and port of one of the iSCSI target portals. Click on the "OK" button. + +5. Close the iSCSI Initiator Properties window. A prompt will ask to rescan the + iSCSI software adapter. Select Yes. + +6. In the Details pane, the LUN on the iSCSI target will be displayed. Right click + on a device and select "Manage Paths": + +7. On the Manage Paths window, select “Most Recently Used (VMware)” for the policy + path selection. Close and repeat for the other disks: + +Now the disks can be used for datastores. diff --git a/doc/rbd/iscsi-initiator-rhel.rst b/doc/rbd/iscsi-initiator-rhel.rst new file mode 100644 index 0000000000000..3244ffaf0cef0 --- /dev/null +++ b/doc/rbd/iscsi-initiator-rhel.rst @@ -0,0 +1,89 @@ +------------------------------------------------ +The iSCSI Initiator for Red Hat Enterprise Linux +------------------------------------------------ + +**Prerequisite:** + +- Package ``iscsi-initiator-utils-6.2.0.873-35`` or newer must be + installed + +- Package ``device-mapper-multipath-0.4.9-99`` or newer must be + installed + +**Installing:** + +1. Install the iSCSI initiator and multipath tools: + + :: + + # yum install iscsi-initiator-utils + # yum install device-mapper-multipath + +**Configuring:** + +1. Create the default ``/etc/multipath.conf`` file and enable the + ``multiapthd`` service: + + :: + + # mpathconf --enable --with_multipathd y + +2. Add the following to ``/etc/multipath.conf`` file: + + :: + + devices { + device { + vendor "LIO-ORG" + hardware_handler "1 alua" + path_grouping_policy "failover" + path_selector "queue-length 0" + failback 60 + path_checker tur + prio alua + prio_args exclusive_pref_bit + no_path_retry 120 + } + } + +3. Restart the ``multipathd`` service: + + :: + + # systemctl reload multipathd + +**iSCSI Discovery and Setup:** + +1. Discover the target portals: + + :: + + # iscsiadm -m discovery -t -st 192.168.56.101 + 192.168.56.101:3260,1 iqn.2003-01.org.linux-iscsi.rheln1 + 192.168.56.102:3260,2 iqn.2003-01.org.linux-iscsi.rheln1 + +2. Login to target: + + :: + + # iscsiadm -m node -T iqn.2003-01.org.linux-iscsi.rheln1 -l + +**Multipath IO Setup:** + +The multipath daemon (``multipathd``), will set up devices automatically +based on the ``multipath.conf`` settings. Running the ``multipath`` +command show devices setup in a failover configuration with a priority +group for each path. + +:: + + # multipath -ll + mpathbt (360014059ca317516a69465c883a29603) dm-1 LIO-ORG ,IBLOCK + size=1.0G features='0' hwhandler='1 alua' wp=rw + |-+- policy='queue-length 0' prio=50 status=active + | `- 28:0:0:1 sde 8:64 active ready running + `-+- policy='queue-length 0' prio=10 status=enabled + `- 29:0:0:1 sdc 8:32 active ready running + +You should now be able to use the RBD image like you would a normal +multipath’d iSCSI disk. diff --git a/doc/rbd/iscsi-initiator-win.rst b/doc/rbd/iscsi-initiator-win.rst new file mode 100644 index 0000000000000..27175a54a3ee7 --- /dev/null +++ b/doc/rbd/iscsi-initiator-win.rst @@ -0,0 +1,100 @@ +----------------------------------------- +The iSCSI Initiator for Microsoft Windows +----------------------------------------- + +**Prerequisite:** + +- Microsoft Windows 2016 + +**iSCSI Initiator, Discovery and Setup:** + +1. Install the iSCSI initiator driver and MPIO tools. + +2. Launch the MPIO program, click on the “Discover Multi-Paths” tab select “Add + support for iSCSI devices”. + +3. On the iSCSI Initiator Properties window, on the "Discovery" tab, add a target + portal. Enter the IP address or DNS name and Port of the Ceph iSCSI gateway. + +4. On the “Targets” tab, select the target and click on “Connect”. + +5. On the “Connect To Target” window, select the “Enable multi-path” option, and + click the “Advanced” button. + +6. Under the "Connet using" section, select a “Target portal IP” . Select the + “Enable CHAP login on” and enter the "Name" and "Target secret" values from the + Ceph iSCSI Ansible client credentials section, and click OK. + +7. Repeat steps 5 and 6 for each target portal defined when setting up + the iSCSI gateway. + +**Multipath IO Setup:** + +Configuring the MPIO load balancing policy, setting the timeout and +retry options are using PowerShell with the ``mpclaim`` command. The +reset is done in the MPIO tool. + +.. NOTE:: + It is recommended to increase the ``PDORemovePeriod`` option to 120 + seconds from PowerShell. This value might need to be adjusted based + on the application. When all paths are down, and 120 seconds + expires, the operating system will start failing IO requests. + +:: + + Set-MPIOSetting -NewPDORemovePeriod 120 + +:: + + mpclaim.exe -l -m 1 + +:: + + mpclaim -s -m + MSDSM-wide Load Balance Policy: Fail Over Only + +1. Using the MPIO tool, from the “Targets” tab, click on the + “Devices…​” button: + +2. From the Devices window, select a disk and click the + “MPIO…​” button: + +3. On the "Device Details" window the paths to each target portal is + displayed. If using the ``ceph-iscsi-ansible`` setup method, the + iSCSI gateway will use ALUA to tell the iSCSI initiator which path + and iSCSI gateway should be used as the primary path. The Load + Balancing Policy “Fail Over Only” must be selected + +:: + + mpclaim -s -d $MPIO_DISK_ID + +.. NOTE:: + For the ``ceph-iscsi-ansible`` setup method, there will be one + Active/Optimized path which is the path to the iSCSI gateway node + that owns the LUN, and there will be an Active/Unoptimized path for + each other iSCSI gateway node. + +**Tuning:** + +Consider using the following registry settings: + +- Windows Disk Timeout + + :: + + HKEY_LOCAL_MACHINE\System\CurrentControlSet\Services\Disk + + :: + + DiskTimeout = 25 + +- Microsoft iSCSI Initiator Driver + + :: + + HKEY_LOCAL_MACHINE\\SYSTEM\CurrentControlSet\Control\Class\{4D36E97B-E325-11CE-BFC1-08002BE10318}\\Parameters + + :: + + SRBTimeoutDelta = 5 diff --git a/doc/rbd/iscsi-initiators.rst b/doc/rbd/iscsi-initiators.rst new file mode 100644 index 0000000000000..d3ad633480d96 --- /dev/null +++ b/doc/rbd/iscsi-initiators.rst @@ -0,0 +1,10 @@ +-------------------------------- +Configuring the iSCSI Initiators +-------------------------------- + +.. toctree:: + :maxdepth: 1 + + The iSCSI Initiator for Red Hat Enterprise Linux + The iSCSI Initiator for Microsoft Windows + The iSCSI Initiator for VMware ESX -- 2.39.5