.. _Sharing:

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.

FreeNAS® provides an :ref:`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.

These types of shares and services are available:

* :ref:`Apple (AFP) Shares`: the Apple File Protocol (AFP) type of
  share is a good choice if all of your computers run Mac OS X.

* :ref:`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.

* :ref:`WebDAV Shares`: this type of share is accessible using an
  authenticated web browser (read-only) or
  `WebDAV client <https://en.wikipedia.org/wiki/WebDAV#Clients>`_
  running on any operating system.

* :ref:`Windows (SMB) Shares`: the Server Message Block
  type of share, also known as Common Internet File System (SMB), 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 the CPU is
  maxed out, upgrade the CPU or consider another type of share.

* :ref:`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 :ref:`FTP` service instead
of a share and use a cross-platform FTP and file manager client
application such as `Filezilla <https://filezilla-project.org/>`_.
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 <http://winscp.net/eng/index.php>`_,
consider configuring the :ref:`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 SMB, 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, SMB, WebDAV, and iSCSI shares. FTP and SSH configurations
are described in :ref:`Services Configuration`.


.. index:: AFP, Apple Filing Protocol
.. _Apple (AFP) Shares:

Apple (AFP) Shares
------------------

FreeNAS® uses the
`Netatalk <http://netatalk.sourceforge.net/>`_
AFP server to share data with Apple systems. This section describes
the configuration screen for fine-tuning AFP shares created using the
:ref:`Initial Configuration Wizard`. It then provides configuration
examples for using the Wizard to create a guest share, configuring
Time Machine to backup to a dataset on the FreeNAS® system, and for
connecting to the share from a Mac OS X client.

To view the AFP share created by the Wizard, click
:menuselection:`Sharing --> Apple (AFP)`
and highlight the name of the share. Click its :guilabel:`Edit` button
to see the configuration options shown in
:numref:`Figure %s <creating_afp_share_fig>`.
The values showing for these options will vary, depending upon the
information given when the share was created.


.. _creating_afp_share_fig:

.. figure:: images/afp2.png

   Creating an AFP Share


.. note:: While
   :numref:`Table %s <afp_share_config_opts_tab>`
   summarizes the available options for fine-tuning an AFP share, you
   typically should not change the default settings of an AFP share as
   doing so may cause the share to not work as expected. Most settings
   are only available when you click :guilabel:`Advanced Mode`. Do
   **not** change an advanced option without fully understanding the
   function of that option. Refer to
   `Setting up Netatalk
   <http://netatalk.sourceforge.net/2.2/htmldocs/configuration.html>`_
   for a more detailed explanation of the available options.


.. _afp_share_config_opts_tab:

.. table:: AFP Share Configuration Options

   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Setting                      | Value         | Description                                                                                                 |
   |                              |               |                                                                                                             |
   +==============================+===============+=============================================================================================================+
   | Path                         | browse button | browse to the volume/dataset to share; do not nest additional volumes, datasets, or symbolic links beneath  |
   |                              |               | this path because Netatalk lacks complete support                                                           |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Name                         | string        | volume name that will appear in the Mac computer's :guilabel:`connect to server` dialog; limited to         |
   |                              |               | 27 characters and cannot contain a period                                                                   |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Share Comment                | string        | only available in :guilabel:`Advanced Mode`; optional                                                       |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Allow List                   | string        | only available in :guilabel:`Advanced Mode`; comma delimited list of allowed users and/or groups            |
   |                              |               | where groupname begins with a *@*; note that adding an entry will deny any user/group that is               |
   |                              |               | not specified                                                                                               |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Deny List                    | string        | only available in :guilabel:`Advanced Mode`; comma delimited list of denied users and/or groups             |
   |                              |               | where groupname begins with a *@*; note that adding an entry will allow all users/groups that               |
   |                              |               | are not specified                                                                                           |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Read-only Access             | string        | only available in :guilabel:`Advanced Mode`; comma delimited list of users and/or groups who                |
   |                              |               | only have read access where groupname begins with a *@*                                                     |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Read-write Access            | string        | only available in :guilabel:`Advanced Mode`; comma delimited list of users and/or groups who                |
   |                              |               | have read and write access where groupname begins with a *@*                                                |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Time Machine                 | checkbox      | when checked, FreeNAS® advertises itself as a Time Machine disk so it can be found by Macs; due to a        |
   |                              |               | limitation in how the Mac deals with low-diskspace issues when multiple Macs share the same volume,         |
   |                              |               | checking :guilabel:`Time Machine` on multiple shares could result in intermittent failed backups            |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Zero Device Numbers          | checkbox      | only available in :guilabel:`Advanced Mode`; enable when the device number is not constant                  |
   |                              |               | across a reboot                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | No Stat                      | checkbox      | only available in :guilabel:`Advanced Mode`; if checked, AFP won't stat the volume path when                |
   |                              |               | enumerating the volumes list; useful for automounting or volumes created by a preexec script                |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | AFP3 UNIX Privs              | checkbox      | only available in :guilabel:`Advanced Mode`; enables Unix privileges supported by OSX 10.5 and              |
   |                              |               | higher; do not enable if the network contains Mac OS X 10.4 clients or lower as they do not                 |
   |                              |               | support these                                                                                               |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Default file permission      | checkboxes    | only available in :guilabel:`Advanced Mode`; only works with Unix ACLs; new files created on the            |
   |                              |               | share are set with the selected permissions                                                                 |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Default directory permission | checkboxes    | only available in :guilabel:`Advanced Mode`; only works with Unix ACLs; new directories created on          |
   |                              |               | the share are set with the selected permissions                                                             |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Default umask                | integer       | only available in :guilabel:`Advanced Mode`; umask for newly created files, default is *000*                |
   |                              |               | (anyone can read, write, and execute)                                                                       |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Hosts Allow                  | string        | only available in :guilabel:`Advanced Mode`; comma, space, or tab-delimited list of allowed                 |
   |                              |               | hostnames or IP addresses                                                                                   |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Hosts Deny                   | string        | only available in :guilabel:`Advanced Mode`; comma, space, or tab-delimited list of denied                  |
   |                              |               | hostnames or IP addresses                                                                                   |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+


.. _Creating AFP Guest Shares:

Creating AFP Guest Shares
~~~~~~~~~~~~~~~~~~~~~~~~~

AFP supports guest logins, meaning that all of your Mac OS X users can
access the AFP share without requiring their user accounts to first be
created on or imported into the FreeNAS® system.

.. note:: If you create a guest share as well a share that requires
   authentication, AFP will only map users who login as guest to the
   guest share. This means that if a user logs in to the share that
   requires authentication, the permissions on the guest share may
   prevent that user from writing to the guest share. The only way to
   allow both guest and authenticated users to write to a guest share
   is to set the permissions on the guest share to 777 or to add the
   authenticated users to a guest group and set the permissions to
   77x.


Before creating a guest share, go to
:menuselection:`Services --> AFP`
and make sure that the :guilabel:`Guest Access` box is checked.

To create the AFP guest share, click :guilabel:`Wizard`, then click
the :guilabel:`Next` button twice to display the screen shown in
:numref:`Figure %s <creating_guest_afp_share_fig>`.
Complete these fields in this screen:

#. **Share name:** enter a name for the share that is useful to you
   but which is under 27 characters and does not contain a period. In
   this example, the share is named *afp_guest*.

#. Click the button for :guilabel:`Mac OS X (AFP)`.

#. Click the :guilabel:`Ownership` button. Click the drop-down
   :guilabel:`User` menu and select :guilabel:`nobody`. Click the
   :guilabel:`Return` button to return to the previous screen.

#. Click the :guilabel:`Add` button.
   **If you forget to do this, the share will not be created**.
   Clicking the :guilabel:`Add` button adds an entry to the
   :guilabel:`Name` frame with the name that was entered in
   :guilabel:`Share name`.


.. _creating_guest_afp_share_fig:

.. figure:: images/afp6a.png

   Creating a Guest AFP Share


Click the :guilabel:`Next` button twice, then the :guilabel:`Confirm`
button to create the share. The Wizard automatically creates a dataset
for the share that contains the correct default permissions and starts
the AFP service so the share is immediately available. The new share
is also added as an entry to
:menuselection:`Sharing --> Apple (AFP)`.

