TrueNAS CORETrueNAS CORE Nightly Development Documentation
This content follows experimental early release software. Pre-release software is intended for testing purposes only.
Use the Product and Version selectors above to view content specific to a stable software release.

iSCSI Shares

Users can configure an iSCSI block share using either the wizard or the individual configuration screens. The wizard steps users through the configuration process in an ordered sequence. Using the seven tabs on the iSCSI screen allows users to configure settings in any order they choose (a manual process).

iSCSI Wizard Configuration Screens

The iSCSI Wizard configuration forms guide users through the process of setting up an iSCSI block share. Click WIZARD to display the first configuration screen.

Wizard Navigation

Use Next to advance to the next wizard configuration form. Use Back to return to a previous wizard configuration form. Use Cancel to exit the configuration wizard.

Wizard Configuration Screens and Settings

Create or Choose Block Device Screen Settings

Create or Choose Block Device

SharingISCSIWizardDevice

SettingDescription
NameType a lower case alphanumeric character string that can include a dot (.), dash (-), or colon (:). Keep the string short and do not exceed 63 characters.
Extent TypeChoose either Device or File. If selecting Device use a zvol created for the share. If selecting File also select the path to the extent and include the file size.
DeviceRequired field. Create New or select from devices listed
Sharing PlatformSelect from the options provided:
VMware: extent block size 512b, TCP enabled, no Xen 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
Use Moderon OS for updated operating systems like Linux OS.

Portal Screen Settings

Portal

The Wizard Portal configuration form includes only the Portal field unless you select Create New on the dropdown list.

iSCSIWizardPortalAfterCreateNewAndAddIPAddress

SettingDescription
PortalSelect either Create New or an existing portal from the dropdown list. Selecting Create New displays the Discovery Authentication Method, Discovery Authentication Group, IP Address and Port fields.
Discovery Authentication MethodRequired if creating a new portal. Select either NONE, CHAP or Mutual CHAP from the dropdown list. If NONE you can leave Discovery Authentication Group set to NONE as well.
Discovery Authentication GroupRequired if the discovery authentication method is set to CHAP or MUTUAL CHAP. Select either NONE or Create New on the dropdown list. If Discovery Authentication Method is set to NONE you can select NONE here but if Discovery Authentication Method is set to CHAP or MUTUAL CHAP select CREATE NEW. This displays the Group ID, User, Secret and Secret (Confirm) configuration fields.
Group IDDisplays after selecting Create New in the Discovery Authentication Group field. Group IDs allow you to configure different groups with different authentication profiles. For example, all users with a group ID of 1 inherits the authentication profile associated with group 1. Type a number for the group ID.
UserDisplays after selecting Create New in for the discovery authentication group. Type the name of the user account to create for the CHAP authentication with the user on the remote system. For example, you could use the initiator name as the user name.
SecretDisplays after selecting Create New as the discovery authentication group. Type a user password of at least 12 but no more than 16 characters.
Secret (Confirm)Displays after selecting Create New as the discovery authentication group. Retype the user password entered into the Secret field. Click the icon to display the characters you typed to verify you typed the desired password string. Click to hide the password string.
IP AddressSelect the IP address from the dropdown list. This is the IP address to list on the portal. Click ADD to add more IP addresses if desired or necessary. Click DELETE to remove any IP addresses and ports you added after clicking ADD. Use 0.0.0.0 to listen on all IPv4 addresses or use :: to listen on all IPv6 IP addresses.
PortType the TCP port used to access the iSCSI target. The default port is 3260.
ADDSaves the selected IP address and allows the user to add another IP address. New IP address and port entry fields includes the DELETE button allows you to remove the new entry if necessary.
DELETEDisplays after clicking ADD. Removes the new IP address and port line created after clicking ADD.

Initiator Screen Settings

Initiator

SharingISCSIWizardInitiator

SettingDescription
InitiatorsLeave blank to allow all host names or to enter a list of initiator host names. Use the keyboard Enter after entering each host name to save.
Authorized NetworksNetwork addresses allowed to use this initiator. Leave blank to allow all networks or list all network addresses with a CIDR mask. Separate each entry with the keyboard Enter.

Confirm Options Screen Settings

Confirm Options Form

SharingISCSIWizardSummary

Use Back to return to a previous configuration form to make any changes on that form. Use SUBMIT to save the settings and the new iSCSI share.

Manual Setup Screens

The manual configuration screens allow you to add or edit an iSCSI block share. There are seven configuration screens accessed from tabs at the top of the iSCSI screen. Unlike the wizard configuration option, you can move from one screen to another in any sequence.

Manual Configuration Screens and Settings

Target Global Configuration Tab

The Target Global Configuration screen allows user to add or edit global configuration settings that apply to all iSCSI shares.

