(408) 943-4100               V   Commercial Support Toggle between Light and Dark mode

iSCSI Shares

  12 minute read.

Last Modified 2021-09-09 13:47 EDT

To get started, make sure you have created a zvol or a dataset with at least one file to share.

Go to Sharing > Block Shares (iSCSI). You can either set one up manually or use the wizard to guide you through creation.

Wizard Setup

First, enter a name for the iSCSI share. It can only contain lowercase alphanumeric characters plus a dot (.), dash (-), or colon (:). We recommend keeping the name short or at most 63 characters. Next, choose the Extent Type.

  • If the Extent Type is Device, select the Zvol to share from the Device menu.

  • If the Extent Type is File, select the path to the Extent and indicate the file size.

Select the type of platform that will be using the share. For example, if using the share from an updated Linux OS, choose Modern OS.

SharingISCSIWizardDevice

Now you will either create a new portal or select an existing one from the dropdown.

If you create a new portal, you will need to select a Discovery Authentication Method.

If you set the Discovery Authentication Method to CHAP or MUTUAL CHAP, you will also need to select a Discovery Authentication Group. If no group exists, click Create New from the drop-down and enter a Group ID, User, and Secret.

SharingISCSIWizardPortal

When the Discovery Authentication Method is NONE, the Discovery Authentication Group can be left empty.

Select 0.0.0.0 or :: from the IP Address dropdown and click NEXT.

0.0.0.0 listens on all IPv4 addresses and :: listens on all IPv6 addresses.

Decide which initiators or networks can use the iSCSI share. Leave the list empty to allow all initiators or networks, or add entries to the list to limit access to those systems.

SharingISCSIWizardInitiator

Confirm the settings are correct and click SUBMIT.

SharingISCSIWizardSummary

Manual Setup

The Target Global Configuration tab lets users configure settings that will 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 ServersHostnames or IP addresses of the ISNS servers to be registered with the iSCSI targets and portals of the system. Separate entries by pressing Enter.
Pool Available Space Threshold (%)Generate an alert when the pool has this percent 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.

The Portals tab lets users create new portals or edit existing ones in the list.

SharingISCSIManualPortals

To add a new portal, click ADD and enter the basic and IP address information.

To edit an existing portal, click next to the portal and select Edit.

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 to be listened on by the portal. 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.

The Initiators Groups tab lets users create new authorized access client groups or edit existing ones in the list.

SharingISCSIManualInitiators

To add a new initiators group, click ADD and either leave Allow All Initiators checked or configure your own allowed initiators and authorized networks.

To edit an existing initiators group, click next to the initiators group and select Edit.

SettingDescription
Allow All InitiatorsAllows All Initiators when checked.
Allowed Initiators (IQN)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.
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.
DescriptionAny notes about initiators.

The Authorized Access tab lets users create new authorized access networks or edit existing ones in the list.

SharingISCSIManualAuthorizedAccess

To add a new authorized access network, click ADD and fill out the group, user, and peer user information.

To edit an existing authorized access network, click next to it and select Edit.

SharingISCSIManualAuthorizedAccessForm

Group

SettingDescription
Group IDAllow different groups to be configured with different authentication profiles. Example: all users with a group ID of 1 will 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. Must be at least 12 and no more than 16 characters long.
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. Must be different than the Secret.
Peer Secret (Confirm)Confirm the mutual secret password.

The Targets tab lets users create new TrueNAS storage resources or edit existing ones in the list.

SharingISCSIManualTargets

To add a new target, click ADD and enter the basic and iSCSI group information.

To edit an existing target, click next to it and select Edit.

SharingISCSIManualTargetsForm

Basic Info

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

iSCSI Group

SettingDescription
Portal Group IDLeave empty or select an existing portal to use.
Initiator Group IDSelect which existing initiator group has access to the target.
Authentication MethodChoices are None, Auto, CHAP, or Mutual CHAP.
Authentication Group NumberSelect None or an integer. This value represents the number of existing authorized accesses.

