Block (iSCSI) Share Target Screens

If you have not added iSCSI shares to the system, the iSCSI widget shows text stating general information about the block (iSCSI) share targets until a share is added.

After adding a share, the widget lists them in a table.

The Block (iSCSI) Shares Targets widget header shows the status of the iSCSI service as STOPPED (red) or RUNNING (green). Before adding the first share, the STOPPED status displays in the default color. The header includes the Wizard button and the more_vert dropdown list of iSCSI share and service options. The header is a link that opens the iSCSI screen.

Wizard opens the Wizard iSCSI wizard on the Target screen. See Target Screens below.

The more_vert dropdown list shows two options available to iSCSI shares and the iSCSI service in general:

• Turn Off/ON Service toggles to Turn Off Service when the iSCSI service is enabled, and to Turn On Service when the iSCSI service is disabled.
• Config Service opens the iSCSI Global Configuration screen.

The more_vert dropdown list for each target shows two options:

• edit Edit opens the Edit iSCSI Target screen.
• delete Delete opens the Delete dialog.

The Start iSCSI Service dialog shows after adding the first share. It includes an Enable this service to start automatically toggle and two buttons: Start and No. Start starts the service and changes the status on the iSCSI widget toolbar from STOPPED (in red) to RUNNING (in blue).

Delete opens a confirmation dialog with two options:

• Delete 1 associated extent - Shows the number of associated extend for the selected target.
• Force Delete - Deletes the target even if the share is still in use.

Cancel closes the dialog without deleting. Delete deletes the target but does not delete the iSCSI volumes associated with the extents.

The iSCSI Global Configuration screen opens when you click Edit on the iSCSI Service row of the System > Services screen, and after clicking the Global Target Configuration button at the top of all iSCSI share screens.

Global Configuration Settings

Setting	Description
Base Name	Enter a name using lowercase alphanumeric characters. Allowed special characters are dot (.), dash (-), and colon (:). See the “Constructing iSCSI names using the iqn.format” section RFC3721 for more information.
ISNS Servers	Enter host names or IP addresses of the ISNS servers to be registered with the iSCSI targets and portals of the system. Press Enter to separate each entry.
Pool Available Space Threshold (%)	Generate an alert when the pool reaches this percentage of space remaining. This is typically configured at the pool level when using zvols or at the extent level for both file and device-based extents.
iSCSI listen port	TCP port used to access the iSCSI target. The default is 3260.

The Wizard button opens the iSCSI wizard on the Targets screen. The wizard has three screens:

• Target
• Extent
• Protocol Options

The wizard steps you through creating an iSCSI target, adding the extent for the target, including setting up the storage (device or file) it uses, and setting up the portal and initiators for the target.

Alternatively, you can use the individual iSCSI screens, accessible by clicking on the iSCSI widget header, to manually configure targets, extents, portals, etc. The Targets screen opens by default. For more information on iSCSI screens and settings, see iSCSI Screens below.

Next advances to the next wizard screen. Back shows the previous wizard screen. Save creates the iSCSI share.

The iSCSI Wizard opens and shows the Target screen.

The Target dropdown shows Create New and any other existing targets on the system. Create New creates a target. Selecting an existing target from the dropdown list allows you to edit it, but we recommend using the iSCSI Target screen to edit an existing target rather than using the wizard screens.

The iSCSI wizard Extent screen shows settings to name the target, set the type of extent storage (device or file), and the sharing platform for the device.

Wizard Extent Settings

