Adding iSCSI Block Shares

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

Go to Shares and click Configure in the Block (iSCSI) Shares Targets window. You can either use the creation wizard or set one up manually.

TrueNAS offers two methods to add an iSCSI block share: the setup wizard or the manual steps using the screen tabs. Both methods cover the same basic steps but have some differences.

The setup wizard requires you to enter some settings before you can move on to the next screen or step in the setup process. It is designed to ensure you configure the iSCSI share completely so it can be used immediately.

The manual process has more configuration screens over the wizard and allows you to configure the block share in any order. Use this process to customize your share for special use cases. It is designed to give you additional flexibility to build or tune a share to your exact requirements.

Have the following ready before you begin adding your iSCSI block share:

• Storage pool and dataset.
• A path to a Device (zvol or file) that doesn’t use capital letters or spaces.

This section walks you through the setup process using the wizard screens.

To use the setup wizard:

1. Click Wizard to open the Target screen. Click Create New.

   

2. Add the extent.

   

   

   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.

   Select the extent type. Choose between device and file based on your use case.

   Adding a Device

   If choosing Device, select an existing device from the dropdown list or Create New to add a new device.

   Enter or browse to select the path to the dataset to use for storage. If one does not exist, click Create Dataset to add a new dataset.

   Enter a numerical value and suffix to specify the size of the zvol you are creating in Size.

   Adding a File

   If choosing File, enter or browse to select the mount point for the directory the extent uses. If a directory does not exist, after selecting the dataset where you want to add the directory, enter a / followed by the name to add the directory to the dataset.

   Enter the size for the directory in Filesize. Leaving this set to 0 uses the actual file size and requires that the file already exists. Otherwise, specify the file size for the new file.

   Select the sharing platform, then click Next.

3. Create the portal.

   

   Select a portal from the dropdown list or click Create New to add a new portal. If you create a new portal, click Add to enter an IP address and netmask (CIDR) for the portal. To add another, click Add again.

   Leave Initiator blank to allow all, or enter a host name. To enter more than one host name, press Enter after each to separate each entry. select a Discovery Authentication Method from the dropdown list.

4. click Save.

This procedure guides you through adding an iSCSI share using the individual configuration screens. While the procedure places each screen in order, you can select tab screens in any order.

Click on the Block (iSCSI) Share Targets widget header to open the individual share screens. The Targets screen opens by default.

1. Add a target.

   

   a. Click Add to open the Add Target screen.

   

   b. Enter a name using lowercase alphanumeric characters plus dot (.), dash (-), and colon (:) in Target Name. Use the iqn.format for the name. See the “Constructing iSCSI names using the iqn.format” section of RFC3721.

   You can enter a common name for the target in Target Alias but this is not required.

   c. Add authorized networks. Click Add to show the Network fields to enter an IP address and netmask (CIDR). This allows communication between client computers and the iSCSI target. Click Add for each address you want to add. Addresses are added to the authorized networks list.

   d. Click Add to the right of Add Groups to enter portal settings.

   Select a target with a number assignment from the dropdown list in Portal ID.

   Select the authentication method from the dropdown list. None allows anonymous discovery. CHAP uses one-way authentication. Mutual CHAP uses two-way authentication. For more information on authentication methods, see iSCSI Screens.

   Select a portal ID from the Initiator Group ID dropdown list.

   The Authentication Group Number dropdown list is populated after configuration groups on the Add Authorized Access screen. Edit the target after adding these groups if you want to include them.

   e. Click Save.

2. Add extent(s). Click on the Extents tab, then click Add to open the Add Extent screen.

   

   

   a. Enter a name.

   b. Add a description about the extent if you want but this is not required.

   c. Select Enabled to enable the extent.

   d. Leave Enable TCP selected. To disable it, clear the checkbox. Select Xen initiator compat mode* if required for your share.

   e. Set the device type as Device or File.

   Adding a Device Extent

     After choosing **Device** in **Extent Type**, select the zvol or zvol snapshot from the **Device** dropdown list.
     
     Accept the default in **Logical Block Size** or change the size to what fits your use case.
   

   Adding a File Extent

     After choosing **File** in **Extent Type**, 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).
   
     Enter the file size. Enter 0 to use the actual file size of an existing file, or specify the size to apply to the new file added in **Path to the Extent**.
   

   f. Leave Disable Physical Block Size Reporting disabled unless you want to enable this function.

   g. Click Save.

3. Add initiator groups. Click on the Initiators tab, then click Add to open the Add Initiator screen.

   

   Leave Allow All Initiators selected, or clear and enter the host names or IP address of the ISNS servers to register with the iSCSI targets and portals of the system. Separate entries by pressing Enter.

   Click Save.

4. Add portals. Click on the Portals tab, then click Add to open the Add Portal screen.

   

   a. Enter a description for the portal if desired.

   b. Click Add to show the IP Address field. Enter the IP address and netmask (CIDR) for the portal. Click Add for each IP address to add.

   Enter 0.0.0.0 to listen on all IPv4 addresses, :: to listen on all IPv6 addresses, or enter the server IP address.

   c. Click Save.

5. Enter authorized access networks. Click on the Authorized Access tab, then click Add to open the Add Authorized Access screen.

   

   a. Enter a number in Group ID. This field 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.

   b. Select the discovery method from the dropdown list. None allows anonymous discovery. CHAP uses one-way discovery. Mutual CHAP uses two-way discovery.

   c. Enter a user account name and password for CHAP authentication to the remote system. This can be the admin user account credentials.

   d. Enter a peer user account and password if using Mutual CHAP authentication.

   e. Click Save.

TrueNAS allows users to add iSCSI targets without needing to add another share. Go to Shares and click the Block (iSCSI) Shares Targets widget header to open the Targets screen.

1. Click Add at the top right of the screen to open the Add iSCSI Target screen.

2. Enter a name in Target Name. Use lowercase alphanumeric characters plus dot (.), dash (-), and colon (:) in the iqn.format. See the “Constructing iSCSI names using the iqn.format” section of RFC3721.

3. (Optional) Enter a user-friendly name in Target Alias.

4. Add authorized networks. Click Add to show the Network fields where you can enter an IP address and netmask (CIDR). This allows communication between client computers and the iSCSI target. Click Add for each address you want to add. Addresses are added to the authorized networks list.

5. Click Add to the right of Add Groups to enter portal settings.

   Select a target with a number assignment from the dropdown list in Portal ID.

   Select the authentication method from the dropdown list. None allows anonymous discovery. CHAP uses one-way authentication. Mutual CHAP uses two-way authentication. For more information on authentication methods, see iSCSI Screens.

   Select a portal ID from the Initiator Group ID dropdown list.

   The Authentication Group Number dropdown list is populated after configuration groups on the Add Authorized Access screen. Edit the target after adding these groups if you want to include them.

6. Click Save.

After adding a share with the iSCSI wizard or manual entry screens, the system shows a dialog prompting you to start or restart the service.

You can also start the service by clicking on the more_vert on the Block (iSCSI) Shares Targets widget and selecting Turn On Service. You can also go to System > Services, locate iSCSI on the service list, and click the Running toggle to start the service.