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 kernel <https://shaman.ceph.com/repos/kernel/ceph-iscsi-stable>`_
|
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``
|
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
|
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-stable 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.
|