Sharing and Unsharing ZFS File Systems

The Oracle Solaris 11.1 release simplifies ZFS share administration by leveraging ZFS property inheritance. The new share syntax is enabled on pools running pool version 34.

Multiple shares can be defined per file system. A share name uniquely identifies each share. You can define the properties that are used to share a particular path in a file system. By default, all file systems are unshared. In general, the NFS server services are not started until a share is created. If you create a valid share, the NFS services are started automatically. If a ZFS file system's mountpoint property is set to legacy, the file system can only be shared by using the legacy share command.

• The share.nfs property replaces the sharenfs property in previous releases to define and publish an NFS share.

• The share.smb property replaces the sharesmb property in previous releases to define and publish an SMB share.

• Both the sharenfs property and sharesmb property are aliases to the share.nfs property and the sharenfs property.

• The /etc/dfs/dfstab file is no longer used to share file systems at boot time. Setting these properties share file systems automatically. SMF manages ZFS or UFS share information so that file systems are shared automatically when the system is rebooted. This feature means that all file systems whose sharenfs or sharesmb property are not set to off are shared at boot time.

• The sharemgr interface is no longer available. The legacy share command is still available to create a legacy share. See the examples below.

• The share -a command is like the previous share -ap command so that sharing a file system is persistent. The share -p option is no longer available.

For example, if you want to share the tank/home file system, use syntax similar to the following:

# zfs set share.nfs=on tank/home

You can also specify additional property values or modify existing property values on existing file system shares. For example:

# zfs set share.nfs.nosuid=on tank/home/userA

In preceding example, where the share.nfs property is set on the tank/home file system, the share.nfs property value is inherited to any descendent file systems. For example:

# zfs create tank/home/userA
# zfs create tank/home/userB

Legacy ZFS Sharing Syntax

Oracle Solaris 11 syntax is still supported so that you can share file systems in two steps. This syntax is supported in all pool versions.

• First, use the zfs set share command to create an NFS or SMB share of ZFS file system.

  # zfs create rpool/fs1
  # zfs set share=name=fs1,path=/rpool/fs1,prot=nfs rpool/fs1
  name=fs1,path=/rpool/fs1,prot=nfs

• Then, set the sharenfs or sharesmb property to on to publish the share. For example:

  # zfs set sharenfs=on rpool/fs1
  # grep fs1 /etc/dfs/sharetab
  /rpool/fs1      fs1     nfs     sec=sys,rw

File system shares can be displayed with the legacy zfs get share command.

# zfs get share rpool/fs1
NAME       PROPERTY  VALUE  SOURCE
rpool/fs1  share     name=fs1,path=/rpool/fs1,prot=nfs  local

In addition, the share command to share a file system, similar to the syntax in the Oracle Solaris 10 release, is still supported to share any directory within a file system. For example, to share a ZFS file system:

# share -F nfs /tank/zfsfs
# grep zfsfs /etc/dfs/sharetab
/tank/zfsfs    tank_zfsfs     nfs     sec=sys,rw

The above syntax is identical to sharing a UFS file system:

# share -F nfs /ufsfs
# grep ufsfs /etc/dfs/sharetab
/ufsfs          -               nfs     rw      
/tank/zfsfs     tank_zfsfs      nfs     rw      

New ZFS Sharing Syntax

The zfs set command is used to share and publish a ZFS file system over the NFS or SMB protocols. Or, you can set the share.nfs or share.smb property when the file system is created.

For example, the tank/sales file system is created and shared. The default share permissions are read-write for everyone. The descendent tank/sales/logs file system is also shared automatically because the share.nfs property is inherited to descendent file systems and the tank/sales/log file system is set to read-only access.

# zfs create -o share.nfs=on tank/sales
# zfs create -o share.nfs.ro=\* tank/sales/logs
# zfs get -r share.nfs tank/sales
NAME             PROPERTY   VALUE  SOURCE
tank/sales       share.nfs  on     local
tank/sales%      share.nfs  on     inherited from tank/sales
tank/sales/log   share.nfs  on     inherited from tank/sales
tank/sales/log%  share.nfs  on     inherited from tank/sales

You can provide root access to a specific system for a shared file system as follows:

# zfs set share.nfs=on tank/home/data
# zfs set share.nfs.sec.default.root=neo tank/home/data

ZFS Sharing with Per-Property Inheritance

In pools that have been upgraded to the latest pool version 34, new sharing syntax is available that makes use of ZFS property inheritance to ease share maintenance. Each sharing characteristic becomes a separate share property. The share properties are identified by names that start with the share. prefix. Examples of share properties include share.desc, share.nfs.nosuid, and share.smb.guestok.