Mac OS X users can connect to the guest AFP share by clicking
:menuselection:`Go --> Connect to Server`. In the example shown in
:numref:`Figure %s <afp_connect_server_fig>`,
the user has entered *afp://* followed by the IP address of the
FreeNAS® system.

Click the :guilabel:`Connect` button. Once connected, Finder opens
automatically. The name of the AFP share is displayed in the SHARED
section in the left frame and the contents of any data saved in the
share is displayed in the right frame.


.. _afp_connect_server_fig:

.. figure:: images/afp3.png

   Connect to Server Dialogue


To disconnect from the volume, click the :guilabel:`eject` button in
the :guilabel:`Shared` sidebar.


.. index:: Time Machine
.. _Creating Authenticated and Time Machine Shares:

Creating Authenticated and Time Machine Shares
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Mac OS X includes the Time Machine application which can be used to
schedule automatic backups.  In this configuration example, a Time
Machine user will be configured to backup to an AFP share on a
FreeNAS® system. It is recommended to create a separate Time Machine
share for each user that will be using Time Machine to backup their
Mac OS X system to FreeNAS®. The process for creating an authenticated
share for a user is the same as creating a Time Machine share for that
user.

To use the Wizard to create an authenticated or Time Machine share,
enter the following information, as seen in the example in
:numref:`Figure %s <create_time_machine_share_fig>`.

#. **Share name:** input a name for the share that is useful to you
   but which is under 27 characters and does not contain a period. In
   this example, the share is named *backup_user1*.

#. Click the button for :guilabel:`Mac OS X (AFP)` and check the box
   for :guilabel:`Time Machine`. If the user will not be using Time
   Machine, leave the box unchecked.

#. Click the :guilabel:`Ownership` button. If the user already exists
   on the FreeNAS® system, click the drop-down :guilabel:`User` menu to
   select their user account.  If the user does not yet exist on the
   FreeNAS® system, type their name into the :guilabel:`User` field and
   check the :guilabel:`Create User` checkbox. If the user will be a
   member of a group that already exists on the FreeNAS® system, click
   the drop-down :guilabel:`Group` menu to select the group name. To
   create a new group to be used by Time Machine users, enter the name
   in the :guilabel:`Group` field and check the
   :guilabel:`Create Group` checkbox. Otherwise, enter the same name
   as the user. In the example shown in
   :numref:`Figure %s <create_tm_auth_user_fig>`,
   both a new *user1* user and a new *tm_backups* group will be
   created. Since a new user is being created, this screen prompts for
   the user password to be used when accessing the share. It also
   provides an opportunity to change the default permissions on the
   share. When finished, click :guilabel:`Return` to return to the
   screen shown in
   :numref:`Figure %s <create_time_machine_share_fig>`.

#. Click the :guilabel:`Add` button.
   **If you forget to do this, the share will not be created**.
   Clicking the :guilabel:`Add` button adds an entry to the
   :guilabel:`Name` frame with the name that was entered in
   :guilabel:`Share name`.


To configure multiple authenticated or Time Machine shares, repeat for
each user, giving each user their own :guilabel:`Share name` and
:guilabel:`Ownership`. When finished, click the :guilabel:`Next`
button twice, then the :guilabel:`Confirm` button to create the
shares. The Wizard automatically creates a dataset for each share with
the correct ownership and starts the AFP service so the shares are
immediately available. The new shares are also added to
:menuselection:`Sharing --> Apple (AFP)`.


.. _create_time_machine_share_fig:

.. figure:: images/afp7a.png

   Creating a Time Machine Share


.. _create_tm_auth_user_fig:

.. figure:: images/afp8.png

   Creating an Authenticated User


At this point, it may be desirable to configure a quota for each Time
Machine share, to restrict backups from using all of the available
space on the FreeNAS® system. The first time Time Machine makes a
backup, it will create a full backup after waiting two minutes. It
will then create a one hour incremental backup for the next 24 hours,
and then one backup each day, each week and each month.
**Since the oldest backups are deleted when a Time Machine share
becomes full, make sure that the quota size you set is sufficient to
hold the desired number of backups.**
Note that a default installation of Mac OS X is ~21 GB in size.

To configure a quota, go to
:menuselection:`Storage --> Volumes`
and highlight the entry for the share. In the example shown in
:numref:`Figure %s <set_quota_fig>`,
the Time Machine share name is *backup_user1*. Click the
:guilabel:`Edit Options` button for the share, then
:guilabel:`Advanced Mode`. Enter a value in the
:guilabel:`Quota for this dataset` field, then click
:guilabel:`Edit Dataset` to save the change. In this example, the
Time Machine share is restricted to 200 GB.


.. _set_quota_fig:

.. figure:: images/afp9a.png

   Setting a Quota


To configure Time Machine on the Mac OS X client, go to
:menuselection:`System Preferences --> Time Machine`
which opens the screen shown in
:numref:`Figure %s <config_tm_osx>`.
Click :guilabel:`ON` and a pop-up menu shows the FreeNAS® system as a
backup option. In our example, it is listed as
*backup_user1 on "freenas"*. Highlight the FreeNAS® system and click
:guilabel:`Use Backup Disk`. A connection bar opens and prompts for
the user account's password--in this example, the password that was
set for the *user1* account.


.. _config_tm_osx:

.. figure:: images/afp5.png

   Configuring Time Machine on Mac OS X Lion


If :guilabel:`Time Machine could not complete the backup. The
backup disk image could not be created (error 45)` is shown when
backing up to the FreeNAS® system, a sparsebundle
image must be created using
`these instructions
<http://forum1.netgear.com/showthread.php?t=49482>`_.

If :guilabel:`Time Machine completed a verification of
your backups. To improve reliability, Time Machine must create a new
backup for you.` is shown, and you do not want to perform another
complete backup or lose past backups, follow the instructions in
`this post
<http://www.garth.org/archives/2011,08,27,169,fix-time-machine-sparsebundle-nas-based-backup-errors.html>`_.


.. index:: NFS, Network File System
.. _Unix (NFS) Shares:

Unix (NFS) Shares
-----------------

FreeNAS® supports sharing over the Network File System (NFS). Clients
use the :command:`mount` command to mount the share. Once mounted, the
NFS share appears as just another directory on the client system. Some
Linux distros require the installation of additional software in order
to mount an NFS share. On Windows systems, enable Services for NFS in
the Ultimate or Enterprise editions or install an NFS client
application.

.. note:: For performance reasons, iSCSI is preferred to NFS shares
   when FreeNAS® is installed on ESXi. If you are considering creating
   NFS shares on ESXi, read through the performance analysis at
   `Running ZFS over NFS as a VMware Store
   <http://blog.laspina.ca/ubiquitous/running-zfs-over-nfs-as-a-vmware-store>`_.

To create an NFS share using the Wizard, click the :guilabel:`Next`
button twice to display the screen shown in
:numref:`Figure %s <nfs_share_wiz_fig>`.
Enter a :guilabel:`Share name` which makes sense to you, but does not
contain a space. Click the button for :guilabel:`Generic Unix (NFS)`,
then click :guilabel:`Add` so the share's name appears in the
:guilabel:`Name` frame. When finished, click the :guilabel:`Next`
button twice, then the :guilabel:`Confirm` button to create the share.
Creating an NFS share using the wizard automatically creates a new
dataset for the share, starts the services required for NFS, and adds
an entry in
:menuselection:`Sharing --> Unix (NFS) Shares`.
Depending on your requirements, you may wish to fine-tune which IP
addresses are allowed to access the NFS share or to restrict the
permissions of the mounted share.


.. _nfs_share_wiz_fig:

.. figure:: images/nfs6a.png

   NFS Share Wizard


To edit the NFS share, click
:menuselection:`Sharing --> Unix (NFS)`,
highlight the entry for the share, and click its :guilabel:`Edit`
button. In the example shown in
:numref:`Figure %s <nfs_share_settings_fig>`,
the configuration screen is open for the *nfs_share1* share.


.. _nfs_share_settings_fig:

.. figure:: images/nfs2.png

   NFS Share Settings


:numref:`Table %s <nfs_share_opts_tab>`
summarizes the available configuration options in this screen. Some
settings are only available by clicking the :guilabel:`Advanced Mode`
button.


.. _nfs_share_opts_tab:

