JavaScript is required to for searching.
Skip Navigation Links
Exit Print View
Oracle Solaris 11.1 Administration: ZFS File Systems     Oracle Solaris 11.1 Information Library
search filter icon
search icon

Document Information

Preface

1.  Oracle Solaris ZFS File System (Introduction)

2.  Getting Started With Oracle Solaris ZFS

3.  Managing Oracle Solaris ZFS Storage Pools

4.  Managing ZFS Root Pool Components

5.  Managing Oracle Solaris ZFS File Systems

Managing ZFS File Systems (Overview)

Creating, Destroying, and Renaming ZFS File Systems

Creating a ZFS File System

Destroying a ZFS File System

Renaming a ZFS File System

Introducing ZFS Properties

ZFS Read-Only Native Properties

The used Property

Settable ZFS Native Properties

The canmount Property

The casesensitivity Property

The copies Property

The dedup Property

The encryption Property

The recordsize Property

The share.smb Property

The volsize Property

ZFS User Properties

Querying ZFS File System Information

Listing Basic ZFS Information

Creating Complex ZFS Queries

Managing ZFS Properties

Setting ZFS Properties

Inheriting ZFS Properties

Querying ZFS Properties

Querying ZFS Properties for Scripting

Mounting ZFS File Systems

Managing ZFS Mount Points

Automatic Mount Points

Legacy Mount Points

Mounting ZFS File Systems

Using Temporary Mount Properties

Unmounting ZFS File Systems

Sharing and Unsharing ZFS File Systems

Legacy ZFS Sharing Syntax

New ZFS Sharing Syntax

ZFS Sharing with Per-Property Inheritance

ZFS Sharing Inheritance in Older Pools

ZFS Named Shares

ZFS Automatic Shares

Displaying ZFS Share Information

Changing a ZFS Share Property Values

Publishing and Unpublishing ZFS Shares

Removing a ZFS Share

ZFS File Sharing Within a Non-Global Zone

ZFS Sharing Migration/Transition Issues

Troubleshooting ZFS File System Sharing Problems

Setting ZFS Quotas and Reservations

Setting Quotas on ZFS File Systems

Setting User and Group Quotas on a ZFS File System

Setting Reservations on ZFS File Systems

Encrypting ZFS File Systems

Changing an Encrypted ZFS File System's Keys

Managing ZFS Encryption Keys

Delegating ZFS Key Operation Permissions

Mounting an Encrypted ZFS File System

Upgrading Encrypted ZFS File Systems

Interactions Between ZFS Compression, Deduplication, and Encryption Properties

Examples of Encrypting ZFS File Systems

Migrating ZFS File Systems

How to Migrate a File System to a ZFS File System

Troubleshooting ZFS File System Migrations

Upgrading ZFS File Systems

6.  Working With Oracle Solaris ZFS Snapshots and Clones

7.  Using ACLs and Attributes to Protect Oracle Solaris ZFS Files

8.  Oracle Solaris ZFS Delegated Administration

9.  Oracle Solaris ZFS Advanced Topics

10.  Oracle Solaris ZFS Troubleshooting and Pool Recovery

11.  Archiving Snapshots and Root Pool Recovery

12.  Recommended Oracle Solaris ZFS Practices

A.  Oracle Solaris ZFS Version Descriptions

Index

Introducing ZFS Properties

Properties are the main mechanism that you use to control the behavior of file systems, volumes, snapshots, and clones. Unless stated otherwise, the properties defined in this section apply to all the dataset types.

Properties are divided into two types, native properties and user-defined properties. Native properties either provide internal statistics or control ZFS file system behavior. In addition, native properties are either settable or read-only. User properties have no effect on ZFS file system behavior, but you can use them to annotate datasets in a way that is meaningful in your environment. For more information about user properties, see ZFS User Properties.

Most settable properties are also inheritable. An inheritable property is a property that, when set on a parent file system, is propagated down to all of its descendents.

All inheritable properties have an associated source that indicates how a property was obtained. The source of a property can have the following values:

