doc/rbd: add mutual CHAP authentication example

Based on https://github.com/ceph/ceph-iscsi/pull/260.

Signed-off-by: Ilya Dryomov <idryomov@gmail.com>

diff --git a/doc/rbd/iscsi-initiator-linux.rst b/doc/rbd/iscsi-initiator-linux.rst
index e15e81bb98554dac2974c742890475097fdbe3fd..ea8fe0e34338f1f4a56cc729bb05a44b815d6a95 100644 (file)
--- a/doc/rbd/iscsi-initiator-linux.rst
+++ b/doc/rbd/iscsi-initiator-linux.rst
@@ -54,8 +54,23 @@ Install the iSCSI initiator and multipath tools:
 
 **iSCSI Discovery and Setup:**
 
-#. If CHAP was setup on the iSCSI gateway, provide a CHAP username and
-   password by updating the ``/etc/iscsi/iscsid.conf`` file accordingly.
+#. Enable CHAP authentication and provide the initiator CHAP username
+   and password by uncommenting and setting the following options in
+   ``/etc/iscsi/iscsid.conf`` file:
+
+   ::
+
+       node.session.auth.authmethod = CHAP
+       node.session.auth.username = myusername
+       node.session.auth.password = mypassword
+
+   If mutual (bidirectional) authentication is used, also provide the
+   target CHAP username and password:
+
+   ::
+
+       node.session.auth.username_in = mytgtusername
+       node.session.auth.password_in = mytgtpassword
 
 #. Discover the target portals:
 

diff --git a/doc/rbd/iscsi-target-cli.rst b/doc/rbd/iscsi-target-cli.rst
index 91d57f2055e86d28d479345a66c28b26293f496c..d74166e16cb69aba7a6b3899b0809cef046c2f0e 100644 (file)
--- a/doc/rbd/iscsi-target-cli.rst
+++ b/doc/rbd/iscsi-target-cli.rst
@@ -217,17 +217,39 @@ to create a iSCSI target and export a RBD image as LUN 0.
        > /disks> cd /iscsi-targets/iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw/hosts
        > /iscsi-target...eph-igw/hosts>  create iqn.1994-05.com.redhat:rh7-client
 
-#. Set the client's CHAP username to myiscsiusername and password to
-   myiscsipassword:
+#. Set the initiator CHAP username and password which the target would
+   use when authenticating the initiator:
 
    .. code-block:: console
 
-       > /iscsi-target...at:rh7-client>  auth username=myiscsiusername password=myiscsipassword
+       > /iscsi-target...at:rh7-client>  auth username=myusername password=mypassword
 
    .. warning::
       CHAP must always be configured. Without CHAP, the target will
       reject any login requests.
 
+   To use mutual (bidirectional) authentication, also set the target CHAP
+   username and password which the initiator would use when authenticating
+   the target:
+
+   .. code-block:: console
+
+       > /iscsi-target...at:rh7-client>  auth username=myusername password=mypassword mutual_username=mytgtusername mutual_password=mytgtpassword
+
+   .. note::
+      CHAP usernames must be between 8 and 64 characters long.  Valid
+      characters: ``0`` to ``9``, ``a`` to ``z``, ``A`` to ``Z``, ``@``,
+      ``_``, ``-``, ``.``, ``:``.
+
+   .. note::
+      CHAP passwords must be between 12 and 16 characters long.  Valid
+      characters: ``0`` to ``9``, ``a`` to ``z``, ``A`` to ``Z``, ``@``,
+      ``_``, ``-``, ``/``.
+
+   .. note::
+      For mutual CHAP, initiator and target usernames and passwords
+      must not be the same.
+
 #. Add the disk to the client:
 
    .. code-block:: console