Setting	Description
Name	The name given to the iSCSI block target. Enter a name using up to 64 lowercase alphanumeric and special characters. Allowed characters are dot (.), dash (-), and colon (:). A name longer than 64 characters is not allowed. See the “Constructing iSCSI names using the iqn.format” section of RFC3721. The base name (from Target Global Configuration) is automatically prepended if the target name does not start with iqn.
Extent Type	The storage device for the target. The dropdown list shows two options: Device and File. Selecting Device shows the Device dropdown list. File sows the Path to the Extent fields and the Filesize field.
Device	Shows if Extent Type is set to Device. Shows Create New or a list of iSCSI extents added to the system. Create New shows the Pool/Dataset fields and the Size field.
Pool/Dataset	Sets the mount path to the zvol for the extent. Shows two fields after selecting Create New in Device. The blank field allows text entry of a share mount path or allows Truenas to populate it with the path to the dataset selected in the file browser field. The file browser selects the mount path to the extent parent dataset on the local file system that TrueNAS exports over the iSCSI protocol. Use the arrow_right icon to the left of to expand the dataset directory tree. Create Dataset activates after selecting the parent dataset.
Size	Sets the block size for the zvol. Shows after clicking Create New in Device and after adding the mount point to the zvol in Pool/Dataset. Enter a numerical value and a suffix to specify the block size for the zvol you are creating.
Path to the Extent	Sets the mount path to the file. Shows if Extent Type is set to File. Enter or browse to select the mount point for the directory and file for the extent to use. If a directory does not exist, after selecting the dataset where you want to add the directory, and then enter a / followed by the name to add the directory to the dataset or zvol.
Filesize	Sets the size of the file. Shows if the Extent Type is set to File. Enter the size for the directory. Leaving this set to 0 uses the actual file size and requires the file to exist. Otherwise, specify the file size for the new file.
Sharing Platform	Sets the platform type for the target extent connection. Shows for both Device and File options. Select the platform that matches your use case. Options are: VMware: Extent block size 512b, TCP enabled, no Zen compat mode, SSD speed Xen: Extent block size 512b, TCP enabled, Xen compat mode enabled, SSD speed Legacy OS: Extent block size 512b, TCP enabled, no Xen compat mode, SSD speed Modern OS: Extent block size 4k, TCP enabled, no Xen compat mode, SSD speed

The iSCSI wizard Protocol Options screen shows settings to add a portal and initiators. Create New shows settings to add a new portal if one does not exist.

The iSCSI screen provides access to manage targets, and the extents, initiators (clients), portals, and authorized access for the targets. The iSCSI screen shows five tabs: Targets, Extents, Initiators, Portals, and Autorized Access. The iSCSI screen opens with the Targets tab selected by default.

The Block (iSCSI) Shares Targets widget header opens the iSCSI screens.

Global Target Configuration opens the iSCSI service configuration screen.

Wizard opens the iSCSI wizard configuration screens.

iSCSI targets are storage resources on an iSCSI server that are made available to iSCSI initiators (clients) over a TCP/IP network. The target is a server-side torage object that encapuslates a block storage resource (e.g., a phyical disk, logical volume, or file) and makes it accessible to initiators via the iSCSI protocol. A target is identified by a unique iSCSI qualified name (IQN), and is associated with portal groups for network access and initiator groups for access control.

The Target tab shows by default when opening the iSCSI screen. Use it to manage iSCSI targets.

The Targets table lists all targets added to the system. It shows the target name and alias if one is configured for it. The first row of the table is selected by default.

Each target shows three Details for targetname widgets:

• iSCSI Authorized Networks shows networks added on the Add or Edit iSCSI Target screens.
• iSCSI Connections shows active connections between an authorized client and the target. Connections show the IQN and IP address of the client connecting to the target.
• Extents shows extents associated with the target.

Add opens the Add iSCSI Target screen.

Edit opens the Edit iSCSI Target screen for the target selected in the table.

Delete opens the Delete Target dialog.

The screen shows three widgets on the right side of the screen for the selected target:

• Extents- Shows a list of LUNs, and includes two options:

  • Associate button
  • Remove Extent Association link_off icon.

• iSCSI Authorized Networks - Shows a list of authorized networks configured when you create the target or using the Authorized Network settings on the Add or Edit iSCSI Target screens.

• iSCSI Connections - Shows a list of the connections.