The Extents tab lets users create new shared storage units or edit existing ones in the list.

SharingISCSIManualExtents

To add a new extent, click ADD and enter the basic, type, and compatibility information.

To edit an existing extent, click next to it and select Edit.

SharingISCSIManualExtentsForm

Basic Info

SettingDescription
NameName of the extent. If the Extent size is not 0, it cannot be an existing file within the pool or dataset.
DescriptionNotes about this extent.
EnabledSet to enable the iSCSI extent.

Type

SettingDescription
Extent TypeDevice provides virtual storage access to zvols, zvol snapshots, or physical devices. File provides virtual storage access to a single file.
DeviceOnly appears if Device is selected. Select the unformatted disk, controller, or zvol snapshot.
Path to the ExtentOnly appears if File is selected. 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 appears if File is selected. Entering 0 uses the actual file size and 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.
Disable Physical Block Size ReportingSet if the initiator does not support physical block size values over 4K (MS SQL).

Compatibility

SettingDescription
Enable TPCSet 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 modeSet when using Xen as the iSCSI initiator.
LUN RPMDo NOT change this setting when using Windows as the initiator. Only needs to be changed in large environments where the number of systems using a specific RPM is needed for accurate reporting statistics.
Read-onlySet to prevent the initiator from initializing this LUN.

The Associated Targets tab lets users create new associated TrueNAS storage resources or edit existing ones in the list.

SharingISCSIManualAssociatedTargets

To add a new associated target, click ADD and fill out the information.

To edit an existing associated target, click next to it and select Edit.

SharingISCSIManualAssociatedTargetsForm

SettingDescription
TargetSelect an existing target.
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.

Starting the iSCSI Service

To turn on the iSCSI service, go to Services and toggle iSCSI. Set Start Automatically to start it when TrueNAS boots up.

ServicesISCSIEnable

Clicking the returns to the options in Sharing > iSCSI.

Using the iSCSI Share

Connecting to and using an iSCSI share can differ between operating systems:

iSCSI Utilities and Service

First, open the command line and ensure that the open-iscsi utility is installed. To install the utility on an Ubuntu/Debian distribution, enter sudo apt update && sudo apt install open-iscsi. After the installation completes, ensure the iscsid service is running: sudo service iscsid start. With the iscsid service started, run the iscsiadm command with the discovery arguments and get the necessary information to connect to the share.

LinuxISCSIAppInstall

Discover and Log In to the iSCSI Share

Run the command sudo iscsiadm \--mode discovery \--type sendtargets \--portal {IPADDRESS}. The output provides the basename and target name that TrueNAS configured.

LinuxISCSIDiscoveryList

Alternatively, enter sudo iscsiadm -m discovery -t st -p {IPADDRESS} to get the same output. Note the basename and target name given in the output, since they you need them to log in to the iSCSI share.

When a Portal Discovery Authentication Method is CHAP, add the three following lines to /etc/iscsi/iscsid.conf.

discovery.sendtargets.auth.authmethod = CHAP
discovery.sendtargets.auth.username = user
discovery.sendtargets.auth.password = secret

The user for discovery.sendtargets.auth.username is set in the Authorized Access used by the Portal of the iSCSI share. Likewise, the password to use for discovery.sendtargets.auth.password is the Authorized Access secret. Without those lines, the iscsiadm will not discover the Portal with the CHAP authentication method.

Next, enter sudo iscsiadm \--mode node \--targetname {BASENAME}:{TARGETNAME} \--portal {IPADDRESS} \--login, where {BASENAME} and {TARGETNAME} is the information from the discovery command.

LinuxISCSILogin

Partition iSCSI Disk

When the iSCSI share login succeeds, the device shared through iSCSI shows on the Linux system as an iSCSI Disk. To view a list of connected disks in Linux, enter sudo fdisk -l.

FDiskList

