Merge pull request #19931 from mikechristie/wip-doc-mnc-iscsi-updates

Misc iSCSI doc updates

Reviewed-by: John Wilkins <jowilkin@redhat.com>

doc/rbd/iscsi-initiator-esx.rst

@@ -6,32 +6,100 @@ iSCSI Initiator for VMware ESX
 
 -  VMware ESX 6.5 or later using Virtual Machine compatibility 6.5 with VMFS 6.
 
-
 **iSCSI Discovery and Multipath Device Setup:**
 
-#. From vSphere, open the Storage Adapters, on the Configuration tab. Right click
-   on the iSCSI Software Adapter and select Properties.
+The following instructions will use the default vSphere web client and esxcli.
 
-#. In the General tab click the "Advanced" button and in the "Advanced Settings"
-   set RecoveryTimeout to 25.
+#. Enable Software iSCSI
 
-#. 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.
+   .. image:: ../images/esx_web_client_storage_main.png
+      :align: center
 
-#. 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.
+   Click on "Storage" from "Navigator", and select the "Adapters" tab.
+   From there right click "Confgure iSCSI".
 
-#. 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.
+#. Set Initiator Name
 
-#. Close the iSCSI Initiator Properties window. A prompt will ask to rescan the
-   iSCSI software adapter. Select Yes.
+   .. image:: ../images/esx_config_iscsi_main.png
+      :align: center
 
-#. In the Details pane, the LUN on the iSCSI target will be displayed. Right click
-   on a device and select "Manage Paths".
+   If the initiator name in the "Name & alias" section is not the same name
+   used when creating the client during gwcli setup or the initiator name used
+   in the ansible client_connections client variable, then ssh to the ESX
+   host and run the following esxcli commands to change the name.
 
-#. On the Manage Paths window, select “Most Recently Used (VMware)” for the policy
-   path selection. Close and repeat for the other disks.
+   Get the adapter name for Software iSCSI:
+
+   ::
+
+       > esxcli iscsi adapter list
+       > Adapter  Driver     State   UID            Description
+       > -------  ---------  ------  -------------  ----------------------
+       > vmhba64  iscsi_vmk  online  iscsi.vmhba64  iSCSI Software Adapter
+
+   In this example the software iSCSI adapter is vmhba64 and the initiator
+   name is iqn.1994-05.com.redhat:rh7-client:
+
+    ::
+
+        > esxcli iscsi adapter set -A vmhba64 -n iqn.1994-05.com.redhat:rh7-client
+
+#. Setup CHAP
+
+   .. image:: ../images/esx_chap.png
+      :align: center
+
+   Expand the CHAP authentication section, select "Do not use CHAP unless
+   required by target" and enter the CHAP credentials used in the gwcli
+   auth command or ansible client_connections credentials variable.
+
+   The Mutual CHAP authentication section should have "Do not use CHAP"
+   selected.
+
+   Warning: There is a bug in the web client where the requested CHAP
+   settings are not always used initially. On the iSCSI gateway kernel
+   logs you will see the error:
+
+    ::
+
+       > kernel: CHAP user or password not set for Initiator ACL
+       > kernel: Security negotiation failed.
+       > kernel: iSCSI Login negotiation failed.
+
+   To workaround this set the CHAP settings with the esxcli command. Here
+   authname is the username and secret is the password used in previous
+   examples:
+
+   ::
+
+       > esxcli iscsi adapter auth chap set --direction=uni --authname=myiscsiusername --secret=myiscsipassword --level=discouraged -A vmhba64
+
+#. Configure iSCSI Settings
+
+   .. image:: ../images/esx_iscsi_recov_timeout.png
+      :align: center
+
+   Expand Advanced settings and set the "RecoveryTimeout" to 25.
+
+#. Set the discovery address
+
+   .. image:: ../images/esx_config_iscsi_main.png
+      :align: center
+
+   In the Dynamic targets section, click "Add dynamic target" and under
+   Addresses add one of the gateway IP addresses added during the iSCSI
+   gateway setup stage in the gwcli section or an IP set in the ansible
+   gateway_ip_list variable. Only one address needs to be added as the gateways
+   have been setup so all the iSCSI portals are returned during discovery.
+
+   Finally, click the "Save configuration" button. In the Devices tab, you
+   should see the RBD image.
+
+   The LUN should be automatically configured and using the ALUA SATP and
+   MRU PSP. Other SATPs and PSPs must not be used. This can be verified with
+   the esxcli command:
+
+   ::
+
+       > esxcli storage nmp path list -d eui.your_devices_id
 
