qs_systemtunables.conf

From OSNEXUS Online Documentation Site
Revision as of 07:23, 3 September 2026 by Qadmin (talk | contribs) (Link the touch-file and configuration-file pages that own those topics (QSTOR-12429))
Jump to navigation Jump to search


qs_systemtunables.conf declares the Storage System tuning parameters -- the tunables -- that QuantaStor exposes in the Storage System Optimization dialog. Each section of the file defines one tunable: its identifier, the label and help text the dialog shows, the kernel parameter it writes, and its accepted range and shipped default. The file is read once, when the QuantaStor service starts, so it is both the reference for what a tunable does and the place to change which tunables a site exposes.

Location and precedence

The file QuantaStor ships is: 

/opt/osnexus/quantastor/conf/qs_systemtunables.conf

That copy is replaced on every upgrade. It belongs to the QuantaStor service package and is not registered as a Debian conffile, so the package manager overwrites it without prompting and without leaving the previous version behind. An edit made in place is lost silently the next time the package is upgraded.

To change the file and keep the change, put your copy in an override location instead. QuantaStor checks these paths in order and reads the first one that exists:

Order Path Notes
1 /var/opt/osnexus/quantastor/conf/qs_systemtunables.conf The preferred override. It sits outside the package, so an upgrade never touches it.
2 /var/opt/osnexus/quantastor/conf/qs_systemtunables.conf.override Equivalent to 1; use whichever name suits your configuration management.
3 /opt/osnexus/quantastor/conf/qs_systemtunables.conf.override Honoured, but it lives in the package's own directory. Prefer 1 or 2.
4 /opt/osnexus/quantastor/conf/qs_systemtunables.conf The shipped file, used when no override is present.

Precedence is per file, not per tunable: an override replaces the shipped file rather than merging with it. Exactly one of those four paths is read, so an override has to be a complete copy of the tunable set. Start from the shipped file: 

sudo cp /opt/osnexus/quantastor/conf/qs_systemtunables.conf /var/opt/osnexus/quantastor/conf/qs_systemtunables.conf

Two consequences follow from that:

  • A tunable missing from the file in force is removed from the Storage System, along with any value stored for it. Dropping a section is how a tunable is retired, and an override behaves the same way -- a hand-written override listing only the settings you care about deletes all the others.
  • An override does not pick up tunables added in a later release. Re-base it on the newly shipped file after each upgrade, or the Storage System keeps only the tunables your copy lists.

There is one safety net. If the file in force yields fewer than two valid tunables, the load is abandoned, the tunable set already stored for the Storage System is left untouched, and the service log records: 

Failed to properly load Storage System Tunables, no valid tunables found in config file '<path>'

The service log is /var/log/qs/qs_service.log, and it names the path that was actually selected on each start, which is the quickest way to confirm an override is being read: 

Merging '33' Storage System Tunables from configuration '/opt/osnexus/quantastor/conf/qs_systemtunables.conf'.

File format

The file is INI style: one section per tunable, and one key=value pair per line within it. 

[sst_cache_size]
tab=cache_settings
param=/sys/module/zfs/parameters/zfs_arc_max
title="Cache Size (% of RAM)"
desc="Sets the percentage of the system's RAM available as in-memory read cache for use by all Storage Pools."
type=percentage
min=30
max=90
default=70

The section name is the tunable's identifier and it must begin with sst_. That prefix is how the CLI and the profile parser tell a QuantaStor tunable from a raw kernel parameter name, so a section without it cannot be addressed by name.

Parsing rules worth knowing:

  • A line is a comment only when # is the first character on the line. An indented # is not a comment, and there is no end-of-line comment syntax -- a # after a value becomes part of the value.
  • A section header is recognised the same way, so an indented [section] is not a section.
  • Everything up to the first = is the key and everything after it is the value. Both are trimmed, so surrounding spaces do not matter, and a value may itself contain =.
  • Double quote characters are removed as the file is read. Quoting title and desc is the house convention rather than a requirement, and a quote cannot be part of a value.
  • Blank lines are ignored. A line longer than 1024 characters is skipped, with a warning in the service log.
  • Within a tab, settings appear in the dialog in the order their sections appear in the file.
  • The [globals] section at the top of the shipped file holds no keys and the loader skips it by name. It is a placeholder -- keys added there have no effect.