SharingISCSIManualTargetGlobalConfig

SettingDescription
Base NameLowercase alphanumeric characters plus dot (.), dash (-), and colon (:) are allowed. See the “Constructing iSCSI names using the iqn.format” section of RFC3721.
ISNS ServersHost names or IP addresses of the ISNS servers to register with the iSCSI targets and portals of the system. Use keyboard Enter. to separate entries.
Pool Available Space Threshold (%)Generates an alert when the pool has this percent space remaining. It is typical to configure this at the pool level when using zvols or at the extent level for both file and device-based extents.

Click SAVE before leaving the global configuration settings screen.

Portals Tab

The Portals screen displays a list of configured portals. It lets users create new portals or edit the existing ones in the list. Use the blue Columns dropdown list to display a list of available options to add or remove columns in the Portals table. Select from Unselect All, Listen, Description, Discovery Auth Method, Discover Auth Group or Reset to Defaults to reverse any changes you made to the table.

SharingISCSIManualPortals

Use ADD to display the Portals Add configuration form. Click the icon for the portal and select Edit to display the Portal Edit configuration form. Both the Add and Edit forms have the same settings fields.

SharingISCSIManualPortalsForm

Basic Info

SettingDescription
DescriptionOptional description. Portals are automatically assigned a numeric group.

Authentication Method and Group

SettingDescription
Discovery Authentication MethodiSCSI supports multiple authentication methods that the target uses to discover valid devices. None allows anonymous discovery while CHAP and Mutual CHAP require authentication.
Discovery Authentication GroupGroup ID created in Authorized Access. Required when the discovery authentication method is CHAP or Mutual CHAP.

IP Address

SettingDescription
IP AddressSelect the IP addresses the portal uses to listened on. Click ADD to add IP addresses with a different network port. 0.0.0.0 listens on all IPv4 addresses and :: listens on all IPv6 addresses.
PortTCP port used to access the iSCSI target. Default is 3260.
ADDAdds another IP address row.

Initiators Groups Tab

The Initiators Groups screen displays a lis of configured initiators. It lets users create new authorized access client groups or edit existing ones on the list. Use the blue Columns dropdown list to display a list of available options to add or remove columns in the Initiator Groups table. Select from Unselect All, Initiators, Authorized Networks, Description or Reset to Defaults to reverse any changes you made to the table.

SharingISCSIManualInitiators

Use ADD to display the Initiators Add configuration screen. Click the icon for the initiator and select Edit to display the Initiators Edit configuration form. Both the Add and Edit forms have the same settings fields.

iSCSIAddInitiators

SettingDescription
Connected InitiatorsInitiators currently connected to the system, displayed in the IQN format with an IP address. Set initiators and click an to add the initiators to either the Allowed Initiators or Authorized Networks lists. Click Refresh to update the list of connected initiators.
Allow All InitiatorsAllows all initiators when selected. If not selected, configure your own allowed initiators and authorized networks.
Allowed Initiators (IQN)Initiators allowed access to this system. Enter an iSCSI Qualified Name (IQN) and click the to add it to the list. Example: iqn.1994-09.org.freebsd:freenas.local.
Authorized NetworksNetwork addresses allowed use this initiator. Each address can include an optional CIDR netmask. Click to add the network address to the list. Example: 192.168.2.0/24.
DescriptionEnter any notes about initiators.
REFRESHRefreshes the list displayed in Connected Initiators.
SAVESaves changes made on the Add or Edit initiator screens.
CANCELDiscards changes made on and closes the Add or Edit initiator screens.

Authorized Access Tab

The Authorized Access screen displays a list of authorized access networks. It lets users create new authorized access networks or edit existing ones in the list. Use the blue Columns dropdown list to display a list of available options to add or remove columns in the Initiator Groups table. Select from Unselect All, User, Peer User or Reset to Defaults to reverse any changes you made to the table.

SharingISCSIManualAuthorizedAccess

Use ADD to display the Authorized Access Add configuration screen. Click the icon for the authorized access and select Edit to display the Authorized Access Edit configuration form. Both the Add and Edit forms have the same settings fields.

SharingISCSIManualAuthorizedAccessForm

Group

SettingDescription
Group IDAllow you to configure different groups with different authentication profiles. For example, all users with a group ID of 1 inherit the authentication profile associated with Group 1.

User

SettingDescription
UserUser account to create for CHAP authentication with the user on the remote system. Many initiators use the initiator name as the user name.
SecretUser password of at least 12 but no more than 16 characters. Click the icon to display the characters you typed to verify you typed the desired password string. Click to hide the password string.
Secret (Confirm)Confirm the user password.

Peer User