-Now the disks can be used for datastores.

doc/rbd/iscsi-initiators.rst

@@ -8,6 +8,12 @@ Configuring the iSCSI Initiators
 
 - `iSCSI Initiator for VMware ESX <../iscsi-initiator-esx>`_
 
+    .. warning::
+
+        Applications that use SCSI persistent group reservations (PGR) and
+        SCSI 2 based reservations are not supported when exporting a RBD image
+        through more than one iSCSI gateway.
+
 .. toctree::
   :maxdepth: 1
   :hidden:

doc/rbd/iscsi-target-ansible.rst

@@ -11,7 +11,7 @@ install, and configure the Ceph iSCSI gateway for basic operation.
 
 -  A running Ceph Luminous (12.2.x) cluster or newer
 
--  RHEL/CentOS 7.4; or Linux kernel v4.14 or newer
+-  RHEL/CentOS 7.5; Linux kernel v4.17 or newer; or the `Ceph iSCSI client kernel <https://shaman.ceph.com/repos/kernel/ceph-iscsi-stable>`_
 
 -  The ``ceph-iscsi-config`` package installed on all the iSCSI gateway nodes
 

doc/rbd/iscsi-target-cli-manual-install.rst

@@ -0,0 +1,149 @@
+==================================
+Manual ceph-iscsi-cli Installation
+==================================
+
+**Requirements**
+
+The following packages will be used by ceph-iscsi-cli and target tools.
+They must be installed from your Linux distribution's software repository
+on each machine that will be a iSCSI gateway:
+
+-  libnl3
+-  libkmod
+-  librbd1
+-  pyparsing
+-  python kmod
+-  python pyudev
+-  python gobject
+-  python kmod
+-  python pyudev
+-  python gobject
+-  python urwid
+-  python pyparsing
+-  python rados
+-  python rbd
+-  python netaddr
+-  python netifaces
+-  python crypto
+-  python requests
+-  python flask
+-  pyOpenSSL
+
+**Packages**
+
+-  Linux Kernel
+
+   If not using a distro kernel that contains the required Ceph iSCSI patches,
+   then Linux kernel v4.17 or newer or the ceph-client ceph-iscsi-stable
+   branch must be used. To get the ceph-iscsi-stable branch run:
+
+   ::
+
+       > git clone https://github.com/ceph/ceph-client.git
+       > git checkout ceph-iscsi-stable
+
+   Check your distro's docs for specific instructions on how to build a
+   kernel. The only Ceph iSCSI specific requirements are the following
+   build options must be enabled:
+
+   ::
+
+       CONFIG_TARGET_CORE=m
+       CONFIG_TCM_USER2=m
+       CONFIG_ISCSI_TARGET=m
+
+-  tcmu-runner
+
+   Installation:
+
+   ::
+
+       > git clone https://github.com/open-iscsi/tcmu-runner
+       > cd tcmu-runner
+
+   Ceph iSCSI requires systemd so the following build command must be used:
+
+   ::
+
+       > cmake -Dwith-glfs=false -Dwith-qcow=false -DSUPPORT_SYSTEMD=ON -DCMAKE_INSTALL_PREFIX=/usr
+       > make install
+
+   Enable and start the daemon:
+
+   ::
+
+       > systemctl daemon-reload
+       > systemctl enable tcmu-runner
+       > systemctl start tcmu-runner
+
+-  rtslib-fb
+
+   Installation:
+
+   ::
+
+       > git clone https://github.com/open-iscsi/rtslib-fb.git
+       > cd rtslib-fb
+       > python setup.py install
+
+-  configshell-fb
+
+   Installation:
+
+   ::
+
+       > git clone https://github.com/open-iscsi/configshell-fb.git
+       > cd configshell-fb
+       > python setup.py install
+
+-  targetcli-fb
+
+   Installation:
+
+   ::
+
+       > git clone https://github.com/open-iscsi/targetcli-fb.git
+       > cd targetcli-fb
+       > python setup.py install
+       > mkdir /etc/target
+       > mkdir /var/target
+
+   .. warning:: The ceph-iscsi tools assume they are managing all targets
+      on the system. If targets have been setup and are being managed by
+      targetcli the target service must be disabled.
+
+-  ceph-iscsi-config
+
+   Installation:
+
+   ::
+
+       > git clone https://github.com/ceph/ceph-iscsi-config.git
+       > cd ceph-iscsi-config
+       > python setup.py install
+       > cp usr/lib/systemd/system/rbd-target-gw.service /lib/systemd/system
+
+   Enable and start the daemon:
+
+   ::
+
+       > systemctl daemon-reload
+       > systemctl enable rbd-target-gw
+       > systemctl start rbd-target-gw
+
+-  ceph-iscsi-cli
+
+   Installation:
+
+   ::
+
+       > git clone https://github.com/ceph/ceph-iscsi-cli.git
+       > cd ceph-iscsi-cli
+       > python setup.py install
+       > cp usr/lib/systemd/system/rbd-target-api.service /lib/systemd/system
+
+
+Installation is complete. Proceed to the setup section in the
+`main ceph-iscsi-cli page`_.
+
+.. _`main ceph-iscsi-cli page`: ../iscsi-target-cli

