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


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


Managing ZFS Properties

Dataset properties are managed through the zfs command's set, inherit, and get subcommands.

Setting ZFS Properties

You can use the zfs set command to modify any settable dataset property. Or, you can use the zfs create command to set properties when a dataset is created. For a list of settable dataset properties, see Settable ZFS Native Properties.

The zfs set command takes a property/value sequence in the format of property=value followed by a dataset name. Only one property can be set or modified during each zfs set invocation.

The following example sets the atime property to off for tank/home.

# zfs set atime=off tank/home

In addition, any file system property can be set when a file system is created. For example:

# zfs create -o atime=off tank/home

You can specify numeric property values by using the following easy-to-understand suffixes (in increasing sizes): BKMGTPEZ. Any of these suffixes can be followed by an optional b, indicating bytes, with the exception of the B suffix, which already indicates bytes. The following four invocations of zfs set are equivalent numeric expressions that set the quota property be set to the value of 20 GB on the users/home/mark file system:

# zfs set quota=20G users/home/mark
# zfs set quota=20g users/home/mark
# zfs set quota=20GB users/home/mark
# zfs set quota=20gb users/home/mark

If you attempt to set a property on a file system that is 100% full, you will see a message similar to the following:

# zfs set quota=20gb users/home/mark
cannot set property for '/users/home/mark': out of space

The values of non-numeric properties are case-sensitive and must be in lowercase letters, with the exception of mountpoint. The values of this property can have mixed upper and lower case letters.

For more information about the zfs set command, see zfs(1M).

Inheriting ZFS Properties

All settable properties, with the exception of quotas and reservations, inherit their value from the parent file system, unless a quota or reservation is explicitly set on the descendent file system. If no ancestor has an explicit value set for an inherited property, the default value for the property is used. You can use the zfs inherit command to clear a property value, thus causing the value to be inherited from the parent file system.

The following example uses the zfs set command to turn on compression for the tank/home/jeff file system. Then, zfs inherit is used to clear the compression property, thus causing the property to inherit the default value of off. Because neither home nor tank has the compression property set locally, the default value is used. If both had compression enabled, the value set in the most immediate ancestor would be used (home in this example).

# zfs set compression=on tank/home/jeff
# zfs get -r compression tank/home
NAME                  PROPERTY     VALUE     SOURCE
tank/home             compression  off       default
tank/home/eric        compression  off       default
tank/home/eric@today  compression  -         -
tank/home/jeff        compression  on        local
# zfs inherit compression tank/home/jeff
# zfs get -r compression tank/home
NAME                  PROPERTY     VALUE     SOURCE
tank/home             compression  off       default
tank/home/eric        compression  off       default
tank/home/eric@today  compression  -         -
tank/home/jeff        compression  off       default

The inherit subcommand is applied recursively when the -r option is specified. In the following example, the command causes the value for the compression property to be inherited by tank/home and any descendents it might have:

# zfs inherit -r compression tank/home

Note - Be aware that the use of the -r option clears the current property setting for all descendent file systems.

For more information about the zfs inherit command, see zfs(1M).

Querying ZFS Properties

The simplest way to query property values is by using the zfs list command. For more information, see Listing Basic ZFS Information. However, for complicated queries and for scripting, use the zfs get command to provide more detailed information in a customized format.

You can use the zfs get command to retrieve any dataset property. The following example shows how to retrieve a single property value on a dataset:

# zfs get checksum tank/ws
NAME             PROPERTY       VALUE                      SOURCE
tank/ws          checksum       on                         default

The fourth column, SOURCE, indicates the origin of this property value. The following table defines the possible source values.

Table 5-3 Possible SOURCE Values (zfs get Command)

Source Value
This property value was never explicitly set for this dataset or any of its ancestors. The default value for this property is being used.
inherited from dataset-name
This property value is inherited from the parent dataset specified in dataset-name.
This property value was explicitly set for this dataset by using zfs set.
This property value was set by using the zfs mount -o option and is only valid for the duration of the mount. For more information about temporary mount point properties, see Using Temporary Mount Properties.
- (none)
This property is read-only. Its value is generated by ZFS.