local

Indicates that the property was explicitly set on the dataset by using the zfs set command as described in Setting ZFS Properties.

inherited from dataset-name

Indicates that the property was inherited from the named ancestor.

default

Indicates that the property value was not inherited or set locally. This source is a result of no ancestor having the property set as source local.

The following table identifies both read-only and settable native ZFS file system properties. Read-only native properties are identified as such. All other native properties listed in this table are settable. For information about user properties, see ZFS User Properties.

Table 5-1 ZFS Native Property Descriptions

Property Name
Type
Default Value
Description
aclinherit
String
secure
Controls how ACL entries are inherited when files and directories are created. The values are discard, noallow, secure, and passthrough. For a description of these values, see ACL Properties.
aclmode
String
groupmask
Controls how an ACL entry is modified during a chmod operation. The values are discard, groupmask, and passthrough. For a description of these values, see ACL Properties.
atime
Boolean
on
Controls whether the access time for files is updated when they are read. Turning this property off avoids producing write traffic when reading files and can result in significant performance gains, though it might confuse mailers and similar utilities.
available
Number
N/A
Read-only property that identifies the amount of disk space available to a file system and all its children, assuming no other activity in the pool. Because disk space is shared within a pool, available space can be limited by various factors including physical pool size, quotas, reservations, and other datasets within the pool.

The property abbreviation is avail.

For more information about disk space accounting, see ZFS Disk Space Accounting.

canmount
Boolean
on
Controls whether a file system can be mounted with the zfs mount command. This property can be set on any file system, and the property itself is not inheritable. However, when this property is set to off, a mount point can be inherited to descendent file systems, but the file system itself is never mounted.

When the noauto option is set, a file system can only be mounted and unmounted explicitly. The file system is not mounted automatically when the file system is created or imported, nor is it mounted by the zfs mount-a command or unmounted by the zfs unmount-a command.

For more information, see The canmount Property.

casesensitivity
String
mixed
This property indicates whether the file name matching algorithm used by the file system should be casesensitive, caseinsensitive, or allow a combination of both styles of matching (mixed). Traditionally, UNIX and POSIX file systems have case-sensitive file names.

The mixed value for this property indicates 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 Oracle Solaris SMB server product. For more information about using the mixed value, see The casesensitivity Property.

Regardless of the casesensitivity property setting, the file system preserves the case of the name specified to create a file. This property cannot be changed after the file system is created.

checksum
String
on
Controls the checksum used to verify data integrity. The default value is on, which automatically selects an appropriate algorithm, currently fletcher4. The values are on, off, fletcher2, fletcher4, sha256, and sha256+mac. A value of off disables integrity checking on user data. A value of off is not recommended.
compression
String
off
Enables or disables compression for a dataset. The values are on, off, lzjb, gzip, and gzip-N. Currently, setting this property to lzjb, gzip, or gzip-N has the same effect as setting this property to on. Enabling compression on a file system with existing data only compresses new data. Existing data remains uncompressed.

The property abbreviation is compress.

compressratio
Number
N/A
Read-only property that identifies the compression ratio achieved for a dataset, expressed as a multiplier. Compression can be enabled by the zfs set compression=on dataset command.

The value is calculated from the logical size of all files and the amount of referenced physical data. It includes explicit savings through the use of the compression property.

copies
Number
1
Sets the number of copies of user data per file system. Available values are 1, 2, or 3. These copies are in addition to any pool-level redundancy. Disk space used by multiple copies of user data is charged to the corresponding file and dataset, and counts against quotas and reservations. In addition, the used property is updated when multiple copies are enabled. Consider setting this property when the file system is created because changing this property on an existing file system only affects newly written data.
creation
String
N/A
Read-only property that identifies the date and time that a dataset was created.
dedup
String
off
Controls the ability to remove duplicate data in a ZFS file system. Possible values are on, off, verify, and sha256[,verify]. The default checksum for deduplication is sha256.

