deb-python-rtslib-fb/doc/getting_started.md

Getting started using the rtslib API

The rtslib API wraps the LIO kernel target's configfs-based userspace configuration with an object-based, Python interface. Its operating model is that instantiating a Python object will result in that object creating the corresponding kernel object if it doesn't already exist, or will refer to the existing object if it does.

Also, note that the Python objects wrap LIO's configfs objects, but do no buffering or caching of values or properties. Setting a value on an object via rtslib results in the LIO kernel configuration being modified immediately as well -- there is no additional save or flush required.

Let's try it.

> sudo python

Configuring LIO must be done by root, so run the python REPL as root.

>>> from rtslib import FileIOStorageObject
>>> f = FileIOStorageObject("test1", "/tmp/test.img", 100000000)

FileIO storage objects enable a file to serve as a disk image. In this example, a few things are happening. First, since a backing file path is given and does not yet exist, rtslib creates the backing file at /tmp/test.img with a size of 100000000 bytes. Next, rtslib configures LIO to use the file to back a fileio storage object called "test1".

The storage object has a number of properties.

>>> f.status
'deactivated'

This shows that while the backstore has been registered, it hasn't yet been exported via a fabric. Now, let's create a fabric.

>>> from rtslib import FabricModule, Target, TPG
>>> iscsi = FabricModule("iscsi")

Fabric objects are singleton objects. The preferred way to obtain a reference to one is via the FabricModule factory method, as shown. Then, we can create a Target, an instance of that fabric.

>>> target = Target(iscsi)

For other fabrics that are linked to actual hardware resources, we would have also needed to supply a valid "wwn" parameter that matched available hardware IDs. But for iscsi, we can omit this and rtslib will autogenerate one.

>>> target.wwn
'iqn.2003-01.org.linux-iscsi.localhost.x8664:sn.c11be18bebc3'

Next, we must create a TPG. iSCSI allows a single named target to have multiple independent configurations within it, divided into Target Port Groups, or TPGs. Usually one is enough, so we just need to create one, and then all further configuration will be on the TPG.

>>> tpg = TPG(target, 1)

Our TPG needs to listen on a TCP port for incoming connections from initiators, so let's set that up.

>>> from rtslib import NetworkPortal, NodeACL, LUN, MappedLUN
>>> portal = NetworkPortal(tpg, "0.0.0.0", 3260)

Now LIO is listening on all IP addresses, on port 3260, the iSCSI default. But, we aren't exporting any luns yet!

>>> lun = LUN(tpg, 0, f)

We've just assigned the FileIO storage object to the TPG. as we can see:

>>> f.status
'activated'

...the storage object is now active and linked to the TPG.

The final thing to configure is Node ACLs. There are some authentication modes where just assigning a LUN to a TPG will export it to all initiators (see targetcli manpage for more info), but usually one creates individual permissions and LUN mappings for each initiator.

LIO configures initiator access via initiator IQN, instead of some other targets that are based on initiator IP address. (For open-iscsi, the autogenerated initiator IQN is in "/etc/iscsi/initiatorname.iscsi".)

>>> nodeacl = NodeACL(tpg, "iqn.2004-03.com.example.foo:0987")

When we are using nodeacl-based authentication, i.e. when generate_node_acls is 0, we then need to map the tpg lun to the nodeacl. This is handy in that each initiator can have its own view of the available LUNs.

>>> mlun = MappedLUN(nodeacl, 5, lun)

Finding associated objects

All rtslib objects have properties to obtain other related objects. For example, if you have a TPG object called "tpg", then tpg.parent_target will be the Target that contains the tpg.

>>> tpg
<TPG 1>

>>> tpg.parent_target
<Target iqn.2003-01.org.linux-iscsi.localhost.x8664:sn.c11be18bebc3>

The FabricModule object is then accessible from the target:

>>> tpg.parent_target.fabric_module.name
'iscsi'

Going down the hierarchy, an object can have multiple child objects of a given type, so a list is returned:

>>> iscsi.targets
<generator object _list_targets at 0x2836f00>

Actually it's a Python generator, list's less memory-intensive cousin. If we really want a list, call:

>>> list(iscsi.targets)
[<Target iqn.2003-01.org.linux-iscsi.localhost.x8664:sn.c11be18bebc3>]

Finding objects using RTSRoot()

The RTSRoot object enables finding all rtslib objects of a type that are configured on the system.

>>> root = rtslib.RTSRoot()
>>> list(root.storage_objects)
[<FileIOStorageObject fileio/test1>]

RTSRoot contains generators for all levels of objects. For example, if we want to obtain all NodeACL objects, instead of needing nested for loops to iterate through all fabrics, then all targets, then all tpgs, then all node acls, the root.node_acls generator iterates through NodeACLs wherever they are:

>>> list(root.node_acls)
[<NodeACL iqn.2004-03.com.example.foo:0987>,
 <NodeACL iqn.2004-03.com.example.foo:1234>]

Other handy things to try

All objects have a dump() method, which outputs a dict of the object's current state.

>>> mlun.dump()
{'index': 5, 'tpg_lun': 0, 'write_protect': False}

Finally, rtslib is just a wrapper around LIO's configfs interface, which is usually mounted at /sys/kernel/config/target. Poking around there may also help to understand what's going on.

Other sample code

While targetcli uses rtslib, it has a parallel configshell-based tree structure that may make it less helpful as a reference. Focus on 'rtsnode' objects -- these are references to rtslib objects, as described here.

Also, the 'targetd' project (https://github.com/agrover/targetd) uses rtslib for its kernel target support, see 'targetd/block.py' for more examples of rtslib usage.