.. table:: NFS Share Options

   +---------------------+----------------+--------------------------------------------------------------------------------------------------------------------+
   | Setting             | Value          | Description                                                                                                        |
   |                     |                |                                                                                                                    |
   +=====================+================+====================================================================================================================+
   | Path                | browse button  | the path that clients will use when mounting the share; click :guilabel:`Add extra path` to select                 |
   |                     |                | multiple paths                                                                                                     |
   +---------------------+----------------+--------------------------------------------------------------------------------------------------------------------+
   | Comment             | string         | used to set the share name; if left empty, share name is the list of selected :guilabel:`Path` entries             |
   |                     |                |                                                                                                                    |
   +---------------------+----------------+--------------------------------------------------------------------------------------------------------------------+
   | Authorized networks | string         | only available in :guilabel:`Advanced Mode`; space delimited list of allowed network addresses in the              |
   |                     |                | form *1.2.3.0/24* where the number after the slash is a CIDR mask                                                  |
   |                     |                |                                                                                                                    |
   +---------------------+----------------+--------------------------------------------------------------------------------------------------------------------+
   | Authorized  IP      | string         | only available in :guilabel:`Advanced Mode`; space delimited list of allowed IP addresses or hostnames             |
   | addresses or hosts  |                |                                                                                                                    |
   |                     |                |                                                                                                                    |
   +---------------------+----------------+--------------------------------------------------------------------------------------------------------------------+
   | All directories     | checkbox       | if checked, the client can mount any subdirectory within the :guilabel:`Path`                                      |
   |                     |                |                                                                                                                    |
   +---------------------+----------------+--------------------------------------------------------------------------------------------------------------------+
   | Read only           | checkbox       | prohibit writing to the share                                                                                      |
   |                     |                |                                                                                                                    |
   +---------------------+----------------+--------------------------------------------------------------------------------------------------------------------+
   | Quiet               | checkbox       | only available in :guilabel:`Advanced Mode`; inhibits some syslog diagnostics which can be useful to               |
   |                     |                | avoid some annoying error messages; see                                                                            |
   |                     |                | `exports(5) <http://www.freebsd.org/cgi/man.cgi?query=exports>`_                                                   |
   |                     |                | for examples                                                                                                       |
   |                     |                |                                                                                                                    |
   +---------------------+----------------+--------------------------------------------------------------------------------------------------------------------+
   | Maproot User        | drop-down menu | only available in :guilabel:`Advanced Mode`; if a user is selected, the *root* user is limited to that             |
   |                     |                | user's permissions                                                                                                 |
   +---------------------+----------------+--------------------------------------------------------------------------------------------------------------------+
   | Maproot Group       | drop-down menu | only available in :guilabel:`Advanced Mode`; if a group is selected, the *root* user will also be limited          |
   |                     |                | to that group's permissions                                                                                        |
   |                     |                |                                                                                                                    |
   +---------------------+----------------+--------------------------------------------------------------------------------------------------------------------+
   | Mapall User         | drop-down menu | only available in :guilabel:`Advanced Mode`; the specified user's permissions are used by all clients              |
   |                     |                |                                                                                                                    |
   +---------------------+----------------+--------------------------------------------------------------------------------------------------------------------+
   | Mapall Group        | drop-down menu | only available in :guilabel:`Advanced Mode`; the specified group's permission are used by all clients              |
   |                     |                |                                                                                                                    |
   +---------------------+----------------+--------------------------------------------------------------------------------------------------------------------+
   | Security            | selection      | only available in :guilabel:`Advanced Mode` and only appears if :guilabel:`Enable NFSv4` is checked in             |
   |                     |                | :menuselection:`Services --> NFS`; choices are *sys* or these Kerberos options:                                    |
   |                     |                | *krb5* (authentication only),                                                                                      |
   |                     |                | *krb5i* (authentication and integrity), or                                                                         |
   |                     |                | *krb5p* (authentication and privacy); if multiple security mechanisms are added to the                             |
   |                     |                | :guilabel:`Selected` column using the arrows, use the :guilabel:`Up` or :guilabel:`Down` buttons                   |
   |                     |                | to list in order of preference                                                                                     |
   +---------------------+----------------+--------------------------------------------------------------------------------------------------------------------+


When creating NFS shares, keep the following points in mind:


#.  The :guilabel:`Maproot` and :guilabel:`Mapall` options are
    exclusive, meaning only one can be used--the GUI does not allow
    both. The :guilabel:`Mapall` options supersede the
    :guilabel:`Maproot` options. To restrict only the *root* user's
    permissions, set the :guilabel:`Maproot` option. To restrict
    permissions of all users, set the :guilabel:`Mapall` options.

#.  Each volume or dataset is considered to be its own filesystem and
    NFS is not able to cross filesystem boundaries.

#.  The network or host must be unique per share and per filesystem or
    directory.

#.  The :guilabel:`All directories` option can only be used once per
    share per filesystem.


To better understand these restrictions, consider the following
scenario where there are:

* 2 networks named *10.0.0.0/8* and
  *20.0.0.0/8*

* a ZFS volume named :file:`volume1` with 2 datasets named
  :file:`dataset1` and :file:`dataset2`

* :file:`dataset1` has a directory named :file:`directory1`

Because of restriction #3, an error is shown if you try to create one
NFS share like this:

* :guilabel:`Authorized networks` set to *10.0.0.0/8 20.0.0.0/8*

* :guilabel:`Path` set to :file:`/mnt/volume1/dataset1` and
  :file:`/mnt/volume1/dataset1/directory1`

Instead, you should set a :guilabel:`Path` of
:file:`/mnt/volume1/dataset1` and check the
:guilabel:`All directories` box.

However, you could restrict that directory to one of the networks by
creating two shares instead:

First NFS share:

* :guilabel:`Authorized networks` set to *10.0.0.0/8*

* :guilabel:`Path` set to :file:`/mnt/volume1/dataset1`

Second NFS share:

* :guilabel:`Authorized networks` set to *20.0.0.0/8*

* :guilabel:`Path` set to :file:`/mnt/volume1/dataset1/directory1`

Note that this requires the creation of two shares as it cannot be
done with only one share.


.. _Example Configuration:

Example Configuration
~~~~~~~~~~~~~~~~~~~~~

By default, the :guilabel:`Mapall` options show as *N/A*. This means
that when a user connects to the NFS share, they connect with the
permissions associated with their user account. This is a security
risk if a user is able to connect as *root* as they will have complete
access to the share.

A better scenario is to do the following:

#.  Specify the built-in *nobody* account to be used for NFS access.

#.  In the :guilabel:`Change Permissions` screen of the volume/dataset
    that is being shared, change the owner and group to *nobody* and
    set the permissions according to your requirements.

#.  Select *nobody* in the :guilabel:`Mapall User` and
    :guilabel:`Mapall Group` drop-down menus for the share in
    :menuselection:`Sharing --> Unix (NFS) Shares`.


With this configuration, it does not matter which user account
connects to the NFS share, as it will be mapped to the *nobody* user
account and will only have the permissions that were specified on the
volume/dataset. For example, even if the *root* user is able to
connect, it will not gain *root* access to the share.


.. _Connecting to the Share:

Connecting to the Share
~~~~~~~~~~~~~~~~~~~~~~~

In the following examples, an NFS share on a FreeNAS® system with the
IP address of *192.168.2.2* has been configured as follows:

#.  A ZFS volume named :file:`/mnt/data` has its permissions set to
    the *nobody* user account and the *nobody* group.

#.  A NFS share has been created with these attributes:

    * :guilabel:`Path`: :file:`/mnt/data`

    * :guilabel:`Authorized Network`: *192.168.2.0/24*

    * :guilabel:`MapAll User` and :guilabel:`MapAll Group` are both
      set to *nobody*

    * the :guilabel:`All Directories` checkbox has been checked


.. _From BSD or Linux:

From BSD or Linux
^^^^^^^^^^^^^^^^^

To make this share accessible on a BSD or a Linux system, run the
following command as the superuser (or with :command:`sudo`) from the
client system. Repeat on each client that needs access to the NFS
share:

.. code-block:: none

   mount -t nfs 192.168.2.2:/mnt/data /mnt


The :command:`mount` command uses these:

* **-t nfs:** specifies the type of share.

