summaryrefslogtreecommitdiffstats
path: root/doc/rbd/iscsi-initiator-linux.rst
diff options
context:
space:
mode:
Diffstat (limited to 'doc/rbd/iscsi-initiator-linux.rst')
-rw-r--r--doc/rbd/iscsi-initiator-linux.rst119
1 files changed, 119 insertions, 0 deletions
diff --git a/doc/rbd/iscsi-initiator-linux.rst b/doc/rbd/iscsi-initiator-linux.rst
new file mode 100644
index 000000000..bf8c930f3
--- /dev/null
+++ b/doc/rbd/iscsi-initiator-linux.rst
@@ -0,0 +1,119 @@
+-------------------------
+iSCSI Initiator for Linux
+-------------------------
+
+**Prerequisite:**
+
+- Package ``iscsi-initiator-utils``
+
+- Package ``device-mapper-multipath``
+
+**Installing:**
+
+Install the iSCSI initiator and multipath tools:
+
+.. prompt:: bash #
+
+ yum install iscsi-initiator-utils
+ yum install device-mapper-multipath
+
+**Configuring:**
+
+#. Create the default ``/etc/multipath.conf`` file and enable the
+ ``multipathd`` service:
+
+ .. prompt:: bash #
+
+ mpathconf --enable --with_multipathd y
+
+#. Add the following to the ``/etc/multipath.conf`` file:
+
+ ::
+
+ devices {
+ device {
+ vendor "LIO-ORG"
+ product "TCMU device"
+ 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
+ fast_io_fail_tmo 25
+ no_path_retry queue
+ }
+ }
+
+#. Restart the ``multipathd`` service:
+
+ .. prompt:: bash #
+
+ systemctl reload multipathd
+
+**iSCSI Discovery and Setup:**
+
+#. Enable CHAP authentication and provide the initiator CHAP username
+ and password by uncommenting and setting the following options in
+ the ``/etc/iscsi/iscsid.conf`` file:
+
+ ::
+
+ node.session.auth.authmethod = CHAP
+ node.session.auth.username = myusername
+ node.session.auth.password = mypassword
+
+ If you intend to use mutual (bidirectional) authentication, provide the
+ target CHAP username and password:
+
+ ::
+
+ node.session.auth.username_in = mytgtusername
+ node.session.auth.password_in = mytgtpassword
+
+#. Discover the target portals:
+
+ .. prompt:: bash #
+
+ iscsiadm -m discovery -t st -p 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
+
+#. Log in to the target:
+
+ .. prompt:: bash #
+
+ iscsiadm -m node -T iqn.2003-01.org.linux-iscsi.rheln1 -l
+
+**Multipath IO Setup:**
+
+#. The multipath daemon (``multipathd``) uses the ``multipath.conf`` settings
+ to set up devices automatically. Running the ``multipath`` command shows
+ that the devices have been set up in a failover configuration. Notice that
+ each path has been placed into its own priority group:
+
+ .. prompt:: bash #
+
+ 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 in the same way that you would
+ use a normal multipath iSCSI disk.
+
+#. Log out of the target:
+
+ .. prompt:: bash #
+
+ iscsiadm -m node -T iqn.2003-01.org.linux-iscsi.rheln1 -u