You can use the special keyword all to retrieve all dataset property values. The following examples use the all keyword:

# zfs get all tank/home
NAME       PROPERTY              VALUE                  SOURCE
tank/home  aclinherit            restricted             default
tank/home  aclmode               discard                default
tank/home  atime                 on                     default
tank/home  available             66.9G                  -
tank/home  canmount              on                     default
tank/home  casesensitivity       mixed                  -
tank/home  checksum              on                     default
tank/home  compression           off                    default
tank/home  compressratio         1.00x                  -
tank/home  copies                1                      default
tank/home  creation              Fri May 11 10:58 2012  -
tank/home  dedup                 off                    default
tank/home  devices               on                     default
tank/home  encryption            off                    -
tank/home  exec                  on                     default
tank/home  keysource             none                   default
tank/home  keystatus             none                   -
tank/home  logbias               latency                default
tank/home  mlslabel              none                   -
tank/home  mounted               yes                    -
tank/home  mountpoint            /tank/home             default
tank/home  multilevel            off                    -
tank/home  nbmand                off                    default
tank/home  normalization         none                   -
tank/home  primarycache          all                    default
tank/home  quota                 none                   default
tank/home  readonly              off                    default
tank/home  recordsize            128K                   default
tank/home  referenced            43K                    -
tank/home  refquota              none                   default
tank/home  refreservation        none                   default
tank/home  rekeydate             -                      default
tank/home  reservation           none                   default
tank/home  rstchown              on                     default
tank/home  secondarycache        all                    default
tank/home  setuid                on                     default
tank/home  shadow                none                   -
tank/home  share.*               ...                    local
tank/home  snapdir               hidden                 default
tank/home  sync                  standard               default
tank/home  type                  filesystem             -
tank/home  used                  8.54M                  -
tank/home  usedbychildren        8.49M                  -
tank/home  usedbydataset         43K                    -
tank/home  usedbyrefreservation  0                      -
tank/home  usedbysnapshots       0                      -
tank/home  utf8only              off                    -
tank/home  version               6                      -
tank/home  vscan                 off                    default
tank/home  xattr                 on                     default
tank/home  zoned                 off                    default

The -s option to zfs get enables you to specify, by source type, the properties to display. This option takes a comma-separated list indicating the desired source types. Only properties with the specified source type are displayed. The valid source types are local, default, inherited, temporary, and none. The following example shows all properties that have been locally set on tank/ws.

# zfs get -s local all tank/ws
NAME     PROPERTY              VALUE                  SOURCE
tank/ws  compression           on                     local

Any of the above options can be combined with the -r option to recursively display the specified properties on all children of the specified file system. In the following example, all temporary properties on all file systems within tank/home are recursively displayed:

# zfs get -r -s temporary all tank/home
NAME             PROPERTY       VALUE                      SOURCE
tank/home          atime          off                      temporary
tank/home/jeff     atime          off                      temporary
tank/home/mark     quota          20G                      temporary

You can query property values by using the zfs get command without specifying a target file system, which means the command operates on all pools or file systems. For example:

# zfs get -s local all
tank/home               atime          off                    local
tank/home/jeff          atime          off                    local
tank/home/mark          quota          20G                    local

For more information about the zfs get command, see zfs(1M).

Querying ZFS Properties for Scripting

The zfs get command supports the -H and -o options, which are designed for scripting. You can use the -H option to omit header information and to replace white space with the Tab character. Uniform white space allows for easily parseable data. You can use the -o option to customize the output in the following ways:

The following example shows how to retrieve a single value by using the -H and -o options of zfs get:

# zfs get -H -o value compression tank/home

The -p option reports numeric values as their exact values. For example, 1 MB would be reported as 1000000. This option can be used as follows:

# zfs get -H -o value -p used tank/home

You can use the -r option, along with any of the preceding options, to recursively retrieve the requested values for all descendents. The following example uses the -H, -o, and -r options to retrieve the file system name and the value of the used property for export/home and its descendents, while omitting the header output:

# zfs get -H -o name,value -r used export/home