FAQ Troubleshooting Storage Cluster Incus#

Lingkungan: 4 node Incus 7.2 (Debian 13) · QNAP HA Qnap-Cl01 via iSCSI · multipath · LVM shared (lvmcluster + sanlock) Disusun dari: insiden 30 Juli 2026 Terakhir diperbarui: 30 Juli 2026

Cara memakai dokumen ini#

Storage di cluster ini bertumpuk enam lapis. Hampir semua kesalahan diagnosa terjadi karena orang mulai dari lapisan yang salah — melihat VM lambat, lalu langsung menyalahkan VM.

6. Incus (instance, storage volume)
5. LV        /dev/vg-qnap-hdd-01/<volume>
4. VG        vg-qnap-hdd-01  (shared, butuh sanlock)
3. PV        /dev/mapper/qnap-hdd-01
2. multipath map  dm-X
1. path SCSI      /dev/sdb, /dev/sdc
0. sesi iSCSI     172.16.145.69:3260

Aturannya: selalu diagnosa dari bawah ke atas. Lapisan 0 yang rusak akan menghasilkan gejala di lapisan 6 yang terlihat seperti masalah aplikasi. Sebaliknya tidak pernah terjadi.

Triase cepat — jalankan ini dulu, apa pun gejalanya#

iscsiadm -m session -P 1 | grep -E 'Session State|Connection State'
multipath -ll
pvs; vgs; lvs -o vg_name,lv_name,lv_active
systemctl status sanlock lvmlockd incus
journalctl -k --since "10 min ago" | grep -cE 'conn error|Failing path|over max size'
incus cluster list

Lapisan pertama yang bermasalah dari atas daftar itu adalah tempat kamu harus bekerja. Jangan lanjut ke atasnya sebelum yang bawah bersih.

A. Lapisan iSCSI#

A1. conn error (1020 - ISCSI_ERR_TCP_CONN_CLOSE) berulang setiap beberapa detik#

Artinya: target menutup koneksi TCP. Bukan timeout dari sisi kita, bukan packet loss.

Penyebab paling sering: IQN duplikat. Dalam iSCSI, IQN adalah identitas sesi. Kalau dua node memakai IQN yang sama, target menganggap keduanya satu initiator yang sedang recovery, lalu menutup sesi lama setiap kali salah satunya login. Hasilnya loop dengan irama sangat teratur.

Ciri pembeda: keteraturan. Kongesti dan packet loss menghasilkan pola acak. Interval yang konsisten (misal sesi hidup persis ~3 detik, berulang puluhan kali) menunjukkan mekanisme deterministik, bukan gangguan jaringan.

for n in 01 02 03 04; do
  echo -n "incus-$n: "
  ssh trim-computes-shr-incus-$n "grep '^InitiatorName' /etc/iscsi/initiatorname.iscsi"
done

Keempat baris harus berbeda. Kalau ada yang kembar, itu penyebabnya.

Perbaikan: daftarkan IQN baru di ACL QNAP lebih dulu, baru ganti /etc/iscsi/initiatorname.iscsi per node, backup file lamanya, lalu reboot node satu per satu.

A2. Bagaimana membedakan masalah jaringan vs masalah sesi?#

iscsiadm -m discovery -t st -p 172.16.145.69

Ini pemisah paling cepat yang tersedia. Discovery memakai PDU kecil, jadi dia lolos walaupun ada masalah MTU — sementara transfer data tidak.

A3. iSCSI Session State: FAILED — apakah sesinya mati?#

Belum tentu. Polling beberapa kali:

watch -n1 "iscsiadm -m session -P 1 | grep -E 'Session State|Connection State'"

Kalau berosilasi antara LOGGED_IN / NO CHANGE dan FAILED / REOPEN, sesinya sedang flapping, bukan mati. Snapshot tunggal mudah menipu — kamu bisa kebetulan menangkapnya di tengah siklus.

