Get a Quote     (408) 943-4100   TrueNAS Discord VendOp_Icon_15x15px Commercial Support
TrueNAS.com Software Systems Company Community Security iX Portal Download
TrueNAS CORE TrueNAS Enterprise TrueNAS SCALE Compare Editions TrueCommand Software Status FreeNAS
Compare Systems F-Series M-Series X-Series R-Series Mini Series
About iXsystems Our Clients Reviews Careers Awards iX Blog & News iX Website Contact Us
Community Forum Discord TrueNAS GitHub TrueNAS Merch Store
Application Analytics Backup and Archival Cloud Data Mobility File Sharing iX Storj Media Creation Video Surveillance Virtualization
Industry Automotive Education Gaming Government Healthcare MSP Manufacturing Research & AI Media & Entertainment
Download TrueNAS CORE Download TrueNAS SCALE Get TrueNAS Enterprise Compare TrueNAS Editions Where to Buy
  1. Documentation Hub
  2. /
  3. TrueNAS SCALE
  4. /
  5. CLI Reference Guide
  6. /
  7. Storage
  8. /
  9. Scrub
Edit page
TrueNAS SCALETrueNAS SCALE Nightly Development Documentation
This content follows experimental early release software. Use the Product and Version selectors above to view content specific to a stable software release.

Scrub

  7 minute read.

Last Modified 2024-04-24 11:56 EDT

The SCALE CLI guide is a work in progress! New namespace and command documentation is continually added and maintained, so check back here often to see what is new!

Scrub Namespace

The scrub namespace has 7 commands, and is based on data integrity check (scrub) functions found in the SCALE API and web UI. It provides access to scrub task management methods through the scrub namespace commands.

Scrub Commands

The following scrub namespace commands allow you to manage scheduled scrub task configuration and to start, pause, or stop a scrub.

You can enter commands from the main CLI prompt or from the storage namespace prompt.

Create Command

The create command configures a new scheduled scrub task.

Using the Create Command

Description

create has one required property, pool, and four optional properties (see Create Properties below). The value for pool is the pool id number. Use storage pool query to find the id for the selected pool and enter this integer.

Enter the full command string along with any optional properties you want to configure, or accept the default values, and then press Enter. create returns an empty line when successful. Use query to confirm the task is created correctly.

Create Properties
PropertyRequiredDescriptionSyntax Example
poolYesEnter the id number for the selected pool.
Use storage pool query to find the id numbers for all pools on the system.		pool=1
thresholdNoEnter the number of days before a completed scrub is allowed to run again. Default value is 35. This controls the task schedule. For example, scheduling a scrub to run daily and setting Threshold days to 7 means the scrub attempts to run daily. When the scrub succeeds, it continues to check daily but does not run again until the seven days have elapsed. Using a multiple of seven ensures the scrub always occurs on the same weekday.threshold=7
descriptionNoEnter a human-readable name or description for the scrub task.description= “scrub task 1"
scheduleNoEnter an array of properties that specify the date and time when the scrub task runs. The default setting is to run the task weekly, every Sunday at 00:00 (0 0 * * 0). Enter {} without property arguments to accept default values for schedule properties, or enter each property argument enclosed in square brackets with double-quoted properties and values. Separate each array property argument enclosed in square brackets [] with a comma and space. Properties are:
  • minute specified in the format of minutes:seconds or use the default 00
  • hour specified in the format of 00 (0-23) or use the default * for every hour.
  • dom specifies the day of month in the format of jan through dec or use the default * for every month.
  • month specifies the month in the format of jan or use the default * for any month.
  • dow specifies the day(s) of the week as sun, mon, tue, wed, thu, fri, or sat or use the default * for every day of the week.
