qs_io_profiles.conf

From OSNEXUS Online Documentation Site
Revision as of 10:23, 3 September 2026 by Qadmin (talk | contribs) (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))
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigation Jump to search

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

Property Value
Shipped path /opt/osnexus/quantastor/conf/qs_io_profiles.conf
Override path /var/opt/osnexus/quantastor/conf/qs_io_profiles.conf
Read Once, at QuantaStor service start
Format INI-style sections of key=value; # 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.

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

A section with no name= is skipped silently. The loader requires both a section name and a name 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.

Key default virtualization archive edgeware_webtv edgeware_iptv video512ra1024 video1024ra1024
hdd_scheduler deadline deadline deadline deadline deadline deadline deadline
hdd_nr_requests 256 64 256 64 64 256 1024
hdd_nr_requests_multiplier 2 0 2 0 0 2 3
hdd_read_ahead_kb 256 128 512 256 256 1024 512
ssd_scheduler noop noop noop noop noop noop noop
ssd_nr_requests 256 256 256 256 256 256 256
ssd_nr_requests_multiplier 1 1 1 1 1 1 1
ssd_read_ahead_kb 4 4 4 4 4 4 4
chunk_size_kb 128 256 64 512 512 512 1024
min_target_driver_threads 0 64 0 0 0 0 0
min_target_driver_tasklets 0 32 0 0 0 0 0

Keys

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

Key Applies to Meaning
name the profile The label shown in the interface. Required -- a section without it is skipped.
description the profile The one-line description shown beside the name.
<media>_scheduler /sys/block/<dev>/queue/scheduler The I/O scheduler to select for that media class.
<media>_nr_requests queue/nr_requests Request queue depth, as a literal value.
<media>_nr_requests_multiplier queue/nr_requests Queue depth as a multiple of the device's hardware queue depth. Takes precedence over the literal value -- see below.
<media>_read_ahead_kb queue/read_ahead_kb Read-ahead window in KB. The single most workload-sensitive value here.
<media>_fifo_batch queue/iosched/fifo_batch Deadline-scheduler batch size. Only meaningful while that scheduler is selected.
min_target_driver_threads SCST Minimum SCSI target driver threads. 0 means use the SCST default, which scales with processor core count.
min_target_driver_tasklets SCST Minimum SCSI target driver tasklets. 0 means the SCST default.
chunk_size_kb 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 hdd_ and ssd_. These are read and honoured if you add them: 

nvme_scheduler
nvme_nr_requests
nvme_nr_requests_multiplier
nvme_read_ahead_kb
nvme_fifo_batch
hdd_fifo_batch
ssd_fifo_batch

So an NVMe-backed pool runs on whatever queue settings the devices booted with under every shipped profile, because no shipped profile sets an nvme_ 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: 

nr_requests = queue_depth x multiplier

where queue_depth is read from /sys/block/<dev>/device/queue_depth. Only physical devices expose that file. If it is absent or reads zero, the multiplier is skipped and the literal nr_requests 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: 

Requested device '...' queue depth based on multiplier 'N' is to large at 'X' > 1024, reducing to 1024

So on a device with a deep hardware queue, a multiplier of 3 may quietly become the same as a multiplier of 2. The video1024ra1024 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 nr_requests=200 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: 

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

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: 

qs pool-profile-list
qs pool-profile-get --profile="Virtualization"

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

Applying one to a pool: 

qs pool-modify --pool=<pool> --profile="Disk Archive"

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

Verified against QuantaStor 6.9.0.

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