TrueNAS — Xử lý sự cố storage và dịch vụ

Doc Type

Troubleshooting

Technology

truenas

Status

Active

Version

25.10.6

Tags

truenassmbnfsiscsireplication

Khoanh vùng theo storage, network, protocol, quyền truy cập và backup freshness. Đọc theo thứ tự các chương hoặc chọn mục cần tra cứu trong mục lục.

Khoanh vùng theo từng lớp

Khoanh vùng lỗi theo lớp và phân biệt hành vi bảo mật dự kiến với lỗi storage. Không thay đổi pool hoặc quyền truy cập trước khi xác định phạm vi.

Khoanh vùng

Triệu chứng	Kiểm tra đầu tiên	Không vội kết luận
Pool ONLINE nhưng share lỗi	Service, listener, network, ACL	ONLINE không chứng minh client dùng được
NFS mount có nhưng I/O treo	TCP/2049, hard mount, process state	Không mount chồng hoặc mở nhiều process test
SMB user RO vẫn ghi được	Toàn bộ group và ALLOW ACE	Một ACE READ không thu hồi WRITE từ group khác
iSCSI session còn nhưng I/O lỗi	TCP/3260, session state, LUN/UUID	Session entry không chứng minh kết nối hoạt động
Replication SUCCESS nhưng file mới thiếu	Snapshot chứa file, latest hai phía, task mode	Job cũ thành công không có nghĩa backup mới
USED cao hơn dữ liệu nhìn thấy	Snapshot/reservation accounting	Không dọn snapshot theo phỏng đoán

Lệnh TrueNAS chỉ đọc để xác định lớp:

zpool status -v tank
sudo midclt call service.query
sudo ss -lntp
sudo midclt call alert.list

Output có inventory; lưu nội bộ. Lệnh query/API phụ thuộc phiên bản, baseline ở đây là 25.10.6.

Kiểm tra theo lớp

Thay vì chạy nhiều lệnh ngẫu nhiên, hãy khoanh vùng nguyên nhân theo từng lớp. Cách này giảm thời gian tìm nguyên nhân và tránh sửa sai layer.

1. Physical / Device
2. ZFS Pool / VDEV
3. Dataset / ZVOL / Permission
4. Service / Port
5. Network
6. Client mount/session
7. Application / Data Protection

Ví dụ: user báo SMB không truy cập được

1. Kiểm tra zpool status: pool có ONLINE không?

2. Kiểm tra SMB service và TCP 445.

3. Kiểm tra share tồn tại và dataset không locked/readonly ngoài dự kiến.

4. Kiểm tra network path từ client.

5. Kiểm tra authentication và ACL.

6. Cuối cùng mới kết luận lỗi storage, service hay client.

Ví dụ: backup không có file mới

1. Xác nhận file thực sự tồn tại ở source.

2. Xem snapshot mới nhất ở source.

3. Xem task snapshot có enabled/schedule đúng không.

4. Xem replication last state/last snapshot.

5. So sánh source latest và destination latest.

6. Nếu có common snapshot, chạy incremental replication thay vì full-copy.

Lỗi thường gặp

Hiện tượng	Nguyên nhân thường gặp	Hướng xử lý
Pool ONLINE nhưng user không truy cập được	Service/network/ACL/client	Không tập trung vào disk; kiểm tra protocol layer.
NFS root bị Permission denied	root_squash + permission dataset	Test đúng UID/GID; không vội đổi mode 777.
Replication FINISHED nhưng backup cũ	Task manual/disabled/schedule hoặc snapshot stale	Kiểm tra freshness, không chỉ state.
Dataset USED lớn hơn dữ liệu nhìn thấy	Snapshot, children, reservation/refreservation	Phân rã usedby* trước khi xóa dữ liệu.
iSCSI session vẫn hiện khi target down	Kernel/iscsid đang giữ/retry session	Test TCP/data path; xác nhận I/O thực tế thay vì chỉ xem session.
Đã thay disk nhưng chưa đủ redundancy	Resilver chưa hoàn tất	Chờ resilver hoàn tất, kiểm tra trạng thái pool và kết quả scrub.
Xóa snapshot không giải phóng nhiều	Block vẫn được snapshot/clone khác tham chiếu	Kiểm tra dependency và USED.

NFS và gián đoạn dịch vụ

NFS từ chối truy cập

Định danh UID/GID

Triệu chứng: cùng username ở client/server nhưng thao tác bị từ chối.

AUTH_SYS kiểm tra numeric UID/GID, không so username. Ví dụ client UID 2002 không có quyền owner của thư mục UID 3002 chỉ vì tên user giống nhau. Đối chiếu định danh và mode ở cả hai phía trước khi sửa ownership.

id nfsuser
ls -ldn /mnt/truenas-nfs

Trên TrueNAS:

