Qadmin: Link the touch-file and configuration-file pages that own those topics (QSTOR-12429)

2026-09-03T07:23:50Z

Link the touch-file and configuration-file pages that own those topics (QSTOR-12429)

← Older revision		Revision as of 07:23, 3 September 2026
Line 335:		Line 335:
	* Changing {{Code\|1=title}}, {{Code\|1=desc}}, {{Code\|1=tab}} or the units only affects presentation.		* Changing {{Code\|1=title}}, {{Code\|1=desc}}, {{Code\|1=tab}} or the units only affects presentation.

	For troubleshooting, the step that writes the values out to the kernel can be suppressed ~~entirely by creating~~ the file {{Code\|1=~~/var/opt/osnexus/quantastor/touchfiles/~~tf_storage_system_tunables.disable}}~~. The~~ tunables still load and still show their stored values, but no kernel parameter is written~~. We recommend contacting OSNEXUS support before using it~~, ~~since it~~ leaves the dialog reporting settings the system is not applying.		For troubleshooting, the step that writes the values out to the kernel can be suppressed altogether with the touch file {{Code\|1=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 ==		== Relationship to qs_systemprofiles.conf ==
Line 348:		Line 348:

	* [[Storage System Optimization]] -- the dialog these tunables appear in, the Optimization Profiles, and the CLI commands that set them		* [[Storage System Optimization]] -- the dialog these tunables appear in, the Optimization Profiles, and the CLI commands that set them
			* [[QuantaStor Configuration Files]] -- the other configuration files under the same directory
			* [[Performance Tuning]] -- choosing what to tune, and measuring the result
	* [[Storage System]] -- the rest of the Storage System level configuration		* [[Storage System]] -- the rest of the Storage System level configuration

	----		----
	<small>''Verified against QuantaStor 6.9.0.''</small>		<small>''Verified against QuantaStor 6.9.0.''</small>

Qadmin: New page: qs_systemtunables.conf configuration file reference; tunables reference moved here from Storage System Optimization (QSTOR-12429)

2026-09-03T07:21:00Z

New page: qs_systemtunables.conf configuration file reference; tunables reference moved here from Storage System Optimization (QSTOR-12429)

New page

[[Category:admin_guide]]
{{DISPLAYTITLE:qs_systemtunables.conf}}

{{Code|1=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|Location and precedence]] -- which copy of the file wins, and how to make a local change survive an upgrade
* [[#File format|File format]] -- sections, keys, comments and quoting
* [[#Tunable keys|Tunable keys]] -- every key a section accepts
* [[#Tunable reference|Tunable reference]] -- all 33 shipped tunables, by dialog tab, with ranges and defaults
* [[#Deprecated tunables|Deprecated tunables]] -- identifiers that have been retired
* [[#What the service rejects|What the service rejects]] -- how a malformed or out-of-range entry is handled
* [[#When a change takes effect|When a change takes effect]] -- and what a change to a default does not do
* [[#Relationship to qs_systemprofiles.conf|Relationship to qs_systemprofiles.conf]]
* [[#Reading and setting tunable values|Reading and setting tunable values]]

== Location and precedence ==

The file QuantaStor ships is:

<pre style="font-size: smaller">
/opt/osnexus/quantastor/conf/qs_systemtunables.conf
</pre>

'''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:

{| class="wikitable"
! Order !! Path !! Notes
|-
| 1 || {{Code|1=/var/opt/osnexus/quantastor/conf/qs_systemtunables.conf}} || The preferred override. It sits outside the package, so an upgrade never touches it.
|-
| 2 || {{Code|1=/var/opt/osnexus/quantastor/conf/qs_systemtunables.conf.override}} || Equivalent to 1; use whichever name suits your configuration management.
|-
| 3 || {{Code|1=/opt/osnexus/quantastor/conf/qs_systemtunables.conf.override}} || Honoured, but it lives in the package's own directory. Prefer 1 or 2.
|-
| 4 || {{Code|1=/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:

<pre style="font-size: smaller">
sudo cp /opt/osnexus/quantastor/conf/qs_systemtunables.conf /var/opt/osnexus/quantastor/conf/qs_systemtunables.conf
</pre>

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:

<pre style="font-size: smaller">
Failed to properly load Storage System Tunables, no valid tunables found in config file '<path>'
</pre>

The service log is {{Code|1=/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:

<pre style="font-size: smaller">
Merging '33' Storage System Tunables from configuration '/opt/osnexus/quantastor/conf/qs_systemtunables.conf'.
</pre>

== File format ==

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

<pre style="font-size: smaller">
[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
</pre>

The section name is the tunable's identifier and it '''must''' begin with {{Code|1=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 {{Code|1=#}} is the first character on the line.''' An indented {{Code|1=#}} is not a comment, and there is no end-of-line comment syntax -- a {{Code|1=#}} after a value becomes part of the value.
* A section header is recognised the same way, so an indented {{Code|1=[section]}} is not a section.
* Everything up to the first {{Code|1==}} 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 {{Code|1==}}.
* Double quote characters are removed as the file is read. Quoting {{Code|1=title}} and {{Code|1=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 {{Code|1=[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 ==

{| class="wikitable"
! Key !! Required !! Purpose
|-
| {{Code|1=tab}} || yes || Which tab of the dialog the setting appears on. The set is fixed by the web interface: {{Code|1=general_settings}}, {{Code|1=cache_settings}}, {{Code|1=pool_settings}}, {{Code|1=network_settings}}, {{Code|1=volume_settings}}, {{Code|1=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.
|-
| {{Code|1=param}} || yes || The kernel parameter the setting writes, given as a full path such as {{Code|1=/sys/module/zfs/parameters/zfs_arc_max}}. Set {{Code|1=param=deprecated}} to retire a tunable -- see [[#Deprecated tunables|Deprecated tunables]].
|-
| {{Code|1=title}} || yes || The label shown in the dialog and in {{Code|1=qs tunable-list}}.
|-
| {{Code|1=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.
|-
| {{Code|1=type}} || yes || {{Code|1=range}} for a numeric slider, {{Code|1=percentage}} for a slider expressed as a percentage, {{Code|1=boolean}} for a checkbox. The value is matched loosely: any value containing {{Code|1=bool}} gives a checkbox, one containing {{Code|1=percent}} or {{Code|1=%}} gives a percentage, and anything else gives a range.
|-
| {{Code|1=min}} / {{Code|1=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.
|-
| {{Code|1=default}} || yes || The shipped default, and the value the '''Default''' profile restores. It must fall within {{Code|1=min}} and {{Code|1=max}}.
|-
| {{Code|1=param_units}} / {{Code|1=display_units}} || no || Used when the kernel parameter's unit differs from the unit to present. {{Code|1=param_units=B}} with {{Code|1=display_units=MB}} lets an administrator work in megabytes while the parameter is written in bytes. Recognised units are {{Code|1=B}}, {{Code|1=KB}}, {{Code|1=MB}}, {{Code|1=GB}} and {{Code|1=PB}} (the {{Code|1=KiB}} style spellings are accepted too). An unrecognised token is treated as bytes.
|-
| {{Code|1=rounding}} || no || {{Code|1=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.
|-
| {{Code|1=module_conf}} || no || Present when the setting is a driver module parameter that cannot be changed on a running system. QuantaStor writes an {{Code|1=options <module> <parameter>=<value>}} line into the named file -- {{Code|1=/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 {{Code|1=tab}} value. The tables below are generated from {{Code|1=/opt/osnexus/quantastor/conf/qs_systemtunables.conf}}, so each range and default is the shipped value; use {{Code|1=qs tunable-list}} to see what a particular Storage System is running.

=== General Settings ===

[[File:ssopt_general.png|thumb|right|650px|Storage System Optimization, General Settings tab.]]

{| class="wikitable"
! Tunable !! Setting !! Range !! Default !! What it does
|-
| {{Code|1=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).
|-
| {{Code|1=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)
|-
| {{Code|1=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.
|-
| {{Code|1=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.
|-
| {{Code|1=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.
|-
| {{Code|1=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.
|-
| {{Code|1=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.
|-
| {{Code|1=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.
|-
| {{Code|1=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.
|-
| {{Code|1=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.
|-
| {{Code|1=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:

<pre style="font-size: smaller">
/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
</pre>

=== Cache Settings ===

[[File:ssopt_cache.png|thumb|right|650px|Storage System Optimization, Cache Settings tab.]]

{| class="wikitable"
! Tunable !! Setting !! Range !! Default !! What it does
|-
| {{Code|1=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.
|-
| {{Code|1=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).
|-
| {{Code|1=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)
|-
| {{Code|1=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)
|-
| {{Code|1=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.
|-
| {{Code|1=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)
|-
| {{Code|1=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:

<pre style="font-size: smaller">
/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
</pre>

=== Pool Settings ===

[[File:ssopt_pool.png|thumb|right|650px|Storage System Optimization, Pool Settings tab.]]

{| class="wikitable"
! Tunable !! Setting !! Range !! Default !! What it does
|-
| {{Code|1=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.
|-
| {{Code|1=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)
|-
| {{Code|1=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)
|-
| {{Code|1=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)
|-
| {{Code|1=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.
|-
| {{Code|1=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)
|-
| {{Code|1=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.
|-
| {{Code|1=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.
|-
| {{Code|1=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:

<pre style="font-size: smaller">
/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
</pre>

=== Network Settings ===

[[File:ssopt_network.png|thumb|right|650px|Storage System Optimization, Network Settings tab.]]

{| class="wikitable"
! Tunable !! Setting !! Range !! Default !! What it does
|-
| {{Code|1=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)
|-
| {{Code|1=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:

<pre style="font-size: smaller">
ip.link.txqueuelen
/proc/sys/net/core/netdev_max_backlog
</pre>

=== Volume Settings ===

[[File:ssopt_volume.png|thumb|right|650px|Storage System Optimization, Volume Settings tab.]]

{| class="wikitable"
! Tunable !! Setting !! Range !! Default !! What it does
|-
| {{Code|1=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:

<pre style="font-size: smaller">
/sys/module/zfs/parameters/zvol_request_sync
</pre>

=== Driver Settings ===

[[File:ssopt_driver.png|thumb|right|650px|Storage System Optimization, Driver Settings tab.]]

{| class="wikitable"
! Tunable !! Setting !! Range !! Default !! What it does
|-
| {{Code|1=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.
|-
| {{Code|1=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.
|-
| {{Code|1=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:

<pre style="font-size: smaller">
/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
</pre>
== Deprecated tunables ==

A section whose {{Code|1=param}} is the literal value {{Code|1=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:

* {{Code|1=sst_resilver_prio}} -- superseded by '''Resilver Priority (msec/TXG)''' ({{Code|1=sst_resilver_min_time_ms}})
* {{Code|1=sst_write_flush_rate_mb}} -- superseded by '''Write Flush Threshold (% of Write Queue RAM)''' ({{Code|1=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 {{Code|1=/var/log/qs/qs_service.log}}, when:

* {{Code|1=title}}, {{Code|1=desc}} or {{Code|1=tab}} is missing;
* {{Code|1=default}} falls outside {{Code|1=min}} and {{Code|1=max}};
* {{Code|1=min}}, {{Code|1=max}} and {{Code|1=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 {{Code|1=min}}/{{Code|1=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:

<pre style="font-size: smaller">
systemctl restart quantastor
</pre>

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 {{Code|1=param}} path only produces a warning rather than an error.

What a restart does and does not change:

* '''Changing {{Code|1=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 {{Code|1=min}} or {{Code|1=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 {{Code|1=title}}, {{Code|1=desc}}, {{Code|1=tab}} or the units only affects presentation.

For troubleshooting, the step that writes the values out to the kernel can be suppressed entirely by creating the file {{Code|1=/var/opt/osnexus/quantastor/touchfiles/tf_storage_system_tunables.disable}}. The tunables still load and still show their stored values, but no kernel parameter is written. We recommend contacting OSNEXUS support before using it, since it leaves the dialog reporting settings the system is not applying.

== Relationship to qs_systemprofiles.conf ==

{{Code|1=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. {{Code|1=[[QuantaStor CLI Command Reference#tunable-list|qs tunable-list]]}} lists every tunable on every Storage System in the grid with its current value, default and range, and {{Code|1=[[QuantaStor CLI Command Reference#tunable-get|qs tunable-get]] --tunable=<sst_name>}} shows one in full, including its {{Code|1=tab}} and parameter path. See [[Storage System Optimization]] for the dialog itself and the full set of tunable and profile commands.

== Related pages ==

* [[Storage System Optimization]] -- the dialog these tunables appear in, the Optimization Profiles, and the CLI commands that set them
* [[Storage System]] -- the rest of the Storage System level configuration

----
<small>''Verified against QuantaStor 6.9.0.''</small>

← Older revision		Revision as of 10:23, 3 September 2026
Line 1:		Line 1:
	~~[[Category:admin_guide]]~~
	{{DISPLAYTITLE:qs_systemtunables.conf}}		{{DISPLAYTITLE:qs_systemtunables.conf}}

Qs systemtunables.conf - Revision history

Qadmin: Remove the admin_guide category so the page no longer appears in the sidebar; it is reference material reached from QuantaStor Configuration Files (QSTOR-12429)

Qadmin: Link the touch-file and configuration-file pages that own those topics (QSTOR-12429)

Qadmin: New page: qs_systemtunables.conf configuration file reference; tunables reference moved here from Storage System Optimization (QSTOR-12429)