Command example shows the default values for each property in the object array.		schedule={[“minute”=“00”], [“hour”="*”], [“dom”="*"], [“month”="*"], [“dow”="*"]}
enabledNoEnter false to create but not allow it to execute or accept the default value of true.enabled=false

Usage

From the CLI prompt, enter:

storage scrub create pool=1

Where 1 is the id number for the selected pool. Press Enter.

Command Example 
storage scrub create pool=2 threshold=30 description="tank scrub" schedule={} enabled=true

Delete Command

The delete command erases an existing scrub task.

Using the Delete Command

Description

delete has one required property, id. Use query to find the id number of the scrub task you want to remove.

Enter the command string and then press Enter. delete returns an empty line when successful. Use query or get_instance to confirm the task is deleted.

Usage

From the CLI prompt, enter:

storage scrub delete id=1

Where 1 is the scrub task id. Press Enter.

Command Example 
storage scrub delete id=1

Get_instance Command

The get_instance command returns the current configuration for an existing scrub task.

Using the Get_instance Command

Description

get_instance has one required property, id. Use query to find the id number of the scrub task you want to view.

Enter the command string and then press Enter. get_instance returns a table containing configured settings for that scrub task.

Usage

From the CLI prompt, enter:

storage scrub get_instance id=1

Where 1 is the id number for the selected scrub task. Press Enter.

Command Example 
storage scrub get_instance id=1
+-------------+------------+
|          id | 1          |
|   threshold | 30         |
| description | tank scrub |
|     enabled | true       |
|        pool | 2          |
|   pool_name | tank       |
|    schedule | <dict>     |
+-------------+------------+

Query Command

The query command returns information about all scheduled scrub tasks on the system.

Using the Query Command

Description

query does not require entering properties or arguments.

Enter the command string and then press Enter. query returns a table containing configured settings for all existing scrub tasks.

Usage

From the CLI prompt, enter:

storage scrub query

Press Enter.

Command Example 
storage scrub query
+----+-----------+-------------+---------+------+-----------+----------+
| id | threshold | description | enabled | pool | pool_name | schedule |
+----+-----------+-------------+---------+------+-----------+----------+
| 1  | 35        |             | true    | 2    | tank      | <dict>   |
+----+-----------+-------------+---------+------+-----------+----------+

Run Command

The run command activates a one-time scrub task for the selected pool.

Using the Run Command

Description

run has one required property, name, and one optional property, threshold. To find the name of the pool you want to scrub, use storage pool query or storage dataset query id to return the paths of all pools and child datasets on the system.

threshold defaults to 35 days. To preserve system resources, the scrub runs only if time since the pool was last scrubbed is greater than the threshold value. To override the threshold and run immediately, you can use threshold=0.

Enter the full command string and then press Enter. run returns an empty line. To check if the scrub starts successfully, you can use system alert list to view system alerts.

Usage

From the CLI prompt, enter:

storage scrub run name="tank"

Where tank is the name of the pool you want to scrub. Press Enter.

Command Example 
storage scrub run name="tank" threshold=35

Scrub Command

The scrub command allows you to start a one-time scrub task for the selected pool and to pause or stop an active scrub.

Using the Scrub Command

Description

scrub has two required properties, name and action. To find the name of the pool you want to scrub, use storage pool query or storage dataset query id to return the paths of all pools and child datasets on the system.

There are three possible values for action:

  • START
  • PAUSE
  • STOP

Enter the full command string and then press Enter. Returns the percentage status of action.

Usage

From the CLI prompt, enter:

storage scrub scrub name="tank" action=START

Where tank is the name of the selected pool and START is one of the three possible actions. Press Enter.

Command Examples

START 

storage scrub scrub name="tank" action=START
[0%] ...
[0%] Scrubbing...
[1%] Scrubbing...
[4%] Scrubbing...
...
[98%] Scrubbing...
[99%] Scrubbing...
[100%] Scrub finished...

<h4 id="pause"
>
    <code>PAUSE</code>
    <a data-clipboard-text="" class="gdoc-page__anchor clip flex align-center" title="Anchor to: PAUSE" aria-label="Anchor to: PAUSE" href="#pause">
        <svg class="gdoc-icon gdoc_link"><use xlink:href="#gdoc_link"></use></svg>
    </a>
</h4>

storage scrub scrub name="tank" action=PAUSE
[0%] ...
[100%] ...

<h4 id="stop"
>
    <code>STOP</code>
    <a data-clipboard-text="" class="gdoc-page__anchor clip flex align-center" title="Anchor to: STOP" aria-label="Anchor to: STOP" href="#stop">
        <svg class="gdoc-icon gdoc_link"><use xlink:href="#gdoc_link"></use></svg>
    </a>
</h4>

storage scrub scrub name="tank" action=STOP
[100%] ...

Update Command

The update command allows you to change the configuration of an existing scheduled scrub task.

Using the Update Command

Description

update has one required property, id, and eight optional properties. Use query to view the id numbers for existing scheduled scrub tasks. For optional properties, see the create properties.

Enter the command string with any optional properties you want to update and then press Enter.

Usage

From the CLI prompt, enter:

storage scrub update id=1 property=value

Where 1 is the id of the scrub task to update, property is one of the configuration properties, and value is the new setting for that property. Press Enter.

update returns an empty line. Use query or get_instance to confirm the new settings are applied.

Command Example 
storage scrub update id=1 enabled=false

Related Content

SCALE Tutorials
SCALE UI Reference

Have more questions?

For further discussion or assistance, see these resources:

Found content that needs an update?  You can suggest content changes directly! To request changes to this content, click the Feedback button located on the middle-right side of the page (might require disabling ad blocking plugins).