ZFS Quotas and Reservations in TrueNAS: Fairly Dividing Pool Space Across Departments

Every TrueNAS admin knows the scene: a single pool, multiple departments, and overnight marketing pushed in 4 TB of raw video footage. Accounting, engineering, and the CAD team come in on Monday to find nothing writes. Instead of expanding the pool or carving LUNs on old NAS heads, there is a feature ZFS has shipped with since version one: quotas and reservations at the dataset level.

At DATAZONE we deploy this daily for mid-market customers – from the 20-person law firm to production environments with 80 users. In this article we walk through the four relevant properties, show the GUI and CLI path in TrueNAS 25.10 Goldeye, and point out the usual pitfalls.

Why ZFS Quotas Instead of Classic LUN Carving

In older storage worlds, departments were separated through dedicated LUNs or isolated volumes. The downside: free space on LUN A did not help LUN B, even if both lived on the same disks. ZFS flips the model – one pool, many datasets, shared free space. Quotas and reservations make sure that this flexibility does not turn into a liability.

A dataset without a limit can theoretically consume the entire pool. You do not want that in a multi-user environment. At the same time, a critical department should keep a guaranteed buffer even when other datasets grow. That is exactly what the four tools exist for: quota, refquota, reservation, and refreservation.

For deeper pool planning, our ZFS pool planner covers VDEV layout and capacity math. Quotas and reservations add the multi-user dimension on top of that.

Quota vs Refquota: The Key Distinction

This one gets mixed up in every other project – keep them clearly separated:

• Quota limits a dataset including all snapshots and child datasets. Everything underneath that path counts against the limit.
• Refquota limits only the referenced data – meaning what is currently visible in the filesystem. Snapshots and child datasets do not count.

Example: you give tank/departments/sales a quota of 500 GB. Sales uses 300 GB. A snapshot schedule holds two weeks and consumes 180 GB. Mathematically only 20 GB remain before the quota triggers – even though 300 GB are visible in the filesystem. Users will be confused.

With refquota 500 GB, ZFS only blocks writes once referenced data crosses 500 GB. Snapshots can grow on top of that – it costs pool space, but users do not get a “disk full” message while their recycle bin looks empty.

Which to Use When

In practice we almost always run refquota on the working dataset and a quota on the parent dataset that groups the departmental hierarchy. The department gets a clear usage envelope, and the hard ceiling including snapshots sits one layer above. For pure archive or backup datasets without snapshot history, a plain quota is fine.

Reservation vs Refreservation: Guaranteeing Space

The mirror image on the guarantee side:

• Reservation reserves space including snapshots and children – other datasets in the pool see this space as occupied, even if it is currently free.
• Refreservation reserves only the referenced space, meaning guaranteed write capacity for the current filesystem without snapshot overhead.

For filesystems, refreservation is usually the better choice: the department gets a guarantee that it may write, say, 1 TB before the pool fills. For zvols – block devices used for iSCSI or VM disks – TrueNAS 25.10 Goldeye sets a refreservation equal to the zvol size by default. This prevents a thin-provisioned VM disk from hitting a wall when the pool runs out. For thin zvols, the refreservation has to be set to zero manually – a topic we cover in our Proxmox ZFS tuning series.

The GUI Path in TrueNAS Goldeye

For most standard cases the web UI is enough. In TrueNAS 25.10 Goldeye navigate to Datasets, pick the target, and click Edit. Under Space Management you will see:

• Quota for this dataset
• Quota for this dataset and all children
• Reserved space for this dataset
• Reserved space for this dataset and all children

The GUI remaps the terminology a bit: “for this dataset” is refquota/refreservation, “and all children” is quota/reservation. Internalize it once and the mapping is clear.

TrueNAS also warns when you set a quota smaller than the current usage – in that case users can no longer write until data is removed. Useful, but easy to miss in a hurry.

When the CLI Is Faster

For bulk setups – ten departments at once – the CLI pays off:

zfs set refquota=1T tank/departments/sales
zfs set quota=1.3T tank/departments/sales
zfs set refreservation=200G tank/departments/sales

That is trivially scriptable across all children of a parent. For documentation, zfs get all tank/departments/sales is far clearer than the GUI view. If you provision regularly, keep a small Ansible role or Bash snippet around.

User and Group Quotas: The Often-Forgotten Layer

Dataset quotas govern the departmental envelope. But what happens when a single person inside marketing takes 70 percent of the allocated space? That is where user quotas and group quotas come in.

ZFS exposes separate properties:

zfs set userquota@mschmidt=50G tank/departments/marketing
zfs set groupquota@design=200G tank/departments/marketing
zfs set defaultuserquota=20G tank/departments/marketing

The defaultuserquota has been available since OpenZFS 2.2 and is highly practical: every user without a specific quota inherits 20 GB automatically. New hires do not need manual bookkeeping. More context in our OpenZFS 2.4 user update.

Combination With SMB Shares

In Windows environments, an exceeded user quota surfaces as a regular “disk full” error through the SMB protocol. Users see it as if it were a local disk issue – no cryptic hints required. That cuts support load dramatically. SMB itself should run encrypted and authenticated, which we covered in the article on TrueNAS SMB protocol security.

Monitoring: What You Actually Need

A limit without monitoring is a time bomb. Three things to check regularly:

1. Dataset usage

zfs list -o name,used,refer,quota,refquota,reservation,refreservation -r tank/departments

2. User quota status

zfs userspace tank/departments/marketing
zfs groupspace tank/departments/marketing

3. TrueNAS alerts

Under System → Alert Settings you configure pool and dataset fill thresholds (for example 80 percent as warning, 90 percent as critical). Alerts go out via email or webhook. In practice we often hook a webhook into the internal chat system – that way IT sees the problem before the first call comes in.

For larger environments a Prometheus exporter with a Grafana dashboard is worthwhile. We set that up as part of our TrueNAS support on request, including Alertmanager routing.

Common Pitfalls From the Field

Snapshots Eating the Quota

We see it every few months: a dataset with quota=500G, 400 GB of real data, and a “disk full” alert. In 80 percent of cases the cause is old snapshots that have not been pruned for months. A quick look at zfs list -t snapshot -o name,used -r tank/departments reveals the culprit. The fix: review the snapshot plan or move to refquota.

Reservations Blocking Other Datasets

Generous reservations across multiple datasets can report the pool as full even though 2 TB are physically free. The pool counts reserved space as occupied. If a VM image sitting on a zvol has its own refreservation on top, you can hit surprises quickly. Always cross-check: zpool list -v shows the actual free space, zfs list shows the pool view including reservations.

User Quotas on Nested Datasets

User quotas apply per dataset, not per pool. If a department spans multiple datasets, user quotas have to be set on each one. For compliance environments – for example under the CER directive – a central mapping table is worth maintaining so nothing gets missed.

When DATAZONE Does It for You

We set up quotas and reservations as part of the TrueNAS initial deployment. That means we analyze the departmental structure, lay out the dataset hierarchy, configure snapshots, document the limits, and wire up monitoring. Our TrueNAS support then handles ongoing changes – when a department grows, when a new project launches, when a user leaves.

Which hardware makes sense depends on the workload. For a rough frame we recommend running the TrueNAS configurator – you can play through pool size, protocols, and RAID level and get a hardware recommendation including a price range. The current iXsystems appliances M30 and M40 fit most mid-market scenarios. The older M50 and M60 are end-of-life as of this year – if you still have one in the building, let us know.

FAQ

What is the difference between ZFS quota and ZFS refquota?

Quota limits a dataset including all snapshots and child datasets. Refquota only limits the referenced data, meaning what is currently visible in the filesystem. In multi-user environments with a snapshot plan, you almost always want refquota on the working dataset and optionally a stricter quota one level above.

Can I set ZFS quotas on datasets that are already full?

Yes. If you set a quota smaller than the current usage, ZFS blocks new writes. Reads and deletes still work. Users have to clean up first before they can write again. The TrueNAS GUI warns when you set a quota that is too small.

Do user quotas work with SMB shares in Windows environments?

Yes. ZFS maps user quotas via the UID mapping mechanism. In SMB shares, an exceeded quota appears as a regular “disk full” error, which Windows clients display without extra information. The prerequisite is correct user authentication, either via Active Directory or local users.

What happens if a reservation would oversubscribe the pool?

ZFS prevents it actively. If you try to set a reservation that – combined with others – would exceed the available pool capacity, you get an error. That is why reservations should be used consciously and sparingly, as a guarantee for business-critical datasets rather than blanket for everything.

Is the TrueNAS GUI enough or do I need the CLI?

For standard setups up to maybe 20 datasets, the GUI is fine. Beyond that – larger hierarchies or bulk operations – the CLI is significantly more efficient. For documentation and audit, zfs get all is still the most complete view regardless of how the values were set.

Can quotas and reservations be used together?

Yes, that is actually the typical pattern: a refquota as upper bound and a refreservation as guaranteed buffer. The department has a clear envelope in which it can work safely. For business-critical datasets, this combination is the cleanest way to express fairness and availability at the same time.