doc/rbd/iscsi-target-cli.rst

@@ -11,7 +11,7 @@ install, and configure the Ceph iSCSI gateway for basic operation.
 
 -  A running Ceph Luminous or later storage cluster
 
--  RHEL/CentOS 7.4; or Linux kernel v4.14 or newer
+-  RHEL/CentOS 7.5; Linux kernel v4.17 or newer; or the `Ceph iSCSI client kernel <https://shaman.ceph.com/repos/kernel/ceph-iscsi-stable>`_
 
 -  The following packages must be installed from your Linux distribution's software repository:
 
@@ -47,6 +47,18 @@ to the *Installing* section:
 
 **Installing:**
 
+If you are using the upstream ceph-iscsi-cli package follow the
+`manual install instructions`_.
+
+.. _`manual install instructions`: ../iscsi-target-cli-manual-install
+
+.. toctree::
+   :hidden:
+
+   iscsi-target-cli-manual-install
+
+For rpm based instructions execute the following commands:
+
 #. As ``root``, on all iSCSI gateway nodes, install the
    ``ceph-iscsi-cli`` package:
 
@@ -61,6 +73,20 @@ to the *Installing* section:
 
        # yum install tcmu-runner
 
+**Setup:**
+
+#. gwcli requires a pool with the name ``rbd``, so it can store metadata
+   like the iSCSI configuration. To check if this pool has been created
+   run:
+
+   ::
+
+       # ceph osd lspools
+
+   If it does not exist instructions for creating pools can be found on the
+   `RADOS pool operations page
+   <http://docs.ceph.com/docs/master/rados/operations/pools/>`_.
+
 #. As ``root``, on a iSCSI gateway node, create a file named
    ``iscsi-gateway.cfg`` in the ``/etc/ceph/`` directory:
 
@@ -101,6 +127,13 @@ to the *Installing* section:
           # api_port = 5001
           # trusted_ip_list = 192.168.0.10,192.168.0.11
 
+      ..note::
+        trusted_ip_list is a list of IP addresses on each iscsi gateway that
+        will be used for management operations like target creation, lun
+        exporting, etc. The IP can be the same that will be used for iSCSI
+        data, like READ/WRITE commands to/from the RBD image, but using
+        separate IPs is recommended.
+
       .. important::
         The ``iscsi-gateway.cfg`` file must be identical on all iSCSI gateway nodes.
 
@@ -112,11 +145,18 @@ to the *Installing* section:
 
    ::
 
+       # systemctl daemon-reload
        # systemctl enable rbd-target-api
        # systemctl start rbd-target-api
 
 **Configuring:**
 