The Remove Extent Association link_off icon opens the Remove extent association dialog that shows the LUN link association and two buttons: Cancel and Remove.

Removing the association activates the Associate button on the Extent widget. The Associate button is inactive when the extent is associated with a LUN. Clicking the button opens the Associate target dialog.

The Associate dialog shows the target name.

LUN ID accepts a LUN ID between 0 and 1023. TrueNaS requires at least one LUN 0. Some initiators expect a value between 0 and 256. Leaving this field blank automatically assigns the next available ID.

Extent shows a dropdown list of targets to select and associate the extent with.

The Add Target and Edit Target screens show the same configuration settings.

The Extents screen shows a table listing extents configured on the system. Extents are shared storage units.

Add and Edit open the configuration screen for the selected target. Delete opens a dialog with delete options.

The Delete iSCSI Extent name deletes the specified extend. The name of the extent shows in the dialog title.

Force allows deleting the extend even if the share is active.

Delete deletes the extent and closes the dialog. Cancel closes the dialog without deleting the extent.

The Add Extent and Edit Extent screens show the same configuration settings.

Extent Basic Info Settings

Setting	Description
Name	Enter a name for the extent. An Extent where the size is not 0, cannot be an existing file within the pool or dataset.
Description	Enter any notes about this extent.
Enabled	Select to enable the iSCSI extent.

Extent Compatibility Settings

Setting	Description
Enable TPC	Select to allow an initiator to bypass normal access control and access any scannable target. Third Party Copy (TPC) enables a disk target to process Extended Copy (XCOPY) operations that would otherwise be blocked, allowing data transfers to occur directly between storage devices without passing through the initiator.
Xen initiator compat mode	Select when using Xen as the iSCSI initiator.
LUN RPM	Select the option from the dropdown list. Options are UNKNOWN, SSD, 5400, 7200, 10000 or 15000. Do not change this setting when using Windows as the initiator. Only change LUN RPM in large environments where the number of systems using a specific RPM is needed for accurate reporting statistics.
Read-only	Select to prevent the initiator from initializing this LUN.

Extent Type Settings

Setting	Description
Extent Type	Provides virtual storage access to zvols, zvol snapshots, or physical devices. Select the extent (zvol) option from the dropdown list. Dropdown options: Device - Select to specify a device (default option). Device provides virtual storage access to zvols, zvol snapshots, or physical devices. Shows the Device field. File - Select to specify a path to a file. File provides virtual storage access to a single file. Shows the Path to the Extent and Filesize fields.
Device	Shows after specifying Device in Extent Type. Select the unused zvol or zvol snapshot from the dropdown list.
Path to the Extent	Enter or browse to select the path to an existing file. Enter a slash (/) followed by a file name to create a file in a dataset and append the file name to the path (/filename.ext).
Filesize	Enter 0 to use the actual file size of an existing file, or specify the file size for the new file added in Path to the Extent.
Logical Block Size	Shows the default 512 size. If the initiator requires a different block size, enter the numerical value.
Disable Physical Block Size Reporting	Select if the initiator does not support physical block size values over 4K (MS SQL).

The Initators Groups screen manages iSCSI initiator groups for targets. Initiator groups are a logical grouping of iSCSI initiators (clients), identified by their iSCSI qualified name (IQN), that control access to iSCSI targets they are associated with, and define what operations clients can perform on storage for those targets.

The Initiators Groups screen shows after clicking the Initiator tab. The table lists initiator groups configured on the system.

Add opens the Add Initiator screen. Edit opens a version of the Add Initiator screen with only two fields. Delete opens a dialog to delete an initiator group.

Add opens the Add Initiator screen showing the settings to create new authorized access client groups or edit existing ones in the list.

Add Initiator Group Settings