Because the connected iSCSI disk is raw, you must partition it. Identify the iSCSI device in the list and enter sudo fdisk {/PATH/TO/iSCSIDEVICE}.

FDiskPartition

Shell lists the iSCSI device path in the sudo fdisk -l output. Use the fdisk command defaults when partitioning the disk.

Remember to type w when finished partitioning the disk. The w command tells fdisk to save any changes before quitting.

LinuxISCSIFilesystemCreated

After creating the partition on the iSCSI disk, a partition slice displays on the device name. For example, /dev/sdb1. Enter fdisk -l to see the new partition slice.

Make a Filesystem on the iSCSI Disk

Finally, use mkfs to make a filesystem on the device’s new partition slice. To create the default filesystem (ext2), enter sudo mkfs {/PATH/TO/iSCSIDEVICEPARTITIONSLICE}.

LinuxISCSIFilesystem

Mount the iSCSI Device

Now the iSCSI device can mount and share data. Enter sudo mount {/PATH/TO/iSCSIDEVICEPARTITIONSLICE}. For example, sudo mount /dev/sdb1 /mnt mounts the iSCSI device sdb1 to /mnt.

To access the data on the iSCSI share, clients will need to use iSCSI Initiator software. An iSCSI Initiator client is pre-installed in Windows 7 to 10 Pro, and Windows Server 2008, 2012, and 2019. Windows Professional Edition is usually required.

First, click the Start Menu and search for the iSCSI Initiator application.

WindowsISCSIInitiatorApp

Next, go to the Configuration tab and click Change to change the iSCSI initiator to the same name created earlier. Click OK.

Windows ISCSI Initiator Config Name

Next, switch to the Discovery Tab, click Discover Portal, and type in the TrueNAS IP address.

  • If TrueNAS changed the port number from the default 3260, enter the new port number.

  • If you set up CHAP when creating the iSCSI share, click Advanced…, set Enable CHAP log on, and enter the initiator name and the same target/secret set earlier in TrueNAS.

Click OK.

Windows ISCSI Initiator Discover Portal

Go to the Targets tab, highlight the iSCSI target, and click Connect.

Windows ISCSI Initiator Target Connect

After Windows connects to the iSCSI target, you can partition the drive.

Search for and open the Disk Management app.

WindowsISCSIDiskManagementApp

Your drive should currently be unallocated. Right-click the drive and click New Simple Volume….

WindowsISCSIDiskNewVolume

Complete the Wizard to format the drive and assign a drive letter and name.

WindowsISCSIDiskNewVolumeOptions

Finally, go to This PC or My Computer in File Explorer. The new iSCSI volume should show up under the list of drives. You should now be able to add, delete, and modify files and folders on your iSCSI drive.

WindowsiSCSIVolumeLocation

Expanding LUNs

TrueNAS lets users expand Zvol and file-based LUNs to increase the available storage that the iSCSI shares.

To expand a Zvol LUN, go to Storage > Pools and click the next to the Zvol LUN, then select Edit Zvol.

ExpandingZvolLUNList

Enter a new size in the Size for this zvol field, then click SAVE.

ExpandingZvolLUNSize

To prevent data loss, the web interface does not allow users to reduce the Zvol’s size. TrueNAS also does not allow users to increase the Zvol’s size past 80% of the pool size.

To expand a file-based LUN, you will need to know the path to the file. You can find the path by going to Sharing > Block Shares (iSCSI) and clicking the Extents tab. Click the next to the file-based LUN and select Edit.

ExpandingFileLUNPath

Highlight and copy the path, then click CANCEL

Go to Shell and input truncate -s +[size] [path to file], then press Enter.

The [size] is how much space you want to grow the file by, and the [path to file] is the file path you copied earlier.

ExpandingFileLUNShell

An example of the command could look like this: truncate -s +2g /mnt/Shares/Dataset1/FileLun/FileLUN

Lastly, go back to the extent in Sharing > Block Shares (iSCSI) and make sure the Filesize is set to 0 so that the share uses the actual file size.