Warning

This documentation is actively being updated as the project evolves and may not be complete in all areas.

iSCSI server 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"
      # 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 default IP.	str	no	auto
port	TCP port the target listens on.	int	no	3260

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