10. Sharing¶
Once you have a volume, create at least one share so that the storage is accessible by the other computers in your network. The type of share you create depends upon the operating system(s) running in your network, your security requirements, and expectations for network transfer speeds.
Beginning with version 9.3, FreeNAS® provides an Initial Configuration Wizard for creating shares. The Wizard will automatically create the correct type of dataset and permissions for the type of share, set the default permissions for the share type, and start the service needed by the share. It is recommended to use the Wizard to create shares, fine-tune the share settings using the instructions in the rest of this chapter if needed, then to fine-tune the default permissions from the client operating system to meet the requirements of the network.
Note
shares are created to provide and control access to an area of storage. Before creating your shares, it is recommended to make a list of the users that will need access to storage data, which operating systems these users are using, whether or not all users should have the same permissions to the stored data, and whether or not these users should authenticate before accessing the data. This information can help you determine which type of share(s) you need to create, whether or not you need to create multiple datasets in order to divide up the storage into areas with differing access and permission requirements, and how complex it will be to setup your permission requirements. It should be noted that a share is used to provide access to data. If you delete a share, it removes access to data but does not delete the data itself.
The following types of shares and services are available:
- Apple (AFP) Shares: the Apple File Protocol (AFP) type of share is a good choice if all of your computers run Mac OS X.
- Unix (NFS) Shares: the Network File System (NFS) type of share is accessible by Mac OS X, Linux, BSD, and the professional and enterprise versions (not the home editions) of Windows. It is a good choice if there are many different operating systems in your network. Depending upon the operating system, it may require the installation or configuration of client software on the desktop.
- WebDAV Shares: this type of share is accessible using an authenticated web browser (read-only) or WebDAV client running on any operating system.
- Windows (CIFS) Shares: the Common Internet File System (CIFS) type of share is accessible by Windows, Mac OS X, Linux, and BSD computers, but it is slower than an NFS share due to the single-threaded design of Samba. It provides more configuration options than NFS and is a good choice on a network containing any Windows systems. However, it is a poor choice if the CPU on the FreeNAS® system is limited; if your CPU is maxed out, you need to upgrade the CPU or consider another type of share.
- Block (iSCSI) shares: this type of share appears as an unformatted disk to clients running iSCSI initiator software or a virtualization solution such as VMware.
If you are looking for a solution that allows fast access from any operating system, consider configuring the FTP service instead of a share and use a cross-platform FTP and file manager client application such as Filezilla. Secure FTP can be configured if the data needs to be encrypted.
If data security is a concern and your network’s users are familiar with SSH command line utilities or WinSCP, consider configuring the SSH service instead of a share. It will be slower than unencrypted FTP due to the overhead of encryption, but the data passing through the network will be encrypted.
Note
while the GUI will let you do it, it is a bad idea to share the same volume or dataset using multiple types of access methods. Different types of shares and services use different file locking methods. For example, if the same volume is configured to use both NFS and FTP, NFS will lock a file for editing by an NFS user, but a FTP user can simultaneously edit or delete that file. This will result in lost edits and confused users. Another example: if a volume is configured for both AFP and CIFS, Windows users may be confused by the extra filenames used by Mac files and delete the ones they don’t understand; this will corrupt the files on the AFP share. Pick the one type of share or service that makes the most sense for the types of clients that will access that volume, and configure that volume for that one type of share or service. If you need to support multiple types of shares, divide the volume into datasets and use one dataset per share.
This section will demonstrate how to fine-tune the configuration of AFP, NFS, CIFS, WebDAV, and iSCSI shares. FTP and SSH configurations are described in Services Configuration.
11. <<<<<<< HEAD¶
Note
when using “fruit”, also add the “streams_xattr” and “catia” VFS objects and be sure to configure all CIFS shares this way. Reboot the Mac client after making this change.
The following VFS objects do not appear in the drop-down menu as they are always enabled:
- recycle: moves deleted files to the recycle directory instead of deleting them
- shadow_copy2: a more recent implementation of “shadow_copy” with some additonal features
- zfs_space: correctly calculates ZFS space used by share, including any reservations or quotas
- zfsacl:
>>>>>>> 3d83805... Note that client should be rebooted.
CIFS supports guest logins, meaning that users can access the CIFS share without needing to provide a username or password. This type of share is convenient as it is easy to configure, easy to access, and does not require any users to be configured on the FreeNAS® system. This type of configuration is also the least secure as anyone on the network can access the contents of the share. Additionally, since all access is as the guest user, even if the user inputs a username or password, there is no way to differentiate which users accessed or modified the data on the share. This type of configuration is best suited for small networks where quick and easy access to the share is more important than the security of the data on the share.
To configure an unauthenticated CIFS share, click “Wizard”, then click the “Next” button twice to display the screen shown in Figure 10.4b. Complete the following fields in this screen:
- Share name: input a name for the share that is useful to you. In this example, the share is named cifs_insecure.
- Click the button for “Windows (CIFS)” and check the box for “Allow Guest”.
- Click the “Ownership” button. Click the drop-down “User” menu and select “nobody”. Click the “Return” button to return to the previous screen.
- Click the “Add” button. If you forget to do this, the share will not be created. Clicking the “Add” button will add an entry to the “Name” frame with the name that you typed into “Share name”.
Figure 10.4b: Creating an Unauthenticated CIFS Share

