Tiny PXE Server

iSCSI (pyTarget)

pyTarget is a Windows iSCSI Target with a GPLv2 licence. The project homepage (here) states that pyTarget can be used to "...Implement a powerful iSCSI target in python, easily use under most popular systems. It also includes the following features: multi-target, multi-connect/session support chap authentication support header & data digest support erl =2..."

A standalone binary is available for Windows 32-bit - this version does not require that the python environment be installed on the Target system. The pyTarget executable is a console application and can be configured from a web interface. Alternatively the pytarget configuration file can be manually edited.

A third party GUI is being developed by Erwan and is available for download here. The pyTarget GUI is in active development at the time of writing. Screenshots in this page are from version 0.3 - screenshots in this page may not reflect the GUI in any newer version(s).

A Discussion topic on reboot.pro may cover additional settings not discussed in this guide - see here.

pyTarget documentation is limited. A .pdf document is included in the download package and a .txt document is available here. This page covers creating a basic Target using either the configuration file or the GUI.

This page contains the following sections -

Supported Disk Images
GUI
Configuration File
iSCSI Negotiation Parameters
Error Messages
Client/Host Connections
Installing Windows 7 to iSCSI Target

Supported Disk Images

pyTarget supports fixed type disks including RAW files and Virtual Hard Disks (VHD). pyTarget does not support EXPANDABLE type VHD files, however it does support SPARSE type disk images\files.

An existing disk image can be specified in the configuration file. The disk capacity will also need to be specified - 1 x unit = 512 bytes. The following may be useful in calculating disk image capacity -

1 KiB = 2 units (use capacity="2" in config.xml).
1 MiB = 2048 units (use capacity="2048" in config.xml).
1 GiB = 2097152 units (use capacity="2097152" in config.xml).

If a disk specified in the configuration file does not exist, the pyTarget executable will create a RAW file of the size specified in the capacity= field in config.xml.

GUI

Running the GUI will parse data from any existing configuration file (config.xml). Any settings changed in the GUI will be written to the configuration file and will start the pyTarget executable when the Start button is selected. The pyTarget executable will be hidden, however any output will be displaying in the GUI. Starting the GUI without an existing configuration file will display settings similar to the following (GUI version 0.3 - released on 6th February 2017) -

Working from the top to the bottom (and left to right), the fields in the GUI displayed in the image above -

Target IQN - hardcoded to pytarget.

Debug - levels 0 to 6 are supported. The differences between the Debug levels are not documented. The Debug level will control the console output - with Debug level 6 displaying the most verbose output.

IP - IP address automatically retrieved from the pyTarget configuration file. If the configuration file does not exist then the IP address of the system the GUI is running on will be retrieved. pyTarget will send the IP address specified in this field to the iSCSI initiator during discovery. This field can be edited manually, which may be required if the system has more than one network interface.

Disk Image - the name of the disk image. The full path must be specified if the disk image is not in the same directory as pyTarget.exe. This information will be retrieved from any existing configuration file. A disk/path can be manually entered in this field. If an existing disk image + path is manually entered in this field then its capacity will not be calculated and will also have to be specified manually.

Capacity - 1 unit appears to equal 512 bytes. This information will be retrieved from any existing configuration file. The Capacity will automatically be retrieved if the browse button is used to select a Disk Image.

... - browse button. Use to select a disk image. Using the browse button to select an existing file will retrieve its size and calculate the capacity in the format required by pyTarget.

Initiator IQN - specify the IQN of the iSCSI initiator that will be connecting to the Target. This is required for authentication - if the initiator IQN does not match the IQN specified in this field then the connection will be refused.

Start - run pyTarget.exe. The console will be hidden - all console output will be parsed to the GUI and displayed in the field below the Start button.

Stop - stop pyTarget.exe.

Any changes made in the GUI will be written to the configuration file when the Start button is pressed.

Configuration File

A configuration file config.xml is included in the pyTarget download, however I recommend that you use the GUI to create a configuration file or compile your own.

The following entries can be used as the header for config.xml
<?xml version="1.0" encoding="UTF-8" standalone="no" ?> <root> <console ip="" port="3260" debug_level="5" />

console ip="" - this field can be left empty. Specifying an IP address in this field will limit the IP addresses the Target can listen on.

port="3260" - the TCP port that the Target will listen on. Port 3260 is the default port for iSCSI connections.

debug_level="5" - set the Debug level. See here.

Now add a Target -
<target name="iqn.iSCSI-target1" ip="192.168.1.1" port="3260" portal="1">

Where

name="iqn.iSCSI-target1" - Target IQN.

ip="192.168.1.1" - Target IP address. Use a valid IP address for a network adapter in use on the Target system.

port="3260" - listed ton port 3260 for incoming connections.

portal="1" - the documentation states that this is the "... the portal field of TargetAddress..."

Now add a Host for authentication purposes. Connections to this Target will be refused from any Client/Host not specified -
<host name="iqn.client" target_pwd="" initiator_pwd="">

name="iqn.client" - allow connection from a Client/Host with the iSCSI Qualified Name iqn.client.

target_pwd="" - use for CHAP authentication. Leave blank to allow anonymous connections (none password protected).

initiator_pwd="" - use for CHAP authentication. Leave blank to allow anonymous connections (none password protected).

