zfs_share(1m) - share and unshare a ZFS file system
-
System Administration Commands zfs_share(1M) 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 exam- ple, 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 EXAM- PLES section. The listshares pool property is used to determine whether share infor- mation is displayed when using the zfs list command. For more informa- tion, see zpool(1M). 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(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. 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 prop- erties 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 prop- erties are also set. For information about setting SMB share prop- erties, 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 com- mands, 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 com- bination of both styles of matching. The default value for the cas- esensitivity 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.3. normalization = none | formC | formD | formKC | formKD Indicates whether the file system should perform a unicode normal- ization 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 prop- erty is automatically set to on. The default value of the normal- ization 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 can- not be changed after the file system is created. Specific NFS or SMB Properties In addition to native properties and user properties, you can also des- ignate 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 Yes string provides a user-defined description and can be set on the file system or a share. The default value is no description. share.fs Read-only property that No filesystem identifies the file sys- tem name for a share. share.name Read-only property that No share-name identifies the share name for a share. share.auto Editable property that No on or off enables automatic shar- ing and can only be set on the file system to be shared. share.path Editable property that No mountpoint-relative-path sets the share path on a share. share.point Read-only property that No path identifies the absolute path of an existing share that is derived from the current value of the share.path prop- erty relative to the dataset mount point. share.protocols Read-only property that No protocol-list identifies the protocols established for the file system or the share. share.state Read-only property that No unshared, shared, or failed identifies the current state of the share. 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.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 Japa- nese). 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.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 sys- tem. 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 Helman (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 on or off system is shared over the SMB protocol. The default value it off. share.smb.ad-container Enables SMB share to be string published in an AD con- tainer. The default value is off. share.smb.abe Enables Access-Based Enu- share-name meration (abe) support. The default is off. share.smb.csc Enables client side disabled, manual, auto, or vdo caching support. The default value is dis- abled. share.smb.catia Enables CATIA translation on or off support. The default value is off. share.smb.dfsroot Enables a DFS root sup- on or off port. The default value is off. share.smb.guestok Enables guest access. The on or off default value is off. share.smb.ro Sets the SMB share to access-list read-only. You can spec- ify on, off, or list of names (access-list). The default value is off. share.smb.rw Sets the SMB share to access-list read-write. You can spec- ify on, off, or list of names (access-list). The default value is on. share.smb.none Sets the SMB share to off access-list for the specified users in the 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 prop- erty=value was invoked at the same time the dataset was cre- ated. 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 com- mand 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 snap- shot). -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] property=value filesystem|volume|snapshot|share ... Sets the property to the given value for each file system or 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. -r Recursively applies the effective value of the setting through- out 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 accord- ing 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 prop- erties. -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 share- abe 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 exam- ple: # 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(5) for descriptions of the following attributes: +-----------------------------+-----------------------------+ | ATTRIBUTE TYPE | ATTRIBUTE VALUE | +-----------------------------+-----------------------------+ |Availability |system/file-system/zfs | +-----------------------------+-----------------------------+ |Interface Stability |Committed | +-----------------------------+-----------------------------+ SEE ALSO share(1M), share_nfs(1M), share_smb(1M), unshare(1M), zfs(1M), zpool(1M), chmod(2), chown(2), stat(2), write(2), fsync(3C), dfstab(4), vfstab(4), attributes(5) For information about using other ZFS features, see zfs_allow(1M), zfs_encrypt(1M), and zfs(1M), and the Managing ZFS File Systems in Ora- cle Solaris 11.3. SunOS 5.11 23 Jul 2015 zfs_share(1M)
© Lightnetics 2024