Tunable keys

Key Required Purpose
tab yes Which tab of the dialog the setting appears on. The set is fixed by the web interface: general_settings, cache_settings, pool_settings, network_settings, volume_settings, driver_settings. A tunable carrying any other value loads and is reachable from the CLI, but no tab is rendered for it, so it never appears in the dialog.
param yes The kernel parameter the setting writes, given as a full path such as /sys/module/zfs/parameters/zfs_arc_max. Set param=deprecated to retire a tunable -- see Deprecated tunables.
title yes The label shown in the dialog and in qs tunable-list.
desc yes The help text shown for the setting. Naming the underlying kernel parameter in the text is the existing convention and worth following, because it is the only place a reader sees it.
type yes range for a numeric slider, percentage for a slider expressed as a percentage, boolean for a checkbox. The value is matched loosely: any value containing bool gives a checkbox, one containing percent or % gives a percentage, and anything else gives a range.
min / max yes The permitted range, in display units. The dialog will not offer a value outside it, the CLI rejects one, and a profile value outside it is skipped.
default yes The shipped default, and the value the Default profile restores. It must fall within min and max.
param_units / display_units no Used when the kernel parameter's unit differs from the unit to present. param_units=B with display_units=MB lets an administrator work in megabytes while the parameter is written in bytes. Recognised units are B, KB, MB, GB and PB (the KiB style spellings are accepted too). An unrecognised token is treated as bytes.
rounding no rounding=base2_power rounds the value up to the next power of two before it is written. Used by I/O Aggregation Limit (KB), where ZFS expects a power-of-two size.
module_conf no Present when the setting is a driver module parameter that cannot be changed on a running system. QuantaStor writes an options <module> <parameter>=<value> line into the named file -- /etc/modprobe.d/spl.conf for the three Driver Settings -- then rebuilds the initramfs and raises an alert saying a reboot is required. Without this key the parameter is written directly and takes effect immediately.

Tunable reference

The dialog groups the tunables into six tabs, one per tab value. The tables below are generated from /opt/osnexus/quantastor/conf/qs_systemtunables.conf, so each range and default is the shipped value; use qs tunable-list to see what a particular Storage System is running.

General Settings

Storage System Optimization, General Settings tab.
Tunable Setting Range Default What it does
sst_resilver_min_time_ms Resilver Priority (msec/TXG) 500 – 8000 3000 Higher settings indicates more time should be dedicated to resilvering between transaction groups (zfs_resilver_min_time_ms).
sst_rep_prefetch Remote Replication Prefetch (MB) 4 – 128 MB 50 MB Improves performance of replication send operations by prefetching data from disk (units in MB). Reducing this may reduce latency for systems replicating during production hours. (zfs_pd_bytes_max)
sst_cleanup_priority Cleanup Priority (% of TXG) 5 – 90 30 Controls the maximum amount of dirty blocks to be freed as a percentage of each transaction group. Increase to give high priority to cleanup operations like file deletion.
sst_limit_active_async_writes Limit Active Async Writes 5 – 50 30 Limit active asynchronous writes based on dirty percent. This can help with write latency and resilver performance when set to a value between 10 and 30.
sst_commit_timeout Transaction Group (TXG) Commit Timeout 5 – 90 10 Percentage of dirty data at which the transaction group commit timeout is reduced to 1 second to speed up commits and reduce latency. Default is 10% which means that once the dirty data reaches 10% of RAM the system will start aggressively committing transaction groups to keep latency low.
sst_max_ms_shift Pool Metaslab Shift 28 – 38 34 Controls the size of metaslabs used for space allocation. Larger metaslabs can improve performance on large pools but may lead to fragmentation and reduced performance over time if set too high.
sst_ms_count_limit Pool Metaslab Count Limit 1024 – 262144 131072 Limits the number of metaslabs that can be allocated for a single IO operation. Increasing this can improve performance for large IO operations on large pools.
sst_lba_weighting Pool Metaslab LBA Weighting on / off on Enabling LBA weighting allows the allocator to prefer lower LBAs for better performance. This can be beneficial for some workloads but may lead to increased fragmentation over time.
sst_metaslab_aliquot Metaslab Aliquot 64 – 32768 KB 1024 KB Controls the size of metaslab aliquots used for space allocation. Larger aliquots can improve performance on large pools but may lead to fragmentation and reduced performance over time if set too high.
sst_zfetch_max_distance Read-Ahead Distance Max (MB) 8 – 512 MB 64 MB Maximum distance in bytes that the ZFS prefetcher will read ahead. Increasing this can improve performance for sequential read workloads.
sst_zfetch_min_distance Read-Ahead Distance Min (MB) 0 – 128 MB 4 MB Minimum distance in bytes that the ZFS prefetcher will read ahead. Reducing this can improve performance for workloads with smaller sequential read patterns.