+gwcli will create and configure the iSCSI target and RBD images and copy the
+configuration across the gateways setup in the last section. Lower level
+tools, like targetcli and rbd, can be used to query the local configuration,
+but should not be used to modify it. This next section will demonstrate how
+to create a iSCSI target and export a RBD image as LUN 0.
+
 #. As ``root``, on a iSCSI gateway node, start the iSCSI gateway
    command-line interface:
 
@@ -124,40 +164,67 @@ to the *Installing* section:
 
        # gwcli
 
-#. Creating the iSCSI gateways:
+#. Go to iscsi-targets and create a target with the name
+   iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw:
 
    ::
 
-       >/iscsi-target create iqn.2003-01.com.redhat.iscsi-gw:<target_name>
-       > goto gateways
-       > create <iscsi_gw_name> <IP_addr_of_gw>
-       > create <iscsi_gw_name> <IP_addr_of_gw>
+       > /> cd /iscsi-target
+       > /iscsi-target>  create iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw
 
-#. Adding a RADOS Block Device (RBD):
+#. Create the iSCSI gateways. The IPs used below are the ones that will be
+   used for iSCSI data like READ and WRITE commands. They can be the
+   same IPs used for management operations listed in trusted_ip_list,
+   but it is recommended that different IPs are used.
 
    ::
 
-       > cd /iscsi-target/iqn.2003-01.com.redhat.iscsi-gw:<target_name>/disks/
-       >/disks/ create pool=<pool_name> image=<image_name> size=<image_size>m|g|t
+       > /iscsi-target> cd iqn.2003-01.com.redhat.iscsi-gw:ceph-igw/gateways
+       > /iscsi-target...-igw/gateways>  create ceph-gw-1 10.172.19.21
+       > /iscsi-target...-igw/gateways>  create ceph-gw-2 10.172.19.22
 
-#. Creating a client:
+   If not using RHEL/CentOS or using an upstream or ceph-iscsi-stable kernel,
+   the skipchecks=true argument must be used. This will avoid the Red Hat kernel
+   and rpm checks:
 
    ::
 
-       > goto hosts
-       > create iqn.1994-05.com.redhat:<client_name>
-       > auth chap=<user_name>/<password> | nochap
+       > /iscsi-target> cd iqn.2003-01.com.redhat.iscsi-gw:ceph-igw/gateways
+       > /iscsi-target...-igw/gateways>  create ceph-gw-1 10.172.19.21 skipchecks=true
+       > /iscsi-target...-igw/gateways>  create ceph-gw-2 10.172.19.22 skipchecks=true
 
+#. Add a RBD image with the name disk_1 in the pool rbd:
 
-  .. warning::
+   ::
+
+       > /iscsi-target...-igw/gateways> cd /disks
+       > /disks> create pool=rbd image=disk_1 size=90G
+
+   .. warning::
+       There can not be any periods (.) in the pool name or in the image name.
+
+#. Create a client with the initiator name iqn.1994-05.com.redhat:rh7-client:
+
+   ::
+
+       > /disks> cd /iscsi-target/iqn.2003-01.com.redhat.iscsi-gw:ceph-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:
+
+   ::
+
+       > /iscsi-target...at:rh7-client>  auth chap=myiscsiusername/myiscsipassword
+
+   .. warning::
       CHAP must always be configured. Without CHAP, the target will
       reject any login requests.
 
-#. Adding disks to a client:
+#. Add the disk to the client:
 
    ::
 
-       >/iscsi-target..eph-igw/hosts> cd iqn.1994-05.com.redhat:<client_name>
-       > disk add <pool_name>.<image_name>
+       > /iscsi-target...at:rh7-client> disk add rbd.disk_1
 
 The next step is to configure the iSCSI initiators.

doc/rbd/iscsi-targets.rst

@@ -8,7 +8,7 @@ within OpenStack environments. Starting with the Ceph Luminous release,
 block-level access is expanding to offer standard iSCSI support allowing
 wider platform usage, and potentially opening new use cases.
 
--  RHEL/CentOS 7.4; or Linux kernel v4.14 or newer
+-  RHEL/CentOS 7.5; Linux kernel v4.17 or newer; or the `Ceph iSCSI client kernel <https://shaman.ceph.com/repos/kernel/ceph-iscsi-stable>`_
 
 -  A working Ceph Storage cluster, deployed with ``ceph-ansible`` or using the command-line interface