src/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.4; or Linux kernel v4.14 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-config-2.3`` 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 #. As ``root``, on all iSCSI gateway nodes, install the
  51    ``ceph-iscsi-cli`` package:
  52
  53    ::
  54
  55        # yum install ceph-iscsi-cli
  56
  57 #. As ``root``, on all iSCSI gateway nodes, install the ``tcmu-runner``
  58    package:
  59
  60    ::
  61
  62        # yum install tcmu-runner
  63
  64 #. As ``root``, on a iSCSI gateway node, create a file named
  65    ``iscsi-gateway.cfg`` in the ``/etc/ceph/`` directory:
  66
  67    ::
  68
  69        # touch /etc/ceph/iscsi-gateway.cfg
  70
  71    #. Edit the ``iscsi-gateway.cfg`` file and add the following lines:
  72
  73       ::
  74
  75           [config]
  76           # Name of the Ceph storage cluster. A suitable Ceph configuration file allowing
  77           # access to the Ceph storage cluster from the gateway node is required, if not
  78           # colocated on an OSD node.
  79           cluster_name = ceph
  80
  81           # Place a copy of the ceph cluster's admin keyring in the gateway's /etc/ceph
  82           # drectory and reference the filename here
  83           gateway_keyring = ceph.client.admin.keyring
  84
  85
  86           # API settings.
  87           # The API supports a number of options that allow you to tailor it to your
  88           # local environment. If you want to run the API under https, you will need to
  89           # create cert/key files that are compatible for each iSCSI gateway node, that is
  90           # not locked to a specific node. SSL cert and key files *must* be called
  91           # 'iscsi-gateway.crt' and 'iscsi-gateway.key' and placed in the '/etc/ceph/' directory
  92           # on *each* gateway node. With the SSL files in place, you can use 'api_secure = true'
  93           # to switch to https mode.
  94
  95           # To support the API, the bear minimum settings are:
  96           api_secure = false
  97
  98           # Additional API configuration options are as follows, defaults shown.
  99           # api_user = admin
 100           # api_password = admin
 101           # api_port = 5001
 102           # trusted_ip_list = 192.168.0.10,192.168.0.11
 103
 104       .. important::
 105         The ``iscsi-gateway.cfg`` file must be identical on all iSCSI gateway nodes.
 106
 107    #. As ``root``, copy the ``iscsi-gateway.cfg`` file to all iSCSI
 108       gateway nodes.
 109
 110 #. As ``root``, on all iSCSI gateway nodes, enable and start the API
 111    service:
 112
 113    ::
 114
 115        # systemctl enable rbd-target-api
 116        # systemctl start rbd-target-api
 117
 118 **Configuring:**
 119
 120 #. As ``root``, on a iSCSI gateway node, start the iSCSI gateway
 121    command-line interface:
 122
 123    ::
 124
 125        # gwcli
 126
 127 #. Creating the iSCSI gateways:
 128
 129    ::
 130
 131        >/iscsi-target create iqn.2003-01.com.redhat.iscsi-gw:<target_name>
 132        > goto gateways
 133        > create <iscsi_gw_name> <IP_addr_of_gw>
 134        > create <iscsi_gw_name> <IP_addr_of_gw>
 135
 136 #. Adding a RADOS Block Device (RBD):
 137
 138    ::
 139
 140        > cd /iscsi-target/iqn.2003-01.com.redhat.iscsi-gw:<target_name>/disks/
 141        >/disks/ create pool=<pool_name> image=<image_name> size=<image_size>m|g|t
 142
 143 #. Creating a client:
 144
 145    ::
 146
 147        > goto hosts
 148        > create iqn.1994-05.com.redhat:<client_name>
 149        > auth chap=<user_name>/<password> | nochap
 150
 151
 152   .. warning::
 153       CHAP must always be configured. Without CHAP, the target will
 154       reject any login requests.
 155
 156 #. Adding disks to a client:
 157
 158    ::
 159
 160        >/iscsi-target..eph-igw/hosts> cd iqn.1994-05.com.redhat:<client_name>
 161        > disk add <pool_name>.<image_name>
 162
 163 The next step is to configure the iSCSI initiators.