From 49f670ec80078672d01dbde18d6a7da228073e73 Mon Sep 17 00:00:00 2001 From: Sebastian Vater Date: Mon, 13 Oct 2025 15:15:02 +0200 Subject: Updated documentation README.md in iscsi branch. --- README.md | 114 +++++++++++++++++++++++++++++++++++++++++++++++++++-- src/server/iscsi.c | 2 +- 2 files changed, 112 insertions(+), 4 deletions(-) diff --git a/README.md b/README.md index a77a64d..0220f63 100644 --- a/README.md +++ b/README.md @@ -490,11 +490,25 @@ The _iscsi.conf_ file is the main configuration file for the iSCSI implementatio [iscsi] ; Target name check level (warning) specifying invalid check levels will default to full -; validation!). Default is Full +; validation!). Default is Relaxed ; Full Target name is checked for full standaard compliance (recommended) ; Relaxed All invalid characters according to standard will be allowed if not an IQN, NAA or EUI. ; None No checking at all (be careful) -TargetNameCheck=Full +TargetNameCheck=Relaxed + +... + +; Login/Text Operational Session Text Key: Maximum receive DataSegmentLength. +; +* The initiator or target declares the maximum data segment length in bytes it can receive in an +; iSCSI PDU. +* The transmitter (initiator or target) is required to send PDUs with a data segment that does not +; exceed MaxRecvDataSegmentLength of the receiver. A target receiver is additionally limited by +; MaxBurstLength for solicited data and FirstBurstLength for unsolicited dataAn initiator MUST NOT +; send solicited PDUs exceeding MaxBurstLength nor unsolicited PDUs exceeding FirstBurstLength (or +; FirstBurstLength-Immediate Data Length if immediate data were sent). Valid values range from 512 +; to 16777215 bytes. Default is 65536 bytes (64 KiB) +MaxRecvDataSegmentLength=65536 ... @@ -575,6 +589,100 @@ PhysicalReadOnly=true For a complete list of possible configuration options, look at the comments in the sample _iscsi.conf_ file, which describes the options in detail. -### _World Wide Name (WWN)_ to DNBD3 image mapping for standard compliance. +### _World Wide Name (WWN)_ to DNBD3 image mapping for standard compliance As the iSCSI target node name supports only a very restricted number of allowed characters, DNBD3 images also can be specified either using the _Network Address Authority (NAA) IEEE Extended_ name identifier, the _64-bit extended unique identifier (EUI-64)_ or _iSCSI Qualified Name (IQN)_ using the _wwn-0x_ prefix. The revision of the DNBD3 image is specified with a _:_ (colon) after the DNBD3 image name and also the _Logical Unit Number (LUN)_. +This naming scheme is required when _TargetNameCheck_ is either set to _Full_ or when using other initiators which require standard compliance _IQN_ naming schemes. + +The image information with their _WWN_ can be retrieved as _JSON_ for all images using the URL: + +``` +http://:/query?q=images +``` + +Note that the _WWN_ is in decimal integer _JSON_ format. The target node name expects the _WWN_ to be passed as hexadecimal. + + +### Using _iscsiadm_ to attach and detach DNBD3 images as block device as a replacement for the _DNBD3_ kernel and _FUSE_ module. +You can use _iscsiadm_, which on Debian und Ubuntu based distributions can be found in the package _open-iscsi_: + +```shell +apt-get install open-iscsi +``` + +After successful installation, it is possible to attach _iSCSI_ devices as regular block devices like _/dev/sda_. +Since _iSCSI_ discovery is **NOT** supported yet, target nodes have to be created manually: + +```shell +iscsiadm -m node -T -p : --op=new +``` + +This will create an _iSCSI_ target node _image-name_ which is attached to the portal _iscsi-server_ listening on port _port_. +A target node configuration file will be created in _/etc/iscsi/nodes//,_. +Please note that for any images residing in sub directories of the base path, the sub directory tree has to be created manually in _/etc/iscsi/nodes_ and _/etc/iscsi/static_ before adding the target node with _iscsiadm_. + +After the target node has been created, it can be made available as a block device using: + +```shell +iscsiadm -m node -T -p : --login +``` + +Now the image is accessible using either e.g. _/dev/sda_ or _/dev/disk/by-id_. +If the operating system has removable device attach mechanisms, they will be invoked, too. + +After finishing work with the image, the _iSCSI_ session needs to be logged out with: + +```shell +iscsiadm -m node -T -p : --logout +``` + +Now the block device e.g. _/dev/sda_ and links in _/dev/disk/by-id_ will be removed. +If the operating system has removable device detach mechanisms, they will be invoked, too. + +If the _iSCSI_ target node is not required anymore, it can be removed using: + +```shell +iscsiadm -m node -T -p : --op=delete +``` + +This will delete the target node in _/etc/iscsi/nodes//,_ and also remove the directory _/etc/iscsi/nodes/_ if empty. +Please note that for any images residing in sub directories of the base path, the sub directory tree has to be removed manually from _/etc/iscsi/nodes_ and _/etc/iscsi/static_ after removing the target node with _iscsiadm_. + + +### Configuring and using _QEMU_ for using the iSCSI server +Here is a bash script called _qemu-iscsi.sh_ that invokes QEMU with iSCSI. + +```shell +#!/bin/bash + +CRC32C='None' + +[ -n "$3" ] && CRC32C="$3" + +qemu-system-x86_64 \ + -enable-kvm \ + -m 4096 \ + -smp 4 \ + -cpu host \ + -machine type=q35,accel=kvm \ + -boot menu=on \ + -device virtio-scsi-pci,id=scsi0 \ + -drive if=none,file=/data/storage/ubuntu.2404.lts.img.r1,format=raw,id=drive0,cache=none \ + -device scsi-hd,drive=drive0,bus=scsi0.0 \ + -drive if=none,id=iscsi0,file=iscsi://localhost:5003/iqn.2025-07.de.uni-freiburg.rz:dnbd3:images:"$1":"$2"/"$2",format=raw,cache=none,aio=native,readonly=on \ + -device scsi-hd,drive=iscsi0,bus=scsi0.0 \ + -iscsi initiator-name=iqn.2025-07.de.uni-freiburg.rz:bwlehrpool:client:"$(hostname)":"$1":"$2" \ + -iscsi header-digest="${CRC32C}" \ + -display gtk +``` + +Usage: + +```shell +qemu-iscsi.sh [CRC32C] +``` + +This will invoke QEMU with a KVM accelerated virtual machine with 4 GiB memory and 4 CPU cores, a primary writable local hard drive located in _/data/storage/ubuntu.2404.lts.img.r1_ and a secondary read only _DNBD3_ with revision attached via iSCSI protocol on _localhost_ using port _5003_. +The QEMU client will get the initiator name _iqn.2025-07.de.uni-freiburg.rz:bwlehrpool:client:::_. +If the third optional argument _CRC32C_ is passed, iSCSI header CRC32C checksumming will be enabled. + diff --git a/src/server/iscsi.c b/src/server/iscsi.c index 2ca2225..4c0fc4d 100644 --- a/src/server/iscsi.c +++ b/src/server/iscsi.c @@ -1311,7 +1311,7 @@ int iscsi_create() return -1; } - globvec->flags = (ISCSI_GLOBALS_FLAGS_INIT_R2T | ISCSI_GLOBALS_FLAGS_IMMEDIATE_DATA | ISCSI_GLOBALS_FLAGS_DATA_PDU_IN_ORDER | ISCSI_GLOBALS_FLAGS_DATA_SEQ_IN_ORDER | ISCSI_GLOBALS_FLAGS_SCSI_IO_REMOVABLE | ISCSI_GLOBALS_FLAGS_SCSI_IO_WRITE_PROTECT); + globvec->flags = (ISCSI_GLOBALS_FLAGS_CHAP_DISABLE | ISCSI_GLOBALS_FLAGS_INIT_R2T | ISCSI_GLOBALS_FLAGS_IMMEDIATE_DATA | ISCSI_GLOBALS_FLAGS_DATA_PDU_IN_ORDER | ISCSI_GLOBALS_FLAGS_DATA_SEQ_IN_ORDER | ISCSI_GLOBALS_FLAGS_SCSI_IO_REMOVABLE | ISCSI_GLOBALS_FLAGS_SCSI_IO_WRITE_PROTECT); globvec->target_name_check = ISCSI_GLOBALS_TARGET_NAME_CHECK_RELAXED; globvec->max_sessions = 0U; globvec->header_digest = 0; -- cgit v1.2.3-55-g7522