Click the “Next” button twice, then the “Confirm” button to create the share. The Wizard will automatically create a dataset for the share and start the CIFS service for you, so that the share is immediately available. The new share will also be added as an entry to
.Users can now access the share from any CIFS client and should not be prompted for their username or password. For example, to access the share from a Windows system, open Explorer and click on “Network”. For this configuration example, a system named FREENAS should appear with a share named “insecure_cifs”. The user should be able to copy data to and from the unauthenticated CIFS share.
Most configuration scenarios require each user to have their own user account and to authenticate before accessing the share. This allows the administrator to control access to data, provide appropriate permissions to that data, and to determine who accesses and modifies stored data. A Windows domain controller is not needed for authenticated CIFS shares, which means that additional licensing costs are not required. However, since there is no domain controller to provide authentication for the network, each user account needs to be created on the FreeNAS® system. This type of configuration scenario is often used in home and small networks as it does not scale well if many users accounts are needed.
Before configuring this scenario, determine which users will need authenticated access. While not required for the configuration, it eases troubleshooting if the username and password that will be created on the FreeNAS® system matches that information on the client system. Next, determine if each user should have their own share to store their own data or if several users will be using the same share. The simpler configuration is to make one share per user as it does not require the creation of groups, adding the correct users to the groups, and ensuring that group permissions are set correctly.
To use the Wizard to create an authenticated CIFS share, enter the following information, as seen in the example in Figure 10.4c.
- Share name: input a name for the share that is useful to you. In this example, the share is named cifs_user1.
- Click the button for “Windows (CIFS)”.
- Click the “Ownership” button. To create the user account on the FreeNAS® system, type their name into the “User” field and check the “Create User” checkbox. This will prompt you to type in and confirm the user’s password. If the user will not be sharing this share with other users, type their name into the “Group” field and click the box “Create Group”. If, however, the share will be used by several users, instead type in a group name and check the “Create Group” box. In the example shown in Figure 10.4d, user1 has been used for both the user and group name, meaning that this share will only be used by user1. When finished, click “Return” to return to the screen shown in Figure 10.1d.
- Click the “Add” button. If you forget to do this, the share will not be created. Clicking the “Add” button will add an entry to the “Name” frame with the name that you typed into “Share name”.
If you wish to configure multiple authenticated shares, repeat for each user, giving each user their own “Share name” and “Ownership”. When finished, click the “Next” button twice, then the “Confirm” button to create the share(s). The Wizard will automatically create a dataset for each share that contains the correct ownership and start the CIFS service for you, so that the share(s) are immediately available. The new share(s) will also be added as entries to
.Figure 10.4c: Creating an Authenticated CIFS Share

Figure 10.4d: Creating the User and Group