The share.nfs property controls whether NFS sharing is enabled. The share.smb property controls whether SMB sharing is enabled. The legacy sharenfs and sharesmb property names can still be used, because in new pools, sharenfs is an alias for share.nfs and sharesmb is an alias for share.smb. If you want to share the tank/home file system, use syntax similar to the following:

# zfs set share.nfs=on tank/home

In this example, the share.nfs property value is inherited to any descendent file systems. For example:

# zfs create tank/home/userA 
# zfs create tank/home/userB
# grep tank/home /etc/dfs/sharetab
/tank/home      tank_home       nfs     sec=sys,rw      
/tank/home/userA        tank_home_userA nfs     sec=sys,rw      
/tank/home/userB        tank_home_userB nfs     sec=sys,rw   

ZFS Sharing Inheritance in Older Pools

In older pools, only the sharenfs and sharesmb properties are inherited by descendent file systems. Other sharing characteristics are stored in the .zfs/shares file for each share and are not inherited.

A special rule is that whenever a new file system is created that inherits sharenfs or sharesmb from its parent, a default share is created for that file system from the sharenfs or sharesmb value. Note that when sharenfs is simply on, the default share that is created in a descendent file system has only the default NFS characteristics. For example:

# zpool get version tank
NAME  PROPERTY  VALUE  SOURCE
tank  version   33     default
# zfs create -o sharenfs=on tank/home
# zfs create tank/home/userA
# grep tank/home /etc/dfs/sharetab
/tank/home      tank_home       nfs     sec=sys,rw      
/tank/home/userA        tank_home_userA nfs     sec=sys,r

ZFS Named Shares

You can also create a named share, which provides more flexibility in setting permissions and properties in an SMB environment. For example:

# zfs share -o share.smb=on tank/workspace%myshare

In the preceding example, the zfs share command creates an SMB share called myshare of the tank/workspace file system. You can access the SMB share and display or set specific permissions or ACLs through the .zfs/shares directory of the file system. Each SMB share is represented by a separate .zfs/shares file. For example:

# ls -lv /tank/workspace/.zfs/shares
-rwxrwxrwx+  1 root     root           0 May 15 10:31 myshare
     0:everyone@:read_data/write_data/append_data/read_xattr/write_xattr
         /execute/delete_child/read_attributes/write_attributes/delete
         /read_acl/write_acl/write_owner/synchronize:allow

Named shares inherit sharing properties from the parent file system. If you add the share.smb.guestok property to the parent file system in the previous example, this property is inherited to the named share. For example:

# zfs get -r share.smb.guestok tank/workspace
NAME                    PROPERTY           VALUE  SOURCE
tank/workspace          share.smb.guestok  on     inherited from tank
tank/workspace%myshare  share.smb.guestok  on     inherited from tank

Named shares can be helpful in the NFS environment when defining shares for a subdirectory of the file system. For example:

# zfs create -o share.nfs=on -o share.nfs.anon=99 -o share.auto=off tank/home
# mkdir /tank/home/userA
# mkdir /tank/home/userB
# zfs share -o share.path=/tank/home/userA tank/home%userA
# zfs share -o share.path=/tank/home/userB tank/home%userB
# grep tank/home /etc/dfs/sharetab
/tank/home/userA        userA   nfs     anon=99,sec=sys,rw      
/tank/home/userB        userB   nfs     anon=99,sec=sys,rw  

The above example also illustrates that setting the share.auto to off for a file system turns off the auto share for that file system while leaving all other property inheritance intact. Unlike most other sharing properties, the share.auto property is not inheritable.

Named shares are also used when creating a public NFS share. A public share can only be created on a named NFS share. For example:

# zfs create -o mountpoint=/pub tank/public
# zfs share -o share.nfs=on -o share.nfs.public=on tank/public%pubshare
# grep pub /etc/dfs/sharetab
/pub    pubshare        nfs     public,sec=sys,rw

See share_nfs(1M) and share_smb(1M) for a detailed description of NFS and SMB share properties.

ZFS Automatic Shares

When an automatic (auto) share is created, a unique resource name is constructed from the file system name. The constructed name is a copy of the file system name except that the characters in the file system name that would be illegal in the resource name, are replaced with underscore (_) characters. For example, the resource name of data/home/john is data_home_john.

Setting a share.autoname property name allows you to replace the file system name with a specific name when creating the auto share. The specific name is also used to replace the prefix file system name in the case of inheritance. For example:

# zfs create -o share.smb=on -o share.autoname=john data/home/john
# zfs create data/home/john/backups
# grep john /etc/dfs/sharetab
/data/home/john john    smb     
/data/home/john/backups john_backups    smb

If a legacy share command or the zfs set share command is used on a file system that has not yet been shared, its share.auto value is automatically set to off. The legacy commands always create named shares. This special rule prevents the auto share from interfering with the named share that is being created.

Displaying ZFS Share Information

Display the value of the file sharing properties by using zfs get command. The following example shows how to display the share.nfs property for a single file system:

# zfs get share.nfs tank/sales
NAME        PROPERTY   VALUE  SOURCE
tank/sales  share.nfs  on     local

The following example shows how to display the share.nfs property for descendent file systems:

# zfs get -r share.nfs tank/sales
NAME             PROPERTY   VALUE  SOURCE
tank/sales       share.nfs  on     local
tank/sales%      share.nfs  on     inherited from tank/sales
tank/sales/log   share.nfs  on     inherited from tank/sales
tank/sales/log%  share.nfs  on     inherited from tank/sales

The extended share property information is not available in the zfs get all command syntax.

You can display specific details about NFS or SMB share information by using the following syntax:

# zfs get share.nfs.all tank/sales
NAME        PROPERTY             VALUE  SOURCE
tank/sales  share.nfs.aclok      off    default
tank/sales  share.nfs.anon              default
tank/sales  share.nfs.charset.*  ...    default
tank/sales  share.nfs.cksum             default
tank/sales  share.nfs.index             default
tank/sales  share.nfs.log               default
tank/sales  share.nfs.noaclfab   off    default
tank/sales  share.nfs.nosub      off    default
tank/sales  share.nfs.nosuid     off    default
tank/sales  share.nfs.public     -      -
tank/sales  share.nfs.sec               default
tank/sales  share.nfs.sec.*      ...    default

Because there are many share properties, consider displaying the properties with a non-default value. For example:

# zfs get -e -s local,received,inherited share.all tank/home
NAME       PROPERTY           VALUE  SOURCE
tank/home  share.auto         off    local
tank/home  share.nfs          on     local
tank/home  share.nfs.anon     99     local
tank/home  share.protocols    nfs    local
tank/home  share.smb.guestok  on     inherited from tank

Changing a ZFS Share Property Values

You can change share property values by specifying new or modified properties on a file system share. For example, if the read-only property is set when the file system is created, the property can be set to off.

# zfs create -o share.nfs.ro=\* tank/data
# zfs get share.nfs.ro tank/data
NAME       PROPERTY              VALUE  SOURCE
tank/data  share.nfs.sec.sys.ro  on     local
# zfs set share.nfs.ro=none tank/data
# zfs get share.nfs.ro tank/data
NAME       PROPERTY              VALUE  SOURCE
tank/data  share.nfs.sec.sys.ro  off    local

If you create an SMB share, you can also add the NFS share protocol. For example:

# zfs set share.smb=on tank/multifs
# zfs set share.nfs=on tank/multifs
# grep multifs /etc/dfs/sharetab
/tank/multifs   tank_multifs    nfs     sec=sys,rw      
/tank/multifs   tank_multifs    smb     -       

Remove the SMB protocol:

# zfs set share.smb=off tank/multifs
# grep multifs /etc/dfs/sharetab
/tank/multifs   tank_multifs    nfs     sec=sys,rw

You can rename a named share. For example:

# zfs share -o share.smb=on tank/home/abc%abcshare
# grep abc /etc/dfs/sharetab
/tank/home/abc  abcshare        smb     -   
# zfs rename tank/home/abc%abcshare tank/home/abc%a1share
# grep abc /etc/dfs/sharetab
/tank/home/abc  a1share        smb     -   

Publishing and Unpublishing ZFS Shares

You can temporarily unshare a named share without destroying it by using the zfs unshare command. For example:

# zfs unshare tank/home/abc%a1share
# grep abc /etc/dfs/sharetab
#
# zfs share tank/home/abc%a1share
# grep abc /etc/dfs/sharetab
/tank/home/abc  a1share smb     -

When the zfs unshare command is issued, all file system shares are unshared. These shares remain unshared until the zfs share command is issued for the file system or the share.nfs or share.smb property is set for the file system.

Defined shares are not removed when the zfs unshare command is issued, and they are re-shared the next time the zfs share command is issued for the file system or the share.nfs or share.smb property is set for the file system.