* **192.168.2.2:** replace with the IP address of the FreeNAS® system

* **/mnt/data:** replace with the name of the NFS share

* **/mnt:** a mount point on the client system. This must be an
  existing, **empty** directory. The data in the NFS share will be
  made available to the client in this directory.

The :command:`mount` command should return to the command prompt
without any error messages, indicating that the share was successfully
mounted.

.. note:: If this command fails on a Linux system, make sure that the
   `nfs-utils
   <http://sourceforge.net/projects/nfs/files/nfs-utils/>`_
   package is installed.


Once mounted, this configuration allows users on the client system to
copy files to and from :file:`/mnt` (the mount point) and all files
will be owned by *nobody:nobody*. Any changes to :file:`/mnt` will be
saved to the FreeNAS® system's :file:`/mnt/data` volume.

Should you wish to make any changes to the NFS share's settings or
wish to make the share inaccessible, first unmount the share on the
client as the superuser:

.. code-block:: none

   umount /mnt


.. _From Microsoft:

From Microsoft
^^^^^^^^^^^^^^

Windows systems can connect to NFS shares using Services for NFS
(refer to the documentation for your version of Windows for
instructions on how to find, activate, and use this service) or a
third-party NFS client.

`Nekodrive <http://code.google.com/p/nekodrive/downloads/list>`_
provides an open source graphical NFS client. To use this client, you
will need to install the following on the Windows system:

* `7zip <http://www.7-zip.org/>`_
  to extract the Nekodrive download files

* NFSClient and NFSLibrary from the Nekodrive download page; once
  downloaded, extract these files using 7zip

* `.NET Framework 4.0
  <http://www.microsoft.com/en-us/download/details.aspx?id=17851>`_

After everything is installed, run the NFSClient executable to start
the GUI client. In the example shown in
:numref:`Figure %s <nekodrive_fig>`,
the user has connected to the example :file:`/mnt/data` share of the
FreeNAS® system at *192.168.2.2*.


.. note:: Nekodrive does not support Explorer drive mapping via NFS.
   If you need this functionality,
   `try this utility
   <http://www.citi.umich.edu/projects/nfsv4/windows/readme.html>`_
   instead.


.. _nekodrive_fig:

.. figure:: images/nfs5.jpg

   Using the Nekodrive NFSClient from Windows 7 Home Edition


.. _From Mac OS X:

From Mac OS X
^^^^^^^^^^^^^

To mount the NFS volume from a Mac OS X client, click on
:menuselection:`Go --> Connect to Server`.
In the :guilabel:`Server Address` field, enter *nfs://* followed by
the IP address of the FreeNAS® system and the name of the
volume/dataset being shared by NFS. The example shown in
:numref:`Figure %s <mount_nfs_osx_fig>`
continues with our example of *192.168.2.2:/mnt/data*.

Once connected, Finder opens automatically. The IP address of the
FreeNAS® system is displayed in the SHARED section in the left frame
and the contents of the share are displayed in the right frame. In the
example shown in
:numref:`Figure %s <view_nfs_finder_fig>`,
:file:`/mnt/data` has one folder named :file:`images`. The user can
now copy files to and from the share.


.. _mount_nfs_osx_fig:

.. figure:: images/nfs3.png

   Mounting the NFS Share from Mac OS X


.. _view_nfs_finder_fig:

.. figure:: images/nfs4.png

   Viewing the NFS Share in Finder


.. _Troubleshooting NFS:

Troubleshooting NFS
~~~~~~~~~~~~~~~~~~~

Some NFS clients do not support the NLM (Network Lock Manager)
protocol used by NFS. You will know that this is the case if the
client receives an error that all or part of the file may be locked
when a file transfer is attempted. To resolve this error, add the
option **-o nolock** when running the :command:`mount` command on the
client in order to allow write access to the NFS share.

If a "time out giving up" error is shown when trying to mount the
share from a Linux system, make sure that the portmapper service is
running on the Linux client. If portmapper is running and timeouts are
still shown, force the use of TCP by including **-o tcp** in the
:command:`mount` command.

If a "RPC: Program not registered" error is shown, upgrade to the
latest version of FreeNAS® and restart the NFS service after the
upgrade to clear the NFS cache.

If clients see "reverse DNS" errors, add the FreeNAS® IP address in the
:guilabel:`Host name database` field of
:menuselection:`Network --> Global Configuration`.

If clients receive timeout errors when trying to mount the share, add
the client IP address and hostname to the
:guilabel:`Host name data base` field in
:menuselection:`Network --> Global Configuration`.

Some older versions of NFS clients default to UDP instead of TCP and
do not auto-negotiate for TCP. By default, FreeNAS® uses TCP. To
support UDP connections, go to
:menuselection:`Services --> NFS`
and check the box :guilabel:`Serve UDP NFS clients`.


.. index:: WebDAV
.. _WebDAV Shares:

WebDAV Shares
------------------

In FreeNAS®, WebDAV shares can be created so that authenticated users
can browse the contents of the specified volume, dataset, or directory
from a web browser.

Configuring WebDAV shares is a two step process. First, create the
WebDAV share(s) to specify which data can be accessed. Then, configure
the WebDAV service by specifying the port, authentication type, and
authentication password. Once the configuration is complete, the share
can be accessed using a URL in the format:

.. code-block:: none

   protocol://IP_address:port_number/share_name


where:

* **protocol:** is either
  *http* or
  *https*, depending upon the :guilabel:`Protocol` configured in
  :menuselection:`Services --> WebDAV`.

* **IP address:** is the IP address or hostname of the FreeNAS®
  system. Take care when configuring a public IP address to ensure
  that the network's firewall only allows access to authorized
  systems.

* **port_number:** is configured in
  :menuselection:`Services --> WebDAV`. If the FreeNAS® system is to
  be accessed using a public IP address, consider changing the default
  port number and ensure that the network's firewall only allows
  access to authorized systems.

* **share_name:** is configured in
  :menuselection:`Sharing --> WebDAV Shares`.

Entering the URL in a web browser brings up an authentication pop-up
message. Enter a username of *webdav* and the password configured in
:menuselection:`Services --> WebDAV`.

.. warning:: At this time, only the *webdav* user is supported. For
   this reason, it is important to set a good password for this
   account and to only give the password to users which should have
   access to the WebDAV share.

To create a WebDAV share, click
:menuselection:`Sharing --> WebDAV Shares --> Add WebDAV Share`
which will open the screen shown in
:numref:`Figure %s <add_webdav_share_fig>`.


.. _add_webdav_share_fig:

.. figure:: images/webdav.png

   Adding a WebDAV Share


:numref:`Table %s <webdav_share_opts_tab>`
summarizes the available options.


.. _webdav_share_opts_tab:

.. table:: WebDAV Share Options

   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Setting                      | Value         | Description                                                                                                 |
   |                              |               |                                                                                                             |
   +==============================+===============+=============================================================================================================+
   | Share Path Name              | string        | input a name for the share                                                                                  |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Comment                      | string        | optional                                                                                                    |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Path                         | browse button | browse to the volume/dataset to share                                                                       |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Read Only                    | checkbox      | if checked, users cannot write to the share                                                                 |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Change User & Group          | checkbox      | if checked, automatically sets the share's contents to the *webdav* user and group                          |
   | Ownership                    |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+


After clicking :guilabel:`OK`, a pop-up asks about enabling the
service. Once the service starts, review the settings in
:menuselection:`Services --> WebDAV`
as they are used to determine which URL is used to access the WebDAV
share and whether or not authentication is required to access the
share. These settings are described in :ref:`WebDAV`.


.. index:: CIFS, Samba, Windows Shares, SMB
.. _Windows (SMB) Shares:

Windows (SMB) Shares
---------------------

FreeNAS® uses `Samba <https://www.samba.org/>`_ to share volumes using
Microsoft's SMB protocol. SMB is built into the Windows and Mac OS X
operating systems and most Linux and BSD systems pre-install the Samba
client in order to provide support for SMB. If your distro did not,
install the Samba client using the distro's software repository.

The SMB protocol supports many different types of configuration
scenarios, ranging from the very simple to quite complex. The
complexity of the scenario depends upon the types and versions of the
client operating systems that will connect to the share, whether the
network has a Windows server, and whether Active Directory is being
used. Depending on the authentication requirements, it might be
necessary to create or import users and groups.