Kernel parameters set by this tab: 

/sys/module/zfs/parameters/zfs_resilver_min_time_ms
/sys/module/zfs/parameters/zfs_pd_bytes_max
/sys/module/zfs/parameters/zfs_per_txg_dirty_frees_percent
/sys/module/zfs/parameters/zfs_vdev_async_write_active_min_dirty_percent
/sys/module/zfs/parameters/zfs_commit_timeout_pct
/sys/module/zfs/parameters/zfs_vdev_max_ms_shift
/sys/module/zfs/parameters/zfs_vdev_ms_count_limit
/sys/module/zfs/parameters/metaslab_lba_weighting_enabled
/sys/module/zfs/parameters/metaslab_aliquot
/sys/module/zfs/parameters/zfetch_max_distance
/sys/module/zfs/parameters/zfetch_min_distance

Cache Settings

Storage System Optimization, Cache Settings tab.
Tunable Setting Range Default What it does
sst_cache_size Cache Size (% of RAM) 30 – 90 70 Sets the percentage of the system's RAM available as in-memory read cache for use by all Storage Pools.
sst_write_queue_data_max Write Throttle Limit (% of RAM) 3 – 20 10 Percentage of system RAM allocated for dirty data which after exeeded halts further writes until enough has flushed to free up more space in RAM. (controls zfs_dirty_data_max).
sst_write_flush_rate_percent Write Flush Threshold (% of Write Queue RAM) 5 – 80 20 Percentage of write queue filled at which transaction group syncing is ensured. Reducing this can improve IOPS.(zfs_dirty_data_sync_percent)
sst_write_flush_rate_sec Write Flush Threshold (sec) 1 – 10 5 Once the threshold has been reached a new transaction group will be started. Reducing this can improve IOPS.(zfs_txg_timeout)
sst_vdev_async_write_min_active Async Write - Min Active I/Os 1 – 5 2 Minimum asynchronous write I/Os active to each VDEV (zfs_vdev_async_write_min_active). Lower values generally improve latency on rotational media and hurt resilver performance.
sst_cache_compression Cache Compression on / off on Compresses ARC data to increase the effective size of the in-memory read cache for Storage Pools.(zfs_compressed_arc_enabled)
sst_prefetch_disable Prefetch Disable on / off off In cases where the IO patterns is predominantly random reads performance may be improved by disabling prefetch.(zfs_prefetch_disable)

Kernel parameters set by this tab: 

/sys/module/zfs/parameters/zfs_arc_max
/sys/module/zfs/parameters/zfs_dirty_data_max
/sys/module/zfs/parameters/zfs_dirty_data_sync_percent
/sys/module/zfs/parameters/zfs_txg_timeout
/sys/module/zfs/parameters/zfs_vdev_async_write_min_active
/sys/module/zfs/parameters/zfs_compressed_arc_enabled
/sys/module/zfs/parameters/zfs_prefetch_disable

Pool Settings

