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)

2026-09-03T10:23:54Z

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)

← Older revision		Revision as of 10:23, 3 September 2026
Line 1:		Line 1:
	{{DISPLAYTITLE:qs_io_profiles.conf}}		{{DISPLAYTITLE:qs_io_profiles.conf}}
	~~[[Category:admin_guide]]~~
	<code>qs_io_profiles.conf</code> defines the '''Storage Pool I/O optimization profiles''' -- the list you choose from when you set an I/O profile on a storage pool. Each section in the file becomes one selectable profile, and the values in it are applied to the block-device queue settings of the disks backing that pool.		<code>qs_io_profiles.conf</code> defines the '''Storage Pool I/O optimization profiles''' -- the list you choose from when you set an I/O profile on a storage pool. Each section in the file becomes one selectable profile, and the values in it are applied to the block-device queue settings of the disks backing that pool.

Qadmin: New page for qs_io_profiles.conf under the configuration-file program (QSTOR-12429): the seven shipped profiles and their values generated from the shipped file, the full key reference including the nvme_/fifo_batch keys the loader honours but the file never sets, and the three applied behaviours not visible in the file - the hardware queue_depth dependency of the multiplier, the 1024 cap and the power-of-two rounding

2026-09-03T07:59:07Z

New page for qs_io_profiles.conf under the configuration-file program (QSTOR-12429): the seven shipped profiles and their values generated from the shipped file, the full key reference including the nvme_/fifo_batch keys the loader honours but the file never sets, and the three applied behaviours not visible in the file - the hardware queue_depth dependency of the multiplier, the 1024 cap and the power-of-two rounding

New page

{{DISPLAYTITLE:qs_io_profiles.conf}}
[[Category:admin_guide]]
<code>qs_io_profiles.conf</code> defines the '''Storage Pool I/O optimization profiles''' -- the list you choose from when you set an I/O profile on a storage pool. Each section in the file becomes one selectable profile, and the values in it are applied to the block-device queue settings of the disks backing that pool.

Adding a section to this file adds a profile to the product. That is the file's purpose: a new workload profile can be delivered without a code change.

''(Note: change this file only with guidance from OSNEXUS support. The shipped profiles are the tested ones, and a hand-built profile can degrade pool performance rather than improve it.)''

{| class="wikitable"
! Property !! Value
|-
| Shipped path || <code>/opt/osnexus/quantastor/conf/qs_io_profiles.conf</code>
|-
| Override path || <code>/var/opt/osnexus/quantastor/conf/qs_io_profiles.conf</code>
|-
| Read || Once, at QuantaStor service start
|-
| Format || INI-style sections of <code>key=value</code>; <code>#</code> begins a comment
|-
| Profiles shipped || 7
|}

For where profiles fit into pool tuning as a whole, see [[Performance Tuning]]. For the override mechanism and the other configuration files, see [[QuantaStor Configuration Files]].

== Shipped profiles ==

The '''section name is the profile's identity''', not its label. The profile's object ID is generated from it, so renaming a section creates a new profile rather than renaming the existing one.

{| class="wikitable"
! Section !! Profile name (as shown in the interface) !! Optimizes for
|-
| <code>default</code> || '''Default''' || Optimizes for general purpose server application workloads
|-
| <code>virtualization</code> || '''Virtualization''' || Optimizes for virtual machine workloads such as database and web servers under ESXi/XenServer/Hyper-V/Virtuozzo
|-
| <code>archive</code> || '''Disk Archive''' || Optimizes pool IO characteristics for disk-to-disk backup & archive applications
|-
| <code>edgeware_webtv</code> || '''Edgeware Web TV Optimized''' || Optimizes pool IO characteristics Edgeware Web TV application workflow
|-
| <code>edgeware_iptv</code> || '''Edgeware IP TV Optimized''' || Optimizes pool IO characteristics Edgeware IP TV application workflow
|-
| <code>video512ra1024</code> || '''Media Post-Production (Playback Optimized)''' || Optimizes pool IO characteristics for media post-production playback
|-
| <code>video1024ra1024</code> || '''Media Post-Production (Ingest Optimized)''' || Optimizes pool IO characteristics for media post-production editing
|}