You should now be able to test an authenticated share from any CIFS client. For example, to test an authenticated share from a Windows system, open Explorer and click on “Network”. For this configuration example, a system named FREENAS should appear with a share named “cifs_user1”. If you click on “cifs_user1”, a Windows Security pop-up screen should prompt for that user’s username and password. Input the values that were configured for that share, in this case it is for the user user1. Once authenticated, that user can copy data to and from the CIFS share.
To prevent Windows Explorer from hanging when accessing the share, map the share as a network drive. To do this, right-click the share and select “Map network drive...”. Choose a drive letter from the drop-down menu and click the “Finish” button.
Note that Windows systems cache a user’s credentials which can cause issues when testing or accessing multiple authenticated shares as only one authentication is allowed at a time. If you are having problems authenticating to a share and are sure that you are inputting the correct username and password, type cmd in the “Search programs and files” box and use the following command to see if you are already authenticated to a share. In this example, the user has already authenticated to the cifs_user1 share:
net use
New connections will be remembered.
Status Local Remote Network
------------------------------------------------------------------------
OK \\FREENAS\cifs_user1 Microsoft Windows Network
The command completed successfully.
To clear the cache:
net use * /DELETE
You have these remote connections:
\\FREENAS\cifs_user1
Continuing will cancel the connections.
Do you want to continue this operation? <Y/N> [N]: y
You will get an additional warning if the share is currently open in Explorer:
There are open files and/or incomplete directory searches pending on the connection
to \\FREENAS|cifs_user1.
Is it OK to continue disconnecting and force them closed? <Y/N> [N]: y
The command completed successfully.
The next time you access a share using Explorer, you should be prompted to authenticate.
Shadow Copies, also known as the Volume Shadow Copy Service (VSS) or Previous Versions, is a Microsoft service for creating volume snapshots. Shadow copies allow you to easily restore previous versions of files from within Windows Explorer. Shadow Copy support is built into Vista and Windows 7. Windows XP or 2000 users need to install the Shadow Copy client.
When you create a periodic snapshot task on a ZFS volume that is configured as a CIFS share in FreeNAS®, it is automatically configured to support shadow copies.
Before using shadow copies with FreeNAS®, be aware of the following caveats:
- If the Windows system is not fully patched to the latest service pack, Shadow Copies may not work. If you are unable to see any previous versions of files to restore, use Windows Update to make sure that the system is fully up-to-date.
- Shadow copy support only works for ZFS pools or datasets. This means that the CIFS share must be configured on a volume or dataset, not on a directory.
- Datasets are filesystems and shadow copies cannot traverse filesystems. If you want to be able to see the shadow copies in your child datasets, create separate shares for them.
- Shadow copies will not work with a manual snapshot, you must create a periodic snapshot task for the pool or dataset being shared by CIFS or a recursive task for a parent dataset.
- The periodic snapshot task should be created and at least one snapshot should exist before creating the CIFS share. If you created the CIFS share first, restart the CIFS service in .
- Appropriate permissions must be configured on the volume/dataset being shared by CIFS.
- Users can not delete shadow copies on the Windows system due to the way Samba works. Instead, the administrator can remove snapshots from the FreeNAS® administrative GUI. The only way to disable shadow copies completely is to remove the periodic snapshot task and delete all snapshots associated with the CIFS share.
To configure shadow copy support, use the instructions in Configuring Authenticated Access Without a Domain Controller to create the desired number of shares. In this configuration example, a Windows 7 computer has two users: user1 and user2. For this example, two authenticated shares are created so that each user account has their own share. The first share is named user1 and the second share is named user2. Then:
- Use
/mnt/volume1/user1
and/mnt/volume1/user2
, or you can create one periodic snapshot task for the entire volume, in this case/mnt/volume1
. Before continuing to the next step, confirm that at least one snapshot for each defined task is displayed in the tab. When creating the schedule for the periodic snapshot tasks, keep in mind how often your users need to access modified files and during which days and time of day they are likely to make changes.
, to create at least one periodic snapshot task. You can either create
a snapshot task for each user’s dataset, in this example the dataset names are - Go to . Highlight a share and click its “Edit” button then its “Advanced Mode” button. Click the “Periodic Snapshot Task” drop-down menu and select the periodic snapshot task to use for that share. Repeat for each share being configured as a shadow copy. For this example, the share named “/mnt/volume1/user1” is configured to use a periodic snapshot task that was configured to take snapshots of the “/mnt/volume1/user1” dataset and the share named “/mnt/volume1/user2” is configured to use a periodic snapshot task that was configured to take snapshots of the “/mnt/volume1/user2” dataset.
- Verify that the CIFS service is set to “ON” in .
Figure 10.4e provides an example of using shadow copies while logged in as user1 on the Windows system. In this example, the user right-clicked modified file and selected “Restore previous versions” from the menu. This particular file has three versions: the current version, plus two previous versions stored on the FreeNAS® system. The user can choose to open one of the previous versions, copy a previous version to the current folder, or restore one of the previous versions, which will overwrite the existing file on the Windows system.
Figure 10.4e: Viewing Previous Versions within Explorer

