Go to main content

man pages section 8: System Administration Commands

Exit Print View

Updated: Thursday, June 13, 2019
 
 

zfs_share(8)

Name

zfs_share - share and unshare a ZFS file system

Synopsis

zfs help subcommand | help | property property-name | permission
zfs help -l properties
zfs destroy share
zfs get [-rHpe|-d max][-o all | field[,...]] [-s source[,...]]
     all | property[,...] filesystem|volume|snapshot|share ...
zfs get share [filesystem]
zfs [-r] set [-r | -c] filesystem|volume|snapshot|share ...
zfs [-r] set share.nfs=on | off filesystem
zfs [-r] set share.smb=on | off filesystem
zfs share -u [-o property=value]...  filesystem%share
zfs share filesystem|mountpoint|filesystem%share
zfs share -a | -r filesystem
zfs unshare filesystem|mountpoint|filesystem%share
zfs unshare -a | -r filesystem

Description

You can create an NFS share or an SMB share of a ZFS file system by setting share.nfs or share.smb property. You can also use the zfs share and zfs unshare commands to publish or unpublish a ZFS share.

Sharing ZFS File Systems

A file system can be shared by setting or inheriting the share.nfs=on or share.smb=on property value. For example:


# zfs set share.nfs=on tank/home
# zfs set share.smb=on tank/data

The above simple syntax creates and publishes the file system shares automatically. This method is referred to as an automatic share. For more information, see the EXAMPLES section.

The automatic share is read-only and inherits all of its properties from the parent file system. This method allows sharing to be enabled by inheritance alone, if needed, without having to create a share for each descendent file system. The published share name, share.name, of an automatic share is generated from the dataset mount point.

For example, the share.name of tank/home is tank_home.

A file system's automatic share name displays as filesystem%. For example, tank/home%.

You can also create and publish a share by using the zfs share command as follows:

# zfs share -o share.smb=on sandbox/myfs%myshare

The above syntax creates and publishes a named share, which provides more flexibility when you need to share subdirectories within a file system over NFS or SMB protocols. For more information, see the EXAMPLES section.

The listshares pool property is used to determine whether share information is displayed when using the zfs list command. For more information, see zpool(8).

Native Share File System Properties

File system properties are divided into two types, native properties and user-defined (or user) properties. Native properties either display information or control ZFS behavior. In addition, native properties are either editable or read-only.

Properties are inherited from the parent unless overridden by the child. Some properties apply only to certain types of datasets (file systems, volumes, or snapshots).

The following native properties can be used to change the behavior of a ZFS file system and are generally used when a file system is shared.

nbmand=on | off

Controls whether the file system should be mounted with nbmand (Non Blocking mandatory locks). This is used for SMB clients. Changes to this property only take effect when the file system is unmounted and remounted. See mount(8) for more information on nbmand mounts.

readonly=on | off

Controls whether this dataset can be modified. The default value is off.

This property can also be referred to by its shortened column name, rdonly.

share.nfs=on | off

Controls whether a ZFS dataset is created and published as an NFS share. You can also publish and unpublish an named NFS share of a ZFS dataset by using the zfs share and zfs unshare commands. Both methods of publishing an NFS share require that the NFS share properties are already set. For information about setting NFS share properties, see the zfs set command syntax below.

When the share.nfs property is changed, the file system share and any children inheriting the property are re-published with any new options that have been set with the zfs set command only if the property was previously off, or if the shares were published before the property was changed. If the new property value is off, the file system shares are unpublished.

share.smb=on | off

Controls whether a ZFS dataset is created and published as an SMB share. You can also publish and unpublish an named SMB share of a ZFS dataset by using the zfs share and zfs unshare commands. Both methods of publishing an SMB share require that the SMB share properties are also set. For information about setting SMB share properties, see the zfs set command syntax below.

When SMB shares are created, the SMB share name appears as an entry in the .zfs/shares directory. You can use the ls or chmod command to display the share-level ACLs on the entries in this directory.

