ceph/doc/rbd/iscsi-target-cli.rst

   1 =============================================================
   2 Configuring the iSCSI Target using the Command Line Interface
   3 =============================================================
   4
   5 The Ceph iSCSI gateway is the iSCSI target node and also a Ceph client
   6 node. The Ceph iSCSI gateway can be a standalone node or be colocated on
   7 a Ceph Object Store Disk (OSD) node. Completing the following steps will
   8 install, and configure the Ceph iSCSI gateway for basic operation.
   9
  10 **Requirements:**
  11
  12 -  A running Ceph Luminous or later storage cluster
  13
  14 -  Red Hat Enterprise Linux/CentOS 7.5 (or newer); Linux kernel v4.16 (or newer)
  15
  16 -  The following packages must be installed from your Linux distribution's software repository:
  17
  18    -  ``targetcli-2.1.fb47`` or newer package
  19
  20    -  ``python-rtslib-2.1.fb64`` or newer package
  21
  22    -  ``tcmu-runner-1.3.0`` or newer package
  23
  24    -  ``ceph-iscsi-2.7`` or newer package
  25
  26      .. important::
  27         If previous versions of these packages exist, then they must
  28         be removed first before installing the newer versions.
  29
  30 Do the following steps on the Ceph iSCSI gateway node before proceeding
  31 to the *Installing* section:
  32
  33 #. If the Ceph iSCSI gateway is not colocated on an OSD node, then copy
  34    the Ceph configuration files, located in ``/etc/ceph/``, from a
  35    running Ceph node in the storage cluster to the iSCSI Gateway node.
  36    The Ceph configuration files must exist on the iSCSI gateway node
  37    under ``/etc/ceph/``.
  38
  39 #. Install and configure the `Ceph Command-line
  40    Interface <http://docs.ceph.com/docs/master/start/quick-rbd/#install-ceph>`_
  41
  42 #. If needed, open TCP ports 3260 and 5000 on the firewall.
  43
  44    .. note::
  45       Access to port 5000 should be restricted to a trusted internal network or
  46       only the individual hosts where ``gwcli`` is used or ``ceph-mgr`` daemons
  47       are running.
  48
  49 #. Create a new or use an existing RADOS Block Device (RBD).
  50
  51 **Installing:**
  52
  53 If you are using the upstream ceph-iscsi package follow the
  54 `manual install instructions`_.
  55
  56 .. _`manual install instructions`: ../iscsi-target-cli-manual-install
  57
  58 .. toctree::
  59    :hidden:
  60
  61    iscsi-target-cli-manual-install
  62
  63 For rpm based instructions execute the following commands:
  64
  65 #. As ``root``, on all iSCSI gateway nodes, install the
  66    ``ceph-iscsi`` package:
  67
  68    ::
  69
  70        # yum install ceph-iscsi
  71
  72 #. As ``root``, on all iSCSI gateway nodes, install the ``tcmu-runner``
  73    package:
  74
  75    ::
  76
  77        # yum install tcmu-runner
  78
  79 **Setup:**
  80
  81 #. gwcli requires a pool with the name ``rbd``, so it can store metadata
  82    like the iSCSI configuration. To check if this pool has been created
  83    run:
  84
  85    ::
  86
  87        # ceph osd lspools
  88
  89    If it does not exist instructions for creating pools can be found on the
  90    `RADOS pool operations page
  91    <http://docs.ceph.com/docs/master/rados/operations/pools/>`_.
  92
  93 #. As ``root``, on a iSCSI gateway node, create a file named
  94    ``iscsi-gateway.cfg`` in the ``/etc/ceph/`` directory:
  95
  96    ::
  97
  98        # touch /etc/ceph/iscsi-gateway.cfg
  99
 100    #. Edit the ``iscsi-gateway.cfg`` file and add the following lines:
 101
 102       ::
 103
 104           [config]
 105           # Name of the Ceph storage cluster. A suitable Ceph configuration file allowing
 106           # access to the Ceph storage cluster from the gateway node is required, if not
 107           # colocated on an OSD node.
 108           cluster_name = ceph
 109
 110           # Place a copy of the ceph cluster's admin keyring in the gateway's /etc/ceph
 111           # drectory and reference the filename here
 112           gateway_keyring = ceph.client.admin.keyring
 113
 114
 115           # API settings.
 116           # The API supports a number of options that allow you to tailor it to your
 117           # local environment. If you want to run the API under https, you will need to
 118           # create cert/key files that are compatible for each iSCSI gateway node, that is
 119           # not locked to a specific node. SSL cert and key files *must* be called
 120           # 'iscsi-gateway.crt' and 'iscsi-gateway.key' and placed in the '/etc/ceph/' directory
 121           # on *each* gateway node. With the SSL files in place, you can use 'api_secure = true'
 122           # to switch to https mode.
 123
 124           # To support the API, the bear minimum settings are:
 125           api_secure = false
 126
 127           # Additional API configuration options are as follows, defaults shown.
 128           # api_user = admin
 129           # api_password = admin
 130           # api_port = 5001
 131           # trusted_ip_list = 192.168.0.10,192.168.0.11
 132
 133       .. note::
 134         trusted_ip_list is a list of IP addresses on each iscsi gateway that
 135         will be used for management operations like target creation, lun
 136         exporting, etc. The IP can be the same that will be used for iSCSI
 137         data, like READ/WRITE commands to/from the RBD image, but using
 138         separate IPs is recommended.
 139
 140       .. important::
 141         The ``iscsi-gateway.cfg`` file must be identical on all iSCSI gateway nodes.
 142
 143    #. As ``root``, copy the ``iscsi-gateway.cfg`` file to all iSCSI
 144       gateway nodes.
 145
 146 #. As ``root``, on all iSCSI gateway nodes, enable and start the API
 147    service:
 148
 149    ::
 150
 151        # systemctl daemon-reload
 152        # systemctl enable rbd-target-api
 153        # systemctl start rbd-target-api
 154
 155 **Configuring:**
 156
 157 gwcli will create and configure the iSCSI target and RBD images and copy the
 158 configuration across the gateways setup in the last section. Lower level
 159 tools, like targetcli and rbd, can be used to query the local configuration,
 160 but should not be used to modify it. This next section will demonstrate how
 161 to create a iSCSI target and export a RBD image as LUN 0.
 162
 163 #. As ``root``, on a iSCSI gateway node, start the iSCSI gateway
 164    command-line interface:
 165
 166    ::
 167
 168        # gwcli
 169
 170 #. Go to iscsi-targets and create a target with the name
 171    iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw:
 172
 173    ::
 174
 175        > /> cd /iscsi-target
 176        > /iscsi-target>  create iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw
 177
 178 #. Create the iSCSI gateways. The IPs used below are the ones that will be
 179    used for iSCSI data like READ and WRITE commands. They can be the
 180    same IPs used for management operations listed in trusted_ip_list,
 181    but it is recommended that different IPs are used.
 182
 183    ::
 184
 185        > /iscsi-target> cd iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw/gateways
 186        > /iscsi-target...-igw/gateways>  create ceph-gw-1 10.172.19.21
 187        > /iscsi-target...-igw/gateways>  create ceph-gw-2 10.172.19.22
 188
 189    If not using RHEL/CentOS or using an upstream or ceph-iscsi-test kernel,
 190    the skipchecks=true argument must be used. This will avoid the Red Hat kernel
 191    and rpm checks:
 192
 193    ::
 194
 195        > /iscsi-target> cd iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw/gateways
 196        > /iscsi-target...-igw/gateways>  create ceph-gw-1 10.172.19.21 skipchecks=true
 197        > /iscsi-target...-igw/gateways>  create ceph-gw-2 10.172.19.22 skipchecks=true
 198
 199 #. Add a RBD image with the name disk_1 in the pool rbd:
 200
 201    ::
 202
 203        > /iscsi-target...-igw/gateways> cd /disks
 204        > /disks> create pool=rbd image=disk_1 size=90G
 205
 206 #. Create a client with the initiator name iqn.1994-05.com.redhat:rh7-client:
 207
 208    ::
 209
 210        > /disks> cd /iscsi-target/iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw/hosts
 211        > /iscsi-target...eph-igw/hosts>  create iqn.1994-05.com.redhat:rh7-client
 212
 213 #. Set the client's CHAP username to myiscsiusername and password to
 214    myiscsipassword:
 215
 216    ::
 217
 218        > /iscsi-target...at:rh7-client>  auth username=myiscsiusername password=myiscsipassword
 219
 220    .. warning::
 221       CHAP must always be configured. Without CHAP, the target will
 222       reject any login requests.
 223
 224 #. Add the disk to the client:
 225
 226    ::
 227
 228        > /iscsi-target...at:rh7-client> disk add rbd/disk_1
 229
 230 The next step is to configure the iSCSI initiators.