11.1. Block (iSCSI)¶
iSCSI is a protocol standard for the consolidation of storage data. iSCSI allows FreeNAS® to act like a storage area network (SAN) over an existing Ethernet network. Specifically, it exports disk devices over an Ethernet network that iSCSI clients (called initiators) can attach to and mount. Traditional SANs operate over fibre channel networks which require a fibre channel infrastructure such as fibre channel HBAs, fibre channel switches, and discrete cabling. iSCSI can be used over an existing Ethernet network, although dedicated networks can be built for iSCSI traffic in an effort to boost performance. iSCSI also provides an advantage in an environment that uses Windows shell programs; these programs tend to filter “Network Location” but iSCSI mounts are not filtered.
Before configuring the iSCSI service, you should be familiar with the following iSCSI terminology:
CHAP: an authentication method which uses a shared secret and three-way authentication to determine if a system is authorized to access the storage device and to periodically confirm that the session has not been hijacked by another system. In iSCSI, the initiator (client) performs the CHAP authentication.
Mutual CHAP: a superset of CHAP in that both ends of the communication authenticate to each other.
Initiator: a client which has authorized access to the storage data on the FreeNAS® system. The client requires initiator software in order to initiate the connection to the iSCSI share.
Target: a storage resource on the FreeNAS® system. Every target has a unique name known as an iSCSI Qualified Name (IQN).
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(s) and port(s) to listen on for connection requests.
LUN: stands for Logical Unit Number and 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 the same way as they would a raw SCSI or IDE 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, you will experience contention from TCP if there is more than one target per LUN.
Beginning with FreeNAS® 9.3, iSCSI is built into the kernel. This version of iSCSI supports Microsoft Offloaded Data Transfer (ODX), meaning that file copies happen locally, rather than over the network. It also supports the following VAAI (vStorage APIs for Array Integration) primitives, where VAAI is VMware’s API framework that enables certain storage tasks, such as large data moves, to be offloaded from the virtualization hardware to the storage array.
- unmap: tells ZFS that the space occupied by deleted files should be freed. Without unmap, ZFS is unaware of freed space made when the initiator deletes files. For this feature to work, the initiator must support the unmap command.
- atomic test and set: allows multiple initiators to synchronize LUN access in a fine-grained manner rather than locking the whole LUN, which would prevent other hosts from accessing the same LUN simultaneously.
- write same: when allocating virtual machines with thick provisioning, the necessary write of zeroes is done locally, rather than over the network, so virtual machine creation is much quicker.
- xcopy: similar to Microsoft ODX, copies happen locally rather than over the network.
- stun: if a volume runs out of space, this feature pauses any running virtual machines so that the space issue can be fixed, instead of reporting write errors.
- threshold warning: the system reports a warning when a configurable capacity is reached. In FreeNAS, this threshold can be configured at the pool level when using zvols (see Table 10.5a) or at the extent level (see Table 10.5f) for both file- and device-based extents. Typically, the warning is set at the pool level, unless file extents are used, in which case it must be set at the extent level.
- LUN reporting: the LUN reports that it is thin provisioned.
To take advantage of these VAAI primitives, create a zvol using the instructions in Create zvol and use it to create a device extent, as described in Extents.
In order to configure iSCSI:
- Review the target global configuration parameters.
- Create at least one portal.
- Determine which hosts are allowed to connect using iSCSI and create an initiator.
- Decide if you will use authentication, and if so, whether it will be CHAP or mutual CHAP. If using authentication, create an authorized access.
- Create a target.
- Create either a device or a file extent to be used as storage.
- Associate a target with an extent.
- Start the iSCSI service in .
The rest of this section describes these steps in more detail.
11.1.1. Target Global Configuration¶
, shown in Figures 10.5a, contains settings that apply to all iSCSI shares. Table 10.5a summarizes the settings that can be configured in the Target Global Configuration screen.
Figure 10.5a: iSCSI Target Global Configuration Variables