When the property is changed from off to on, any shares that inherit the property are re-shared with their current options. When the property is set to off, the shares that inherit the property are unshared.

vscan=on | off

Controls whether regular files should be scanned for viruses when a file is opened and closed. In addition to enabling this property, the virus scan service must also be enabled for virus scanning to occur. The default value is off.

The following properties cannot be changed after the file system is created and, therefore, should be set when the file system is created. If the properties are not set with the zfs create or zpool create commands, these properties are inherited from the parent dataset. If the parent dataset lacks these properties due to having been created prior to these features being supported, the new file system will have the default values for these properties.

casesensitivity=sensitive | insensitive | mixed

Indicates whether the file name matching algorithm used by the file system should be case-sensitive, case-insensitive, or allow a combination of both styles of matching. The default value for the casesensitivity property is mixed. Traditionally, UNIX and POSIX file systems have case-sensitive file names.

The mixed value for the casesensitivity property indicates that the file system can support requests for both case-sensitive and case-insensitive matching behavior. Currently, case-insensitive matching behavior on a file system that supports mixed behavior is limited to the Solaris SMB server product. For more information about the mixed value behavior, see the Managing ZFS File Systems in Oracle Solaris 11.4.

normalization = none | formC | formD | formKC | formKD

Indicates whether the file system should perform a unicode normalization of file names whenever two file names are compared, and which normalization algorithm should be used. File names are always stored unmodified, names are normalized as part of any comparison process. If this property is set to a legal value other than none, and the utf8only property was left unspecified, the utf8only property is automatically set to on. The default value of the normalization property is none. This property cannot be changed after the file system is created.

utf8only=on | off

Indicates whether the file system should reject file names that include characters that are not present in the UTF-8 character code set. If this property is explicitly set to off, the normalization property must either not be explicitly set or be set to none. The default value for the utf8only property is off. This property cannot be changed after the file system is created.

Specific NFS or SMB Properties

In addition to native properties and user properties, you can also designate properties that control the way a file system is shared. The following set of share-related properties fall into 3 categories: global properties that apply to both NFS and SMB sharing, NFS-specific properties, and SMB-specific properties.

Global share properties are mostly read-only with a few exceptions. The following global share properties apply to either a NFS or SMB share or on the shared or to be shared file system:

Table 1  Global Share Property Descriptions
Property
Description
Inheritable
Value
share.desc
Editable property that provides a user-defined description and can be set on the file system or a share. The default value is no description.
Yes
string
share.fs
Read-only property that identifies the file system name for a share.
No
filesystem
share.name
Read-only property that identifies the share name for a share.
No
share-name
share.noauto
Editable property that disables automatic sharing and can only be set on the file system to be shared only.
No
on or off
share.path
Editable property that sets the share path on a share.
No
mountpoint-relative-path
share.point
Read-only property that identifies the absolute path of an existing share that is derived from the current value of the share.path property relative to the dataset mount point.
No
path
share.protocols
Read-only property that identifies the protocols established for the file system or the share.
No
protocol-list
share.state
Read-only property that identifies the current state of the share.
No
unshared, shared, or failed

The following share properties are specific to the NFS protocol. All NFS share specific properties are editable and inheritable. The default value for most of these properties is off unless stated otherwise.

The following are the NFS share property descriptions.

share.nfs

Determines whether a file system is shared over the NFS protocol. Value: on or off

share.nfs.aclok

Determines NFSv2 client access control so that when this property is set on the server, maximum access is given to all clients. If this property is not set, minimum access is given to all clients. Value: on or off

share.nfs.aclfab

Determines whether ACL permissions are fabricated. Value: on or off

share.nfs.anon

Sets UID to the effective user ID of unknown users. By default, unknown users are given the effective UID nobody. If UID is set to -1, access is denied. Value: uid

share.nfs.charset.cp932

Sets NFS character encoding to cp932 (MicroSoft-compatible Japanese). Value: access-list

share.nfs.charset.euc-cn

Sets NFS character encoding to euc-cn (Chinese). Value: access-list