Storage System Optimization, Pool Settings tab.
Tunable Setting Range Default What it does
sst_spdg_queue_depth Aggregate Per-Device Active I/O Limit 256 – 4096 2000 Maximum number of IO operations active per VDEV. Acts as a global cap of the sum of all sync/async read/write IOs and scrub/resilver classes of IO.
sst_sync_read_queue Read Queue Depth (sync I/O) 4 – 128 32 Maximum number of synchronous read IO operations active per VDEV. (zfs_vdev_sync_read_max_active)
sst_sync_write_queue Write Queue Depth (sync I/O) 4 – 128 32 Maximum number of synchronous direct write IO operations active per VDEV. (zfs_vdev_sync_write_max_active)
sst_async_read_queue Read Queue Depth (async I/O) 4 – 128 32 Maximum number of asynchronous read IO operations active per VDEV. (zfs_vdev_async_read_max_active)
sst_async_write_queue Write Queue Depth (async I/O) 2 – 128 32 Maximum asynchronous write I/Os active to each VDEV (zfs_vdev_async_write_max_active). Reducing max-active can improve latency under contention, but it can also lower throughput.
sst_spdg_aggregation_limit I/O Aggregation Limit (KB) 128 – 32768 KB 128 KB Sets the VDEV upper bound on I/O coalescence/aggregation for a stripe of data. Increasing this value to 1M or larger may increase throughput for sequential I/O workloads. (zfs_vdev_aggregation_limit)
sst_vdev_scrub_max_active Scrub Queue Depth - Max Active I/Os 1 – 32 3 Maximum scrub or scan read I/Os active to each VDEV (zfs_vdev_scrub_max_active). Increasing this can speed up scrub and scan operations, but may increase impact on client workloads.
sst_vdev_scrub_min_active Scrub Queue Depth - Min Active I/Os 1 – 8 1 Minimum scrub or scan read I/Os active to each VDEV (zfs_vdev_scrub_min_active). Lower values reduce impact on production I/O, while higher values can improve scrub progress when the pool is busy.
sst_spdg_default_queue_depth I/O Allocator Default Queue Depth 2 – 1024 32 Default queue depth for each VDEV IO allocator. Higher values allow for better coalescing of sequential writes before sending them to the disk, but can increase transaction commit times. (zfs_vdev_def_queue_depth)

Kernel parameters set by this tab: 

/sys/module/zfs/parameters/zfs_vdev_max_active
/sys/module/zfs/parameters/zfs_vdev_sync_read_max_active
/sys/module/zfs/parameters/zfs_vdev_sync_write_max_active
/sys/module/zfs/parameters/zfs_vdev_async_read_max_active
/sys/module/zfs/parameters/zfs_vdev_async_write_max_active
/sys/module/zfs/parameters/zfs_vdev_aggregation_limit
/sys/module/zfs/parameters/zfs_vdev_scrub_max_active
/sys/module/zfs/parameters/zfs_vdev_scrub_min_active
/sys/module/zfs/parameters/zfs_vdev_def_queue_depth

Network Settings

Storage System Optimization, Network Settings tab.
Tunable Setting Range Default What it does
sst_net_queue_length Network TX/RX Queue Length 1000 – 20000 5000 Sets the transmit and receive network queue length for high-speed network ports (10GbE and faster). Values like 5000 and higher are recommended for systems with 10GbE and faster networking. (txqueuelen)
sst_netdev_max_backlog Network Device Max Backlog 128 – 1000000 1000 Maximum number of packets allowed to queue on the input side when the interface receives data faster than the kernel can process it. (netdev_max_backlog)

Kernel parameters set by this tab: 

ip.link.txqueuelen
/proc/sys/net/core/netdev_max_backlog

Volume Settings

Storage System Optimization, Volume Settings tab.
Tunable Setting Range Default What it does
sst_zvol_request_sync Storage Volume sync IO mode on / off on Storage Volume (ZVOL) sync mode can be ON(1) or OFF(0), default is ON.

Kernel parameters set by this tab: 

/sys/module/zfs/parameters/zvol_request_sync

Driver Settings

Storage System Optimization, Driver Settings tab.
Tunable Setting Range Default What it does
sst_kmem_cache_kmem_threads KMEM Cache Threads 1 – 16 4 Number of threads used for KMEM cache operations. Increasing this can improve performance for workloads with high levels of concurrent allocations and frees.
sst_kmem_cache_obj_per_slab KMEM Cache Objects Per Slab 8 – 128 8 Number of objects per slab in the KMEM cache. Increasing this can improve performance for workloads with many small allocations.
sst_kmem_cache_max_size KMEM Cache Max Size (MB) 32 – 2048 MB 32 MB Maximum size of the KMEM cache in megabytes. Increasing this can improve performance for workloads with high memory usage.