Table 10.5a: Target Global Configuration Settings
Setting | Value | Description |
---|---|---|
Base Name | string | see the “Constructing iSCSI names using the iqn. format” section of RFC 3721 if you are unfamiliar with this format |
ISNS Servers | string | space delimited list of hostnames or IP addresses of ISNS server(s) to register the system’s iSCSI targets and portals with |
Pool Available Space Threshold | integer | input the percentage of free space that should remain in the pool; when this percentage is reached, the system will issue an alert, but only if zvols are used |
11.1.2. Portals¶
A portal specifies the IP address and port number to be used for iSCSI connections.
will bring up the screen shown in Figure 10.5b.Table 10.5b summarizes the settings that can be configured when adding a portal. If you need to assign additional IP addresses to the portal, click the link “Add extra Portal IP”.
Figure 10.5b: Adding an iSCSI Portal

Table 10.5b: Portal Configuration Settings
Setting | Value | Description |
---|---|---|
Comment | string | optional description; portals are automatically assigned a numeric group ID |
Discovery Auth Method | drop-down menu | configures the authentication level required by the target for discovery of valid devices, where None will allow anonymous discovery while CHAP and Mutual CHAP require authentication |
Discovery Auth Group | drop-down menu | select a user created in “Authorized Access” if the “Discovery Auth Method” is set to CHAP or Mutual CHAP |
IP address | drop-down menu | select the IP address associated with an interface or the wildcard address of 0.0.0.0 (any interface) |
Port | integer | TCP port used to access the iSCSI target; default is 3260 |
FreeNAS® systems with multiple IP addresses or interfaces can use a portal to provide services on different interfaces or subnets. This can be used to configure multi-path I/O (MPIO). MPIO is more efficient than a link aggregation.
If the FreeNAS® system has multiple configured interfaces, portals can also be used to provide network access control. For example, consider a system with four interfaces configured with the following addresses:
192.168.1.1/24
192.168.2.1/24
192.168.3.1/24
192.168.4.1/24
You could create a portal containing the first two IP addresses (group ID 1) and a portal containing the remaining two IP addresses (group ID 2). You could then create a target named A with a Portal Group ID of 1 and a second target named B with a Portal Group ID of 2. In this scenario, istgt would listen on all four interfaces, but connections to target A would be limited to the first two networks and connections to target B would be limited to the last two networks.
Another scenario would be to create a portal which includes every IP address except for the one used by a management interface. This would prevent iSCSI connections to the management interface.
11.1.3. Initiators¶
The next step is to configure authorized initiators, or the systems which are allowed to connect to the iSCSI targets on the FreeNAS® system. To configure which systems can connect, use
, shown in Figure 10.5c.Figure 10.5c: Adding an iSCSI Initiator

Table 10.5c summarizes the settings that can be configured when adding an initiator.
Table 10.5c: Initiator Configuration Settings
Setting | Value | Description |
---|---|---|
Initiators | string | use ALL keyword or a list of initiator hostnames separated by spaces |
Authorized network | string | use ALL keyword or a network address with CIDR mask such as 192.168.2.0/24 |
Comment | string | optional description |
In the example shown in Figure 10.5d, two groups have been created. Group 1 allows connections from any initiator on any network; Group 2 allows connections from any initiator on the 10.10.1.0/24 network. Click an initiator’s entry to display its “Edit” and “Delete” buttons.
Note
if you delete an initiator, a warning will indicate if any targets or target/extent mappings depend upon the initiator. If you confirm the delete, these will be deleted as well.
Figure 10.5d: Sample iSCSI Initiator Configuration

11.1.4. Authorized Accesses¶
If you will be using CHAP or mutual CHAP to provide authentication, you must create an authorized access in
. This screen is shown in Figure 10.5e.Note
this screen sets login authentication. This is different from discovery authentication which is set in Target Global Configuration.
Figure 10.5e: Adding an iSCSI Authorized Access

Table 10.5d summarizes the settings that can be configured when adding an authorized access:
Table 10.5d: Authorized Access Configuration Settings
Setting | Value | Description |
---|---|---|
Group ID | integer | allows different groups to be configured with different authentication profiles; for instance, all users with a Group ID of 1 will inherit the authentication profile associated with Group 1 |
User | string | name of user account to create for CHAP authentication with the user on the remote system; many initiators default to using the initiator name as the user |
Secret | string | password to be associated with “User”; the iSCSI standard requires that this be between 12 and 16 characters |
Peer User | string | only input when configuring mutual CHAP; in most cases it will need to be the same value as “User” |
Peer Secret | string | the mutual secret password which must be different than the “Secret”; required if the “Peer User” is set |
Note
CHAP does not work with GlobalSAN initiators on Mac OS X.
As authorized accesses are added, they will be listed under View Authorized Accesses. In the example shown in Figure 10.5f, three users (test1, test2, and test3) and two groups ( 1 and 2) have been created, with group 1 consisting of one CHAP user and group 2 consisting of one mutual CHAP user and one CHAP user. Click an authorized access entry to display its “Edit” and “Delete” buttons.
Figure 10.5f: Viewing Authorized Accesses

