TRIM and UNMAP support for storage devices

When you use SSDs or thin‑provisioned storage, the storage usage reported by the Delphix Engine can differ from the actual disk utilization reported by the backend storage array. This discrepancy occurs because, by default, Delphix does not notify the underlying storage when it frees data blocks. As a result, the storage array continues to report capacity as used even after Delphix deletes data.

Starting with Delphix Engine release 2026.1.0.0, you can configure the engine using the CLI to send TRIM or UNMAP commands to the underlying storage. These commands notify storage devices when blocks are freed, allowing the storage system to reclaim capacity and report usage accurately.

Limitations

Be aware of the following limitations when using TRIM support:

  • You can only configure and manage this feature using the CLI.

  • This feature applies only to storage devices that support TRIM (SSDs) or UNMAP (SCSI/SAN) operations.

Overview

All API endpoints related to TRIM support are located under storage/trim. System administrators accesses these endpoints using the CLI. You can use TRIM support in three ways:

  • Manual TRIM

  • Automatic TRIM (Autotrim)

  • Scheduled TRIM

Manual TRIM

You can perform a manual TRIM operation to immediately reclaim all freed blocks on supported storage devices.

  • You start a manual TRIM operation by using storage/trim/start.

  • Delphix runs the operation as an asynchronous STORAGE_TRIM job.

  • You typically use manual TRIM when you want explicit control over when trimming occurs.

Automatic TRIM (Autotrim)

Autotrim enables ZFS to issue TRIM commands automatically as part of normal I/O operations.

  • You enable or disable autotrim by using:

    • storage/trim/enableAutotrim

    • storage/trim/disableAutotrim

  • These commands set the ZFS autotrim feature.

  • You can verify whether autotrim is enabled by running ls at storage/trim and reviewing the autotrimEnabled property.

Performance considerations

Automatic trimming can negatively affect I/O performance. The impact depends on how well your storage devices handle TRIM or UNMAP commands. In some environments, especially with lower‑end storage, scheduled or periodic manual TRIM operations provide most of the benefits with less performance impact.

The ZFS documentation notes:

“Be aware that automatic trimming of recently freed data blocks can put significant stress on the underlying storage devices… For lower-end devices it is often possible to achieve most of the benefits of automatic trimming by running an on-demand (manual) TRIM periodically.”

Scheduled TRIM

Scheduled TRIM periodically runs the same STORAGE_TRIM job used for manual TRIM based on a defined schedule.

  • You configure the schedule by setting the schedule property.

  • You view the current schedule by running ls at storage/trim.

  • If the schedule property is unset or null, scheduled TRIM is disabled.

  • Scheduled TRIM uses the Quartz CronExpression format.

Predefined schedule options

Delphix provides convenience commands for common schedules.

  • setWeeklySchedule

    • schedule: 0 0 0 ? * SUN # Sundays at midnight

  • setMonthlySchedule

    • schedule: 0 0 0 1 * ? # 1st of month at midnight

If the predefined schedules do not meet your needs, you can customize the schedule with storage/trim/update.

TRIM operation state

The state property tracks the most recent TRIM operation and includes the startTime and endTime.

  • NONE: No TRIM operation has been executed.

  • ACTIVE: A TRIM operation is currently in progress.

  • COMPLETED: The TRIM operation completed successfully.

  • FAILED: The TRIM operation failed, typically because the storage does not support TRIM or UNMAP.

CLI usage examples

Run manual TRIM operations

Copy 
delphix-engine>storage trim 
delphix-engine storage trim> ls 
Properties 
    type: TrimStatus 
    autotrimEnabled: false 
    endTime: 2025-12-16T22:28:03.503Z 
    schedule: (unset) 
    startTime: 2025-12-16T22:27:00.015Z 
    state: COMPLETED 

Operations 
update 
start 
enableAutotrim 
disableAutotrim 
setWeeklySchedule 
setMonthlySchedule 

delphix-engine storage trim> start 
delphix-engine storage trim start *> commit 
    Dispatched job JOB-8991 
    STORAGE_TRIM job started. 
    STORAGE_TRIM job completed successfully. 

Enable and disable autotrim

Copy 
delphix-engine storage trim> enableAutotrim  
delphix-engine storage trim enableAutotrim *> commit  
delphix-engine storage trim> ls  
    autotrimEnabled: true  

delphix-engine storage trim> disableAutotrim  
delphix-engine storage trim disableAutotrim *> commit  
delphix-engine storage trim> ls  
    autotrimEnabled: false 

Configure scheduled TRIM

Weekly schedule (Sundays at midnight)

Copy 
delphix-engine storage trim> setWeeklySchedule  
delphix-engine storage trim setWeeklySchedule *> commit  
delphix-engine storage trim> ls  
    schedule: 0 0 0 ? * SUN  

Monthly schedule (first day of the month at midnight)

Copy 
delphix-engine storage trim> setMonthlySchedule  
delphix-engine storage trim setMonthlySchedule *> commit  
delphix-engine storage trim> ls  
    schedule: 0 0 0 1 * ?  

Create custom schedules

Copy 
delphix-engine storage trim> update  
delphix-engine storage trim update *> set schedule="0 0 2 * * ?"  # Daily at 2AM  
delphix-engine storage trim update *> commit

Disable schedules

Copy 
delphix-engine storage trim> update  
delphix-engine storage trim update *> unset schedule  
delphix-engine storage trim update *> commit