]>
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 | ||
11fdf7f2 | 14 | - Red Hat Enterprise Linux/CentOS 7.5 (or newer); Linux kernel v4.16 (or newer) |
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 | ||
11fdf7f2 | 24 | - ``ceph-iscsi-2.7`` or newer package |
181888fb FG |
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 | ||
11fdf7f2 TL |
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 | ||
181888fb FG |
49 | #. Create a new or use an existing RADOS Block Device (RBD). |
50 | ||
51 | **Installing:** | |
52 | ||
11fdf7f2 | 53 | If you are using the upstream ceph-iscsi package follow the |
b32b8144 FG |
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 | ||
181888fb | 65 | #. As ``root``, on all iSCSI gateway nodes, install the |
11fdf7f2 | 66 | ``ceph-iscsi`` package: |
181888fb FG |
67 | |
68 | :: | |
69 | ||
11fdf7f2 | 70 | # yum install ceph-iscsi |
181888fb FG |
71 | |
72 | #. As ``root``, on all iSCSI gateway nodes, install the ``tcmu-runner`` | |
73 | package: | |
74 | ||
75 | :: | |
76 | ||
77 | # yum install tcmu-runner | |
78 | ||
b32b8144 FG |
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 | ||
181888fb FG |
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 | ||
11fdf7f2 | 133 | .. note:: |
b32b8144 FG |
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 | ||
181888fb FG |
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 | ||
b32b8144 | 151 | # systemctl daemon-reload |
181888fb FG |
152 | # systemctl enable rbd-target-api |
153 | # systemctl start rbd-target-api | |
154 | ||
155 | **Configuring:** | |
156 | ||
b32b8144 FG |
157 | gwcli will create and configure the iSCSI target and RBD images and copy the |
158 | configuration across the gateways setup in the last section. Lower level | |
159 | tools, like targetcli and rbd, can be used to query the local configuration, | |
160 | but should not be used to modify it. This next section will demonstrate how | |
161 | to create a iSCSI target and export a RBD image as LUN 0. | |
162 | ||
181888fb FG |
163 | #. As ``root``, on a iSCSI gateway node, start the iSCSI gateway |
164 | command-line interface: | |
165 | ||
166 | :: | |
167 | ||
168 | # gwcli | |
169 | ||
b32b8144 FG |
170 | #. Go to iscsi-targets and create a target with the name |
171 | iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw: | |
181888fb FG |
172 | |
173 | :: | |
174 | ||
b32b8144 FG |
175 | > /> cd /iscsi-target |
176 | > /iscsi-target> create iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw | |
181888fb | 177 | |
b32b8144 FG |
178 | #. Create the iSCSI gateways. The IPs used below are the ones that will be |
179 | used for iSCSI data like READ and WRITE commands. They can be the | |
180 | same IPs used for management operations listed in trusted_ip_list, | |
181 | but it is recommended that different IPs are used. | |
181888fb FG |
182 | |
183 | :: | |
184 | ||
11fdf7f2 | 185 | > /iscsi-target> cd iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw/gateways |
b32b8144 FG |
186 | > /iscsi-target...-igw/gateways> create ceph-gw-1 10.172.19.21 |
187 | > /iscsi-target...-igw/gateways> create ceph-gw-2 10.172.19.22 | |
181888fb | 188 | |
b32b8144 FG |
189 | If not using RHEL/CentOS or using an upstream or ceph-iscsi-test kernel, |
190 | the skipchecks=true argument must be used. This will avoid the Red Hat kernel | |
191 | and rpm checks: | |
181888fb FG |
192 | |
193 | :: | |
194 | ||
11fdf7f2 | 195 | > /iscsi-target> cd iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw/gateways |
b32b8144 FG |
196 | > /iscsi-target...-igw/gateways> create ceph-gw-1 10.172.19.21 skipchecks=true |
197 | > /iscsi-target...-igw/gateways> create ceph-gw-2 10.172.19.22 skipchecks=true | |
198 | ||
199 | #. Add a RBD image with the name disk_1 in the pool rbd: | |
200 | ||
201 | :: | |
202 | ||
203 | > /iscsi-target...-igw/gateways> cd /disks | |
204 | > /disks> create pool=rbd image=disk_1 size=90G | |
205 | ||
b32b8144 FG |
206 | #. Create a client with the initiator name iqn.1994-05.com.redhat:rh7-client: |
207 | ||
208 | :: | |
209 | ||
11fdf7f2 | 210 | > /disks> cd /iscsi-target/iqn.2003-01.com.redhat.iscsi-gw:iscsi-igw/hosts |
b32b8144 FG |
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 | |
11fdf7f2 | 218 | > /iscsi-target...at:rh7-client> auth username=myiscsiusername password=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 | ||
11fdf7f2 | 228 | > /iscsi-target...at:rh7-client> disk add rbd/disk_1 |
181888fb FG |
229 | |
230 | The next step is to configure the iSCSI initiators. |