ls -ldn /mnt/tank/nfs-data
sudo midclt call sharing.nfs.query
sudo exportfs -v

Cách xử lý: thống nhất numeric UID/GID và ownership theo thiết kế, kiểm tra quyền traverse của các parent directory. Không chmod 777 toàn dataset hoặc dùng Mapall chỉ để bỏ qua sai lệch identity.

Root squash và ánh xạ

Baseline owner 2001:2001, mode 770, Maproot/Mapall trống khiến root client bị squash 65534:65534. Root bị Permission denied sau storage recovery vẫn có thể đúng với thiết kế phân quyền.

Kiểm tra bằng user được cấp quyền:

sudo -u nfsuser ls /mnt/truenas-nfs

Nếu quyền chưa phản ánh cấu hình Maproot mới, kiểm tra export đang áp dụng và trạng thái mount. Chỉ remount trong maintenance window sau khi dừng các tác vụ ghi và unmount sạch; không tự cho rằng mọi Permission denied đều do cache.

Còn mount nhưng mất dịch vụ

Client vẫn có thể giữ VFS mount hoặc iSCSI session trong khi transport mất.

nc -zv -w 3 nas-host 2049
nc -zv -w 3 nas-host 445
nc -zv -w 3 nas-host 3260

Connection refused cần được đối chiếu với listener, dịch vụ và firewall; host ping được chưa chứng minh storage protocol sẵn sàng.

Protocol	Quan sát	Xử lý và kiểm tra
NFS hard mount	Process chờ remote I/O, có thể D-state	Khôi phục dịch vụ/network; test lại bằng UID đúng
CIFS	Mount entry còn, I/O timeout/Host is down	Khôi phục SMB; kiểm tra reconnect, checksum và file test
iSCSI	TRANSPORT WAIT, FAILED, REOPEN	Khôi phục target; xác nhận LOGGED IN, UUID và checksum

Không cố unmount/format để “sửa” một LUN chỉ đang reconnect. Với planned iSCSI outage, dừng các tác vụ ghi và unmount trước test; sau recovery mount lại đúng filesystem.

SMB và phiên bản dữ liệu

Quyền SMB thực tế

Nguyên nhân cần kiểm tra: user nhận MODIFY qua builtin_users hoặc group khác; thêm READ vào group riêng không thu hồi WRITE đã được cấp.

• Rà soát group membership và ACL hiện hữu trước khi đổi.
• Loại quyền cấp rộng không đúng thiết kế trong phạm vi phê duyệt, giữ admin ACE.
• Xác nhận inheritance lên các đối tượng test, không áp đệ quy vô điều kiện.
• Kiểm thử smbuser1 RW, smbuser2 RO và anonymous denied.

sudo midclt call filesystem.getacl /mnt/tank/smb-lab4 false true
sudo smbstatus

Hai lệnh chạy trên TrueNAS. smbstatus không có ở Ubuntu client không có nghĩa server hỏng.

CIFS có thể hiển thị owner root:root ở Ubuntu; TrueNAS vẫn kiểm tra user SMB đã xác thực. Kiểm tra owner thực tế và thao tác qua SMB, không chỉ ls -l trên client.

Tra cứu phiên bản cũ

Nếu smbinfo list-snapshots/fileallinfo/secdesc trả Errno 25, kiểm tra khả năng hỗ trợ của công cụ và kernel client trước khi kết luận snapshot phía server bị lỗi.

Cách kiểm tra: liệt kê snapshot ở ZFS, đối chiếu thời gian tạo rồi dùng smbclient đọc @GMT path. Truy cập phiên bản cũ không yêu cầu rollback dữ liệu hiện tại. Xem Khôi phục dữ liệu.

Với cảnh báo CIFS parse_server_interfaces, kiểm tra kết nối và I/O thực tế. Không sửa cấu hình chỉ dựa trên một warning khi chưa xác định ảnh hưởng.

Kết nối iSCSI

Đăng nhập và tự kết nối iSCSI

Hiện tượng	Diễn giải	Cách xử lý
Discovery được, login lỗi 24	Thiếu/sai CHAP hoặc auth policy	Đối chiếu Target/Auth Group và credential bảo mật
iscsid inactive trước lần dùng đầu	Có thể socket-activated	Kiểm tra socket/session trước khi kết luận
open-iscsi active (exited)	Unit hoàn tất login	Kiểm tra iscsid, session và mount thực tế
node.startup=manual sau thay đổi	Policy persistence chưa đúng	Đặt automatic cho đúng node và kiểm thử reboot
Portal chọn một IP, listener wildcard	Hai lớp cấu hình khác nhau	Kiểm tra access control và firewall
Tên sdX đổi	Device re-enumeration	Dùng Target/LUN, by-path và filesystem UUID