For more information, see The dedup Property.

devices
Boolean
on
Controls whether device files in a file system can be opened.
encryption
Boolean
off
Controls whether a file system is encrypted. An encrypted file system means that data is encoded and a key is needed by the file system owner to access the data.
exec
Boolean
on
Controls whether programs in a file system are allowed to be executed. Also, when set to off, mmap(2) calls with PROT_EXEC are disallowed.
keychangedate
String
none
Identifies the date of the last wrapping key change from a zfs key -c operation for the specified file system. If no key change operation has occurred, the value of this read-only property is the same as the file system's creation date.
keysource
String
none
Identifies the format and location of the key that wraps the file system keys. The valid property values are raw, hex, passphrase,prompt, or file. The key must be present when the file system is created, mounted, or loaded by using the zfs key -l command. If encryption is enabled for a new file system, the default keysource is passphrase,prompt.
keystatus
String
none
Read-only property that identifies the file system's encryption key status. The availability of a file system's key is indicated by available or unavailable. For file systems that do not have encryption enabled, none is displayed.
logbias
String
latency
Controls how ZFS optimizes synchronous requests for this file system. If logbias is set to latency, ZFS uses the pool's separate log devices, if any, to handle the requests at low latency. If logbias is set to throughput, ZFS does not use the pool's separate log devices. Instead, ZFS optimizes synchronous operations for global pool throughput and efficient use of resources. The default value is latency.
mlslabel
String
None
See the multilevel property for a description of the behavior of the mlslabel property on multilevel file systems. The following mlslabel description applies to non-multilevel file systems.

Provides a sensitivity label that determines if a file system can be mounted in a Trusted Extensions zone. If the labeled file system matches the labeled zone, the file system can be mounted and accessed from the labeled zone. The default value is none. This property can only be modified when Trusted Extensions is enabled and only with the appropriate privilege.

mounted
Boolean
N/A
Read-only property that indicates whether a file system, clone, or snapshot is currently mounted. This property does not apply to volumes. The value can be either yes or no.
mountpoint
String
N/A
Controls the mount point used for this file system. When the mountpoint property is changed for a file system, the file system and any descendents that inherit the mount point are unmounted. If the new value is legacy, then they remain unmounted. Otherwise, they are automatically remounted in the new location if the property was previously legacy or none, or if they were mounted before the property was changed. In addition, any shared file systems are unshared and shared in the new location.

For more information about using this property, see Managing ZFS Mount Points.

multilevel
Boolean
off
This property can only be used on a system with Trusted Extensions enabled. The default value is off.

Objects in a multilevel file system are individually labeled with an explicit sensitivity label attribute that is automatically generated. Objects can be relabeled in place by changing this label attribute, by using the setlabel or setflabel interfaces.

A root file system, an Oracle Solaris Zone file system, or a file system that contains packaged Solaris code should not be multilevel.

There are differences in the mlslabel property on a multilevel file system. The mlslabel value defines the highest possible label for objects in the file system. An attempt to create a file at (or relabel a file to) a label higher than the mlslabel value is not allowed. Mount policy based on the mlslabel value does not apply to a multilevel file system.

For a multilevel file system, the mlslabel property can be set explicitly when the file system is created. Otherwise, a default mlslabel property of ADMIN_HIGH is automatically created. After creating a multilevel file system, the mlslabel property can be changed, but it cannot be set to a lower label, set to none, nor can it be removed.

primarycache
String
all
Controls what is cached in the primary cache (ARC). Possible values are all, none, and metadata. If set to all, both user data and metadata are cached. If set to none, neither user data nor metadata is cached. If set to metadata, only metadata is cached. When these properties are set on existing file systems, only new I/O is cache based on the values of these properties. Some database environments might benefit from not caching user data. You must determine if setting cache properties is appropriate for your environment.
nbmand
Boolean
off
Controls whether the file system should be mounted with nbmand (Non-blocking mandatory) locks. This property is for SMB clients only. Changes to this property only take effect when the file system is unmounted and remounted.
normalization
String
None
This property indicates whether a 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.
origin
String
N/A
Read-only property for cloned file systems or volumes that identifies the snapshot from which the clone was created. The origin cannot be destroyed (even with the -r or -f option) as long as a clone exists.