share.nfs.charset.euc-jpms

Sets NFS character encoding to euc-jpms (MicroSoft-compatible Japanese). Value: access-list

share.nfs.charset.euc-kr

Sets NFS character encoding to euc-kr (Korean). Value: access-list

share.nfs.charset.euc-tw

Sets NFS character encoding to euc-tw (Taiwanese). Value: access-list

share.nfs.charset.iso8859-1

Sets NFS character encoding to ISO 8859–1 (Latin 1). Value: access-list

share.nfs.charset.iso8859-2

Sets NFS character encoding to ISO 8859–2 (Latin 2). Value: access-list

share.nfs.charset.iso8859-5

Sets NFS character encoding to ISO 8859–5 (Latin/Cyrillic). Value: access-list

share.nfs.charset.iso8859-6

Sets NFS character encoding to ISO 8859–6 (Arabic). Value: access-list

share.nfs.charset.iso8859-7

Sets NFS character encoding to ISO 8859–7 (Greek). Value: access-list

share.nfs.charset.iso8859-8

Sets NFS character encoding to ISO 8859–8 (Hebrew). Value: access-list

share.nfs.charset.iso8859-9

Sets NFS character encoding to ISO 8859–9 (Turkish). Value: access-list

share.nfs.charset.iso8859-13

Sets NFS character encoding to ISO 8859–13 (Baltic). Value: access-list

share.nfs.charset.iso8859-15

Sets NFS character encoding to ISO 8859–15 (Western European). Value: access-list

share.nfs.charset.koi8-r

Sets NFS character encoding to ISO KOI8–R (Russian/Cyrillic). Value: access-list

share.nfs.charset.shift_jis

Sets NFS character encoding to Shift-JIS (Japanese). Value: access-list

share.nfs.cksum

Not yet implemented. Value: string

share.nfs.index

Determines whether a file is loaded rather than a directory listing that contains this file when the directory is referenced by an NFS URL. Value: filename

share.nfs.log

Enables NFSv2 or NFSv3 server logging for the specified file system. The tag is defined in the /etc/nfs/nfslog.conf file. If no tag is specified, the default values associated with the global tag in the /etc/nfs/nfslog.conf file is used. Value: tag

share.nfs.nosub

Prevents NFSv2 or NFSv3 clients from mounting subdirectories of shared directories. Value: on or off

share.nfs.nosuid

Prevents the NFS client from creating files with setuid or setguid permissions. If enabled, the NFS server silently ignores any attempt to enable the setuid or setgid permissions. Value: on or off

share.nfs.public

Changes the location of the public file handle from root to the shared directory for NFS-enabled browsers and clients. Value: on or off

share.nfs.sec

Sets the default security mode to SYS. The SYS security mode uses AUTH_SYS authentication, which means the user's UID and GID are passed in clear text on the network, unauthenticated by the NFS server. Value: security-mode-list

share.nfs.sec.default.none

Sets the default security mode to none for access-list. Value: access-list

share.nfs.sec.default.ro

Sets the default security mode to read-only access for access-list. Value: access-list

share.nfs.sec.default.root

Sets the default security mode to root access for access-list. By default, no system has root access. Value: access-list

share.nfs.sec.default.root_mapping

Sets the default security mode to root access to a specific UID. By default, no user has root access. Value: UID

share.nfs.sec.default.rw

Sets the default security mode to read-write access for access-list. Value: access-list

share.nfs.sec.default.window

Sets a maximum life time in seconds for the requestor's credential that the NFS server allows for the default security mode. The default value is 30000 seconds (8.3 hours). Value: seconds

share.nfs.sec.dh.none

Sets the Diffie-Hellman (dh) security mode to none for access-list. Value: access-list

share.nfs.sec.dh.ro

Sets the dh security mode to read-only access for access-list. Value: access-list.

share.nfs.sec.dh.root

Sets the dh security mode to root access for access-list. By default, no system has root access. Value: access-list.

share.nfs.sec.dh.root_mapping

