TrueNAS Enterprise
TrueNAS SCALE
TrueNAS CORE
Compare Editions
TrueCommand
Software Status
FreeNAS
Compare Systems
F-Series
M-Series
H-Series
R-Series
Mini Series
Download TrueNAS SCALE
Download TrueNAS CORE
Get TrueNAS Enterprise
Contact an Enterprise SpecialistTrueNAS Nightly Development Documentation
This content follows experimental nightly development 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 Services Screen
15 minute read.
The iSCSI screen displays settings to configure iSCSI block shares.
About the Block (iSCSI) Sharing Protocol
Internet Small Computer Systems Interface (iSCSI) represents standards for using Internet-based protocols for linking binary data storage device aggregations. IBM and Cisco submitted the draft standards in March 2000. Since then, iSCSI has seen widespread adoption into enterprise IT environments.
iSCSI functions through encapsulation. The Open Systems Interconnection Model (OSI) encapsulates SCSI commands and storage data within the session stack. The OSI further encapsulates the session stack within the transport stack, the transport stack within the network stack, and the network stack within the data stack. Transmitting data this way permits block-level access to storage devices over LANs, WANs, and even the Internet itself (although performance clould suffer if your data traffic is traversing the Internet).
The table below shows where iSCSI sits in the OSI network stack:
| OSI Layer Number | OSI Layer Name | Activity as it relates to iSCSI |
|---|---|---|
| 7 | Application | An application tells the CPU that it needs to write data to non-volatile storage. |
| 6 | Presentation | OSI creates a SCSI command, SCSI response, or SCSI data payload to hold the application data and communicate it to non-volatile storage. |
| 5 | Session | Communication between the source and the destination devices begins. This communication establishes when the conversation starts, what it talks about, and when the conversion ends. This entire dialogue represents the session. OSI encapsulates the SCSI command, SCSI response, or SCSI data payload containing the application data within an iSCSI Protocol Data Unit (PDU). |
| 4 | Transport | OSI encapsulates the iSCSI PDU within a TCP segment. |
| 3 | Network | OSI encapsulates the TCP segment within an IP packet. |
| 2 | Data | OSI encapsulates the IP packet within the Ethernet frame. |
| 1 | Physical | The Ethernet frame transmits as bits (zeros and ones). |
Unlike other sharing protocols on TrueNAS, an iSCSI share allows block sharing and file sharing. Block sharing provides the benefit of block-level access to data on the TrueNAS. iSCSI exports disk devices (zvols on TrueNAS) over a network that other iSCSI clients (initiators) can attach and mount.
iSCSI Terminology
Challenge-Handshake Authentication Protocol (CHAP): an authentication method that uses a shared secret and three-way authentication to determine if a system is authorized to access the storage device. It also periodically confirms that the session has not been hijacked by another system. In iSCSI, the client (initiator) performs the CHAP authentication.
Mutual CHAP: a CHAP type in which both ends of the communication authenticate to each other.
Internet Storage Name Service (iSNS): protocol for the automated discovery of iSCSI devices on a TCP/IP network.
Extent: the storage unit to be shared. It can either be a file or a device.
Portal: indicates which IP addresses and ports to listen on for connection requests.
Initiators and Targets: iSCSI introduces the concept of initiators and targets which act as sources and destinations respectively. iSCSI initiators and targets follow a client/server model. Below is a diagram of a typical iSCSI network. The TrueNAS storage array acts as the iSCSI target and can be accessed by many of the different iSCSI initiator types, including software and hardware-accelerated initiators.
The iSCSI protocol standards require that iSCSI initiators and targets are represented as iSCSI nodes. It also requires that each node is given a unique iSCSI name. To represent these unique nodes via their names, iSCSI requires the use of one of two naming conventions and formats, IQN or EUI.
IQN names must follow these conventions for allowed characters, as described in RFC-3722:
- dash (
-) - dot (
.) - colon (
:) - lower case characters (
a…z). Upper-case characters must be mapped to their related lower-case counterparts. - digits (
0…9)
iSCSI also allows the use of iSCSI aliases which are not required to be unique and can help manage nodes.
- dash (
Logical Unit Number (LUN): LUN represents a logical SCSI device. An initiator negotiates with a target to establish connectivity to a LUN. The result is an iSCSI connection that emulates a connection to a SCSI hard disk. Initiators treat iSCSI LUNs as if they were a raw SCSI or SATA hard drive. Rather than mounting remote directories, initiators format and directly manage filesystems on iSCSI LUNs. When configuring multiple iSCSI LUNs, create a new target for each LUN. Since iSCSI multiplexes a target with multiple LUNs over the same TCP connection, there can be TCP contention when more than one target accesses the same LUN. TrueNAS supports up to 1024 LUNs.
Jumbo Frames: Jumbo frames are the name given to Ethernet frames that exceed the default 1500 byte size. This parameter is typically referenced by the nomenclature as a maximum transmission unit (MTU). A MTU that exceeds the default 1500 bytes necessitates that all devices transmitting Ethernet frames between the source and destination support the specific jumbo frame MTU setting, which means that NICs, dependent hardware iSCSI, independent hardware iSCSI cards, ingress and egress Ethernet switch ports, and the NICs of the storage array must all support the same jumbo frame MTU value. So, how does one decide if they should use jumbo frames?
Administrative time is consumed configuring jumbo frames and troubleshooting if/when things go sideways. Some network switches might also have ASICs optimized for processing MTU 1500 frames while others might be optimized for larger frames. Systems administrators should also account for the impact on host CPU utilization. Although jumbo frames are designed to increase data throughput, it might measurably increase latency (as is the case with some un-optimized switch ASICs); latency is typically more important than throughput in a VMware environment. Some iSCSI applications might see a net benefit running jumbo frames despite possible increased latency. Systems administrators should test jumbo frames on their workload with lab infrastructure as much as possible before updating the MTU on their production network.
TrueNAS Enterprise
Asymmetric Logical Unit Access (ALUA): ALUA allows a client computer to discover the best path to the storage on a TrueNAS system. HA storage clusters can provide multiple paths to the same storage. For example, the disks are directly connected to the primary computer and provide high speed and bandwidth when accessed through that primary computer. The same disks are also available through the secondary computer, but speed and bandwidth are restricted.
With ALUA, clients automatically ask for and use the best path to the storage. If one of the TrueNAS HA computers becomes inaccessible, the clients automatically switch to the next best alternate path to the storage. When a better path becomes available, as when the primary host becomes available again, the clients automatically switch back to that better path to the storage.
Do not enable ALUA on TrueNAS unless it is also supported by and enabled on the client computers. ALUA only works when enabled on both the client and server.
There are a few different approaches for configuring and managing iSCSI-shared data:
TrueNAS Enterprise customers that use vCenter to manage their systems can use the TrueNAS vCenter Plugin to connect their TrueNAS systems to vCenter and create and share iSCSI datastores. This is all managed through the vCenter web interface.
TrueNAS 13 web interface: the TrueNAS web interface is fully capable of configuring iSCSI shares. This requires creating and populating zvol block devices with data, then setting up the iSCSI Share. TrueNAS Enterprise licensed customers also have additional options to configure the share with Fibre Channel.
TrueNAS 24.10 web interface: TrueNAS 24.10 offers a similar experience to TrueNAS 13 for managing data with iSCSI; create and populate the block storage, then configure the iSCSI share.
The iSCSI configuration screens display seven tabs, one for each of the share configuration areas.
The Add button at the top of the Sharing > iSCSI screen works with the currently selected tab or screen. For example, if Portals is the current tab/screen, the Add button opens the Add Portal screen.
The more_vert on configure tab screens with list views display the Edit and Delete options. Edit opens the Edit screen for the selected tab screen. For example, when on the Portals tab/screen, the Sharing > iSCSI > Portals > Edit screen opens.
The Delete option opens the delete dialog for the screen currently selected.
The Add and Edit screens display the same settings.
The Target Global Configuration displays configuration settings that apply to all iSCSI shares. There are no add, edit, or delete options for this screen. It opens after you click Configure on the Block (iSCSI) Share Target widget on the Sharing screen. It also opens when you click Config Service.
The System > Services > iSCSI displays the Target Global Configuration and all the other configuration screens after you click the iSCSI Config option on the Services screen.
| Setting | Description |
|---|---|
| Base Name | Enter a name using lowercase alphanumeric characters. Allowed characters include the dot (.), dash (-), and colon (:). See the “Constructing iSCSI names using the iqn.format” section of RFC3721. |
| ISNS Servers | Enter host names or IP addresses of the ISNS servers to register with the iSCSI targets and portals of the system. Separate entries by pressing Enter. |
| Pool Available Space Threshold (%) | Enters a value for the threshold percentage that generates 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. |
| iSCSI listen port | The TCP port number that the controller uses to listen for iSCSI logins from host iSCSI initiators. |
| Asymmetric Logical Unit Access (ALUA) | Enable ALUA on TrueNAS only if it is also supported by and enabled on client computers. This option only shows on Enterprise-licensed systems. ALUA only works when enabled on both the client and server. |
The configuration tabs Portals screen displays a list of portal ID groups on the TrueNAS system.
The more_vert next to the portal displays the Edit and Delete options. 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.
| Setting | Description |
|---|---|
| Description | Enter an optional description. Portals are automatically assigned a numeric group. |
| Setting | Description |
|---|---|
| Discovery Authentication Method | Select the discovery method you want to use for authentication from the dropdown list. iSCSI supports multiple authentication methods that targets can use to discover valid devices. None allows anonymous discovery. If set to None, you can leave Discovery Authentication Group set to None or empty. If set to CHAP or Mutual CHAP, you must enter or create a new group in Discovery Authentication Group. |
| Discovery Authentication Group | Select the discovery authentication group you want to use from the dropdown list. This is the group ID created in Authorized Access. Required when the Discovery Authentication Method is CHAP or Mutual CHAP. Select None or Create New. Create New displays additional setting options. |
| Setting | Description |
|---|---|
| IP Address | Select the IP addresses the portal listens to. 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. |
| Port | TCP port used to access the iSCSI target. The default is 3260. |
| Add | Adds another IP address row. |
The Initiators Groups screen display settings to create new authorized access client groups or edit existing ones in the list.
The more_vert next to the initiator group displays the Edit and Delete options. Delete opens the Delete dialog for the selected group ID. Click Confirm and then Delete to delete the selected portal.
Add opens the Sharing > iSCSI > Initiators > Add screen. Edit opens the Sharing > iSCSI > Initiators > Edit screen. Both screens have the same setting options.
| 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. |
The Authorized Access screen displays settings to create new authorized access networks or edit existing ones in the list.
If you have not set up authorized access yet, the No Authorized Access screen displays with the Add Authorized Access button in the center of the screen. Add Authorized Access or Add at the top of the screen opens the Add Authorized Access screen.
After adding authorized access to the system, the Authorized Access screen displays a list of users.
Add opens the Add Authorized Access screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit Authorized Access screen, and Delete opens a dialog to delete the authorized access for the selected user. The Add and Edit screens display the same settings.
| Setting | Description |
|---|---|
| Group ID | Enter a number. This allows configuring different groups with different authentication profiles. Example: all users with a group ID of 1 inherit the authentication profile associated with Group 1. |
| 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. |
| Setting | Description |
|---|---|
| Peer User | Optional. Enter only when configuring mutual CHAP. Usually the same value as User. |
| Peer Secret | Enter the mutual secret password. Required if entering a Peer User. Must be a different password than the password in Secret. |
| Peer Secret (Confirm) | Enter the same password to confirm the mutual secret password. |
The Targets screen displays settings to create new TrueNAS storage resources or edit existing ones in the list.
Add opens the Add iSCSI Targets screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit iSCSI Targets screen, and Delete opens a dialog to delete the select target. The Add iSCSI Targets and Edit iSCSI Targets screens display the same settings.
The Add iSCSI Target and Edit iSCSI Target screens display the same settings, but the current settings populate the Edit iSCSI Target screen settings for the selected share.
To access the Add iSCSI Target screen from the Sharing > iSCSI screen, while on the Targets tab, click Add at the top of the screen. To access the Edit iSCSI Target screen from the Sharing > iSCSI screen, while on the Targets tab, click more_vert next to the share and then click Edit.
The Extents screen displays settings to create new shared storage units or edit existing ones in the list.
Add opens the Add Extent screen.
The more_vert next to each entry opens two options, Edit and Delete. Edit opens the Edit Extent screen, and Delete opens a dialog to delete the extents for the selected user. The Add and Edit screens display the same 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. |
| Setting | Description |
|---|---|
| Extent Type | Select the extent (zvol) option 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. Device provides virtual storage access to zvols, zvol snapshots, or physical devices. File provides virtual storage access to a single file. |
| Device | Required. Displays if Extent Type is set to Device. Select the unformatted disk, controller, or zvol snapshot. |
| Path to the Extent | Displays when Extent Type is set to File. Click the to browse 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. |
| Filesize | Only 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 Size | Enter a new value or leave it at the default of 512 unless the initiator requires a different block size. |
| Disable Physical Block Size Reporting | Select if the initiator does not support physical block size values over 4K (MS SQL). |
| Setting | Description |
|---|---|
| Enable TPC | Select 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 mode | Select when using Xen as the iSCSI initiator. |
| LUN RPM | Select the option from the dropdown list. Options are UNKNOWN, 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. |
The Associated Targets screen displays settings to create new associated TrueNAS storage resources or edit existing ones in the list.
Add opens the Add Associated Target screen.
The more_vert next to each entry displays two options, Edit and Delete. Edit opens the Edit Associated Target screen, and Delete opens a dialog to delete the associated targets for the selected user. The Add and Edit screens display the same settings.
| Setting | Description |
|---|---|
| Target | Required. Select an existing target. |
| LUN ID | Select 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. |
| Extent | Required. Select an existing extent. |