How to view and change dataset properties

When to use

When the question concerns a specific virtual machine disk rather than the entire pool: which compression it uses, how much space it actually occupies, how much space its snapshots retain, or whether deduplication is enabled. A virtual machine disk resides in a pool dataset, and ZFS properties are read and changed at the dataset level.

Another reason is to change the compression algorithm for a single disk without affecting the others. For example, to increase compression for a dataset with cold data.

This procedure does not cover resizing a disk or snapshot operations: these are virtual machine-level operations. Dataset properties cannot replace them.

Prerequisites

• To read properties — the VDC (virtual data center) administrator role or higher, and only for datasets in your own VDC;
• To change properties — the same VDC administrator role or higher, also within your own VDC; a global role can work with datasets in any VDC;
• The filesystem_options feature enabled in the cluster — dataset properties are unavailable without it;
• The zstd and zstd-fast algorithms are available when the zstd_enabled feature is enabled in the cluster;
• vStack Center version 3.0.5.

Steps

Step 1. Open dataset properties

1. Open the virtual machine: Virtual Data Centers → the required VDC → Virtual Machines → the machine. From the cluster, the same list opens through All Virtual Machines.
2. Scroll down to Disks on the machine page. The table shows the machine's disks: Name, Slot, Disk size (GB), Sector size, IOps limit, MBps limit.
3. In the row for the required disk, expand the actions menu and select Filesystems.

The dataset properties form for this disk opens. Its header contains the disk GUID, creation date, and full dataset name, such as pool-a/vm-100-disk-0, which identifies the pool containing the disk.

If Filesystems is missing from the menu, the filesystem_options feature is disabled in the cluster.

Step 2. Read the properties

The form is organized into blocks.

Block	Contents
Size, Reservation	Requested volume size and its reservation; a virtual machine disk cannot be resized through this form
Compression	Compression algorithm and level, with Compressratio and Refcompressratio values alongside
Cache	Primarycache and Secondarycache — what is cached
Other properties	Checksum, Dedup, Copies, Logbias
Used	Space used, broken down into Usedbydataset, Usedbychildren, Usedbyrefreservation, Usedbysnapshots, Logicalused
Remaining fields	Available, Refreservation, Referenced, Logicalreferenced, Written, Volblocksize

Interpret the form as follows. Size is the requested volume size, which is what the guest system sees. Used is the space the dataset currently occupies in the pool, and it remains below the requested size until the guest has written to the entire disk. Usedbysnapshots shows the portion retained by snapshots; the snapshots themselves are listed in Snapshots on the machine page. If the disk occupies more space in the pool than the data inside the guest, the difference is almost always accounted for by these fields. Compressratio shows the gains from compression.

The full set of dataset properties is described in the reference.

Step 3. Change compression

1. In Compression, select an algorithm: on, off, lz4, gzip, lzjb, zle, and, in a cluster with the zstd_enabled feature enabled, also zstd and zstd-fast.
2. For gzip, zstd, and zstd-fast, set the level next to the algorithm: gzip — from 1 to 9, zstd — from 1 to 19, zstd-fast — a value from its own set. A lower value means faster compression; a higher value means denser compression.
3. Click Apply. The button is active only when the form contains changes.
4. Wait for the notification that the file system has been changed.

Only changed properties are sent; the form does not overwrite the others. Dataset ownership by a VDC is checked before writing and before contacting the node: a dataset belonging to another VDC is rejected at entry, and no changes are applied anywhere.

A compression change applies to future writes: blocks already written remain in the old format, and the new algorithm applies to new writes. Compressratio therefore changes gradually after the edit rather than immediately.

The Readonly toggle in the same form makes the dataset read-only. The warning next to it about the performance impact describes an operational limitation, not a cosmetic change.

Verify the result

Close the form and reopen Filesystems for the same disk.

Expected result: Compression shows the new algorithm, and the full dataset name in the header is unchanged. At this point, Compressratio still reflects the old data — this is normal.

Troubleshooting

The Filesystems item is missing from the disk menu. The filesystem_options feature is disabled in the cluster; an API request returns code -87, "Filesystems methods has not been enabled". There is no workaround: dataset properties remain unavailable until the feature is enabled.

The form is unavailable, fields are disabled, or the Apply button is missing. The role lacks sufficient permissions. Reading and changing properties are available to a VDC administrator or higher; a request without this permission is rejected with code -403, "Access denied". A VDC user receives -403 even when reading.

The form does not open, and the dataset is not found (-58 when reading, -88 when writing, "Dataset does not exist at users scope"). The dataset either does not exist or belongs to another VDC. One response covers both cases as a safeguard: the existence of another VDC's dataset is not disclosed. Workaround: check that you are opening a machine disk in your own VDC; datasets in other VDCs are available only to a global role.

The form opens, but properties are not retrieved (-57 when reading, -86 when writing, "param guid has bad value"). The same response covers both an invalid disk identifier and a node communication failure. Refresh the machine page and check whether the node serving this dataset's pool responds.

The dataset row in the database has an empty name (-53 and -83, "Unable to locate the dataset"). The dispatcher found the dataset row, but its name field is empty, so the request does not reach the node. A deleted disk returns code -58 or -88 because the row is no longer in the database.

The dataset's pool has no serving node assigned (-54 and -84, "Unable to locate the pool of the dataset"). The dispatcher found the pool row, but its current node field is empty, so there is nowhere to relay the request. Check Current node for this pool in the ZFS pools table. How to open it is described in How to view cluster pools.

See also

• Storage pools — where a dataset resides and how pool capacity is calculated.
• Storage method fields and error codes — the full set of dataset properties and a code summary.
• Growth in used space caused by snapshots — in the "Troubleshooting" section.

API methods

API operations covered on this page: filesystems-get, filesystems-set — see the API reference.