Removing a ZFS Share

You can unshare a file system share by setting the share.nfs or share.smb property to off. For example:

# zfs set share.nfs=off tank/multifs
# grep multifs /etc/dfs/sharetab
# 

You can permanently remove a named share by using the zfs destroy command. For example:

# zfs destroy tank/home/abc%a1share

ZFS File Sharing Within a Non-Global Zone

Starting with Oracle Solaris 11, you can create and publish NFS shares in an Oracle Solaris non-global zone.

• If a ZFS file system is mounted and available in a non-global zone, it can be shared in that zone.

• A file system can be shared in the global zone if it is not delegated to a non-global zone and is not mounted in a non-global zone. If a file system is added to a non-global zone, it can only be shared by using the legacy share command.

For example, the /export/home/data and /export/home/data1 file systems are available in the zfszone.

zfszone# share -F nfs /export/home/data
zfszone#  cat /etc/dfs/sharetab

zfszone# zfs set share.nfs=on tank/zones/export/home/data1
zfszone# cat /etc/dfs/sharetab

ZFS Sharing Migration/Transition Issues

Identify any transition issues in this section.

• Importing file systems with older sharing properties - When importing a pool or receiving a file system stream that was created before Oracle Solaris 11, the sharenfs and sharesmb properties include all the share properties directly in the property value. In most cases, these legacy share properties are converted to an equivalent set of named shares as soon as each file system is shared. Since import operations trigger mounting and sharing in most cases, the conversion to named shares happens directly during the import process.

• Upgrading from Oracle Solaris 11 - The first file system sharing after a pool upgrade to version 34 can take a long time because the named shares are converted to the new format. The named shares created by the upgrade process are correct but cannot take advantage of share property inheritance.

  • Display share property values:

    # zfs get share.nfs filesystem
    # zfs get share.smb filesystem

  • If you boot back to an older BE, reset the sharenfs and sharesmb properties to their original values.

• Upgrading from Oracle Solaris 11 Express - In Oracle Solaris 11 and 11.1, the sharenfs and sharesmb properties can have only off and on values. These properties are no longer used to define share characteristics.

  The /etc/dfs/dfstab file is no longer used to share file systems at boot time. At boot time, all mounted ZFS file systems that include enabled file system shares are automatically shared. A share is enabled when it sharenfs or sharesmb is set to on.

  The sharemgr interface is no longer available. The legacy share command is still available to create a legacy share. The share -a command is like the previous share -ap command so that sharing a file system is persistent. The share -p option is no longer available.

• Upgrading your system – ZFS shares will be incorrect if you boot back to an Oracle Solaris 11 Express BE due to property changes in this release. Non-ZFS shares are unaffected. If you plan to boot back to an older BE, you should first save a copy of the existing share configuration prior to the pkg update operation to be able to restore the share configuration on the ZFS datasets.

  In the older BE, use the sharemgr show -vp command to list all shares and their configuration.

  Use the following commands to display share property values:

  # zfs get sharenfs filesystem
  # zfs get sharesmb filesystem

  If you back to an older BE, reset the sharenfs and sharesmb properties and any shares defined with sharemgr to their original values.

• Legacy unsharing behavior – Using the unshare -a command or unshareall command unshares a file system, but does not update the SMF shares repository. If you try to re-share the existing share, the shares repository is checked for conflicts, and an error is displayed.

Troubleshooting ZFS File System Sharing Problems

Review the following share behavior scenarios and considerations:

• Share properties and .zfs/shares files are treated differently in zfs clone and zfs send operations. The .zfs/shares files are included in snapshots and are preserved in zfs clone and zfs send operations. Sharing properties including named shares are not included in snapshots. For a description of the behavior of properties during zfs send and zfs receive operations, see Applying Different Property Values to a ZFS Snapshot Stream. After a clone operation, all files are from the pre-clone snapshot, whereas the properties are inherited from the clone's new position in the ZFS file system hierarchy.

• Certain legacy share operations automatically turn off the auto share or convert an existing auto share to an equivalent named share. If a file system is not shared as expected, check to see if its share.auto value has been set to off.

• If a request to create a named share fails because the share would conflict with the auto share, you may have to turn off the auto share in order to proceed.

• When a pool is imported read only, neither its properties nor its files can be modified. It can be impossible to introduce new sharing in this situation. If sharing was already established before the pool was exported, the existing sharing characteristics are used, if possible.

The following table identifies know share states and how to resolve them, if necessary.

# zfs share FS%share