Non-cloned file systems have an origin of none.

quota
Number (or none)
none
Limits the amount of disk space a file system and its descendents can consume. This property enforces a hard limit on the amount of disk space used, including all space consumed by descendents, such as file systems and snapshots. Setting a quota on a descendent of a file system that already has a quota does not override the ancestor's quota, but rather imposes an additional limit. Quotas cannot be set on volumes, as the volsize property acts as an implicit quota.

For information about setting quotas, see Setting Quotas on ZFS File Systems.

rekeydate
String
N/A
Read-only property that indicates the date of the last data encryption key change from a zfs key -K or zfs clone -K operation on this file system. If no rekey operation has been performed, the value of this property is the same as the creation date.
readonly
Boolean
off
Controls whether a dataset can be modified. When set to on, no modifications can be made.

The property abbreviation is rdonly.

recordsize
Number
128K
Specifies a suggested block size for files in a file system.

The property abbreviation is recsize. For a detailed description, see The recordsize Property.

referenced
Number
N/A
Read-only property that identifies the amount of data accessible by a dataset, which might or might not be shared with other datasets in the pool.

When a snapshot or clone is created, it initially references the same amount of disk space as the file system or snapshot it was created from, because its contents are identical.

The property abbreviation is refer.

refquota
Number (or none)
none
Sets the amount of disk space that a dataset can consume. This property enforces a hard limit on the amount of space used. This hard limit does not include disk space used by descendents, such as snapshots and clones.
refreservation
Number (or none)
none
Sets the minimum amount of disk space that is guaranteed to a dataset, not including descendents, such as snapshots and clones. When the amount of disk space used is below this value, the dataset is treated as if it were taking up the amount of space specified by refreservation. The refreservation reservation is accounted for in the parent dataset's disk space used, and counts against the parent dataset's quotas and reservations.

If refreservation is set, a snapshot is only allowed if enough free pool space is available outside of this reservation to accommodate the current number of referenced bytes in the dataset.

The property abbreviation is refreserv.

reservation
Number (or none)
none
Sets the minimum amount of disk space guaranteed to a file system and its descendents. When the amount of disk space used is below this value, the file system is treated as if it were using the amount of space specified by its reservation. Reservations are accounted for in the parent file system's disk space used, and count against the parent file system's quotas and reservations.

The property abbreviation is reserv.

For more information, see Setting Reservations on ZFS File Systems.

rstchown
Boolean
on
Indicates whether the file system owner can grant file ownership changes. The default is to restrict chown operations. When rstchown is set to off, the user has the PRIV_FILE_CHOWN_SELF privilege for chown operations.
secondarycache
String
all
Controls what is cached in the secondary cache (L2ARC). Possible values are all, none, and metadata. If set to all, both user data and metadata are cached. If set to none, neither user data nor metadata is cached. If set to metadata, only metadata is cached.
setuid
Boolean
on
Controls whether the setuid bit is honored in a file system.
shadow
String
None
Identifies a ZFS file system as a shadow of the file system described by the URI. Data is migrated to a shadow file system with this property set from the file system identified by the URI. The file system to be migrated must be read-only for a complete migration.
share.nfs
String
off
Controls whether an NFS share of a ZFS file system is created and published and what options are used. You can also publish and unpublish an NFS share by using the zfs share and zfs unshare commands. Using the zfs share command to publish an NFS share requires that an NFS share property is also set. For information about setting NFS share properties, see Sharing and Unsharing ZFS File Systems.

For more information about sharing ZFS file systems, see Sharing and Unsharing ZFS File Systems.