11.1.5. Targets¶
Next, create a Target using
, as shown in Figure 10.5g. A target combines a portal ID, allowed initiator ID, and an authentication method. Table 10.5e summarizes the settings that can be configured when creating a Target.Note
an iSCSI target creates a block device that may be accessible to multiple initiators. A clustered filesystem is required on the block device, such as VMFS used by VMware ESX/ESXi, in order for multiple initiators to mount the block device read/write. If a traditional filesystem such as EXT, XFS, FAT, NTFS, UFS, or ZFS is placed on the block device, care must be taken that only one initiator at a time has read/write access or the result will be filesystem corruption. If you need to support multiple clients to the same data on a non-clustered filesystem, use CIFS or NFS instead of iSCSI or create multiple iSCSI targets (one per client).
Figure 10.5g: Adding an iSCSI Target

Table 10.5e: Target Settings
Setting | Value | Description |
---|---|---|
Target Name | string | required value; base name will be appended automatically if it does not start with iqn |
Target Alias | string | optional user-friendly name |
Portal Group ID | drop-down menu | leave empty or select number of existing portal to use |
Initiator Group ID | drop-down menu | select which existing initiator group has access to the target |
Auth Method | drop-down menu | choices are None, Auto, CHAP, or Mutual CHAP |
Authentication Group number | drop-down menu | None or integer representing number of existing authorized access |
11.1.6. Extents¶
In iSCSI, the target virtualizes something and presents it as a device to the iSCSI client. That something can be a device extent or a file extent:
Device extent: virtualizes an unformatted physical disk, RAID controller, zvol, zvol snapshot, or an existing HAST device.
Virtualizing a single disk is slow as there is no caching but virtualizing a hardware RAID controller has higher performance due to its cache. This type of virtualization does a pass-through to the disk or hardware RAID controller. None of the benefits of ZFS are provided and performance is limited to the capabilities of the disk or controller.
Virtualizing a zvol adds the benefits of ZFS such as its read cache and write cache. Even if the client formats the device extent with a different filesystem, as far as FreeNAS® is concerned, the data benefits from ZFS features such as block checksums and snapshots.
When determining whether or not to use a file or a device extent, be aware that a zvol is required to take advantage of all VAAI primitives and is recommended when using virtualization software as the iSCSI initiator. The ATS, WRITE SAME, XCOPY and STUN, primitives are supported by both file and device extents. The UNMAP primitive is supported by zvols and raw SSDs. The threshold warnings primitive is fully supported by zvols and partially supported by file extents.
File extent: allows you to export a portion of a ZFS volume. The advantage of a file extent is that you can create multiple exports per volume.
Warning
for performance reasons and to avoid excessive fragmentation, it is recommended to keep the used space of the pool below 50% when using iSCSI. As required, you can increase the capacity of an existing extent using the instructions in Growing LUNs.
To add an extent, go to export
zvol that was previously created from the /mnt/volume1
volume.
Table 10.5f summarizes the settings that can be configured when creating an extent. Note that file extent creation will fail if you do not append the name of the file to be created to the volume/dataset name.
Figure 10.5h: Adding an iSCSI Extent

Table 10.5f: Extent Configuration Settings
Setting | Value | Description |
---|---|---|
Extent Name | string | name of extent; if the “Extent size” is not 0, it can not be an existing file within the volume/dataset |
Extent Type | drop-down menu | select from File or Device |
Serial | string | unique LUN ID; the default is generated from the system’s MAC address |
Path to the extent | browse button | only appears if File is selected; either browse to an existing file and use 0 as the “Extent size”, or browse to the volume or dataset, click the “Close” button, append the “Extent Name” to the path, and specify a value in “Extent size” |
Device | drop-down menu | only appears if Device is selected; select the unformatted disk, controller, zvol, zvol snapshot, or HAST device |
Extent size | integer | only appears if File is selected; if the size is specified as 0, the file must already exist and the actual file size will be used; otherwise, specify the size of the file to create |
Logical Block Size | drop-down menu | only override the default if the initiator requires a different block size |
Disable Physical Block Size Reporting | checkbox | if the initiator does not support physical block size values over 4K (MS SQL), check this box |
Available Space Threshold | string | only appears if File or a zvol is selected; when the specified percentage of free space is reached, the system will issue an alert |
Comment | string | optional |
Enable TPC | checkbox | if checked, an initiator can bypass normal access control and access any scannable target; this allows xcopy operations otherwise blocked by access control |
Xen initiator compat mode | checkbox | check this box when using Xen as the iSCSI initiator |
LUN RPM | drop-down menu | do 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-only | checkbox | check this box to prevent the initiator from initializing this LUN |
11.1.7. Target/Extents¶
The last step is associating an extent to a target within
. This screen is shown in Figure 10.5i. Use the drop-down menus to select the existing target and extent.Figure 10.5i: Associating a Target With an Extent