Không in iscsi.auth.query hoặc node credentials vào report/log công khai vì có thể chứa secret. CHAP không mã hóa dữ liệu truyền qua iSCSI.

Replication và điểm phục hồi

Replication thiếu snapshot gốc

Thông báo lỗi:

No incremental base on dataset
and replication from scratch is not allowed.

Điều tra nguyên nhân

1. Source và destination cùng có snapshot auto-* đã dùng cho initial full.
2. Snapshot định kỳ chuyển sang lab6-auto-*.
3. Replication selection chỉ nhận schema mới.
4. Common snapshot cũ còn tồn tại nhưng bị loại khỏi selection; allow_from_scratch=false dừng job để bảo vệ target.

Không chỉ so tên: phải giữ đúng lineage/common snapshot và rule selection phù hợp.

Khắc phục

Tạm chấp nhận cả hai naming schema đã dùng, Run Now và kiểm tra log dùng common snapshot cũ làm base. Khi chain mới đã hình thành, trở về schema chuẩn.

Kết quả cần xác nhận: log có incremental_base hợp lệ; snapshot mới xuất hiện ở destination, checksum đúng. Không bật from-scratch, xóa destination hoặc phá snapshot history chỉ để job báo thành công.

Tác vụ thành công, bản sao vẫn cũ

Nguyên nhân thường gặp: snapshot task bị tắt, replication chỉ chạy thủ công hoặc bản snapshot chưa chứa thay đổi mới. Pool và service hoạt động bình thường không bảo đảm backup đáp ứng RPO.

1. Kiểm tra file mới đã có trong snapshot nào; file trong dataset hiện tại chưa có trong snapshot sẽ không được replication.
2. Kiểm tra snapshot task enabled/schedule.
3. Kiểm tra replication enabled/auto/schedule, last job và last snapshot.
4. Phân biệt trạng thái chủ ý theo policy với vi phạm RPO.
5. Nếu được phê duyệt, tạo snapshot đúng schema sau thay đổi, Run Now replication và kiểm chứng đích.

Sau khi khắc phục, đối chiếu snapshot mới nhất ở hai phía và nội dung cần bảo vệ. Một lần chạy thủ công thành công không thay thế lịch backup tự động.

Bản phục hồi chỉ đọc

Restore policy IGNORE nhưng properties=true có thể mang readonly=on từ replica sang đích.

zfs get readonly,mountpoint tank/replication-lab6-restored

Chỉ sau khi xác nhận đúng restored dataset mới chuyển nó về writable; giữ backup readonly. Kiểm tra write test trước cutover và common snapshot trước khi tiếp tục replication.

Phòng ngừa

Lưu ý khác

Hiện tượng	Phân tích / phòng ngừa
ZVOL USED cao dù ít dữ liệu	Kiểm tra refreservation, không tự bỏ reservation
Snapshot USED tăng khi overwrite	CoW giữ old blocks; đối chiếu USED/REFER
Snapshot có dependent clone	Kiểm tra clones/origin; không force recursive cleanup
NFS mount lại báo access denied nhưng mount cũ dùng được	Kiểm tra mount hiện hữu; không dùng duplicate mount làm tiêu chí cuối
Giờ Ubuntu lệch UI 7 giờ	Đối chiếu UTC với UTC+7 trước khi kết luận clock skew
Pipeline kiểm tra báo exit code 0 dù lệnh đầu lỗi	Dùng set -o pipefail hoặc kiểm tra PIPESTATUS trong Bash
Không truy cập được share phục hồi	Kiểm tra đường dẫn, share, dịch vụ, tài khoản và ACL; không suy đoán lỗi pool

Phòng ngừa

Giữ identity và naming schema thống nhất, theo dõi độ mới của recovery point, ghi định danh disk ổn định vào inventory và xác nhận client I/O sau maintenance. Với disk/VDEV fault, chuyển sang Thay disk thay vì xử lý như lỗi service.

Tài liệu liên quan

• TrueNAS — Kiến trúc và nền tảng ZFS

  Topology TrueNAS, ZFS, pool, VDEV, dataset, ZVOL và lựa chọn thiết kế.

• TrueNAS — Triển khai storage và dịch vụ SMB/NFS/iSCSI

  Tạo pool và dataset; cấu hình quyền, dịch vụ SMB, NFS, iSCSI và kiểm tra từ client.

• TrueNAS — Snapshot, replication và backup

  RPO/RTO, snapshot, replication, retention và kiểm thử backup.

• TrueNAS — Vận hành và tra cứu

  Checklist vận hành cùng lệnh kiểm tra storage, client, backup và integrity.

• TrueNAS — Khôi phục dữ liệu

  Chọn snapshot, clone, rollback hoặc replica restore và kiểm tra trước cutover.

• TrueNAS — Thay disk và resilver

  Xác định disk, replacement, resilver, scrub và xác nhận redundancy.