Sets the dh security mode to root access to a specific UID. By default, no user has root access. Value: UID

share.nfs.sec.dh.rw

Sets the default security mode to read-write access for access-list. Value: access-list

share.nfs.sec.dh.window

Sets a maximum life time in seconds for the requestor's credential that the NFS server allows for the dh security mode. The default value is 30000 seconds (8.3 hours). Value: seconds

share.nfs.sec.krb5.none

Sets the Kerberos V5 (krb5) security mode to none for access-list. Value: access-list

share.nfs.sec.krb5.ro

Sets the krb5 security mode to read-only access for access-list. Value: access-list

share.nfs.sec.krb5.root

Sets the krb5 security mode to root access for access-list. By default, no system has root access. Value: access-list

share.nfs.sec.krb5.root_mapping

Sets the krb5 security mode to root access to a specific UID. By default, no user has root access. Value: UID

share.nfs.sec.krb5.rw

Sets the krb5 security mode to read-write access for access-list. Value: access-list

share.nfs.sec.krb5.window

This property is not implemented for the krb5 security mode. Value: N/A

share.nfs.sec.krb5i.none

Sets the Kerberos V5 (krb5i) security mode to none. Value: access-list

share.nfs.sec.krb5i.ro

Sets the krb5i security mode to read-only access for access-list. Value: access-list

share.nfs.sec.krb5i.root

Sets the krb5i security mode to root access for access-list. By default, no system has root access. Value: access-list

share.nfs.sec.krb5i.root_mapping

Sets the krb5i security mode to root access to a specific UID. By default, no user has root access. Value: UID

share.nfs.sec.krb5i.rw

Sets the krb5i security mode to read-write access for access-list. Value: access-list

share.nfs.sec.krb5i.window

This property is not available for the krb5i security mode. Value: N/A

share.nfs.sec.krb5p.none

Sets the Kerberos V5 (krb5i) security mode to none for access-list. Value: access-list

share.nfs.sec.krb5p.ro

Sets the krb5p security mode to read-only access for access-list. Value: access-list

share.nfs.sec.krb5p.root

Sets the krb5p security mode to root access for access-list. By default, no system has root access. Value: access-list

share.nfs.sec.krb5p.root_mapping

Sets the krb5p security mode to root access to a specific UID. By default, no user has root access. Value: UID

share.nfs.sec.krb5p.rw

Sets the krb5i security mode to read-write access for access-list. Value: access-list

share.nfs.sec.krb5p.window

This property is not implemented for the krb5p security mode. Value: N/A

share.nfs.sec.none.none

Sets the security mode to none for access-list. Value: access-list

share.nfs.sec.none.ro

Sets the security mode to read-only access for access-list. Value: access-list.

share.nfs.sec.none.root

Sets the security mode to root access for access-list. By default, no system has root access. Value: access-list

share.nfs.sec.none.root_mapping

Sets the security mode to root access to a specific UID. By default, no user has root access. Value: UID

share.nfs.sec.none.rw

Sets the security mode to read-write access for access-list. Value: access-list

share.nfs.sec.none.window

This property is not implemented. Value: seconds

share.nfs.sec.sys.resvport

Sets whether the client requires a reserved port when accessing an AUTH_SYS share. Value: on or off.

share.nfs.sec.sys.none

Sets the SYS security mode to none for access-list. Value: access-list

share.nfs.sec.sys.ro

Sets the SYS security mode to read-only access for access-list. Value: access-list.

share.nfs.sec.sys.root

Sets the SYS security mode to root access for access-list. By default, no system has root access. Value: access-list

share.nfs.sec.sys.root_mapping

Sets the security mode to root access to a specific UID. By default, no user has root access. Value: UID

share.nfs.sec.sys.rw

Sets the security mode to read-write access for access-list. Value: access-list

share.nfs.sec.sys.window

This property is not implemented for the SYS security mode. Value: seconds

The following share properties are specific to the SMB protocol. All SMB share specific properties are editable and inheritable.

