iSCSI Driver

jumpstarter-driver-iscsi provides a lightweight iSCSI target implementation powered by the Linux RFC-tgt framework via the rtslib-fb Python bindings.

⚠️ The driver creates and manages an iSCSI target (server). To access the exported LUNs you still need a separate iSCSI initiator (client) on the machine running your test-code / DUT.

---

Installation

rtslib-fb relies on the in-kernel LIO target framework which is packaged differently by each distribution. You should be able to run sudo targetcli without errors before you start the Jumpstarter driver.

Fedora:

$ sudo dnf install targetcli python3-rtslib

Finally, install the driver itself from the Jumpstarter package index:

$ pip3 install --extra-index-url https://pkg.jumpstarter.dev/simple jumpstarter-driver-iscsi

Configuration

The driver is configured through the exporter YAML file. A minimal example exports the local file disk.img as a 5 GiB LUN:

export:
  iscsi:
    type: jumpstarter_driver_iscsi.driver.ISCSI
    config:
      root_dir: "/var/lib/iscsi"
      target_name: "demo"
      remove_created_on_close: false  # Keep disk images persistent (default)
      block_device_allowlist:         # Required to use is_block=True LUNs
        - /dev/sda
        - /dev/disk/by-id/my-disk
      # When size_mb is 0 a pre-existing file size is used.

Config parameters

Parameter	Description	Type	Required	Default
root_dir	Directory where image files will be stored	str	no	/var/lib/iscsi
iqn_prefix	IQN prefix to use when building the target IQN	str	no	iqn.2024-06.dev.jumpstarter
target_name	The target name appended to the IQN prefix	str	no	target1
host	IP address to bind the target to. Empty string will auto-detect	str	no	auto
port	TCP port the target listens on	int	no	3260
remove_created_on_close	Automatically remove created files/directories when driver closes	bool	no	false
block_device_allowlist	List of allowed block device paths for is_block=True LUNs. Symlinks are resolved before matching. Must be set to use block devices.	list[str]	no	[] (empty - block devices disabled)

File Management

The iSCSI server driver automatically tracks disk image files and directories created during the session. By default, remove_created_on_close is set to false to preserve disk images that are typically reused across test sessions. Set to true if you want temporary disk images to be cleaned up automatically.

API Reference

class jumpstarter_driver_iscsi.client.ISCSIServerClient

Client interface for iSCSI Server driver

This client provides methods to control an iSCSI target server and manage LUNs. Supports exposing files and block devices through the iSCSI protocol.

add_lun(name: str, file_path: str, size_mb: int = 0, is_block: bool = False) → str

Add a new LUN to the iSCSI target

Args:

name (str): Unique name for the LUN file_path (str): Path to the file or block device size_mb (int): Size in MB for new file (if file doesn’t exist), 0 means use existing file is_block (bool): If True, the path is treated as a block device

Returns:

str: Name of the created LUN

Raises:

ISCSIError: If the LUN cannot be created

get_host() → str

Get the host address the iSCSI server is listening on

Returns:

str: The IP address or hostname the server is bound to

get_port() → int

Get the port number the iSCSI server is listening on

Returns:

int: The port number (default is 3260)

get_target_iqn() → str

Get the IQN of the target

Returns:

str: The IQN string for connecting to this target

list_luns() → List[Dict[str, Any]]

List all configured LUNs

Returns:

List[Dict[str, Any]]: List of dictionaries with LUN information

remove_lun(name: str)

Remove a LUN from the iSCSI target

Args:

name (str): Name of the LUN to remove

Raises:

ISCSIError: If the LUN cannot be removed

start()

Start the iSCSI target server

Initializes and starts the iSCSI target server if it’s not already running. The server will listen on the configured host and port.

stop()

Stop the iSCSI target server

Stops the running iSCSI target server and releases associated resources.

Raises:

ISCSIError: If the server fails to stop

upload_image(dst_name: str, src: str | PathLike, size_mb: int = 0, operator: Operator | None = None, force_upload: bool = False) → str

Upload an image file and expose it as a LUN

Args:

dst_name (str): Name to use for the LUN and local filename src (PathBuf): Source file path to read from size_mb (int): Size in MB if creating a new image. If 0 will use source file size. operator (Operator): Optional OpenDAL operator to use for reading force_upload (bool): If True, skip file comparison and force upload

Returns:

str: Target IQN for connecting to the LUN

Raises:

ISCSIError: If the operation fails