share.smb
String
off
Controls whether a SMB share of a ZFS file system is created and published and what options are used. You can also publish and unpublish an SMB share by using the zfs share and zfs unshare commands. Using the zfs share command to publish an SMB share require that an SMB share property is also set. For information about setting SMB share properties, see Sharing and Unsharing ZFS File Systems.
snapdir
String
hidden
Controls whether the .zfs directory is hidden or visible in the root of the file system. For more information about using snapshots, see Overview of ZFS Snapshots.
sync
String
standard
Determines the synchronous behavior of a file system's transactions. Possible values are:
  • standard, the default value, which means synchronous file system transactions, such as fsync, O_DSYNC, O_SYNC, and so on, are written to the intent log.

  • always, ensures that every file system transaction is written and flushed to stable storage by a returning system call. This value has a significant performance penalty.

  • disabled, means that synchronous requests are disabled. File system transactions are only committed to stable storage on the next transaction group commit, which might be after many seconds. This value gives the best performance, with no risk of corrupting the pool.


    Caution

    Caution - This disabled value is very dangerous because ZFS is ignoring the synchronous transaction demands of applications, such as databases or NFS operations. Setting this value on the currently active root or /var file system might result in unexpected behavior, application data loss, or increased vulnerability to replay attacks. You should only use this value if you fully understand all the associated risks.


type
String
N/A
Read-only property that identifies the dataset type as filesystem (file system or clone), volume, or snapshot.
used
Number
N/A
Read-only property that identifies the amount of disk space consumed by a dataset and all its descendents.

For a detailed description, see The used Property.

usedbychildren
Number
off
Read-only property that identifies the amount of disk space that is used by children of this dataset, which would be freed if all the dataset's children were destroyed. The property abbreviation is usedchild.
usedbydataset
Number
off
Read-only property that identifies the amount of disk space that is used by a dataset itself, which would be freed if the dataset was destroyed, after first destroying any snapshots and removing any refreservation reservations. The property abbreviation is usedds.
usedbyrefreservation
Number
off
Read-only property that identifies the amount of disk space that is used by a refreservation set on a dataset, which would be freed if the refreservation was removed. The property abbreviation is usedrefreserv.
usedbysnapshots
Number
off
Read-only property that identifies the amount of disk space that is consumed by snapshots of a dataset. In particular, it is the amount of disk space that would be freed if all of this dataset's snapshots were destroyed. Note that this value is not simply the sum of the snapshots' used properties, because space can be shared by multiple snapshots. The property abbreviation is usedsnap.
version
Number
N/A
Identifies the on-disk version of a file system, which is independent of the pool version. This property can only be set to a later version that is available from the supported software release. For more information, see the zfs upgrade command.
utf8only
Boolean
Off
This property indicates whether a 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.
volsize
Number
N/A
For volumes, specifies the logical size of the volume.

For a detailed description, see The volsize Property.

volblocksize
Number
8 KB
For volumes, specifies the block size of the volume. The block size cannot be changed after the volume has been written, so set the block size at volume creation time. The default block size for volumes is 8 KB. Any power of 2 from 512 bytes to 128 KB is valid.

The property abbreviation is volblock.

vscan
Boolean
Off
Controls whether regular files should be scanned for viruses when a file is opened and closed. In addition to enabling this property, a virus scanning service must also be enabled for virus scanning to occur if you have third-party virus scanning software. The default value is off.
zoned
Boolean
N/A
Indicates whether a file system has been added to a non-global zone. If this property is set, then the mount point is not honored in the global zone, and ZFS cannot mount such a file system when requested. When a zone is first installed, this property is set for any added file systems.

For more information about using ZFS with zones installed, see Using ZFS on a Solaris System With Zones Installed.

xattr
Boolean
on
Indicates whether extended attributes are enabled (on) or disabled (off) for this file system.

ZFS Read-Only Native Properties

Read-only native properties can be retrieved but not set. Read-only native properties are not inherited. Some native properties are specific to a particular type of dataset. In such cases, the dataset type is mentioned in the description in Table 5-1.

The read-only native properties are listed here and described in Table 5-1.