This chapter starts by summarizing the available configuration
options. It will then demonstrate some common configuration scenarios
as well as offer some troubleshooting tips. It is recommended to first
read through this entire chapter before creating any SMB shares so
that you have a good idea of the best configuration scenario to meet
your network's needs.

:numref:`Figure %s <adding_smb_share_fig>`
shows the configuration screen that appears after clicking
:menuselection:`Sharing --> Windows (SMB Shares)
--> Add Windows (SMB) Share`.


.. _adding_smb_share_fig:

.. figure:: images/cifs2a.png

   Adding an SMB Share


:numref:`Table %s <smb_share_opts_tab>`
summarizes the options when creating a SMB share. Some settings are
only available after clicking the :guilabel:`Advanced Mode` button.
For simple sharing scenarios, :guilabel:`Advanced Mode` options are
not needed. For more complex sharing scenarios, only change an
:guilabel:`Advanced Mode` option after fully understanding the
function of that option.
`smb.conf(5) <http://www.sloop.net/smb.conf.html>`_ provides more
details for each configurable option.


.. _smb_share_opts_tab:

.. table:: Options for a SMB Share

   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Setting                      | Value         | Description                                                                                                 |
   |                              |               |                                                                                                             |
   +==============================+===============+=============================================================================================================+
   | Path                         | browse button | select volume/dataset/directory to share                                                                    |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Use as home share            | checkbox      | check this box if the share is meant to hold user home directories; only one share can be the homes share   |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Name                         | string        | mandatory; name of share                                                                                    |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Comment                      | string        | only available in :guilabel:`Advanced Mode`; optional description                                           |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Apply Default Permissions    | checkbox      | sets the ACLs to allow read/write for owner/group and read-only for others; should only be unchecked when   |
   |                              |               | creating a share on a system that already has custom ACLs set                                               |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Export Read Only             | checkbox      | only available in :guilabel:`Advanced Mode`; prohibits write access to the share                            |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Browsable to Network Clients | checkbox      | only available in :guilabel:`Advanced Mode`; when checked, users see the contents of */homes*               |
   |                              |               | (including other home directories of other users) and when unchecked, users see only their own              |
   |                              |               | home directory                                                                                              |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Export Recycle Bin           | checkbox      | only available in :guilabel:`Advanced Mode`; deleted files are instead moved to a hidden                    |
   |                              |               | :file:`.recycle` directory in the root folder of the share                                                  |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Show Hidden Files            | checkbox      | only available in :guilabel:`Advanced Mode`; if enabled, the Windows hidden attribute is not                |
   |                              |               | set when filenames that begin with a dot (a Unix hidden file) are created; existing files are               |
   |                              |               | not affected                                                                                                |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Allow Guest Access           | checkbox      | if checked, no password is required to connect to the share and all users share the permissions of the      |
   |                              |               | guest user defined in the SMB service                                                                       |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Only Allow Guest Access      | checkbox      | only available in :guilabel:`Advanced Mode`; requires :guilabel:`Allow guest access` to also be             |
   |                              |               | checked; forces guest access for all connections                                                            |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Hosts Allow                  | string        | only available in :guilabel:`Advanced Mode`; comma-, space-, or tab-delimited list of allowed               |
   |                              |               | hostnames or IP addresses                                                                                   |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Hosts Deny                   | string        | only available in :guilabel:`Advanced Mode`; comma-, space-, or tab-delimited list of denied                |
   |                              |               | hostnames or IP addresses; allowed hosts take precedence so can use *ALL* in this field                     |
   |                              |               | and specify allowed hosts in :guilabel:`Hosts Allow`                                                        |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | VFS Objects                  | selection     | only available in :guilabel:`Advanced Mode`; adds virtual file system modules to enhance functionality;     |
   |                              |               | :numref:`Table %s <avail_vfs_modules_tab>` summarizes the available modules                                 |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Periodic Snapshot Task       | drop-down     | used to configure home directory shadow copies on a per-share basis; select the pre-configured periodic     |
   |                              | menu          | snapshot task to use for the share's shadow copies                                                          |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+
   | Auxiliary Parameters         | string        | only available in :guilabel:`Advanced Mode`; additional :file:`smb4.conf` parameters not covered            |
   |                              |               | by other option fields                                                                                      |
   |                              |               |                                                                                                             |
   +------------------------------+---------------+-------------------------------------------------------------------------------------------------------------+


Note the following regarding some of the :guilabel:`Advanced Mode`
settings:

* Hostname lookups add some time to accessing the SMB share. If you
  only use IP addresses, uncheck the :guilabel:`Hostnames lookups` box
  in
  :menuselection:`Services --> SMB`.

* Be careful about unchecking the
  :guilabel:`Browsable to Network Clients` box. When this box is
  checked (the default), other users will see the names of every share
  that exists using Windows Explorer, but they will receive a
  permissions denied error message if they try to access someone
  else's share. If this box is unchecked, even the owner of the share
  won't see it or be able to create a drive mapping for the share in
  Windows Explorer. However, they can still access the share from the
  command line. Unchecking this option provides limited security and
  is not a substitute for proper permissions and password control.

* If some files on a shared volume should be hidden and inaccessible
  to users, put a *veto files=* line in the
  :guilabel:`Auxiliary Parameters` field. The syntax for the
  :guilabel:`veto files` option and some examples can be found
  `here <http://www.sloop.net/smb.conf.html>`__.

To configure support for OS/2 clients, add this line to
:guilabel:`Auxiliary Parameters`:

.. code-block:: none

   lanman auth = yes


To configure lanman authentication for pre-NT authentication, add
these lines instead:

.. code-block:: none

 client lanman auth = yes
 client plaintext auth = yes


:numref:`Table %s <avail_vfs_modules_tab>`
provides an overview of the available VFS modules. Be sure to research
each module **before** adding or deleting it from the
:guilabel:`Selected` column of the :guilabel:`VFS Objects` field of
the share. Some modules need additional configuration after they are
added. Refer to
`Stackable VFS modules
<https://www.samba.org/samba/docs/man/Samba-HOWTO-Collection/VFS.html>`_
and the
`vfs_* man pages <https://www.samba.org/samba/docs/man/manpages/>`_
for more details.


.. _avail_vfs_modules_tab:

.. table:: Available VFS Modules

   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | Value               | Description                                                                                                                                |
   |                     |                                                                                                                                            |
   +=====================+============================================================================================================================================+
   | acl_tdb             | stores NTFS ACLs in a tdb file in order to enable full mapping of Windows ACLs                                                             |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | acl_xattr           | stores NTFS ACLs in Extended Attributes (EAs) in order to enable the full mapping of Windows ACLs                                          |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | aio_fork            | enables async I/O                                                                                                                          |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | aio_posix           | enables asynchronous I/O on systems running POSIX kernels                                                                                  |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | aio_pthread         | implements async I/O in Samba vfs using a pthread pool instead of the internal Posix AIO interface                                         |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | audit               | logs share access, connects/disconnects, directory opens/creates/removes, and file opens/closes/renames/unlinks/chmods to syslog           |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | cacheprime          | primes the kernel file data cache                                                                                                          |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | cap                 | translates filenames to and from the CAP encoding format, commonly used in Japanese language environments                                  |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | catia               | creates filenames that use characters that are illegal in SMB filenames                                                                    |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | commit              | tracks the amount of data written to a file and synchronizes it to disk when a specified amount accumulates                                |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | crossrename         | allows server side rename operations even if source and target are on different physical devices                                           |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | default_quota       | stores the default quotas that are reported to a windows client in the quota record of a user                                              |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | dfs_samba4          | distributed file system for providing an alternative name space, load balancing, and automatic failover                                    |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | dirsort             | sorts directory entries alphabetically before sending them to the client                                                                   |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | expand_msdfs        | enables support for Microsoft Distributed File System (DFS)                                                                                |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | extd_audit          | sends :guilabel:`audit` logs to both syslog and the Samba log files                                                                        |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | fake_acls           | stores file ownership and ACLs as extended attributes                                                                                      |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | fake_perms          | allows roaming profile files and directories to be set as read-only                                                                        |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | fruit               | enhances OS X support by providing the SMB2 AAPL extension and Netatalk interoperability (see NOTE below table)                            |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | full_audit          | records selected client operations to the system log                                                                                       |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | linux_xfs_sgid      | used to work around an old Linux XFS bug                                                                                                   |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | media_harmony       | allows Avid editorial workstations to share a network drive                                                                                |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | netatalk            | eases the co-existence of SMB and AFP shares                                                                                               |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | posix_eadb          | provides Extended Attributes (EAs) support so they can be used on filesystems which do not provide native support for EAs                  |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | preopen             | useful for video streaming applications that want to read one file per frame                                                               |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | readahead           | useful for Windows Vista clients reading data using Windows Explorer                                                                       |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | readonly            | marks a share as read-only for all clients connecting within the configured time period                                                    |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | scannedonly         | ensures that only files that have been scanned for viruses are visible and accessible                                                      |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | shadow_copy         | allows Microsoft shadow copy clients to browse shadow copies on Windows shares                                                             |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | shadow_copy_test    | shadow copy testing                                                                                                                        |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | shell_snap          | provides shell-script callouts for snapshot creation and deletion operations issued by remote clients using the File Server Remote VSS     |
   |                     | Protocol (FSRVP)                                                                                                                           |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | skel_opaque         | implements dummy versions of all VFS modules (useful to VFS module developers)                                                             |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | skel_transparent    | implements dummy passthrough functions of all VFS modules (useful to VFS module developers)                                                |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | smb_traffic_analyzer| logs Samba read and write operations through a socket to a helper application                                                              |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | snapper             | provides the ability for remote SMB clients to access shadow copies of FSRVP snapshots using Windows Explorer                              |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | streams_depot       | **experimental** module to store alternate data streams in a central directory                                                             |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | streams_xattr       | enables storing of NTFS alternate data streams in the file system                                                                          |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | syncops             | ensures metadata operations are performed synchronously                                                                                    |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | time_audit          | logs system calls that take longer than the number of defined milliseconds                                                                 |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | unityed_media       | allows multiple Avid clients to share a network drive                                                                                      |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | worm                | controls the writability of files and folders depending on their change time and an adjustable grace period                                |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+
   | xattr_tdb           | stores Extended Attributes (EAs) in a tdb file so they can be used on filesystems which do not provide support for EAs                     |
   |                     |                                                                                                                                            |
   +---------------------+--------------------------------------------------------------------------------------------------------------------------------------------+


.. note:: When using :guilabel:`fruit`, also add the
   :guilabel:`streams_xattr` and :guilabel:`catia` VFS objects and be
   sure to configure **all** SMB shares this way. Reboot the Mac
   client after making this change.

These 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
  :guilabel:`shadow_copy` with some additonal features

* **zfs_space:** correctly calculates ZFS space used by share,
  including any reservations or quotas

* **zfsacl:**


.. _Configuring Unauthenticated Access:

Configuring Unauthenticated Access
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

SMB supports guest logins, meaning that users can access the SMB
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 SMB share, click :guilabel:`Wizard`,
then click the :guilabel:`Next` button twice to display the screen
shown in
:numref:`Figure %s <create_unauth_smb_share_fig>`.
Complete the following fields in this screen:

#. **Share name:** enter a name for the share that is useful to you.
   In this example, the share is named *smb_insecure*.

#. Click the button for :guilabel:`Windows (SMB)` and check the box
   for :guilabel:`Allow Guest`.

#. Click the :guilabel:`Ownership` button. Click the drop-down
   :guilabel:`User` menu and select *nobody*. Click the
   :guilabel:`Return` button to return to the previous screen.

#. Click the :guilabel:`Add` button. **If you forget to do this, the
   share will not be created**. Clicking the :guilabel:`Add` button
   adds an entry to the :guilabel:`Name` frame with the name that was
   entered in :guilabel:`Share name`.


.. _create_unauth_smb_share_fig:

.. figure:: images/cifs7a.png

   Creating an Unauthenticated SMB Share


Click the :guilabel:`Next` button twice, then the :guilabel:`Confirm`
button to create the share. The Wizard automatically creates a dataset
for the share and starts the SMB service so the share is immediately
available. The new share is also be added to
:menuselection:`Sharing --> Windows (SMB)`.

Users can now access the share from any SMB client and will not be
prompted for their username or password. For example, to access the
share from a Windows system, open Explorer and click on
:guilabel:`Network`. For this configuration example, a system named
*FREENAS* appears with a share named :guilabel:`insecure_smb`. The
user can copy data to and from the unauthenticated SMB share.


.. _Configuring Authenticated Access Without a Domain Controller:

Configuring Authenticated Access Without a Domain Controller
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

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 SMB 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 SMB share, enter the
following information, as shown in the example in
:numref:`Figure %s <create_auth_smb_share_fig>`.

#. **Share name:** enter a name for the share that is useful to you.
   In this example, the share is named *smb_user1*.

#. Click the button for :guilabel:`Windows (SMB)`.

#. Click the :guilabel:`Ownership` button. To create the user account
   on the FreeNAS® system, type their name into the :guilabel:`User`
   field and check the :guilabel:`Create User` checkbox. The user's
   password is then entered and confirmed. **If the user will not be
   sharing this share with other users**, type their name into the
   :guilabel:`Group` field and click :guilabel:`Create Group`.
   **If, however, the share will be used by several users**,
   instead type in a group name and check the :guilabel:`Create Group`
   box. In the example shown in
   :numref:`Figure %s <create_smb_user_group_fig>`,
   *user1* has been used for both the user and group name, meaning
   that this share will only be used by *user1*. When finished, click
   :guilabel:`Return` to return to the screen shown in
   :numref:`Figure %s <create_auth_smb_share_fig>`.

#. Click the :guilabel:`Add` button. **If you forget to do this, the
   share will not be created**. Clicking the :guilabel:`Add` button
   adds an entry to the :guilabel:`Name` frame with the name that was
   entered in :guilabel:`Share name`.

If you wish to configure multiple authenticated shares, repeat for
each user, giving each user their own :guilabel:`Share name` and
:guilabel:`Ownership`. When finished, click :guilabel:`Next` twice,
then :guilabel:`Confirm` to create the shares. The Wizard
automatically creates a dataset with the correct ownership for each
share and starts the SMB service so the shares are available
immediately. The new shares are also added to
:menuselection:`Sharing --> Windows (SMB)`.


.. _create_auth_smb_share_fig:

.. figure:: images/cifs3a.png

   Creating an Authenticated SMB Share


.. _create_smb_user_group_fig:

.. figure:: images/cifs8.png

   Creating the User and Group


Authenticated share can now be tested from any SMB client. For
example, to test an authenticated share from a Windows system, open
Explorer and click on :guilabel:`Network`. For this configuration
example, a system named *FREENAS* appears with a share named
*smb_user1*. If you click on *smb_user1*, a Windows Security pop-up
screen prompts for that user's username and password. Enter the values
that were configured for that share, in this case user *user1*. After
authentication, the user can copy data to and from the SMB 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 :guilabel:`Map network drive...`. Choose a drive letter from
the drop-down menu and click the :guilabel:`Finish` button.

Note that Windows systems cache a user's credentials. This 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 entering the
correct username and password, type **cmd** in the
:guilabel:`Search programs and files` box and use the following
command to see if you have already authenticated to a share. In this
example, the user has already authenticated to the *smb_user1*
share:

.. code-block:: none

   net use
   New connections will be remembered.

   Status         Local   Remote                  Network
   ------------------------------------------------------------------------
   OK                     \\FREENAS\smb_user1 Microsoft Windows Network
   The command completed successfully.


To clear the cache:

.. code-block:: none

   net use * /DELETE
   You have these remote connections:
                  \\FREENAS\smb_user1
   Continuing will cancel the connections.

   Do you want to continue this operation? <Y/N> [N]: y


An additional warning is shown if the share is currently open in
Explorer:

.. code-block:: none

   There are open files and/or incomplete directory searches pending on the connection
   to \\FREENAS|smb_user1.

   Is it OK to continue disconnecting and force them closed? <Y/N> [N]: y
   The command completed successfully.


The next time a share is accessed with Explorer, you will be
prompted to authenticate.


.. index:: Shadow Copies
.. _Configuring Shadow Copies:

Configuring Shadow Copies
~~~~~~~~~~~~~~~~~~~~~~~~~

`Shadow Copies <https://en.wikipedia.org/wiki/Shadow_copy>`_,
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
<http://www.microsoft.com/en-us/download/details.aspx?displaylang=en&id=16220>`_.

When you create a periodic snapshot task on a ZFS volume that is
configured as a SMB 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 SMB 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
  SMB 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 SMB share. If the
  SMB share was created first, restart the SMB service in
  :menuselection:`Services --> Control Services`.

* Appropriate permissions must be configured on the volume/dataset
  being shared by SMB.

* Users cannot 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 SMB share.

To configure shadow copy support, use the instructions in
:ref:`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
   :menuselection:`Storage --> Periodic Snapshot Tasks
   --> Add Periodic Snapshot`
   to create at least one periodic snapshot task. You can either
   create a snapshot task for each user's dataset, in this example the
   datasets :file:`/mnt/volume1/user1` and :file:`/mnt/volume1/user2`,
   or you can create one periodic snapshot task for the entire volume,
   in this case :file:`/mnt/volume1`.
   **Before continuing to the next step,** confirm that at least one
   snapshot for each defined task is displayed in the
   :menuselection:`Storage --> Snapshots`
   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.

#. Go to
   :menuselection:`Sharing --> Windows (SMB) Shares`.
   Highlight a share and click :guilabel:`Edit`, then
   :guilabel:`Advanced Mode`. Click the
   :guilabel:`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 :file:`/mnt/volume1/user1` is configured to use a periodic
   snapshot task that was configured to take snapshots of the
   :file:`/mnt/volume1/user1` dataset and the share named
   :file:`/mnt/volume1/user2` is configured to use a periodic snapshot
   task that was configured to take snapshots of the
   :file:`/mnt/volume1/user2` dataset.

#. Verify that the SMB service is set to :guilabel:`ON` in
   :menuselection:`Services --> Control Services`.

:numref:`Figure %s <view_shadow_explorer_fig>`
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 :guilabel:`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, overwriting the existing file on the Windows system.


.. _view_shadow_explorer_fig:

.. figure:: images/cifs6.png

   Viewing Previous Versions within Explorer


.. index:: iSCSI, Internet Small Computer System Interface
.. _Block (iSCSI):

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, be familiar with this 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.

In FreeNAS®, 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 :numref:`Table %s <iscsi_targ_global_config_tab>`)
  or at the extent level
  (see :numref:`Table %s <iscsi_extent_conf_tab>`)
  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 :ref:`Create zvol` and use it to create a device
extent, as described in
:ref:`Extents`.

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
    :menuselection:`Services --> Control Services`.

The rest of this section describes these steps in more detail.



.. _Target Global Configuration:

Target Global Configuration
~~~~~~~~~~~~~~~~~~~~~~~~~~~

:menuselection:`Sharing --> Block (iSCSI)
--> Target Global Configuration`, shown in
:numref:`Figure %s <iscsi_targ_global_var_fig>`, contains
settings that apply to all iSCSI shares.
:numref:`Table %s <iscsi_targ_global_config_tab>`
summarizes the settings that can be configured in the Target Global
Configuration screen.


.. _iscsi_targ_global_var_fig:

.. figure:: images/global1c.png

   iSCSI Target Global Configuration Variables


.. _iscsi_targ_global_config_tab:

.. table:: Target Global Configuration Settings

   +---------------------------------+------------------------------+-------------------------------------------------------------------------------------------+
   | Setting                         | Value                        | Description                                                                               |
   |                                 |                              |                                                                                           |
   |                                 |                              |                                                                                           |
   +=================================+==============================+===========================================================================================+
   | Base Name                       | string                       | see the "Constructing iSCSI names using the iqn. format" section of :rfc:`3721`           |
   |                                 |                              | if unfamiliar with this format                                                            |
   |                                 |                              |                                                                                           |
   +---------------------------------+------------------------------+-------------------------------------------------------------------------------------------+
   | ISNS Servers                    | string                       | space delimited list of hostnames or IP addresses of ISNS servers with which              |
   |                                 |                              | to register the system's iSCSI targets and portals                                        |
   |                                 |                              |                                                                                           |
   +---------------------------------+------------------------------+-------------------------------------------------------------------------------------------+
   | Pool Available Space Threshold  | integer                      | enter 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                    |
   |                                 |                              |                                                                                           |
   +---------------------------------+------------------------------+-------------------------------------------------------------------------------------------+


.. _Portals:

Portals
~~~~~~~

A portal specifies the IP address and port number to be used for iSCSI
connections.
:menuselection:`Sharing --> Block (iSCSI) --> Portals --> Add Portal`
brings up the screen shown in
:numref:`Figure %s <iscsi_add_portal_fig>`.

:numref:`Table %s <iscsi_add_portal_fig>`
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 :guilabel:`Add extra Portal IP`.


.. _iscsi_add_portal_fig:

.. figure:: images/portal1a.png

   Adding an iSCSI Portal


.. _iscsi_portal_conf_tab:

.. table:: 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 :guilabel:`Authorized Access` if the               |
   |                       |                | :guilabel:`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, the iSCSI service 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.

.. _Initiators:

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
:menuselection:`Sharing --> Block (iSCSI) --> Initiators
--> Add Initiator`, shown in
:numref:`Figure %s <iscsi_add_initiator_fig>`.


.. _iscsi_add_initiator_fig:

.. figure:: images/initiator1.png

   Adding an iSCSI Initiator


:numref:`Table %s <iscsi_initiator_conf_tab>`
summarizes the settings that can be configured when adding an
initiator.


.. _iscsi_initiator_conf_tab:

.. table:: 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
:numref:`Figure %s <iscsi_initiator_conf_sample_fig>`,
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 :guilabel:`Edit` and :guilabel:`Delete` buttons.

.. note:: Attempting to delete an initiator causes a warning that
   indicates if any targets or target/extent mappings depend upon the
   initiator. Confirming the delete causes these to be deleted as well.


.. _iscsi_initiator_conf_sample_fig:

.. figure:: images/initiator2a.png

   Sample iSCSI Initiator Configuration


.. _Authorized Accesses:

Authorized Accesses
~~~~~~~~~~~~~~~~~~~

If you will be using CHAP or mutual CHAP to provide authentication,
you must create an authorized access in
:menuselection:`Sharing --> Block (iSCSI) --> Authorized Accesses
--> Add Authorized Access`. This screen is shown in
:numref:`Figure %s <iscsi_add_auth_access_fig>`.

.. note:: This screen sets login authentication. This is different
   from discovery authentication which is set in
   `Target Global Configuration`_.


.. _iscsi_add_auth_access_fig:

.. figure:: images/authorized1.png

   Adding an iSCSI Authorized Access


:numref:`Table %s <iscsi_auth_access_config_tab>`
summarizes the settings that can be configured when adding an
authorized access:


.. _iscsi_auth_access_config_tab:

.. table:: 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 :guilabel:`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 :guilabel:`User`                     |
   |             |           |                                                                                                                                  |
   +-------------+-----------+----------------------------------------------------------------------------------------------------------------------------------+
   | Peer Secret | string    | the mutual secret password which **must be different than the** :guilabel:`Secret`; required if :guilabel:`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
:guilabel:`View Authorized Accesses`. In the example shown in
:numref:`Figure %s <iscsi_view_auth_access_fig>`,
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 :guilabel:`Edit` and
:guilabel:`Delete` buttons.


.. _iscsi_view_auth_access_fig:

.. figure:: images/authorized2a.png

   Viewing Authorized Accesses


.. _Targets:

Targets
~~~~~~~

Next, create a Target using
:menuselection:`Sharing --> Block (iSCSI) --> Targets --> Add Target`,
as shown in
:numref:`Figure %s <iscsi_add_target_fig>`.
A target combines a portal ID, allowed initiator ID, and an
authentication method.
:numref:`Table %s <iscsi_target_settings_tab>`
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 multiple clients need
   access to the same data on a non-clustered filesystem, use SMB or
   NFS instead of iSCSI, or create multiple iSCSI targets (one per
   client).


.. _iscsi_add_target_fig:

.. figure:: images/target1a.png

   Adding an iSCSI Target


.. _iscsi_target_settings_tab:

.. table:: 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                                         |
   |                             |                |                                                                                                             |
   +-----------------------------+----------------+-------------------------------------------------------------------------------------------------------------+


.. _Extents:

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
<http://www.freebsd.org/doc/en_US.ISO8859-1/books/handbook/disks-hast.html>`_.

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 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
   :ref:`Growing LUNs`.

To add an extent, go to
:menuselection:`Sharing --> Block (iSCSI) --> Extents --> Add Extent`.
In the example shown in
:numref:`Figure %s <iscsi_adding_extent_fig>`,
the device extent is using the :file:`export` zvol that was previously
created from the :file:`/mnt/volume1` volume.

:numref:`Table %s <iscsi_extent_conf_tab>`
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.**


.. _iscsi_adding_extent_fig:

.. figure:: images/extent2b.png

   Adding an iSCSI Extent


.. _iscsi_extent_conf_tab:

.. table:: Extent Configuration Settings

   +--------------------+----------------+----------------------------------------------------------------------------------------------------------------------+
   | Setting            | Value          | Description                                                                                                          |
   |                    |                |                                                                                                                      |
   +====================+================+======================================================================================================================+
   | Extent Name        | string         | name of extent; if the :guilabel:`Extent size` is not *0*, it cannot 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                             |
   |                    |                | :guilabel:`Extent size`, **or** browse to the volume or dataset, click :guilabel:`Close`,                            |
   |                    |                | append the :guilabel:`Extent Name` to the path, and specify a value in :guilabel:`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   | checkbox       | if the initiator does not support physical block size values over 4K (MS SQL), check this box                        |
   | Block Size         |                |                                                                                                                      |
   | Reporting          |                |                                                                                                                      |
   |                    |                |                                                                                                                      |
   +--------------------+----------------+----------------------------------------------------------------------------------------------------------------------+
   | Available Space    | string         | only appears if *File* or a zvol is selected; when the specified percentage of free space is reached, the system     |
   | Threshold          |                | 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               |
   |                    |                | :command:`xcopy` operations otherwise blocked by access control                                                      |
   |                    |                |                                                                                                                      |
   +--------------------+----------------+----------------------------------------------------------------------------------------------------------------------+
   | Xen initiator      | checkbox       | check this box when using Xen as the iSCSI initiator                                                                 |
   | compat mode        |                |                                                                                                                      |
   |                    |                |                                                                                                                      |
   +--------------------+----------------+----------------------------------------------------------------------------------------------------------------------+
   | 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                                                   |
   |                    |                |                                                                                                                      |
   +--------------------+----------------+----------------------------------------------------------------------------------------------------------------------+


.. _Targets/Extents:

Target/Extents
~~~~~~~~~~~~~~

The last step is associating an extent to a target within
:menuselection:`Sharing --> Block (iSCSI) --> Associated Targets
--> Add Target/Extent`. This screen is shown in
:numref:`Figure %s <iscsi_target_extent_fig>`.
Use the drop-down menus to select the existing target and extent.
Click :guilabel:`OK` to add an entry for the LUN.


.. _iscsi_target_extent_fig:

.. figure:: images/target2b.png

   Associating a Target With an Extent


:numref:`Table %s <iscsi_target_extent_config_tab>`
summarizes the settings that can be configured when associating
targets and extents.


.. _iscsi_target_extent_config_tab:

.. table:: Target/Extents Configuration Settings

   +-------------+----------------+--------------------------------------------------------------------------------------------------------+
   | Setting     | Value          | Description                                                                                            |
   |             |                |                                                                                                        |
   +=============+================+========================================================================================================+
   | Target      | drop-down menu | select the pre-created target                                                                          |
   |             |                |                                                                                                        |
   +-------------+----------------+--------------------------------------------------------------------------------------------------------+
   | LUN ID      | drop-down menu | 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
one-to-one manner, even though the GUI will allow multiple extents to
be associated with the same target.

.. note:: Each LUN entry has :guilabel:`Edit` and :guilabel:`Delete`
   buttons for modifying the settings or deleting the LUN entirely.
   A verification popup appears when the :guilabel:`Delete` button is
   clicked. If an initiator has an active connection to the LUN, it is
   indicated in red text. It is recommended to clear initiator
   connections to a LUN before deleting it.

After iSCSI has been configured, remember to start it in
:menuselection:`Services --> Control Services`.
Click the red :guilabel:`OFF` button next to iSCSI. After a second or
so, it will change to a blue :guilabel:`ON`, indicating that the
service has started.




.. _Connecting to iSCSI:

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
<http://www.windowsnetworking.com/articles-tutorials/windows-7/Connecting-Windows-7-iSCSI-SAN.html>`__.
A client for Windows 2000, XP, and 2003 can be found `here
<http://www.microsoft.com/en-us/download/details.aspx?id=18986>`__.
This
`how-to
<http://blog.pluralsight.com/freenas-8-iscsi-target-windows-7>`_
shows how to create an iSCSI target for a Windows 7 system.

Mac OS X does not include an initiator.
`globalSAN
<http://www.studionetworksolutions.com/globalsan-iscsi-initiator/>`_
is a commercial, easy-to-use Mac initiator.

BSD systems provide command line initiators:
`iscontrol(8) <http://www.freebsd.org/cgi/man.cgi?query=iscontrol>`_
comes with FreeBSD versions 9.x and lower,
`iscsictl(8) <https://www.freebsd.org/cgi/man.cgi?query=iscsictl>`_
comes with FreeBSD versions 10.0 and higher,
`iscsi-initiator(8)
<http://netbsd.gw.com/cgi-bin/man-cgi?iscsi-initiator++NetBSD-current>`_
comes with NetBSD, and
`iscsid(8)
<http://www.openbsd.org/cgi-bin/man.cgi/OpenBSD-current/./man8/iscsid.8?query=iscsid>`_
comes with OpenBSD.

Some Linux distros provide the command line utility
:command:`iscsiadm` from `Open-iSCSI <http://www.open-iscsi.com/>`_.
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 :command:`iscsiadm` is already connected, it
will not see the new LUN until you rescan using
:command:`iscsiadm -m node -R`. Alternately, use
:command:`iscsiadm -m discovery -t st -p portal_IP`
to find the new LUN and :command:`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)
<http://www.vladan.fr/how-to-configure-freenas-8-for-iscsi-and-connect-to-esxi/>`_.
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
<http://www.vmware.com/pdf/vsphere4/r41/vsp_41_iscsi_san_cfg.pdf>`_
for details.

If you can see the target but not connect to it, check the
:guilabel:`Discovery Auth` settings in
:guilabel:`Target Global Configuration`.

If the LUN is not discovered by ESXi, make sure that promiscuous mode
is set to :guilabel:`Accept` in the vSwitch.


.. _Growing LUNs:

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.


.. _Zvol Based LUN:

Zvol Based LUN
^^^^^^^^^^^^^^

To grow a zvol based LUN, go to
:menuselection:`Storage --> Volumes --> View Volumes`,
highlight the zvol to be grown, and click :guilabel:`Edit zvol`. In
the example shown in
:numref:`Figure %s <iscsi_zvol_lun_fig>`,
the current size of the zvol named *zvol1* is 4GB.


.. _iscsi_zvol_lun_fig:

.. figure:: images/grow1.png

   Editing an Existing Zvol


Enter the new size for the zvol in the :guilabel:`Size` field and
click :guilabel:`Edit ZFS Volume`. This menu closes and the new size
for the zvol is immediately shown in the :guilabel:`Used` column of
the :guilabel:`View Volumes` screen.

.. note:: The GUI does not allow reducing (shrinking) the size of the
   zvol, as doing so could result in loss of data. It also does not
   allow increasing the size of the zvol past 80% of the volume size.


.. _File Extent Based LUN:

File Extent Based LUN
^^^^^^^^^^^^^^^^^^^^^

To grow a file extent based LUN, go to
:menuselection:`Services --> iSCSI --> File Extents
--> View File Extents` to determine the path of the file extent to
grow. Open Shell to grow the extent. This example
grows :file:`/mnt/volume1/data` by 2 G:

.. code-block:: none

   truncate -s +2g /mnt/volume1/data


Go back to
:menuselection:`Services --> iSCSI --> File Extents
--> View File Extents` and click the :guilabel:`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.
