Skip Navigation Links | |
Exit Print View | |
Oracle Solaris ZFS Administration Guide Oracle Solaris 11 Express 11/10 |
1. Oracle Solaris ZFS File System (Introduction)
2. Getting Started With Oracle Solaris ZFS
3. Oracle Solaris ZFS and Traditional File System Differences
4. Managing Oracle Solaris ZFS Storage Pools
5. Managing ZFS Root Pool Components
6. Managing Oracle Solaris ZFS File Systems
Managing ZFS File Systems (Overview)
Creating, Destroying, and Renaming ZFS File Systems
Querying ZFS File System Information
Querying ZFS Properties for Scripting
Mounting and Sharing ZFS File Systems
Using Temporary Mount Properties
Sharing and Unsharing ZFS File Systems
Sharing ZFS Files in an Oracle Solaris SMB Environment
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
Changing an Encrypted ZFS File System's Keys
Delegating ZFS Key Operation Permissions
Mounting an Encrypted ZFS File System
Interactions Between ZFS Compression, Deduplication, and Encryption Properties
Examples of Encrypting ZFS File Systems
7. Working With Oracle Solaris ZFS Snapshots and Clones
8. Using ACLs and Attributes to Protect Oracle Solaris ZFS Files
9. Oracle Solaris ZFS Delegated Administration
10. Oracle Solaris ZFS Advanced Topics
11. Oracle Solaris ZFS Troubleshooting and Pool Recovery
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 export 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 dataset, 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:
Indicates that the property was explicitly set on the dataset by using the zfs set command as described in Setting ZFS Properties.
Indicates that the property was inherited from the named ancestor.
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 6-1 ZFS Native Property Descriptions
|
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 6-1.
The read-only native properties are listed here and described in Table 6-1.
available
compressratio
creation
keystatus
mounted
origin
referenced
rekeydate
type
used
For detailed information, see The used Property.
usedbychildren
usedbydataset
usedbyrefreservation
usedbysnapshots
For more information about disk space accounting, including the used, referenced, and available properties, see ZFS Disk Space Accounting.
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 6-1.
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 6-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 6-1.
aclinherit
For a detailed description, see ACL Property (aclinherit).
atime
canmount
casesensitivity
checksum
compression
copies
devices
dedup
encryption
exec
keysource
logbias
mlslabel
mountpoint
nbmand
normalization
primarycache
quota
readonly
recordsize
For a detailed description, see The recordsize Property.
refquota
refreservation
reservation
rstchown
secondarycache
sharesmb
sharenfs
setuid
snapdir
version
vscan
utf8only
volsize
For a detailed description, see The volsize Property.
volblocksize
zoned
xattr
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 dataset 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 dataset can only be mounted explicitly, not automatically. This value setting is used by the Oracle Solaris upgrade software so that only those datasets belonging to the active boot environment are mounted at boot time.
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.
This property controls whether duplicate data is removed from the 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 your file systems until you have reviewed the information in this FAQ:
http://hub.opensolaris.org/bin/view/Community+Group+zfs/dedup
When dedup is enabled, the dedup checksum algorithm overrides the checksum property. Setting the 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-for-byte comparison with the existing block to ensure that the contents are identical.
This property can be enabled per file system as follows:
# 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 as follows:
# 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 dataset or if the dedup property was just enabled on the dataset, the DEDUP ratio is 1.00x.
You can use the zpool get command to determine the value of the dedupratio property.
# zpool get all export NAME PROPERTY VALUE SOURCE export size 33.8G - export capacity 0% - export altroot - default export health ONLINE - export guid 2064230982813446135 default export version 22 default export bootfs - default export delegation on default export autoreplace off default export cachefile - default export failmode wait default export listsnapshots off default export autoexpand off default export dedupditto 0 default export dedupratio 3.00x - export free 33.6G - export allocated 105M -
This pool property illustrates how much deduplication we have been able to achieve.
You can use the encryption property to encrypt ZFS file systems. For more information, see Encrypting ZFS File Systems.
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.
This property enables sharing of ZFS file systems with the Oracle Solaris SMB service, and identifies options to be used.
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, which 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 dataset name with a specific name. The specific 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 a child dataset of data/home/john/backups exists, it has a resource name of john_backups. When the sharesmb property is changed for a dataset, the dataset and any children inheriting the property are re-shared with the new options, only if the property was previously set to off, or if they were shared before the property was changed. If the new property is set to off, the file systems are unshared.
For examples of using the sharesmb property, see Sharing and Unsharing ZFS File Systems.
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.
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:
They must contain a colon (':') character to distinguish them from native properties.
They must contain lowercase letters, numbers, or the following punctuation characters: ':', '+','.', '_'.
The maximum length of a user property name is 256 characters.
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.sun. are reserved for use by Oracle Corporation.
The values of user properties must conform to the following conventions:
They must consist of arbitrary strings that are always inherited and are never validated.
The maximum length of the user property value is 1024 characters.
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.