lrbd.conf man page

lrbd.conf — configuration object for Ceph RBD images

Description

The lrbd.conf holds the configuration describing the relationships of pools, images, luns, gateways, targets, tpgs, initiators and authentication. Although the lrbd command displays the configuration as a single text file, lrbd.conf is the name of the object in a pool and never resides on a filesystem. Each pool can have at most one configuration object. If a pool has no RBD images configured for iSCSI access, that pool will not have a configuration object. The lrbd.conf contains four sections: pools, authentication, targets and portals.

All configuration settings are stored in extended attributes. The extended attributes are targets, portals, hostname, target, _hostname and _target. The hostname and target extended attributes contain the pool configuration.

Pools

Ceph pools may contain objects and RBD images. An RBD image can be mapped by a gateway host, shared via an iSCSI target and accessed by an iSCSI initiator. Likewise, multiple pools may contain multiple RBD images, which can be mapped by multiple gateways and accessed by multiple initiators. Additionally, gateways may grant access across multiple network paths or portals. The following JSON structure represents the pool configuration:

"pools": [
{
"pool": pool_name ,

"gateways": [
{
"host": hostname ,
"tpg": [
{
"image": image_name ,
"portal": portal_group ,
"initiator": initiator_iqn }, ... ],
"target": target_iqn ,
"tpg": [
{
"image": image_name ,
"initiator": initiator_iqn }, ... ], }, ... ] }

]

Authentication

Since gateways may have different security requirements, configurations for authentication are tied to each host and target. The _host and _target extended attributes store the authentication configuration and credentials. A gateway host will only read the relevant entries. These entries are combined under a common structure named auth.

Authentication for iSCSI is flexible. Authentication may be absent or disabled, have common credentials from all initiators to a gateway target or have specific credentials for each initiator to a gateway target. Additionally, discovery authentication can be enabled independently which allows browsing of targets on a gateway with proper credentials. Lastly, iSCSI supports mutual authentication mandating that a gateway target must authenticate itself to an initiator. All methods support mutual athentication.

Many of the authentication sections may be absent, or present but disabled. This allows for quick experimentation prior to finalizing a production configuration. The following JSON structure represents the entire authentication configuration:

"auth": [
{
"host|target": hostname|target_iqn ,

"authentication": none|tpg|tpg+identified|acls ,
"tpg": {
"userid": initiator_userid ,
"password", initiator_password ,
"mutual": enable|disable ,
"userid_mutual": target_userid ,
"password_mutual": target_password
"acls": [
{
"iqn": initiator_iqn ,
"userid": initiator_userid ,
"password", initiator_password ,
"mutual": enable|disable ,
"userid_mutual": target_userid ,
"password_mutual": target_password }, ... ],
"discovery": {
"auth": enable|disable ,
"userid": initiator_userid ,
"password", initiator_password ,
"mutual": enable|disable ,
"userid_mutual": target_userid ,
"password_mutual": target_password } }, }, ...

]

Targets

The target section is optional, but required for environments needing static iqns. Dynamically generated values are only suitable for demonstrations. Generate static values with iscsi-name(5).

The target structure is stored in the extended attribute targets. A target is associated with a host or group of hosts. For locally configured targets, use the host attribute. For redundantly configured targets, use hosts.

"target": [
{
"target": target_iqn ,

"host": hostname
"hosts":
{
"host": host1, "portal": portal1 }, ... ], }, ... ]

Portals

The portal section contains named groups of addresses. Within a pool configuration, a tpg section references a portal group. Multiple addresses provide redundancy on a single gateway or across multiple gateways. The names of the groups are arbitrary and can be set to anything meaningful.

Any addresses not available on a host are placed in a separate TPG. This remote TPG is disabled, but will advertise all the addresses for a given target. This is how high availability can be achieved for an iSCSI initiator across multiple gateways.

The portal structure is stored in the extended attribute portals. A portal has a name and a group of addresses. A single address is permitted. An address may contain a port delimited by space, such as "192.168.1.100 3261".

"portals": [
{
"name": portal_name ,

"addresses": [
address , ... ], ... }

]

Interaction with Target Service

The target service restores a local, saved configuration when enabled. The target service is unnecessary for the lrbd service since the configuration is saved within Ceph. If all storage for iSCSI access is within Ceph, the target service should be disabled.

With care, both services can be enabled applying both a static configuration of local storage and the dynamically applied configuration from Ceph. Systemd will start the target service and apply any configuration saved via targetcli saveconfig. Then, the lrbd service will apply its configuration potentially overwriting any shared sections. Authentication would be the most likely cause of conflict.

To eliminate the chance of conflict, any locally saved configuration should use a unique target. Additionally, avoid saving the dynamic configuration locally. Also, realize that clearing the configuration by stopping the target.service or running lrbd -C will remove all configuration applied from either method.

Caveats

The configuration is validated syntactically only. It's quite possible to overcomplicate a configuration unnecessarily by creating multiple targets or tpgs when fewer are needed.

Files

/usr/share/doc/packages/lrbd/samples/*

Several example configurations. Portions of sections may be combined into a desriable configuration.

Author

Eric Jackson <ejackson@suse.com>

See Also

lrbd.conf(5), targetcli(8), iscsi-name(5),

Referenced By

lrbd(8).