'''A section with no <code>name=</code> is skipped silently.''' The loader requires both a section name and a <code>name</code> value and drops anything else without an error, so a typo in that one key makes a profile vanish rather than fail loudly.

== Shipped values ==

Blank means the key is absent from that profile, in which case the value stays at whatever the device already had.

{| class="wikitable"
! Key !! default !! virtualization !! archive !! edgeware_webtv !! edgeware_iptv !! video512ra1024 !! video1024ra1024
|-
| <code>hdd_scheduler</code> || deadline || deadline || deadline || deadline || deadline || deadline || deadline
|-
| <code>hdd_nr_requests</code> || 256 || 64 || 256 || 64 || 64 || 256 || 1024
|-
| <code>hdd_nr_requests_multiplier</code> || 2 || 0 || 2 || 0 || 0 || 2 || 3
|-
| <code>hdd_read_ahead_kb</code> || 256 || 128 || 512 || 256 || 256 || 1024 || 512
|-
| <code>ssd_scheduler</code> || noop || noop || noop || noop || noop || noop || noop
|-
| <code>ssd_nr_requests</code> || 256 || 256 || 256 || 256 || 256 || 256 || 256
|-
| <code>ssd_nr_requests_multiplier</code> || 1 || 1 || 1 || 1 || 1 || 1 || 1
|-
| <code>ssd_read_ahead_kb</code> || 4 || 4 || 4 || 4 || 4 || 4 || 4
|-
| <code>chunk_size_kb</code> || 128 || 256 || 64 || 512 || 512 || 512 || 1024
|-
| <code>min_target_driver_threads</code> || 0 || 64 || 0 || 0 || 0 || 0 || 0
|-
| <code>min_target_driver_tasklets</code> || 0 || 32 || 0 || 0 || 0 || 0 || 0
|}

== Keys ==

Keys are grouped by media class. The <code>hdd_</code> set applies to rotational disks, <code>ssd_</code> to SATA/SAS solid-state, and <code>nvme_</code> to NVMe devices, so one profile tunes a mixed pool correctly rather than applying one queue depth to everything.

{| class="wikitable"
! Key !! Applies to !! Meaning
|-
| <code>name</code> || the profile || The label shown in the interface. '''Required''' -- a section without it is skipped.
|-
| <code>description</code> || the profile || The one-line description shown beside the name.
|-
| <code><media>_scheduler</code> || <code>/sys/block/<dev>/queue/scheduler</code> || The I/O scheduler to select for that media class.
|-
| <code><media>_nr_requests</code> || <code>queue/nr_requests</code> || Request queue depth, as a literal value.
|-
| <code><media>_nr_requests_multiplier</code> || <code>queue/nr_requests</code> || Queue depth as a multiple of the device's hardware queue depth. Takes precedence over the literal value -- see below.
|-
| <code><media>_read_ahead_kb</code> || <code>queue/read_ahead_kb</code> || Read-ahead window in KB. The single most workload-sensitive value here.
|-
| <code><media>_fifo_batch</code> || <code>queue/iosched/fifo_batch</code> || Deadline-scheduler batch size. Only meaningful while that scheduler is selected.
|-
| <code>min_target_driver_threads</code> || SCST || Minimum SCSI target driver threads. <code>0</code> means use the SCST default, which scales with processor core count.
|-
| <code>min_target_driver_tasklets</code> || SCST || Minimum SCSI target driver tasklets. <code>0</code> means the SCST default.
|-
| <code>chunk_size_kb</code> || ''nothing'' || '''Legacy and deprecated.''' A leftover mdadm parameter, still parsed and still stored on the profile object, but it does not tune anything on a ZFS pool. The file's own comment says as much. Ignore it when building a profile.
|}

=== Keys the loader accepts but the shipped file never sets ===