A4. iscsiadm: No active sessions setelah reboot — VG hilang#

Jangan panik, dan jangan sentuh LVM. Metadata VG ada di LUN QNAP; tidak ada yang hilang. Ini murni masalah visibilitas PV.

JANGAN PERNAH jalankan pvcreate, vgcreate, atau vgreduce --removemissing saat VG tidak terlihat. Itulah yang benar-benar menghancurkan data.

systemctl status iscsid open-iscsi
iscsiadm -m node -T <target> -p 172.16.145.69:3260 -l
multipath -r && multipath -ll
pvs && vgs
vgchange --lock-start

Kenapa auto-login gagal saat boot? Dua kandidat:

iscsiadm -m node -T <target> -p 172.16.145.69:3260 -o show | grep node.startup
journalctl -b -u open-iscsi -u iscsid --no-pager | head -30

• node.startup = manual → perbaiki dengan -o update -n node.startup -v automatic
• Sudah automatic tapi tetap gagal → race urutan boot: open-iscsi login sebelum bond-storage siap. Bond LACP butuh waktu negosiasi. Ciri khasnya: perilaku tidak konsisten antar boot — kadang berhasil, kadang tidak.

A5. iscsiadm ... -l → “1 session requested, but 1 already present”#

Bukan error. Sesi sudah ada, iscsiadm menolak membuat duplikat. Kalau memang mau sesi baru, logout dulu — tapi pastikan LV sudah non-aktif dan sanlock sudah dilepas.

A6. Target IQN vs Initiator IQN — sering tertukar#

Analoginya: target IQN = nomor yang dihubungi, initiator IQN = caller ID kita sendiri.

LUN tidak diidentifikasi dengan IQN. LUN dikenali dari nomor LUN dan WWID naa.*/36e843.... Satu target bisa berisi banyak LUN.

Kesalahan yang pernah terjadi: IQN target ter-paste ke initiatorname.iscsi sebuah node — node itu praktis berkata kepada QNAP “saya adalah kamu”.

B. Lapisan multipath#

B1. blk_insert_cloned_request: over max size limit. (X > Y)#

JEBAKAN UTAMA: angka itu satuan SEKTOR (512 byte), bukan byte.

Kernel mencetak blk_rq_sectors(). Konversikan dulu sebelum membandingkan dengan apa pun:

Salah membaca ini akan membuatmu mengeliminasi hipotesis yang benar. Itu terjadi pada insiden 30 Juli dan memakan waktu berjam-jam.

Artinya: device-mapper meneruskan request lebih besar dari yang bisa diterima path di bawahnya. Karena dm-multipath itu request-based — dia meng-clone request apa adanya, tidak memecahnya — limit yang diiklankan dm wajib ≤ limit path.

Cek semua limit yang relevan, di kedua level:

for d in sdb sdc dm-7 dm-8; do
  echo "== $d"
  for a in max_sectors_kb max_hw_sectors_kb discard_max_bytes write_zeroes_max_bytes; do
    printf "  %-24s %s\n" "$a" "$(cat /sys/block/$d/queue/$a 2>/dev/null)"
  done
done

Nilai di level dm tidak boleh melebihi nilai di level path.

B2. Path gagal lalu pulih setiap ~5 detik, tanpa error iSCSI#

Ini loop yang menopang dirinya sendiri, dan tandanya journalctl -u iscsid justru bersih:

over max size limit → Failing path → (path checker 5 detik) → Reinstating → over max size limit → …

Mekanismenya: path dipulihkan → backlog I/O yang ditahan queue_if_no_path didorong sekaligus → ada request over-size → ditolak → dm menggagalkan path → TUR checker bilang path sehat → dipulihkan → ulang.

Interval 5 detik itu adalah interval path checker multipathd, bukan kebetulan.

Perbaikan: turunkan limit dm agar cocok dengan path (lihat B3).