For more information about disk space accounting, including the used, referenced, and available properties, see ZFS Disk Space Accounting.

The used Property

The used property is a read-only property that identifies the amount of disk space consumed by this dataset and all its descendents. This value is checked against the dataset's quota and reservation. The disk space used does not include the dataset's reservation, but does consider the reservation of any descendent datasets. The amount of disk space that a dataset consumes from its parent, as well as the amount of disk space that is freed if the dataset is recursively destroyed, is the greater of its space used and its reservation.

When snapshots are created, their disk space is initially shared between the snapshot and the file system, and possibly with previous snapshots. As the file system changes, disk space that was previously shared becomes unique to the snapshot and is counted in the snapshot's space used. The disk space that is used by a snapshot accounts for its unique data. Additionally, deleting snapshots can increase the amount of disk space unique to (and used by) other snapshots. For more information about snapshots and space issues, see Out of Space Behavior.

The amount of disk space used, available, and referenced does not include pending changes. Pending changes are generally accounted for within a few seconds. Committing a change to a disk using the fsync(3c) or O_SYNC function does not necessarily guarantee that the disk space usage information will be updated immediately.

The usedbychildren, usedbydataset, usedbyrefreservation, and usedbysnapshots property information can be displayed with the zfs list -o space command. These properties identify the used property into disk space that is consumed by descendents. For more information, see Table 5-1.

Settable ZFS Native Properties

Settable native properties are properties whose values can be both retrieved and set. Settable native properties are set by using the zfs set command, as described in Setting ZFS Properties or by using the zfs create command as described in Creating a ZFS File System. With the exceptions of quotas and reservations, settable native properties are inherited. For more information about quotas and reservations, see Setting ZFS Quotas and Reservations.

Some settable native properties are specific to a particular type of dataset. In such cases, the dataset type is mentioned in the description in Table 5-1. If not specifically mentioned, a property applies to all dataset types: file systems, volumes, clones, and snapshots.

The settable properties are listed here and described in Table 5-1.

The canmount Property

If the canmount property is set to off, the file system cannot be mounted by using the zfs mount or zfs mount -a commands. Setting this property to off is similar to setting the mountpoint property to none, except that the file system still has a normal mountpoint property that can be inherited. For example, you can set this property to off, establish inheritable properties for descendent file systems, but the parent file system itself is never mounted nor is it accessible to users. In this case, the parent file system is serving as a container so that you can set properties on the container, but the container itself is never accessible.

In the following example, userpool is created, and its canmount property is set to off. Mount points for descendent user file systems are set to one common mount point, /export/home. Properties that are set on the parent file system are inherited by descendent file systems, but the parent file system itself is never mounted.

# zpool create userpool mirror c0t5d0 c1t6d0
# zfs set canmount=off userpool
# zfs set mountpoint=/export/home userpool
# zfs set compression=on userpool
# zfs create userpool/user1
# zfs create userpool/user2
# zfs mount
userpool/user1                  /export/home/user1
userpool/user2                  /export/home/user2

Setting the canmount property to noauto means that the file system can only be mounted explicitly, not automatically.

The casesensitivity Property

This property indicates whether the file name matching algorithm used by the file system should be casesensitive, caseinsensitive, or allow a combination of both styles of matching (mixed).

When a case-insensitive matching request is made of a mixed sensitivity file system, the behavior is generally the same as would be expected of a purely case-insensitive file system. The difference is that a mixed sensitivity file system might contain directories with multiple names that are unique from a case-sensitive perspective, but not unique from the case-insensitive perspective.

For example, a directory might contain files foo, Foo, and FOO. If a request is made to case-insensitively match any of the possible forms of foo, (for example foo, FOO, FoO, fOo, and so on) one of the three existing files is chosen as the match by the matching algorithm. Exactly which file the algorithm chooses as a match is not guaranteed, but what is guaranteed is that the same file is chosen as a match for any of the forms of foo. The file chosen as a case-insensitive match for foo, FOO, foO, Foo, and so on, is always the same, so long as the directory remains unchanged.