Table 10.5g summarizes the settings that can be configured when associating targets and extents.
Table 10.5g: Target/Extents Configuration Settings
Setting | Value | Description |
---|---|---|
Target | drop-down menu | select the pre-created target |
LUN ID | drop-down menu | the default of Auto will use the next available LUN ID; alternately, select the value of the ID or type in the desired value |
Extent | drop-down menu | select the pre-created extent |
It is recommended to always associate extents to targets in a 1:1 manner, even though the GUI will allow multiple extents to be associated with the same target.
Once iSCSI has been configured, don’t forget to start it in
. Click the red “OFF” button next to iSCSI. After a second or so, it will change to a blue ON, indicating that the service has started.11.1.8. Connecting to iSCSI¶
In order to access the iSCSI target, clients will need to use iSCSI initiator software.
An iSCSI Initiator client is pre-installed with Windows 7. A detailed how-to for this client can be found here. A client for Windows 2000, XP, and 2003 can be found here. This how-to shows how to create an iSCSI target for a Windows 7 system.
Mac OS X does not include an initiator. globalSAN is a commercial, easy-to-use Mac initiator.
BSD systems provide command line initiators: iscontrol(8) comes with FreeBSD versions 9.x and lower, iscsictl(8) comes with FreeBSD versions 10.0 and higher, iscsi-initiator(8) comes with NetBSD, and iscsid(8) comes with OpenBSD.
Some Linux distros provide the command line utility iscsiadm from Open-iSCSI. Use a web search to see if a package exists for your distribution should the command not exist on your Linux system.
If you add a LUN while iscsiadm is already connected, it will not see the new LUN until you rescan using iscsiadm -m node -R. Alternately, use iscsiadm -m discovery -t st -p portal_IP to find the new LUN and iscsiadm -m node -T LUN_Name -l to log into the LUN.
Instructions for connecting from a VMware ESXi Server can be found at How to configure FreeNAS 8 for iSCSI and connect to ESX(i). Note that the requirements for booting vSphere 4.x off iSCSI differ between ESX and ESXi. ESX requires a hardware iSCSI adapter while ESXi requires specific iSCSI boot firmware support. The magic is on the booting host side, meaning that there is no difference to the FreeNAS® configuration. See the iSCSI SAN Configuration Guide for details.
If you can see the target but not connect to it, check the “Discovery Auth” settings in “Target Global Configuration”.
If the LUN is not discovered by ESXi, make sure that promiscuous mode is set to “Accept” in the vSwitch.
11.1.9. Growing LUNs¶
The method used to grow the size of an existing iSCSI LUN depends on whether the LUN is backed by a file extent or a zvol. Both methods are described in this section.
After the LUN is expanded using one of the methods below, use the tools from the initiator software to grow the partitions and the filesystems it contains.
11.1.9.1. Zvol Based LUN¶
To grow a zvol based LUN, go to
, highlight the zvol to be grown, and click its “Edit zvol” button. In the example shown in Figure 10.5j, the current size of the zvol named zvol1 is 4GB.Figure 10.5j: Editing an Existing Zvol

Input the new size for the zvol in the “Size” field and click the “Edit ZFS Volume” button. This menu will close and the new size for the zvol will immediately show in the “Used” column of the “View Volumes” screen.
11.1.9.2. File Extent Based LUN¶
To grow a file extent based LUN, go to /mnt/volume1/data
by 2G:
truncate -s +2g /mnt/volume1/data
Go back to
and click the “Edit” button for the file extent. Set the size to 0 as this causes the iSCSI target to use the new size of the file.