|Skip Navigation Links|
|Exit Print View|
|Oracle Solaris 11.1 Administration: ZFS File Systems Oracle Solaris 11.1 Information Library|
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
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
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
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
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
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
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.
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
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 -
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.
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
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
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.
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.