The utf8only, normalization, and casesensitivity properties also provide new permissions that can be assigned to non-privileged users by using ZFS delegated administration. For more information, see Delegating ZFS Permissions.

The copies Property

As a reliability feature, ZFS file system metadata is automatically stored multiple times across different disks, if possible. This feature is known as ditto blocks.

In this release, you can also store multiple copies of user data is also stored per file system by using the zfs set copies command. For example:

# zfs set copies=2 users/home
# zfs get copies users/home
NAME        PROPERTY  VALUE       SOURCE
users/home  copies    2           local

Available values are 1, 2, or 3. The default value is 1. These copies are in addition to any pool-level redundancy, such as in a mirrored or RAID-Z configuration.

The benefits of storing multiple copies of ZFS user data are as follows:


Note - Depending on the allocation of the ditto blocks in the storage pool, multiple copies might be placed on a single disk. A subsequent full disk failure might cause all ditto blocks to be unavailable.


You might consider using ditto blocks when you accidentally create a non-redundant pool and when you need to set data retention policies.

The dedup Property

The dedup property controls whether duplicate data is removed from a file system. If a file system has the dedup property enabled, duplicate data blocks are removed synchronously. The result is that only unique data is stored and common components are shared between files.

Do not enable the dedup property on file systems that reside on production systems until you review the following considerations:

  1. Determine if your data would benefit from deduplication space savings. If your data is not dedup-able, then there's not point in enabling dedup. For example:

    # zdb -S tank
    Simulated DDT histogram:
    bucket              allocated                       referenced          
    ______   ______________________________   ______________________________
    refcnt   blocks   LSIZE   PSIZE   DSIZE   blocks   LSIZE   PSIZE   DSIZE
    ------   ------   -----   -----   -----   ------   -----   -----   -----
         1    2.27M    239G    188G    194G    2.27M    239G    188G    194G
         2     327K   34.3G   27.8G   28.1G     698K   73.3G   59.2G   59.9G
         4    30.1K   2.91G   2.10G   2.11G     152K   14.9G   10.6G   10.6G
         8    7.73K    691M    529M    529M    74.5K   6.25G   4.79G   4.80G
        16      673   43.7M   25.8M   25.9M    13.1K    822M    492M    494M
        32      197   12.3M   7.02M   7.03M    7.66K    480M    269M    270M
        64       47   1.27M    626K    626K    3.86K    103M   51.2M   51.2M
       128       22    908K    250K    251K    3.71K    150M   40.3M   40.3M
       256        7    302K     48K   53.7K    2.27K   88.6M   17.3M   19.5M
       512        4    131K   7.50K   7.75K    2.74K    102M   5.62M   5.79M
        2K        1      2K      2K      2K    3.23K   6.47M   6.47M   6.47M
        8K        1    128K      5K      5K    13.9K   1.74G   69.5M   69.5M
     Total    2.63M    277G    218G    225G    3.22M    337G    263G    270G
    
    dedup = 1.20, compress = 1.28, copies = 1.03, dedup * compress / copies = 1.50

    If the estimated dedup ratio is greater than 2, then you might see dedup space savings.

    In the above example, the dedup ratio is less than 2, so enabling dedup is not recommended.

  2. Make sure your system has enough memory to support dedup.

    • Each in-core dedup table entry is approximately 320 bytes

    • Multiply the number of allocated blocks times 320. For example:

      in-core DDT size = 2.63M x 320 = 841.60M
  3. Dedup performance is best when the deduplication table fits into memory. If the dedup table has to be written to disk, then performance will decrease. For example, removing a large file system with dedup enabled will severely decrease system performance if the system doesn't meet the memory requirements described above.

When dedup is enabled, the dedup checksum algorithm overrides the checksum property. Setting the property value to verify is equivalent to specifying sha256,verify. If the property is set to verify and two blocks have the same signature, ZFS does a byte-by-byte comparison with the existing block to ensure that the contents are identical.