The loader reads three key sets, one per media class, but '''the shipped file only ever populates <code>hdd_</code> and <code>ssd_</code>'''. These are read and honoured if you add them:

<pre style="font-size: smaller">
nvme_scheduler
nvme_nr_requests
nvme_nr_requests_multiplier
nvme_read_ahead_kb
nvme_fifo_batch
hdd_fifo_batch
ssd_fifo_batch
</pre>

So an NVMe-backed pool runs on '''whatever queue settings the devices booted with''' under every shipped profile, because no shipped profile sets an <code>nvme_</code> key. That is worth knowing before concluding a profile had no effect on an all-NVMe pool -- it genuinely did not.

== How the values are applied ==

Three behaviours here are not visible in the file and change what a given value actually produces.

'''The multiplier only works on devices that report a hardware queue depth.''' It is applied as:

<pre style="font-size: smaller">
nr_requests = queue_depth x multiplier
</pre>

where <code>queue_depth</code> is read from <code>/sys/block/<dev>/device/queue_depth</code>. Only physical devices expose that file. If it is absent or reads zero, the multiplier is skipped and the literal <code>nr_requests</code> value is used instead. '''On a virtual machine this means the multiplier typically does nothing''', so a profile tested in a VM will not behave the same on physical hardware. Where both keys are set, the multiplier wins whenever a hardware queue depth is available -- which is why the shipped profiles set both.

'''The computed value is capped at 1024''' and logs a warning when it is reduced:

<pre style="font-size: smaller">
Requested device '...' queue depth based on multiplier 'N' is to large at 'X' > 1024, reducing to 1024
</pre>

So on a device with a deep hardware queue, a multiplier of 3 may quietly become the same as a multiplier of 2. The <code>video1024ra1024</code> profile's multiplier of 3 is the most likely to hit this.

'''The value is rounded up to a power of two''' before it is written, so <code>nr_requests=200</code> becomes 256. Choose powers of two to avoid surprises. Writes are also skipped when the device already holds the target value, so applying a profile twice is harmless and logs nothing the second time.

== Changing the file ==

Copy the shipped file to the override path, edit the copy, and restart the service:

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

'''Never edit the shipped copy.''' It is replaced on upgrade with no prompt and no backup of your changes.

'''An override replaces the file rather than merging with it''', and the profile list is reconciled against it at every service start. A profile that is absent from the file in force is '''removed from the system''' -- so an override must carry every profile you still want, including the shipped ones. A pool already set to a profile that disappears keeps the stored setting but the profile is no longer selectable.

'''Restart the service after editing.''' The file is read once at start; nothing rereads it.

== Listing the profiles ==

The profiles the appliance actually loaded are visible from the command line, which is the quickest way to confirm an edit took effect:

<pre style="font-size: smaller">
qs pool-profile-list
qs pool-profile-get --profile="Virtualization"
</pre>

On a shipped appliance <code>pool-profile-list</code> returns the seven profiles above. If a profile you added is missing from that list, the section was skipped -- check that it has a <code>name=</code> value and that the service has been restarted.

Applying one to a pool:

<pre style="font-size: smaller">
qs pool-modify --pool=<pool> --profile="Disk Archive"
</pre>

== Applying a profile to a pool ==

{{Navigation|Storage Management → Storage Pools ''(section)'' → ''select a Storage Pool'' → Modify}}

The profile is chosen from the I/O profile list in the Create and Modify Storage Pool dialogs. See [[Storage Pools]] for the dialog itself and [[Performance Tuning]] for guidance on which profile suits which workload, and for the measurement approach to use before and after a change.

== Related pages ==

* [[Performance Tuning]] -- which profile to choose, and how to measure the effect
* [[qs_systemtunables.conf]] -- the system tunables, a separate mechanism with a similar override model
* [[QuantaStor Configuration Files]] -- the override resolution order and the other configuration files
* [[Storage Pools]] -- the dialogs that apply a profile
* [[Storage System Optimization]] -- the optimization profiles that tune the appliance as a whole

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

Qs io profiles.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)