Table 2  SMB Share Property Descriptions
Property
Description
Value
share.smb
Determines whether a file system is shared over the SMB protocol. The default value it off.
on or off
share.smb.abe
Enables Access-Based Enumeration (abe) support. The default is off.
share-name
share.smb.ad-container
Enables SMB share to be published in an AD container. The default value is off.
string
share.smb.catia
Enables CATIA translation support. The default value is off.
on or off
share.smb.csc
Enables client side caching support. The default value is disabled.
disabled, manual, auto, or vdo
share.smb.dfsroot
Enables a DFS root support. The default value is off.
on or off
share.smb.encrypt
Enables SMB share level encryption. The default value is off.
on or off
share.smb.guestok
Enables guest access. The default value is off.
on or off
share.smb.none
Sets the SMB share to no access for the specified hosts in access-list.
access-list
share.smb.oplocks
Enables or disables oplocks for its corresponding share.
<empty>, disabled, or enabled
share.smb.ro
Sets the SMB share to read-only access for the specified hosts in access-list.
access-list
share.smb.rw
Sets the SMB share to read-write access for the specified hosts in access-list.
access-list

SUBCOMMANDS

All subcommands that modify state are logged persistently to the pool in their original form.

zfs ?

Displays a help message.

zfs help command | help | property property-name | permission

Displays zfs command usage information. You can display help for a specific command, property, or delegated permission. If you display help for a specific command or property, the command syntax or property value is displayed. Using zfs help without any arguments displays a complete list of zfs commands.

zfs help –l properties

Displays zfs property information, including whether the property value is editable and inheritable, and their possible values.

