Go to main content

Managing ZFS File Systems in Oracle® Solaris 11.4

Exit Print View

Updated: August 2019
 
 

Querying ZFS File System Information

The zfs list command provides an extensible mechanism for viewing and querying dataset information. Both basic and complex queries are explained in this section.

Listing Basic ZFS Information

You can list basic dataset information by using the zfs list command with no options. This command displays the names of all datasets on the system and the values of their used, available, referenced, and mountpoint properties. For more information about these properties, see Introducing ZFS Properties.

For example:

$ zfs list
users                   2.00G  64.9G    32K  /users
users/home              2.00G  64.9G    35K  /users/home
users/home/cindy         548K  64.9G   548K  /users/home/cindy
users/home/mark         1.00G  64.9G  1.00G  /users/home/mark
users/home/neil         1.00G  64.9G  1.00G  /users/home/neil

You can also use this command to display specific datasets by providing the dataset name on the command line. Additionally, use the –r option to recursively display all descendents of that dataset. For example:

$ zfs list -t all -r users/home/mark
NAME                        USED  AVAIL  REFER  MOUNTPOINT
users/home/mark            1.00G  64.9G  1.00G  /users/home/mark
users/home/mark@yesterday      0      -  1.00G  -
users/home/mark@today          0      -  1.00G  -

You can use the zfs list command with the mount point of a file system. For example:

$ zfs list /user/home/mark
NAME              USED  AVAIL  REFER  MOUNTPOINT
users/home/mark  1.00G  64.9G  1.00G  /users/home/mark

The following example shows how to display basic information about tank/home/gina and all of its descendent file systems:

$ zfs list -r users/home/gina
NAME                           USED  AVAIL  REFER  MOUNTPOINT
users/home/gina               2.00G  62.9G    32K  /users/home/gina
users/home/gina/projects      2.00G  62.9G    33K  /users/home/gina/projects
users/home/gina/projects/fs1  1.00G  62.9G  1.00G  /users/home/gina/projects/fs1
users/home/gina/projects/fs2  1.00G  62.9G  1.00G  /users/home/gina/projects/fs2

For additional information about the zfs list command, see the see zfs(8) man page.

Creating Complex ZFS Queries

The zfs list output can be customized by using the –o, –t, and –H options.

You can customize property value output by using the –o option and a comma-separated list of desired properties. You can supply any dataset property as a valid argument. For a list of all supported dataset properties, see Introducing ZFS Properties. In addition to the properties defined, the –o option list can also contain the literal name to indicate that the output should include the name of the dataset.

The following example uses zfs list to display the dataset name, along with the share.nfs and mountpoint property values.

$ zfs list -r -o name,share.nfs,mountpoint users/home
NAME                          NFS       MOUNTPOINT
users/home                    on        /users/home
users/home/cindy              on        /users/home/cindy
users/home/gina               on        /users/home/gina
users/home/gina/projects      on        /users/home/gina/projects
users/home/gina/projects/fs1  on        /users/home/gina/projects/fs1
users/home/gina/projects/fs2  on        /users/home/gina/projects/fs2
users/home/mark               on        /users/home/mark
users/home/neil               on        /users/home/neil

You can use the –t option to specify the types of datasets to display. The valid types are described in the following table.

Table 4  Types of ZFS Objects
Type
Description
filesystem
File systems and clones
volume
Volumes
share
File system share
snapshot
Snapshots

The –t options takes a comma-separated list of the types of datasets to be displayed. The following example uses the –t and –o options simultaneously to show the name and used property for all file systems:

$ zfs list -r -t filesystem -o name,used users/home
NAME                           USED
users/home                    4.00G
users/home/cindy               548K
users/home/gina               2.00G
users/home/gina/projects      2.00G
users/home/gina/projects/fs1  1.00G
users/home/gina/projects/fs2  1.00G
users/home/mark               1.00G
users/home/neil               1.00G

You can use the –H option to omit the zfs list header from the generated output. With the –H option, all white space is replaced by the Tab character. This option can be useful when you need parseable output, for example, when scripting. The following example shows the output generated from using the zfs list command with the –H option:

$ zfs list -r -H -o name users/home
users/home
users/home/cindy
users/home/gina
users/home/gina/projects
users/home/gina/projects/fs1
users/home/gina/projects/fs2
users/home/mark
users/home/neil

Listing Incomplete ZFS Datasets

An incomplete dataset is created when a dataset transfer started by running zfs receive is interrupted. The zfs list –I command can be used to show which datasets are incomplete. The state for each dataset can be either receiving or resumable. Arguments with the –I option are all, resumable or receiving.

$ zfs list -I all
NAME            USED  AVAIL  REFER  TYPE    STATE
users/home/dst  189M   910G   189M  volume  resumable

You can use the following command to show just the names of the resumable datasets,

$ zfs list -HI resumable
users/home/dst

Creating Parsable Output with zfs list

The zfs list –o command can be used with the –p option to create exact machine-parsable numeric output. For example:

$ zfs list -o guid users/home
GUID
3.30E
$ zfs list -po guid users/home
GUID
3807001345661527925