1lrbd(5) File Formats Manual lrbd(5)
2
6 lrbd.conf - configuration object for Ceph RBD images
7
9 The lrbd.conf holds the configuration describing the relationships of
10 pools, images, luns, gateways, targets, tpgs, initiators and authenti‐
11 cation. Although the lrbd command displays the configuration as a sin‐
12 gle text file, lrbd.conf is the name of the object in a pool and never
13 resides on a filesystem. Each pool can have at most one configuration
14 object. If a pool has no RBD images configured for iSCSI access, that
15 pool will not have a configuration object. The lrbd.conf contains four
16 sections: pools, authentication, targets and portals.
17 All configuration settings are stored in extended attributes. The
19 extended attributes are targets, portals, hostname, target, _hostname
20 and _target. The hostname and target extended attributes contain the
21 pool configuration.
22 POOLS
24 Ceph pools may contain objects and RBD images. An RBD image can be
25 mapped by a gateway host, shared via an iSCSI target and accessed by an
26 iSCSI initiator. Likewise, multiple pools may contain multiple RBD
27 images, which can be mapped by multiple gateways and accessed by multi‐
28 ple initiators. Additionally, gateways may grant access across multi‐
29 ple network paths or portals. The following JSON structure represents
30 the pool configuration:
31 "pools": [
33 {
34 "pool": pool_name ,
35 "gateways": [
36 {
37 "host": hostname ,
38 "tpg": [
39 {
40 "image": image_name ,
41 "portal": portal_group ,
42 "initiator": initiator_iqn
43 }, ...
44 ],
45 "target": target_iqn ,
46 "tpg": [
47 {
48 "image": image_name ,
49 "initiator": initiator_iqn
50 }, ...
51 ],
52 }, ...
53 ]
54 }
55 ]
56 AUTHENTICATION
58 Since gateways may have different security requirements, configurations
59 for authentication are tied to each host and target. The _host and
60 _target extended attributes store the authentication configuration and
61 credentials. A gateway host will only read the relevant entries.
62 These entries are combined under a common structure named auth.
63 Authentication for iSCSI is flexible. Authentication may be absent or
65 disabled, have common credentials from all initiators to a gateway tar‐
66 get or have specific credentials for each initiator to a gateway tar‐
67 get. Additionally, discovery authentication can be enabled indepen‐
68 dently which allows browsing of targets on a gateway with proper cre‐
69 dentials. Lastly, iSCSI supports mutual authentication mandating that
70 a gateway target must authenticate itself to an initiator. All methods
71 support mutual athentication.
72 Many of the authentication sections may be absent, or present but dis‐
74 abled. This allows for quick experimentation prior to finalizing a
75 production configuration. The following JSON structure represents the
76 entire authentication configuration:
77 "auth": [
79 {
80 "host|target": hostname|target_iqn ,
81 "authentication": none|tpg|tpg+identified|acls ,
82 "tpg": {
83 "userid": initiator_userid ,
84 "password", initiator_password ,
85 "mutual": enable|disable ,
86 "userid_mutual": target_userid ,
87 "password_mutual": target_password
88 "acls": [
89 {
90 "iqn": initiator_iqn ,
91 "userid": initiator_userid ,
92 "password", initiator_password ,
93 "mutual": enable|disable ,
94 "userid_mutual": target_userid ,
95 "password_mutual": target_password
96 }, ...
97 ],
98 "discovery": {
99 "auth": enable|disable ,
100 "userid": initiator_userid ,
101 "password", initiator_password ,
102 "mutual": enable|disable ,
103 "userid_mutual": target_userid ,
104 "password_mutual": target_password
105 }
106 },
107 }, ...
108 ]
109 TARGETS
112 The target section is optional, but required for environments needing
113 static iqns. Dynamically generated values are only suitable for demon‐
114 strations. Generate static values with iscsi-name(5).
115 The target structure is stored in the extended attribute targets. A
117 target is associated with a host or group of hosts. For locally con‐
118 figured targets, use the host attribute. For redundantly configured
119 targets, use hosts.
120 "target": [
122 {
123 "target": target_iqn ,
124 "host": hostname
125 "hosts":
126 {
127 "host": host1, "portal": portal1
128 }, ...
129 ],
130 }, ...
131 ]
132 Portals
134 The portal section contains named groups of addresses. Within a pool
135 configuration, a tpg section references a portal group. Multiple
136 addresses provide redundancy on a single gateway or across multiple
137 gateways. The names of the groups are arbitrary and can be set to any‐
138 thing meaningful.
139 Any addresses not available on a host are placed in a separate TPG.
141 This remote TPG is disabled, but will advertise all the addresses for a
142 given target. This is how high availability can be achieved for an
143 iSCSI initiator across multiple gateways.
144 The portal structure is stored in the extended attribute portals. A
146 portal has a name and a group of addresses. A single address is per‐
147 mitted. An address may contain a port delimited by space, such as
148 "192.168.1.100 3261".
149 "portals": [
151 {
152 "name": portal_name ,
153 "addresses": [
154 address , ...
155 ], ...
156 }
157 ]
158
160 The target service restores a local, saved configuration when enabled.
161 The target service is unnecessary for the lrbd service since the con‐
162 figuration is saved within Ceph. If all storage for iSCSI access is
163 within Ceph, the target service should be disabled.
164 With care, both services can be enabled applying both a static configu‐
166 ration of local storage and the dynamically applied configuration from
167 Ceph. Systemd will start the target service and apply any configura‐
168 tion saved via targetcli saveconfig. Then, the lrbd service will apply
169 its configuration potentially overwriting any shared sections. Authen‐
170 tication would be the most likely cause of conflict.
171 To eliminate the chance of conflict, any locally saved configuration
173 should use a unique target. Additionally, avoid saving the dynamic
174 configuration locally. Also, realize that clearing the configuration
175 by stopping the target.service or running lrbd -C will remove all con‐
176 figuration applied from either method.
177
179 The configuration is validated syntactically only. It's quite possible
180 to overcomplicate a configuration unnecessarily by creating multiple
181 targets or tpgs when fewer are needed.
182
184 /usr/share/doc/packages/lrbd/samples/*
185 Several example configurations. Portions of sections may be
187 combined into a desriable configuration.
188
190 Eric Jackson <ejackson@suse.com>
191
193 lrbd.conf(5), targetcli(8), iscsi-name(5),
194 lrbd(5)