Now specify/add a disk image -
<lun id="0" type="0" path="D:\iSCSI_target1.ima" capacity="41943040"/>

Where

id="0" - documentation states that this field is used to specify the LUN ID "...lun id, keey unique within host...".

type="0" - documentation states that this field is used for "...lun device type (0 for disk, 1 for tape, etc)...."

path="D:\iSCSI_target1.ima" - path to disk image.

capacity="41943040" - 41943040 = 20 GiB. See here for more information.

And now add a second disk image -
<lun id="1" type="0" path="D:\iSCSI_target2.ima" capacity="20971520"/>

Observe that the LUN ID has been changed (id=1), type is still 0 for a disk (type="0"), path is for a different disk image (path="D:\iSCSI_target2.ima") and the disk capacity is 10 GiB (capacity="20971520").

Resulting config.ini file with XML closing tags added for all elements -
<?xml version="1.0" encoding="UTF-8" standalone="no" ?> <root> <console ip="" port="3260" debug_level="5" /> <target name="iqn.iSCSI-target1" ip="192.168.1.1" port="3260" portal="1"> <host name="iqn.client" target_pwd="" initiator_pwd=""> <lun id="0" type="0" path="D:\iSCSI_target1.ima" capacity="41943040"/> <lun id="1" type="0" path="D:\iSCSI_target2.ima" capacity="20971520"/> </host> </target> </root>

NOTE - Multiple Targets can be specified in the Configuration file - this is not (yet?) possible in the GUI.

iSCSI Negotiation Parameters

NOTE - It is not (yet?) possible to set negotiation parameters in the GUI.

iSCSI Negotiation Parameters for individual Targets can be set in the pyTarget configuration file. Supported parameters are -
<item key="MaxConnections" value="8" /> <item key="InitialR2T" value="Yes" /> <item key="ImmediateData" value="Yes" /> <item key="FirstBurstLength" value="65536" /> <item key="MaxBurstLength" value="262144" /> <item key="DefaultTime2Wait" value="2" /> <item key="DefaultTime2Retain" value="20" /> <item key="MaxOutstandingR2T" value="16" /> <item key="DataPDUInOrder" value="Yes" /> <item key="DataSequenceInOrder" value="Yes" /> <item key="ErrorRecoveryLevel" value="0" /> <item key="MaxRecvDataSegmentLength" value="65536" />

NOTE - the above negotiation parameters are the default values used for each Target. The configuration file can be used to change the default values.

Sample config.xml including negotiation parameters -
<?xml version="1.0" encoding="UTF-8" standalone="no" ?> <root> <console ip="" port="3260" debug_level="5" /> <target name="iqn.iSCSI-target1" ip="192.168.1.1" port="3260" portal="1"> <host name="iqn.client" target_pwd="" initiator_pwd=""> <lun id="0" type="0" path="D:\iSCSI_target1.ima" capacity="41943040"/> <lun id="1" type="0" path="D:\iSCSI_target2.ima" capacity="20971520"/> </host>  <item key="MaxConnections" value="8" /> <item key="InitialR2T" value="Yes" /> <item key="ImmediateData" value="Yes" /> <item key="FirstBurstLength" value="65536" /> <item key="MaxBurstLength" value="262144" /> <item key="DefaultTime2Wait" value="2" /> <item key="DefaultTime2Retain" value="20" /> <item key="MaxOutstandingR2T" value="16" /> <item key="DataPDUInOrder" value="Yes" /> <item key="DataSequenceInOrder" value="Yes" /> <item key="ErrorRecoveryLevel" value="0" /> <item key="MaxRecvDataSegmentLength" value="65536" /> </target> </root>

Error Messages

pyTarget documentation is limited and the error messages appear obscure at times.

An error message similar to the following may indicate that another application is listening on port 80 (used by web servers) -
INFO: start Http Service ... Exception in thread Http Service: Traceback (most recent call last): File "threading.pyo", line 525, in __bootstrap_inner File "comm\service_thread.pyo", line 33, in run File "web\main.pyo", line 154, in WebService File "SocketServer.pyo", line 400, in __init__ File "BaseHTTPServer.pyo", line 108, in server_bind File "SocketServer.pyo", line 411, in server_bind File "<string>", line 1, in bind error: [Errno 10013] An attempt was made to access a socket in a way forbidden b y its access permissions

An error message similar to the following may indicate that another application is listening on port 3260 - the default iSCSI port. This may indicate another iSCSI Target is running (including a hidden pyTarget.exe launched from the GUI) -
WARNING: iscsi service start FAILED, check if port(3260) has been used

Client/Host Connections

As stated elsewhere in this page, connections from Client/Host systems will require authentication. Assuming that the Client/Host identifier was set as iqn.client, add the following command to your iPXE script -

set initiator-iqn iqn.client

E.g. -
#!ipxe set boot-url http://${dhcp-server} set gateway 0.0.0.0 set keep-san 1 set initiator-iqn iqn.client SANBOOT iscsi:${dhcp-server}::::iqn.iSCSI-target1

Installing Windows 7 to iSCSI Target

Installing Windows 7 is unusually slow when installing to a pyTarget iSCSI Target. This is covered here.

In tests it took several hours to install Windows 7 when using pyTarget - via a Gigabit Ethernet connection. It is possible that changing the Negotiation parameters may increase the installation speed.

Document date - 28^th February 2017(DRAFT)