B3. Mismatch discard_max_bytes — dm 1 GiB vs path 64 MiB#

Ini mismatch permanen dan sistematis di lingkungan ini. dm mengiklankan 16x lebih besar dari yang diterima path.

Terapkan sekarang, di semua node (idempoten, hanya menyentuh yang nilainya 1 GiB):

for d in /sys/block/dm-*; do
  if [ "$(cat $d/queue/discard_max_bytes)" = "1073741824" ]; then
    echo 67108864 > $d/queue/discard_max_bytes
    echo "clamped: $(cat $d/dm/name)"
  fi
done

Permanen — perhatikan scope pakai nama, bukan nomor dm:

cat > /etc/udev/rules.d/99-qnap-discard-clamp.rules <<'EOF'
ACTION=="add|change", SUBSYSTEM=="block", ENV{DM_NAME}=="qnap-*", ATTR{queue/discard_max_bytes}="67108864"
ACTION=="add|change", SUBSYSTEM=="block", ENV{DM_NAME}=="vg--qnap--*", ATTR{queue/discard_max_bytes}="67108864"
EOF
udevadm control --reload

Jangan pakai KERNEL=="dm-*" (terlalu luas, dan nomor dm berubah antar boot). Jangan jalankan udevadm trigger --action=change massal — itu memicu ulang event untuk semua block device sekaligus dan bisa mengganggu setup device.

Nilai 64 MiB itu bukan angka ajaib — itu yang dilaporkan path (sdb/sdc). Kalau QNAP di-upgrade dan melaporkan angka berbeda, nilai ini harus ditinjau ulang.

Harus seragam di semua node. Nilai ini state kernel per-host, tidak tersimpan di metadata VG, sementara storage-nya shared dan VM bisa mendarat di node mana pun. Node yang belum di-clamp akan memunculkan loop yang sama secara acak.

LV di atas map mewarisi limit saat aktivasi, jadi LV yang sudah aktif sebelum clamp bisa masih mengiklankan nilai lama — makanya rule di atas mencakup pola vg--qnap--* juga.

B4. critical target error ... op 0x9:(WRITE_ZEROES)#

Target QNAP menolak operasi WRITE_ZEROES (WRITE SAME). Error dari target, bukan transport.

Relevan karena Incus menjalankan lvcreate --wipesignatures y yang memicu BLKZEROOUT → WRITE_ZEROES setiap kali membuat volume.

cat /sys/block/dm-7/queue/write_zeroes_max_bytes

Kalau nilainya sudah 0, kernel menonaktifkannya sendiri dan fallback ke menulis nol biasa — selesai. Kalau masih besar, error akan berulang di setiap operasi volume.

B5. couldn't get asymmetric access state / prio ALUA gagal#

multipathd tidak bisa membaca state ALUA walaupun target mengaku mendukung implicit TPGS. Pada setup single-path efeknya kecil, tapi prioritizer bekerja sia-sia setiap reconnect.

Kalau menetap, pertimbangkan di section device QNAP pada multipath.conf:

detect_prio no
prio const

Sering kali gejala ini hilang sendiri setelah masalah di bawahnya (flapping sesi) selesai.

B6. queue_if_no_path — kapan jadi masalah?#

Fitur ini menahan I/O alih-alih menggagalkannya saat path hilang. Bagus untuk gangguan sesaat, tapi punya konsekuensi:

• Backlog menumpuk, lalu didorong sekaligus saat path pulih — memperparah loop di B2
• iscsiadm ... -u dan multipath -F bisa menggantung selamanya

Kalau perlu melepaskannya saat maintenance:

multipathd disablequeueing maps

Mengubahnya jadi no_path_retry <angka> secara permanen adalah keputusan arsitektural, bukan tindakan darurat: I/O akan gagal alih-alih menunggu, dan sanlock bisa kehilangan lease. Pikirkan matang, jangan diubah di tengah insiden.

B7. Nomor dm-X berubah antar boot#

