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. System
  8. /
  9. Tunable
Edit page

Tunable

  6 minute read.

Last Modified 2023-11-30 10:15 EST

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!

Tunable Namespace

The tunable namespace has six commands, and is based on tuned settings functions found in the SCALE API and web UI. It provides access to tunable configuration methods through the tunable namespace commands.

Tunable Commands

The following tunable namespace commands allow you to create and manage tuned settings. Tunables configure kernel parameters while the system is running. Configured settings generally take effect immediately.

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

Create Command

The create command allows you to configure a new tunable.

Using the Create Command

Description

create has three required and three optional properties (see table below). Enter the command string with all required and any optional properties you want and then press Enter. create returns the percent complete status of the tunable create job.

Create Properties
PropertyRequiredDescriptionSyntax Example
typeYesEnter the type of tunable to configure. Options are SYSCTL, UDEV, or ZFS.type=SYSCTL
varYesEnter the name of the variable to configure. If type is:
  • SYSCTL then var is a sysctl name (e.g. kernel.watchdog).
  • UDEV then var is an udev rules file name (e.g. 10-disable-usb). Automatically adds the .rules suffix to the file name.
  • ZFS then var is a ZFS kernel module parameter name (e.g. zfs_dirty_data_max_max).
var=kernel.watchdog
valueYesEnter the value of the variable. If type is:
  • SYSCTL then value is the corresponding value (e.g. 0) for the sysctl name in var.
  • UDEV then value is the contents (e.g. BUS==“usb”, OPTIONS+=“ignore_device”) of the udev rules file in var.
  • ZFS then value is the corresponding value for the ZFS kernel module parameter in var.
value=0
commentNoEnter a human-readable description for the tunable.comment=TunableDescription
enabledNoIf enabled is false, creates and saves the tunable without activating it. Update to false to disable a tunable without deleting it. Defaults to true.enabled=true
update_initramfsNoIf update_initramfs is false, initramfs is not updated after creating a ZFS tunable. If needed, use update on an existing tunable to reconfigure update_initramfs to true.update_initramfs=true

Usage

From the CLI prompt, enter:

system tunable create type=SYSCTL var="kernel.watchdog" value="0"

Where

  • SYSCTL is the type of tunable
  • kernel.watchdog is the name of the variable to configure
  • 0 is the value of the named variable.

Command Example 
system tunable create type=SYSCTL var="kernel.watchdog" value="0" comment="Watchdog" enabled=true update_initramfs=true
[0%] ...
[100%] ...

Delete Command

The delete command removes a configured tunable from the system.

Using the Delete Command

Description

delete has one required property, id. Use query to find the id number of the tunable to remove. Enter the command then press Enter. delete returns the percent complete status of the delete task.

Usage

From the CLI prompt, enter:

system tunable delete id=1

Where 1 is the id number of the tunable to delete.

Command Example 
system tunable delete id=1
[0%] ...
[100%] ...

Get_instance Command

The get_instance command allows you to inspect the configuration of an existing tunable.

Using the Get_instance Command

Description

get_instance has one required property, id. Use query to find the id number of the tunable to inspect. Enter the command then press Enter. get_instance returns a table containing configured settings for the tunable matching id.

Usage

From the CLI prompt, enter:

system tunable get_instance id=1

Where 1 is the id of the tunable to query.

Command Example 
system tunable get_instance id=1
+------------+-----------------+
|         id | 1               |
|       type | SYSCTL          |
|        var | kernel.watchdog |
|      value | 0               |
| orig_value | 1               |
|    comment | Watchdog        |
|    enabled | true            |
+------------+-----------------+

Query Command

The query command allows you to inspect all tuned settings on the system.

Using the Query Command

Description

query does not require entering properties or arguments. Enter the command and then press Enter. query returns a table containing all configured tunable settings.

Usage

From the CLI prompt, enter:

system tunable query

Command Example 
system tunable query
+----+--------+------------------------+-----------+------------+----------+---------+
| id | type   | var                    | value     | orig_value | comment  | enabled |
+----+--------+------------------------+-----------+------------+----------+---------+
| 2  | ZFS    | zfs_dirty_data_max_max | 783091712 | 2076269568 |          | true    |
| 3  | SYSCTL | kernel.watchdog        | 0         | 1          | Watchdog | true    |
+----+--------+------------------------+-----------+------------+----------+---------+

Tunable_type_choices Command

The tunable_type_choices command allows you to view the available tunable types.

Using the Tunable_type_choices Command

Description

tunable_type_choices does not require entering properties or arguments. Enter the command and then press Enter. tunable_type_choices returns a table containing the available choices.

Usage

From the CLI prompt, enter:

system tunable tunable_type_choices

Command Example 
system tunable tunable_type_choices
+--------+--------+
| SYSCTL | SYSCTL |
|   UDEV | UDEV   |
|    ZFS | ZFS    |
+--------+--------+

Update Command

The update command allows you to reconfigure an existing tuned setting.

Using the Update Command

Description

update has one required property, id, and four optional properties (see table below). Use query to find the id number of the tunable to update. Enter the command string with the required property and any optional properties to change. Separate multiple property and value pairs with a space. Then press Enter. update returns the percent complete status of the update task.

Update Properties
PropertyRequiredDescriptionSyntax Example
idYesEnter the id number of an existing tuned setting. Use query to find the id number of the tunable to update.id=1
valueNoEnter the new value for the existing type and variable (var) matching id. If type is:
  • SYSCTL then value is the corresponding value (e.g. 0) for the sysctl name in var.
  • UDEV then value is the contents (e.g. BUS==“usb”, OPTIONS+=“ignore_device”) of the udev rules file in var.
  • ZFS then value is the corresponding value for the ZFS kernel module parameter in var.
value=0
commentNoEnter a human-readable description for the tunable.comment=TunableDescription
enabledNoUpdate enabled to false to disable a tunable without deleting it.enabled=true
update_initramfsNoSet to false to update the tuned setting but not update initramfs. To to update initramfs for an existing tunable (if false at creation), reconfigure update_initramfs to true.update_initramfs=true

Usage

From the CLI prompt, enter:

system tunable update id=1 PROPERTY=VALUE

Where:

  • 1 is the id of an existing tuned setting
  • PROPERTY is an optional property to update
  • VALUE is the new setting for that property.

Command Example 
system tunable update id=3 value=1 comment=KernelWatchdog
[0%] ...
[100%] ...

Related Content

SCALE CLI Reference

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).