]>
Commit | Line | Data |
---|---|---|
181888fb FG |
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 | ||
b32b8144 | 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>`_ |
181888fb FG |
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 | ||
b32b8144 | 24 | - ``ceph-iscsi-config-2.4`` or newer package |
181888fb FG |
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 | ||
b32b8144 FG |
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 | ||
181888fb FG |
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 | ||
b32b8144 FG |
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 | ||
181888fb FG |
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 | ||
b32b8144 FG |
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 | ||
181888fb FG |
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 | ||
b32b8144 | 148 | # systemctl daemon-reload |
181888fb FG |
149 | # systemctl enable rbd-target-api |
150 | # systemctl start rbd-target-api | |
151 | ||
152 | **Configuring:** | |
153 | ||
b32b8144 FG |
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 | ||
181888fb FG |
160 | #. As ``root``, on a iSCSI gateway node, start the iSCSI gateway |
161 | command-line interface: | |
162 | ||
163 | :: | |
164 | ||
165 | # gwcli | |
166 | ||
b32b8144 FG |
167 | #. Go to iscsi-targets and create a target with the name |
168 | iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw: | |
181888fb FG |
169 | |
170 | :: | |
171 | ||
b32b8144 FG |
172 | > /> cd /iscsi-target |
173 | > /iscsi-target> create iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw | |
181888fb | 174 | |
b32b8144 FG |
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. | |
181888fb FG |
179 | |
180 | :: | |
181 | ||
b32b8144 FG |
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 | |
181888fb | 185 | |
b32b8144 FG |
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: | |
181888fb FG |
189 | |
190 | :: | |
191 | ||
b32b8144 FG |
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 | :: | |
181888fb | 217 | |
b32b8144 | 218 | > /iscsi-target...at:rh7-client> auth chap=myiscsiusername/myiscsipassword |
181888fb | 219 | |
b32b8144 | 220 | .. warning:: |
181888fb FG |
221 | CHAP must always be configured. Without CHAP, the target will |
222 | reject any login requests. | |
223 | ||
b32b8144 | 224 | #. Add the disk to the client: |
181888fb FG |
225 | |
226 | :: | |
227 | ||
b32b8144 | 228 | > /iscsi-target...at:rh7-client> disk add rbd.disk_1 |
181888fb FG |
229 | |
230 | The next step is to configure the iSCSI initiators. |