Terverifikasi terjadi di cluster ini: dm-7 pernah qnap-ssd-01, setelah reboot menjadi qnap-hdd-01.

Selalu rujuk dengan nama, jangan nomor. Pakai /dev/mapper/qnap-hdd-01, bukan /dev/dm-7, di semua skrip, konfigurasi, dan udev rule.

for d in /sys/block/dm-*; do echo "$(basename $d) -> $(cat $d/dm/name)"; done

C. Lapisan LVM / VG shared (sanlock)#

C1. Reading VG vg-qnap-hdd-01 without a lock#

Lockspace sanlock belum di-start. VG terlihat tapi belum aman untuk dimodifikasi.

vgchange --lock-start
sleep 5
vgs        # peringatan harus hilang

Ini wajib setelah setiap boot atau setelah sanlock/lvmlockd di-restart. Attr VG shared ditandai s (contoh: wz--ns).

C2. VG shared tidak muncul di vgs#

Diagnosa dari bawah — VG hilang selalu berarti PV tidak terlihat, bukan VG rusak:

iscsiadm -m session     # ada sesi?
multipath -ll           # map terbentuk?
pvs                     # PV terlihat?
vgchange --lock-start   # lockspace jalan?

Lihat juga A4 untuk pemulihan lengkap.

C3. Urutan melepas storage dengan benar (untuk maintenance tanpa reboot)#

Rantainya harus dilepas dari atas ke bawah, kalau tidak akan kena device busy:

incus cluster evacuate <node>
systemctl stop incus.service incus.socket

vgchange --lock-stop <vg-hdd> <vg-ssd>     # keluar lockspace dengan sopan
systemctl stop lvmlockd sanlock

vgchange -an <vg-hdd> <vg-ssd>
lvs -o vg_name,lv_name,lv_active            # semua harus non-aktif

multipathd disablequeueing maps             # cegah logout menggantung
multipath -F

iscsiadm -m node -T <target> -p 172.16.145.69:3260 -u

Membangun kembali: kebalikannya, dari bawah ke atas.

Untuk sebagian besar kasus, reboot lebih aman daripada urutan manual ini — node toh sudah harus di-evacuate, jadi downtime layanannya sama.

C4. LV lvmlock itu apa?#

LV internal tempat sanlock menyimpan lease, satu per VG shared (~0.25 GiB). Jangan disentuh, jangan dihapus.

C5. Sanlock diam saat storage bermasalah — apakah normal?#

Bisa jadi ya. lvmlockd di sini berjalan dengan --sanlock-timeout 30. Kalau gangguan path hanya beberapa detik, queue_if_no_path menahannya dan sanlock tidak pernah tahu.

Konsekuensi penting: flapping storage bersifat “silent” di layer cluster. Dia tidak memicu alarm apa pun, hanya muncul sebagai latency. Jangan pakai kesehatan sanlock sebagai indikator storage sehat — pakai hitungan error di log dan f_await.

D. Lapisan Incus#

D1. Migrasi gagal: Logical Volume "..." already exists in volume group#

Artefak sisa dari percobaan migrasi sebelumnya yang gagal di tengah. Bisa tertinggal di dua lapisan sekaligus, dan keduanya harus dibersihkan:

Lapisan LVM:

lvs -a vg-qnap-ssd-01 -o lv_name,lv_size,lv_attr,lv_time,lv_active --units g

Ciri orphan: lv_time cocok dengan waktu percobaan gagal, tidak aktif, dan tidak punya flag k (skip activation) di kolom attr — LV yang dikelola Incus normalnya -wi------k.

Lapisan database Incus:

incus storage volume list <pool> --all-projects
incus admin sql global "SELECT sv.id, sv.name, sv.type, sp.name AS pool, p.name AS project FROM storage_volumes sv JOIN storage_pools sp ON sv.storage_pool_id=sp.id JOIN projects p ON sv.project_id=p.id WHERE sv.name LIKE '%<nama>%'"