Kernel parameters set by this tab: 

/sys/module/spl/parameters/spl_kmem_cache_kmem_threads
/sys/module/spl/parameters/spl_kmem_cache_obj_per_slab
/sys/module/spl/parameters/spl_kmem_cache_max_size

Deprecated tunables

A section whose param is the literal value deprecated is not loaded, and any row already stored for it is removed from the Storage System's tunable list. Two identifiers have been retired this way:

  • sst_resilver_prio -- superseded by Resilver Priority (msec/TXG) (sst_resilver_min_time_ms)
  • sst_write_flush_rate_mb -- superseded by Write Flush Threshold (% of Write Queue RAM) (sst_write_flush_rate_percent)

The sections are kept in the file to record that those identifiers are spent. Do not reuse them, and do not reference them from a profile -- a profile entry naming a tunable that does not load is skipped.

What the service rejects

The file is validated a section at a time, and a bad section is skipped rather than aborting the load, so one mistake does not cost you the rest of the file. A section is skipped, with an error naming it in /var/log/qs/qs_service.log, when:

  • title, desc or tab is missing;
  • default falls outside min and max;
  • min, max and default are all zero or all absent;
  • the section name duplicates one already read from the file.

Two further behaviours are worth knowing because they look like something reverting on its own:

  • A stored value that falls outside a new min/max range is reset to the default when the file is next read, and the service log names both the old and the new value. Narrowing a range therefore silently re-tunes any system whose value sat outside it.
  • A profile value outside the range is skipped, not clamped. The rest of the profile still applies. This is covered on Storage System Optimization along with the log message to look for.

When a change takes effect

The file is read once, while the QuantaStor service starts. There is no periodic re-read and no reload command, so an edit needs a service restart before it is seen: 

systemctl restart quantastor

Immediately after loading the file, QuantaStor writes every tunable's stored value out to its kernel parameter. That is what makes the settings survive a reboot, and it is why a tunable that is missing its param path only produces a warning rather than an error.

What a restart does and does not change:

  • Changing default does not change the value a Storage System is running. Values are stored per Storage System in the configuration database, and a stored value always wins over the file's default. A new default reaches a system that has no stored value for that tunable yet, and it is what the Default profile restores -- so applying Default after the restart is how you pick up a changed default on an existing system.
  • Changing min or max can change a running value, because a stored value outside the new range is reset to the default.
  • Adding a section adds the tunable at its default. Removing one removes the tunable and its stored value.
  • Changing title, desc, tab or the units only affects presentation.

For troubleshooting, the step that writes the values out to the kernel can be suppressed altogether with the touch file tf_storage_system_tunables.disable: the tunables still load and still show their stored values, but no kernel parameter is written, which leaves the dialog reporting settings the system is not applying. Touch files are for use only with guidance from OSNEXUS support -- see QuantaStor Touch Files.

Relationship to qs_systemprofiles.conf

qs_systemprofiles.conf, in the same directory, holds the pre-canned Optimization Profiles -- named sets of tunable values. The two files divide the work cleanly: this file declares which tunables exist and what each one's range and default are, and the profiles file only picks values for tunables declared here. A profile entry naming a tunable this file does not define is skipped, and so is one whose value falls outside the range this file sets. Profiles are covered on Storage System Optimization.

Reading and setting tunable values

Values are read and changed from the dialog or the CLI, not by editing this file -- editing it changes the tunable definitions, which is a different job. qs tunable-list lists every tunable on every Storage System in the grid with its current value, default and range, and qs tunable-get --tunable=<sst_name> shows one in full, including its tab and parameter path. See Storage System Optimization for the dialog itself and the full set of tunable and profile commands.

Related pages

Verified against QuantaStor 6.9.0.

Retrieved from "https://wiki.osnexus.com/index.php?title=Qs_systemtunables.conf&oldid=27670"