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