type 2 = custom, type 3 = virtual-machine. Dua row dengan nama dan project sama di pool berbeda = satu di antaranya orphan (yang id-nya lebih besar dibuat belakangan).

D2. Storage volumes of type "virtual-machine" cannot be deleted with the storage API#

Incus melindungi volume milik instance. Tidak ada perintah resmi untuk menghapus row basi seperti ini.

Urutan yang aman:

1. systemctl restart incus — kadang cukup, coba dulu karena murah
2. Backup database: incus admin sql global .dump > /root/incus-db-$(date +%F-%H%M).sql — verifikasi file tidak kosong
3. Inspeksi tabel anak sebelum menghapus:

   incus admin sql global "SELECT name FROM sqlite_master WHERE type='table' AND name LIKE 'storage_volume%'"
   incus admin sql global "SELECT * FROM storage_volumes_config WHERE storage_volume_id=<id>"

4. Hapus anak dulu, baru induk, selalu dengan id=, jangan dengan nama (nama akan menyapu row yang asli juga)
5. Baru lvremove LV-nya
6. Verifikasi instance asli masih utuh

Ini bug cleanup-on-failure yang layak dilaporkan ke upstream. Kalau ragu, tanya forum dulu — row menggantung di tabel anak bisa membuat instance gagal start.

D3. used_by dan created_at pada volume show bisa menyesatkan#

• used_by dihitung Incus dari kecocokan nama, bukan linkage sebenarnya. Volume orphan tetap menunjukkan used_by: 1.
• created_at diwarisi dari volume sumber saat migrasi. Timestamp lama bukan bukti record-nya bukan artefak baru.

Yang otoritatif soal lokasi volume instance:

incus config device show <instance> --project <proj>

Baris seperti Storage : pool-qnap-hdd-01 di output incus info sering merupakan bagian dari Description yang ditulis manusia, bukan laporan Incus. Jangan dijadikan sumber.

D4. Custom volume tidak ketemu: Storage pool volume not found#

Hampir selalu salah flag project. Kalau project punya features.storage.volumes=false, custom volume-nya tinggal di project default walaupun instance-nya di project lain.

incus storage volume list <pool> --all-projects   # lihat kolom PROJECT

Pada cluster ini: volume virtual-machine ada di project instance (mis. Staging), sedangkan custom ada di default.

D5. Evacuate menggantung atau instance tidak mau migrate#

Instance will not be migrated because its device cannot be migrated  device=ethXXX

Instance dengan device NIC yang tidak bisa dimigrasikan tidak akan pernah live-migrate — evacuate akan jatuh ke stop. Paksa saja secara eksplisit supaya perilakunya bisa diprediksi:

incus config set <instance> cluster.evacuate=stop --project <proj>

D6. Migrasi antar node lambat padahal storage shared#

Storage shared berarti memindahkan VM antar node tidak perlu menyalin data. Kalau muncul lvcreate atau nbd0, berarti permintaanmu juga mengubah pool — dan itu copy penuh.

# pindah node saja — nyaris instan
incus move <instance> --target <node> --project <proj>

# pindah pool — copy penuh, lakukan dengan instance dimatikan
incus move <instance> --storage <pool-baru> --project <proj>

E. Jaringan storage#

E1. Pastikan interface yang benar sebelum menyimpulkan apa pun#

Jangan menebak dari nama. Kesalahan ini pernah membuat hipotesis MTU dieliminasi keliru:

ip route get 172.16.145.69          # ini yang otoritatif
ip -s link show bond-storage
cat /proc/net/bonding/bond-storage

Di cluster ini: bond-storage (LACP 802.3ad, slave enp59s0f0 + enp59s0f1, driver ixgbe, MTU 9000) yang membawa storage. eno1np0 dan eno2np1 (i40e) untuk jaringan VM/manajemen.