SettingDescription
Peer UserOnly entered when configuring mutual CHAP. Usually the same value as User.
Peer SecretMutual secret password. Required when Peer User is set up. Must be different than the password used in Secret. Click the icon to display the characters you typed to verify you typed the desired password string. Click to hide the password string.
Peer Secret (Confirm)Confirm the mutual secret password.

Targets Tab

The Targets screen displays a list of storage resources configured in the system. It lets users create new TrueNAS storage resources or edit existing ones in the list. Use the blue Columns dropdown list to display a list of available options to add or remove columns in the Targets table. Select from Unselect All, Target Alias or Reset to Defaults to reverse any changes you made to the table.

SharingISCSIManualTargets

Use ADD to display the Targets Add configuration screen. Click the icon for the target and select Edit to display the Targets Edit configuration form. Both the Add and Edit forms have the same settings fields.

SharingISCSIManualTargetsForm

Basic Info

SettingDescription
Target NameThe base name for the target. It is automatically prepended if the target name does not start with iqn. Allowed characters are lowercase alphanumeric characters plus dot (.), dash (-), and colon (:). See the “Constructing iSCSI names using the iqn.format” section of RFC3721.
Target AliasOptional user-friendly name for the Target Name.

iSCSI Group

SettingDescription
Portal Group IDLeave empty or select an existing portal to use. If you click the dropdown arrow, you must select a portal group ID from the list.
Initiator Group IDSelect the existing initiator group that has access to the target. Leave empty if Portal Group ID is empty.
Authentication MethodSelect None, CHAP, or Mutual CHAP.
Authentication Group NumberSelect None or an integer. This value represents the number of existing authorized accesses.

Extents Tab

The Extents screen displays a list of available shared storage units configured on the system. It lets users create new shared storage units or edit existing ones in the list. Use the blue Columns dropdown list to display a list of available options to add or remove columns in the Extents table. Select from Unselect All, Description, Serial, NAA, Enabled or Reset to Defaults to reverse any changes you made to the table.

SharingISCSIManualExtents

Use ADD to display the Extents Add configuration screen. Click the icon for the shared storage unit and select Edit to display the Extents Edit configuration form. Both the Add and Edit forms have the same settings fields.

SharingISCSIManualExtentsForm

Basic Info

SettingDescription
NameName of the extent. An extent with a size of zero can be an existing file within the pool or dataset. An extent with a size other than zero cannot be an existing file within the pool or dataset.
DescriptionType any notes about this extent.
EnabledSelect to enable the iSCSI extent.

Type

SettingDescription
Extent TypeSpecify the storage unit type. Select Device or File from the dropdown list. Device provides virtual storage access to zvols, zvol snapshots, or physical devices. File provides virtual storage access to a single file.
DeviceOnly displays only if Device is the selected in Extent Type. Select the unformatted disk, controller, or zvol snapshot.
Path to the ExtentOnly displays if the Extent Type is set to File. Browse to an existing file. Create a new file by browsing to a dataset and appending /{filename.ext} to the path. Users cannot create extents inside a jail root directory.
FilesizeOnly displays if the Extent Type is set to File. Enter 0 to use the actual file size and it requires that the file already exists. Otherwise, specify the file size for the new file.
Logical Block SizeLeave at the default of 512 unless the initiator requires a different block size. Select from 512, 1024, 2048 or 4096 on the dropdown list.
Disable Physical Block Size ReportingSelect if the initiator does not support physical block size values over 4K (MS SQL).

Compatibility

SettingDescription
Enable TPCSelect to allow an initiator to bypass normal access control and access any scannable target. This allows xcopy operations that are otherwise blocked by access control.
Xen initiator compat modeSelect when using Xen as the iSCSI initiator.
LUN RPMDo not change this setting when using Windows as the initiator! Only change the default SSD setting if in a large environment where you need a number of systems using a specific RPM for accurate reporting statistics. Options are SSD, 5400, 7200, 10000 or 15000.
Read-onlySelect to prevent the initiator from initializing this LUN.

Associated Targets Tab

The Associated Targets screen displays a list of associated TrueNAS storage resources configured on the system. It lets users create new associated TrueNAS storage resources or edit existing ones in the list. Use the blue Columns dropdown list to display a list of available options to add or remove columns in the Associated Targets table. Select from Unselect All, LUN ID, Extent or Reset to Defaults to reverse any changes you made to the table.

SharingISCSIManualAssociatedTargets

Use ADD to display the Associated Targets Add configuration screen. Click the icon for the associated TrueNAS storage resource and select Edit to display the Associated Targets Edit configuration form. Both the Add and Edit forms have the same settings fields.

SharingISCSIManualAssociatedTargetsForm

SettingDescription
TargetSelect an existing target. This is a required field.
LUN IDSelect the value or enter a value between 0 and 1023. Some initiators expect a value below 256. Leave this field blank to automatically assign the next available ID.
ExtentSelect an existing extent. This is a required field.