zfs create [-p] [–o share.nfs=on | share.smb=on –o ... filesystem

Creates a new ZFS file system. The file system is automatically mounted according to the mountpoint property inherited from the parent.

–o property=value

Sets the specified property as if the command zfs set property=value was invoked at the same time the dataset was created. Any editable ZFS property can also be set at creation time. Multiple –o options can be specified. An error results if the same property is specified in multiple –o options.

zfs destroy [share]

The specified file system share is destroyed.

zfs get [-r|-d depth] [–Hp] [–o all | field[,...] [–s source[,...]] all | property[,...] dataset| dataset%namedshare ...

Displays properties for the given datasets. If no datasets are specified, then the command displays properties for all datasets on the system. For each property, the following columns are displayed:

     name      Dataset name
     property  Property name
     value     Property value
     source    Property source. Can either be local, default,
               temporary, inherited, or none (-).

All columns except the RECEIVED column are displayed by default; specify particular or all columns, using the –o option. This command takes a comma-separated list of properties as described in the “Native Properties” and “User Properties” sections.

The special value all can be used to display all properties that apply to the given dataset's type (filesystem, volume, or snapshot).

–r

Recursively display properties for any children.

–d depth

Recursively display any children of the dataset, limiting the recursion to depth. A depth of 1 will display only the dataset and its direct children.

–H

Display output in a form more easily parsed by scripts. Any headers are omitted, and fields are explicitly separated by a single tab instead of an arbitrary amount of space.

–o field

Set of fields to display. One or more of:

name,property,value,received,source

Present multiple fields as a comma-separated list. The default value is:

name,property,value,source

The keyword all specifies all sources.

–s source

A comma-separated list of sources to display. Those properties coming from a source other than those in this list are ignored. Each source must be one of the following:

local,default,inherited,temporary,received,none

The default value is all sources.

–p

Display numbers in parseable (exact) values.

zfs get share [filesystem]

Displays all defined shares or the defined shares for a specified file system.

zfs set share.nfs=on | share.smb=on [desc=description], filesystem | filesystem%share

Defines an NFS or SMB file sharing properties for a ZFS dataset by setting the share.nfs or share.smb property to on.

zfs set [–r] [–c] property=value filesystem|volume|snapshot|share ...

Sets the property to the given value for each file system or file system share or clears the file system share. Only some properties can be edited. See the section for more information on what properties can be set and acceptable values. For more information, see NFS Share Property Descriptions section or the SMB Share Property Descriptions section.

–c

Clears the file system share properties by specifying a share argument in the share=name=value pool/filesystem format.

–r

Recursively applies the effective value of the setting throughout the subtree of child datasets. The effective value may be set or inherited, depending on the property.

zfs share [–u] –o property=value ... filesystem%share
zfs share filesystem|mountpoint|filesystem%share
zfs share –a –r | filesystem

Creates and publishes an NFS or SMB share of a ZFS dataset according to the share properties values.

Sharing a dataset with the NFS or SMB protocol means that the dataset data is available over the network. ZFS datasets that have the share.nfs or share.smb property set are automatically shared when a system is booted.

–u

Creates a share without immediately sharing it.

–o property=value

Shares the ZFS file system with the specified share property value.

–a

Shares all ZFS file systems according to their share property values and to the settings of the share.nfs and share.smb properties.

–r

Applies the share operation recursively to all file systems and shares below the specified file system.

filesystem | filesystem%share

Shares the specified file system or named file system share.

zfs unshare filesystem|mountpoint|filesystem%share
zfs unshare –a | –r |filesystem

Unshares all ZFS datasets that have the share.nfs or share.smb property set.

–a

Unshare all shared ZFS file systems. Invoked automatically as part of the boot process.

–r

Applies the unshare operation recursively to all file systems and shares below the specified file system

filesystem|mountpoint|filesystem%share

Unshare the specified file system. The command can also be given a path to a ZFS file system shared on the system.

Examples

Example 1 Creating an NFS or SMB Share of a ZFS File System

The following examples show how to share ZFS file systems in different ways.

A ZFS file system can be shared when it is created. For example:

# zfs create -o share.nfs=on tank/workspace

You can also apply a share property.

# zfs set share.nfs.nosuid=on tank/workspace

Confirm that the file system is shared. For example:

# grep workspace /etc/dfs/sharetab
/tank/workspace tank_workspace  nfs     nosuid,sec=sys,rw

A descendent file system is automatically shared. For example:

# zfs create tank/workspace/fs1

A file system can be shared after it is created. For example:

# zfs set share.smb=on tank/data
Example 2 Creating a More Complex SMB Share of ZFS File System

The following example shows how to create an SMB that uses ABE (access-enabled enumeration) to determine which users can see files for which they have access. A share called %shareabe is created with the share.smb.abe property set to on. A new share called %sharenoabe is created on the same file system with share.smb.abe set to off.


# zfs share -o share.smb=on -o share.smb.abe=on tank/users/files%shareabe
# zfs share -o share.smb=off tank/users/files%sharenoabe

To allow specific users to see all files in the sharenoabe share and other users to see only files for which they have access in the shareabe share, you would need to modify the share permissions that are accessible in /tank/users/files/.zfs/shares directory.

Example 3 Adding or Changing Share Properties on a ZFS File System

You can share a file system over both NFS and SMB protocols. For example:

# zfs set share.nfs=on tank/data
# zfs set share.smb=on tank/data

You can further add or change share properties. For example:

# zfs set share.nfs.ro=on tank/data
Example 4 Displaying NFS or SMB Share Information

Display NFS or SMB share information.

Confirm that descendent file systems are shared when the parent file system is shared. For example:

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

Exit Status

The following exit values are returned:

0

Successful completion.

1

An error occurred.

2

Invalid command line options were specified.

Attributes

See attributes(7) for descriptions of the following attributes:

ATTRIBUTE TYPE
ATTRIBUTE VALUE
Availability
system/file-system/zfs
Interface Stability
Committed

See Also

chmod(2), chown(2), stat(2), write(2), fsync(3C), dfstab(5), vfstab(5), attributes(7), share(8), share_nfs(8), share_smb(8), unshare(8), zfs(8), zpool(8)

For information about using other ZFS features, see zfs_allow(8), zfs_encrypt(8), and zfs(8), and the Managing ZFS File Systems in Oracle Solaris 11.4.