Qadmin: Create Ceph Encryption Bypass admin page (per-device encryption exceptions)

2026-06-18T22:40:02Z

Create Ceph Encryption Bypass admin page (per-device encryption exceptions)

New page

= Ceph Encryption Bypass (Per-Device Encryption Exceptions) =

The '''Ceph Encryption Bypass''' feature lets you exclude specific device
types from QuantaStor's data-at-rest encryption when those devices already
provide their own encryption. It is used when building OSDs on an
'''encryption-enabled Ceph cluster''' that contains drives or enclosures
which encrypt data internally — most commonly self-encrypting storage
arrays such as the '''Seagate Corvault''' family.

Without this feature, every OSD on an encryption-enabled cluster is wrapped
in QuantaStor's software (dmcrypt/LUKS) or SED encryption. For media that is
already self-encrypting that produces redundant "double encryption", which
adds CPU and latency overhead and complicates key management with no
additional security benefit. The encryption bypass list tells QuantaStor to
create the OSD in the encrypted cluster '''but skip the encryption layer for
that one device''', trusting the hardware to protect data at rest.

{{Note|The bypass only takes effect on Ceph clusters/OSDs that were created
with encryption enabled. On an unencrypted cluster it has no effect — nothing
is encrypted in the first place.}}

== When to use it ==

Add a device to the bypass list when '''all''' of the following are true:

* You are deploying Ceph OSDs on a cluster created with encryption enabled (software dmcrypt/LUKS or SED).
* The target media (drive, or the LUNs presented by a self-encrypting enclosure) performs its own data-at-rest encryption in hardware.
* You want the device's hardware encryption — not QuantaStor's — to be the encryption-at-rest mechanism for those OSDs.

Typical examples:

* '''Seagate Corvault''' self-encrypting enclosures (4U106 and 5U84), which are pre-configured in the bypass list out of the box.
* Other vendor arrays/drives with always-on internal encryption that you have validated meet your data-at-rest requirements.

== How it works ==

# When QuantaStor creates a Bluestore OSD on an encryption-enabled cluster, it looks up the OSD's underlying device by '''SCSI Vendor ID''' and '''Product (Model) ID'''.
# If that Vendor/Model pair appears in the encryption bypass list, the device is treated as an '''encryption exception''':
#* On a '''software (dmcrypt/LUKS)''' cluster, the OSD is still created as part of the encrypted cluster, but the data device is provisioned with <code>--block.skip-enc</code> so its block device is not LUKS-encrypted.
#* On an '''SED''' cluster, the device is not crypt-formatted by QuantaStor; the drive's self-encryption is relied upon instead.
# Devices '''not''' in the list are encrypted normally — the bypass is strictly opt-in, per Vendor/Model.

The matching is by Vendor + Model string only, so a single entry covers
every drive/LUN of that type across the cluster.

== Configuration ==

The bypass list is a per-node configuration file:

/opt/osnexus/quantastor/conf/qs_encryption_bypass.conf

It is an INI-style file. Each entry is a named section with a
<code>vendor</code> and a <code>model</code> key that must match the device's
SCSI Vendor ID and Product ID exactly (case-sensitive):

<pre>
# Seagate Corvault systems have built-in encryption, so QuantaStor's
# software/SED encryption is bypassed for these devices.
[seagate_corvault_4u106]
vendor=SEAGATE
model=6575

[seagate_corvault_5u84]
vendor=SEAGATE
model=6566
</pre>

To add a new device type:

# Determine the device's SCSI '''Vendor ID''' and '''Product/Model ID'''. You can read these from:
#* The WUI — '''Physical Disks/Devices''' → disk properties (Vendor / Model fields).
#* The CLI — <code>qs physical-disk-get <disk></code>.
#* The shell — <code>lsscsi -v</code>, or <code>sg_inq /dev/sdX</code> (Vendor identification / Product identification).
# Add a new section to <code>qs_encryption_bypass.conf</code> with the matching <code>vendor=</code> and <code>model=</code> values.
# Repeat the edit on '''every Ceph node''' that will host OSDs of that device type. This file is '''not''' grid-synced — it is a local, per-node configuration that you must update manually on each node.
# Restart the QuantaStor service so the list is reloaded: <code>systemctl restart quantastor</code> (or <code>qs-util restartmgmt</code>).

{{Note|Add the device to the bypass list '''before''' creating the OSDs you
want excluded. Existing OSDs are not retroactively re-encrypted or
de-encrypted when the list changes — the bypass is evaluated at OSD-creation
time.}}

== ceph-volume patch dependency ==

The <code>--block.skip-enc</code> option used on software-encrypted clusters
is a QuantaStor extension to the stock Ceph <code>ceph-volume</code> tool.
QuantaStor maintains this patch automatically and admins do not normally need
to interact with it:

* The patch is '''idempotent and version-aware''' — safe to re-run, and it only applies the patch set matching the running Ceph release.
* It is re-applied automatically at QuantaStor service start, after any <code>apt</code> operation that may have reinstalled/upgraded <code>ceph-volume</code>, and on boot before any OSD is activated.
* '''Fail-safe by design:''' if the patch cannot be applied to the running <code>ceph-volume</code> (for example after an unexpected Ceph point-release change), QuantaStor logs a loud patch-failure error and the OSD operation fails rather than silently mis-encrypting data. If you see such an alert, contact OSNexus support before forcing OSD creation.

To temporarily disable the ceph-volume patching (advanced/support use only),
create the disable touchfile on the affected node:

/var/opt/osnexus/quantastor/touchfiles/tf_qs_ceph_volume_patch.disable

While this touchfile is present, the patch is not applied and
encryption-bypass OSD creation on software-encrypted clusters will fail.
Remove the touchfile and restart the service to re-enable.

== Verifying ==

After creating OSDs on a bypassed device type:

* Confirm the OSDs come '''up/in''' normally (WUI Ceph view, or <code>ceph osd tree</code>).
* On a software-encrypted cluster, confirm the bypassed device's data block device is '''not''' a LUKS/dmcrypt device (e.g. <code>lsblk</code> shows no <code>crypt</code> layer on it), while non-bypassed OSDs on the same cluster still show the encrypted layer.
* Review <code>/var/log/qs/ceph_volume_patch.log</code> and the QuantaStor service log if you need to confirm the ceph-volume patch applied cleanly.

== See also ==

* [[Create Ceph Cluster Configuration]]
* [[Physical Disks/Devices]]
* [[Security Configuration]]
* [[QuantaStor systemd Services]]

[[Category:Administrator Guide]]
[[Category:Scale-out Storage (Ceph)]]
[[Category:Encryption]]

Ceph Encryption Bypass - Revision history

Qadmin: Create Ceph Encryption Bypass admin page (per-device encryption exceptions)