This property can be enabled per file system. For example:

# zfs set dedup=on tank/home

You can use the zfs get command to determine if the dedup property is set.

Although deduplication is set as a file system property, the scope is pool-wide. For example, you can identify the deduplication ratio. For example:

# zpool list tank
NAME    SIZE  ALLOC   FREE    CAP  DEDUP  HEALTH  ALTROOT
rpool   136G  55.2G  80.8G    40%  2.30x  ONLINE  -

The DEDUP column indicates how much deduplication has occurred. If the dedup property is not enabled on any file system or if the dedup property was just enabled on the file system, the DEDUP ratio is 1.00x.

You can use the zpool get command to determine the value of the dedupratio property. For example:

# zpool get dedupratio export
NAME   PROPERTY    VALUE  SOURCE
rpool  dedupratio  3.00x  -

This pool property illustrates how much data deduplication this pool has achieved.

The encryption Property

You can use the encryption property to encrypt ZFS file systems. For more information, see Encrypting ZFS File Systems.

The recordsize Property

The recordsize property specifies a suggested block size for files in the file system.

This property is designed solely for use with database workloads that access files in fixed-size records. ZFS automatically adjust block sizes according to internal algorithms optimized for typical access patterns. For databases that create very large files but access the files in small random chunks, these algorithms might be suboptimal. Specifying a recordsize value greater than or equal to the record size of the database can result in significant performance gains. Use of this property for general purpose file systems is strongly discouraged and might adversely affect performance. The size specified must be a power of 2 greater than or equal to 512 bytes and less than or equal to 128 KB. Changing the file system's recordsize value only affects files created afterward. Existing files are unaffected.

The property abbreviation is recsize.

The share.smb Property

This property enables sharing of ZFS file systems with the Oracle Solaris SMB service, and identifies options to be used.

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.For examples of using the share.smb property, see Sharing and Unsharing ZFS File Systems.

The volsize Property

The volsize property specifies the logical size of the volume. By default, creating a volume establishes a reservation for the same amount. Any changes to volsize are reflected in an equivalent change to the reservation. These checks are used to prevent unexpected behavior for users. A volume that contains less space than it claims is available can result in undefined behavior or data corruption, depending on how the volume is used. These effects can also occur when the volume size is changed while the volume is in use, particularly when you shrink the size. Use extreme care when adjusting the volume size.

Though not recommended, you can create a sparse volume by specifying the -s flag to zfs create -V or by changing the reservation after the volume has been created. A sparse volume is a volume whose reservation is not equal to the volume size. For a sparse volume, changes to volsize are not reflected in the reservation.

For more information about using volumes, see ZFS Volumes.

ZFS User Properties

In addition to the native properties, ZFS supports arbitrary user properties. User properties have no effect on ZFS behavior, but you can use them to annotate datasets with information that is meaningful in your environment.

User property names must conform to the following conventions:

The expected convention is that the property name is divided into the following two components but this namespace is not enforced by ZFS:

module:property

When making programmatic use of user properties, use a reversed DNS domain name for the module component of property names to reduce the chance that two independently developed packages will use the same property name for different purposes. Property names that begin with com.oracle. are reserved for use by Oracle Corporation.

The values of user properties must conform to the following conventions:

For example:

# zfs set dept:users=finance userpool/user1
# zfs set dept:users=general userpool/user2
# zfs set dept:users=itops userpool/user3

All of the commands that operate on properties, such as zfs list, zfs get, zfs set, and so on, can be used to manipulate both native properties and user properties.

For example:

zfs get -r dept:users userpool
NAME            PROPERTY    VALUE           SOURCE
userpool        dept:users  all             local
userpool/user1  dept:users  finance         local
userpool/user2  dept:users  general         local
userpool/user3  dept:users  itops           local

To clear a user property, use the zfs inherit command. For example:

# zfs inherit -r dept:users userpool

If the property is not defined in any parent dataset, it is removed entirely.