E2. Tes MTU / jumbo frame#

ping -M do -s 8972 -c 5 172.16.145.69    # 9000 - 20 (IP) - 8 (ICMP)
ping -M do -s 1472 -c 3 172.16.145.69

Kalau 1472 jalan tapi 8972 gagal → path MTU jumbo patah. Cek MTU di tiga titik: host, port switch (sering butuh per-port dan global), dan adapter QNAP.

Gejala khas MTU black hole: login iSCSI selalu sukses (PDU kecil), sesi mati begitu transfer data besar mengalir.

E3. Link Failure Count bukan nol pada slave bond#

Cek waktunya dulu sebelum khawatir:

journalctl -k --since "7 days ago" | grep -iE 'enp59s0f1|bond-storage' | grep -iE 'link|down|up'

Semua event terkumpul di rentang beberapa detik saat boot = artefak pembentukan bond, jinak. Urutan normalnya: enslave dengan link down → NIC up → “definitely down, disabling slave” → up lagi. Warning No 802.3ad response from the link partner juga transien pra-negosiasi.

Yang perlu dikhawatirkan: event link yang tersebar di berbagai waktu bukan saat boot.

E4. LACP rate tidak seragam#

Di /proc/net/bonding/bond-storage, bandingkan port state actor vs partner. Selisih pada bit timeout (mis. actor 63 = fast, partner 61 = slow) berarti host dan switch memakai rate berbeda.

Belum tentu langsung bermasalah kalau churn count nol, tapi membuat deteksi kegagalan asimetris dan memperlambat bond siap saat boot — yang bisa memicu race auto-login iSCSI (lihat A4). Seragamkan.

F. Pesan log yang AMAN diabaikan#

G. Jebakan penafsiran#

Lima hal yang terbukti menyesatkan pada insiden 30 Juli. Baca ulang bagian ini sebelum menyimpulkan apa pun.

1. Pesan blk_insert_cloned_request bersatuan sektor, bukan byte. Kalikan 512 sebelum membandingkan dengan discard_max_bytes atau max_sectors_kb.

2. Nomor dm-X berubah antar boot. Selalu petakan ke nama sebelum bertindak.

3. Pastikan interface storage yang benar. ip route get <portal-ip>, bukan tebakan dari nama interface.

4. Snapshot tunggal state sesi bisa menipu. Sesi yang flapping akan menunjukkan FAILED atau LOGGED_IN tergantung kapan kamu melihatnya. Polling beberapa kali.

5. Field Description di incus info adalah teks yang ditulis manusia, bukan laporan Incus. Jangan dijadikan sumber kebenaran soal pool atau storage.

Dan satu prinsip: kalau angka tidak cocok, hipotesisnya belum terbukti — walaupun ceritanya masuk akal. Cocokkan angka persis sebelum menyatakan akar masalah ditemukan.

H. Nilai referensi lingkungan ini#

Simpan sebagai pembanding. Kalau ada yang menyimpang dari ini, itu petunjuk.

iSCSI

Multipath

Features: queue_if_no_path · hwhandler alua · policy service-time 0 · prio 50

Limit block layer

Jaringan

Cluster locking

I. Checklist saat storage terasa lambat#

Jangan langsung menyalahkan HDD atau VM. Urutannya:

# 1. apakah ada flapping tersembunyi?
journalctl -k --since "1 hour ago" | grep -cE 'conn error|Failing path|over max size'

# 2. sesi iSCSI stabil?
iscsiadm -m session -P 1 | grep -E 'Session State'

# 3. semua path aktif?
multipath -ll

# 4. latency sebenarnya
iostat -x 5 6

# 5. baru lihat beban di dalam VM

Angka 0 di langkah 1 adalah syarat sebelum kesimpulan apa pun tentang performa boleh diambil. Pada insiden 30 Juli, angkanya 1604 per jam — dan semua “masalah performa MSSQL” ternyata gejala dari situ.