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