zfs_share

- share and unshare a ZFS file system

Synopsis

zfs [-?]

zfs help subcommand | help | property property-name | permission

zfs create [-p] [-o sharenfs=on | sharesmb=on] [-o property ... filesystem

zfs set share=name=sharename,path=pathname,[desc=description],
prot=smb | nfs[,property=value[,...]] filesystem

zfs  set [-r] sharenfs=on | off filesystem

zfs  set [-r] sharesmb=on | off filesystem

zfs set -c share=name=sharename filesystem

zfs get [-r] sharenfs filesystem ...

zfs  get [-r] sharesmb filesystem ...

zfs  get  [-r] share filesystem ...

zfs share -a | filesystem

zfs unshare -a filesystem|mountpoint

Description

The zfs set share command is used to create an NFS or SMB share within a ZFS storage pool, as described in zpool(1M). Setting the sharenfs or the sharesmb property to on publishes a share. You can also publish and unpublish an NFS share of a ZFS dataset by using the zfs share and zfs unshare commands.

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.

The following native NFS and SMB properties can be used to change the behavior of a ZFS share.

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 umounted and remounted. See mount(1M) 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.

sharenfs=on | off

Controls whether a ZFS dataset is published as an NFS share. You can also publish and unpublish an 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 share command.

When the sharenfs 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 share 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.

sharesmb=on | off

Controls whether a ZFS dataset is published as an SMB share. You can also publish and unpublish an 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 share command.

Because SMB shares requires a resource name, a unique resource name is constructed from the dataset name. The constructed name is a copy of the dataset name except that the characters in the dataset name that would be illegal in the resource name are replaced with underscore (_) characters. A pseudo property “name” is also supported that allows you to replace the data set name with a specified name. The specified name is then used to replace the prefix dataset in the case of inheritance. For example, if the dataset data/home/john is set to name=john, then data/home/john has a resource name of john. If john has a child dataset of data/home/john/backups, it has a resource name of john_backups.

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 sharesmb property is changed, the dataset share and any children inheriting the property are re-published with any new options that have been set with the zfs set share command if the property was previously set to off, or if the shares were published before the property was changed. If the new property value is off, the dataset shares are unpublished.

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 Oracle Solaris Administration: ZFS File Systems.

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.

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 create [-p] [-o sharenfs=on | sharesmb=on -oproperty=value] ... 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 get [-r] share [filesystem]

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

zfs set share=name=sharename,path=pathname,[desc=description],prot=smb | nfs[,property=value[,...]] filesystem

Defines an NFS or SMB file sharing properties for a ZFS dataset. After the NFS or SMB file-sharing properties are established, you can publish the NFS or SMB share of a ZFS file system by setting the sharenfs or sharesmb property to on.

The following share properties are required:

share=name=sharename

Identifies an NFS or SMB share name. Maximum length of a share name is 80 characters.

path=pathname

Identifies the physical path of the dataset to be shared or a subdirectory within the dataset to be shared.

prot=smb | nfs

Identifies the NFS or SMB file sharing protocol.

The following share properties are optional:

desc=description

Identifies a text string that describes the share resource. Spaces or commas in the description must be enclosed in quotation marks (“ “).

ro= | rw=

Identifies whether the share is available as read/write or read-only to all clients. You can also specify a colon-separated list that includes hostnames, IP addresses, or a netgroup.

root=

Identifies a root user from a specified host or list of hosts that have root access. By default, no host has root access.

sec=

Identifies an NFS server security mode, such as sys, dh, krb5, and so on. For supported security mode information, see nfssec(5).

The following optional NFS properties must be specified after prot=nfs but before any sec properties:

anon=TYPE_USER
nosub=[true|false]
nosuid=[true|false]
aclok=[true|false]
public=[true|false]
index=filename
log=TYPE_LOGTAG
cksum=TYPE_STRINGSET

The following optional SMB properties must be specified after prot=smb:

ad-container=string
abe=[true|false]
csc=[disabled|manual|auto|vdo]
catia=[true|false]
guestok=[true|false]
ro=access-list
rw=access-list
none=access-list

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

zfs set [-r] property=value filesystem|volume|snapshot ...

Sets the property to the given value for each dataset. Only some properties can be edited. See the “Properties” section for more information on what properties can be set and acceptable values.

-r

Recursively apply 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 set -c share=name=sharename filesystem

Removes a file system share. The -c option distinguishes this subcommand from the zfs set share command described above.

zfs share -a | dataset

Publishes an NFS or SMB share of a ZFS dataset according to the share properties values and if sharenfs or sharesmb property set.

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

-a

Shares all ZFS datasets according to their share property values and to the settings of the sharenfs and sharesmb properties.

dataset

Shares the specified dataset according to the share property values and to the settings of the sharenfs and sharesmb properties.

zfs unshare -a | dataset|mountpoint

Unshares all ZFS datasets that have the sharenfs or sharesmb property set.

-a

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

dataset|mountpoint

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

Examples

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

Creating an NFS or SMB share of a ZFS file system is a two-step process:

1. Create the share by using the zfs set share command to identify the NFS or SMB share properties.

   To create an NFS share:

   # zfs create -o mountpoint=/data tank/data
   # zfs set share=name=data,path=/data,prot=nfs tank/data

   To create an SMB share:

   # zfs set share=name=fs,path=/fs,prot=smb,ro=@10-132-60-234 \
   tank/fs

2. Publish the share by setting the sharenfs or sharesmb property. Use commands such as:

   # zfs set sharenfs=on tank/data
   # zfs set sharesmb=on tank/fs

Example 2 Displaying NFS or SMB Share Information

Display NFS or SMB share information:

# zfs get share
NAME                      PROPERTY  VALUE  SOURCE
tank/data                 share     name=data,path=/data,prot=nfs  local
tank/fs                   share     name=fs,path=/fs,prot=smb,ro... local

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

Change a share by adding a new option, such as read-only for hostA, as in the following:

# zfs set share=name=data,prot=nfs,ro=hostA tank/data

Example 4 Removing a NFS or SMB Share of a ZFS File System

Remove a share by using zfs set -c command:

# zfs set -c share=name=fs tank/fs
share 'fs' was removed.

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(5) for descriptions of the following attributes:

See Also

chmod(1), chown(1), pktool(1), ssh(1), mount(1M), shadowd(1M), share(1M), share_nfs(1M), share_smb(1M), unshare(1M), zfs(1M), zfs_allow(1M), zfs_encrypt(1M), zonecfg(1M), zpool(1M), chmod(2), chown(2), stat(2), write(2), fsync(3C), dfstab(4), vfstab(4), attributes(5)

See the gzip(1) man page, which is not part of the SunOS man page collection.

For information about using other ZFS features, see the Oracle Solaris Administration: ZFS File Systems.