Setting	Description
Allow All Initiators	Select to allows all initiators.
Allowed Initiators (IQN)	Enter initiators allowed access to this system. Enter an iSCSI Qualified Name (IQN) and click + to add it to the list. Example: iqn.1994-09.org.freebsd:freenas.local.
Description	Enter any notes about the initiators.
Connected Initiators	Shows the list of connected initiators on the system.
Allowed Initiators	Shows the list of allowed initiators on the system.
Refresh	Updates the screen.

Edit opens the Add Initiator edit screen showing two options: Allow All Initiators and Description. Save saves changes and closes the screen. Cancel closes the screen without saving changes.

The Portals screen manages iSCSI portal groups for the target. A portal group is a set of network portals (IP addresses and port combinations) within an iSCSI node that collectively supports the coordination of an iSCSI session. Each portal group is identified by a 16-bit numerical identifier (portal group tag) unique within the iSCSI node. Portal groups allow an iSCSI initiator (client) to connect to a target through multiple network paths.

The Portals screen shows after clicking on the Portals tab on the iSCSI screen. A Portals table lists portal ID groups on the TrueNAS system.

Delete opens the Delete dialog for the selected portal ID. Click Confirm and then Delete to delete the selected portal.

Add opens the Add Portal screen. Edit opens the Edit Portal screen. Both screens have the same setting options.

The Add Portal and Edit Portal screens show the same configuration settings.

Portal Basic Info Settings

Setting	Description
Description	Enter an optional description. Portals are automatically assigned a numeric group.
Add Listen	Click Add to show the IP Address field where you add the IP address and netmask (CIDR) for the portal.
IP Address	Shows several options for setting up a portal. Select from these options: 0.0.0.0 - Select to listen on all IPv4 addresses. :: - Select to listen on all IPv6 addresses. TrueNAS server IP address - Select to use the IPv4 address assigned to the primary network interface for the TrueNAS server being configured. IPv6 address assigned to the system.

The Authorized Access screen shows a table listing groups allowed to access the target. The Authorized Access table lists the group ID, user, and peer users. settings to create new authorized access networks or edit existing ones in the list.

The table shows No records have been added yet until you add access.

Add opens the Add Authorized Access screen.

The more_vert dropdown list for each group ID shows two options:

• edit Edit opens the Edit iSCSI Assoicated Access screen.
• delete Delete opens the Delete dialog.

Delete opens the Delete dialog for the selected portal ID. Confirm enables the delete option. Delete deletes authorized access for the selected user and closes the dialog.

Edit opens the Edit Authorized Access screen.

The Add and Edit screens display the same settings. Both screens have the same setting options.

The Add Target and Edit Target screens show the same configuration settings.

Authentication Method and Group Settings

Setting	Description
Group ID	Enter a number. Allows configuring different groups with different authentication profiles. For example, all users with a group ID of 1 inherit the authentication profile associated with Group 1.
Discover Authentication	Select the discovery method for authentication from the dropdown list. iSCSI supports multiple authentication methods that targets use to discover valid devices. Options are: None - Select to allow anonymous discovery. When set to None, you can leave an iSCSI Group Authentication Method set to None or empty. CHAP - Select to use CHAP as the authentication method. If set to CHAP enter or create a new group on the Add iSCSI Targetscreen. Mutual Chap - Select to use the Mutual CHAP two-way authentication method. To show this option, configure the Peer User and the password.

User Settings

Setting	Description
User	User account to create CHAP authentication with the user on the remote system. Many initiators use the initiator name as the user name.
Secret	Enter the user password. Secret must be at least 12 and no more than 16 characters long. The screen displays a Password does not match error until you enter the same password in Secret (Confirm).
Secret (Confirm)	Enter the same password to confirm the user password.

Peer Settings

Setting	Description
Peer User	(Optional) Enter only when configuring mutual CHAP. Usually the same value as User. Configure the peer user name and password to see Mutual Chap in the Discover Authentication dropdown list.
Peer Secret	Enter the mutual secret password. Required if entering a Peer User. Peer user must use a different password than the password in Secret.
Peer Secret (Confirm)	Enter the same password to confirm the mutual secret password.