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.fb68`` or newer package
  21
  22    -  ``tcmu-runner-1.4.0`` or newer package
  23
  24    -  ``ceph-iscsi-3.2`` 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
 153        # systemctl enable rbd-target-gw
 154        # systemctl start rbd-target-gw
 155
 156        # systemctl enable rbd-target-api
 157        # systemctl start rbd-target-api
 158
 159
 160 **Configuring:**
 161
 162 gwcli will create and configure the iSCSI target and RBD images and copy the
 163 configuration across the gateways setup in the last section. Lower level
 164 tools, like targetcli and rbd, can be used to query the local configuration,
 165 but should not be used to modify it. This next section will demonstrate how
 166 to create a iSCSI target and export a RBD image as LUN 0.
 167
 168 #. As ``root``, on a iSCSI gateway node, start the iSCSI gateway
 169    command-line interface:
 170
 171    ::
 172
 173        # gwcli
 174
 175 #. Go to iscsi-targets and create a target with the name
 176    iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw:
 177
 178    ::
 179
 180        > /> cd /iscsi-target
 181        > /iscsi-target>  create iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw
 182
 183 #. Create the iSCSI gateways. The IPs used below are the ones that will be
 184    used for iSCSI data like READ and WRITE commands. They can be the
 185    same IPs used for management operations listed in trusted_ip_list,
 186    but it is recommended that different IPs are used.
 187
 188    ::
 189
 190        > /iscsi-target> cd iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw/gateways
 191        > /iscsi-target...-igw/gateways>  create ceph-gw-1 10.172.19.21
 192        > /iscsi-target...-igw/gateways>  create ceph-gw-2 10.172.19.22
 193
 194    If not using RHEL/CentOS or using an upstream or ceph-iscsi-test kernel,
 195    the skipchecks=true argument must be used. This will avoid the Red Hat kernel
 196    and rpm checks:
 197
 198    ::
 199
 200        > /iscsi-target> cd iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw/gateways
 201        > /iscsi-target...-igw/gateways>  create ceph-gw-1 10.172.19.21 skipchecks=true
 202        > /iscsi-target...-igw/gateways>  create ceph-gw-2 10.172.19.22 skipchecks=true
 203
 204 #. Add a RBD image with the name disk_1 in the pool rbd:
 205
 206    ::
 207
 208        > /iscsi-target...-igw/gateways> cd /disks
 209        > /disks> create pool=rbd image=disk_1 size=90G
 210
 211 #. Create a client with the initiator name iqn.1994-05.com.redhat:rh7-client:
 212
 213    ::
 214
 215        > /disks> cd /iscsi-target/iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw/hosts
 216        > /iscsi-target...eph-igw/hosts>  create iqn.1994-05.com.redhat:rh7-client
 217
 218 #. Set the client's CHAP username to myiscsiusername and password to
 219    myiscsipassword:
 220
 221    ::
 222
 223        > /iscsi-target...at:rh7-client>  auth username=myiscsiusername password=myiscsipassword
 224
 225    .. warning::
 226       CHAP must always be configured. Without CHAP, the target will
 227       reject any login requests.
 228
 229 #. Add the disk to the client:
 230
 231    ::
 232
 233        > /iscsi-target...at:rh7-client> disk add rbd/disk_1
 234
 235 The next step is to configure the iSCSI initiators.