ZFS zpool clear: cuándo borrar errores es correcto (y cuándo es estúpido)

enero 5, 2026 • febrero 3, 2026 • Lectura: 27 min • Views: 9

¿Te fue útil?

A las 02:17, alguien pregunta: “El almacenamiento muestra errores. ¿Puedo simplemente ejecutar zpool clear?” Eso es el equivalente UNIX de preguntar si puedes apagar la alarma de humo quitando la pila. A veces está bien. Otras veces es la forma de convertir una falla recuperable en un desastre profesional que limita tu carrera.

zpool clear no es magia, y no es mantenimiento. Es una escoba. Úsala para barrer desórdenes ya conocidos y ya arreglados. No la uses para ocultar una tubería rota.

Qué hace realmente `zpool clear` (y qué no hace)

zpool clear borra los contadores de errores y ciertos estados de fallo registrados por ZFS para un pool o un vdev específico. Eso es todo. No “repara datos”. No “arregla el disco”. No “elimina corrupción”. Ni siquiera garantiza que el pool seguirá sano los próximos cinco minutos.

Piensa en ZFS como si tuviera dos capas de verdad:

Realidad física: lo que los discos, HBAs, expanders, cables, backplanes y controladores realmente pueden entregar.
Observación registrada: lo que ZFS ha visto (errores, reintentos, desajustes de checksum) y ha contado.

zpool clear restablece la observación registrada. No hace nada con la realidad física. Si la realidad física sigue rota, ZFS volverá a contar—a menudo inmediatamente, a veces segundos después de limpiar. Si borras y los contadores se mantienen en cero bajo carga, probablemente arreglaste algo y ahora el estado del pool es legible de nuevo. Si borras y los contadores se disparan otra vez, acabas de confirmar un problema activo.

Además: limpiar puede hacer que un pool pase de DEGRADED/FAULTED a ONLINE si el dispositivo subyacente vuelve a ser accesible y la falla fue transitoria. Eso es conveniente. También es la forma de “probar” accidentalmente que una ruta inestable está bien porque funcionó un minuto.

El trabajo de los contadores de error en las operaciones de ZFS

ZFS usa contadores por vdev (READ, WRITE, CKSUM) y máquinas de estado (ONLINE, DEGRADED, UNAVAIL, FAULTED) para ayudarte a responder dos preguntas:

¿Los datos están en riesgo ahora mismo?
Si sí, ¿es problema del dispositivo, de la ruta o corrupción en disco?

Borrar contadores es un paso de higiene después de haber respondido ambas preguntas y de haber mitigado la causa. No es el primer paso.

Idea parafraseada, atribuida: “La esperanza no es una estrategia.” — a menudo atribuida a practicantes en cultura de fiabilidad/operaciones (idea parafraseada).

Hechos y contexto que puedes usar en una war room

ZFS se diseñó para detectar corrupción silenciosa—esa clase de fallos y flips de bits que tu controlador RAID ignora alegremente mientras devuelve “éxito”. Por eso los errores de checksum importan más que un banner aterrador de “degraded”.
El checksum de extremo a extremo no era una característica de sistemas de archivos mainstream cuando ZFS se diseñó a principios de los 2000; ZFS impulsó la idea de que el almacenamiento debe verificar lo que sirve, no solo lo que guarda.
El concepto de “scrub” es intencionalmente proactivo: es un trabajo programado de “leer todo y verificar”, no un fsck reactivo tras un crash. Es como ZFS encuentra sectores malos antes de que los necesites.
Los contadores READ/WRITE/CKSUM son por vdev y persisten a través de reinicios hasta que se borran. Esa persistencia es útil para detectar tendencias y terrible para quienes se asustan con números antiguos.
Un solo desajuste de checksum no significa automáticamente pérdida de datos en vdevs redundantes (mirror/raidz). A menudo significa que ZFS detectó una copia mala y la reparó desde una buena—salvándote en silencio.
La “gestión de fallos” de ZFS fue influida por pensamiento de serviceability: intenta decirte qué componente reemplazar, no solo que “algo anda mal”. Es buena, pero no es omnisciente respecto a cables y backplanes.
Muchos “errores de disco” son en realidad problemas de transporte: resets de enlace SATA/SAS, expanders marginales, unidades mal asentadas, problemas de alimentación. ZFS no puede decir si tu cable está enfurruñado.
En stacks derivados de Solaris, FMA (Fault Management Architecture) se integró con ZFS. En Linux obtienes un ecosistema diferente (ZED, udev, logs del kernel), así que el diagnóstico a menudo requiere correlacionar fuentes.
La llegada de discos grandes y baratos convirtió los errores de sector latentes en un problema operativo real. Scrubs y planificación de redundancia se volvieron no opcionales a medida que los tiempos de rebuild crecían y las matemáticas de URE se pusieron feas.

Interpretar READ/WRITE/CKSUM como un adulto

zpool status te da tres contadores por dispositivo:

READ: el dispositivo devolvió un error de I/O en lectura, hizo timeout, o falló al entregar bloques.
WRITE: el dispositivo falló al escribir bloques (o al confirmar escrituras).
CKSUM: el dispositivo devolvió datos, pero ZFS calculó un desajuste de checksum—los datos no son lo que se escribió originalmente.

En la práctica:

READ/WRITE errors suelen apuntar a un dispositivo que no puede hacer I/O de forma fiable, o a un problema de ruta (HBA, expander, cable, alimentación). Tienden a aparecer con logs del kernel. Pueden provocar que vdevs se desconecten.
CKSUM errors son la categoría “silenciosamente terrorífica”. Pueden ser causados por un disco que está fallando, sí. También pueden ser causados por transporte inestable, RAM mala (menos común con ECC pero no imposible), firmware raro o controladores “que ayudan” demasiado. ZFS te dice: Recibí bytes, pero no los confío.

Qué deberías mapear mentalmente de contadores a acciones

Aquí tienes una guía de campo que coincide con lo que hacen los ingenieros on-call con experiencia, no con lo que dicen que hacen:

CKSUM en un disco, cuenta pequeña, nunca aumenta: probablemente un evento transitorio o ya reparado. Haz un scrub, correlaciona logs y luego borra si has remediado (reinsertar, reemplazar cable, actualizar firmware, etc.).
CKSUM que sube durante un scrub o bajo carga: problema activo de integridad. No borres. Encuentra el componente. Reemplaza cosas hasta que el contador deje de crecer.
READ/WRITE errors con resets/timeouts: trata como inestabilidad de ruta/dispositivo. ZFS puede seguir sirviendo, pero tu presupuesto de resiliencia se está gastando.
Errores en múltiples discos detrás de un mismo HBA/expander: no empieces una racha de reemplazos de discos. Así es como terminas con “discos nuevos, mismos errores”. Sospecha infraestructura compartida.

Cuándo es correcto borrar errores

zpool clear es correcto cuando el estado de error es obsoleto, la causa subyacente ha sido atendida y necesitas contadores limpios para verificar estabilidad en adelante.

Úsalo después de arreglar algo medible

Disparadores razonables:

Has reemplazado un disco fallado, el resilver terminó y el pool está sano pero aún muestra contadores antiguos. Borra para reiniciar el marcador.
Has reinsertado un disco o reemplazado un cable/backplane SATA/SAS, y quieres confirmar que no vuelven a aparecer errores durante un scrub.
Tuviste un evento de energía puntual (p. ej. un PDU que falló, pérdida de energía de chasis) que causó errores transitorios de I/O; tras confirmar que el hardware está estable, borra para no vivir con “vergüenza histórica”.
Corrigiste una mala configuración (firmware incorrecto, modo del controlador, configuración multipath) y quieres demostrar la solución vigilando contadores bajo carga.

Úsalo para volver la monitorización sensata

Muchas configuraciones de monitorización disparan alertas por contadores de errores no cero. Si hiciste el trabajo—scrub, remediación, validación—dejar contadores antiguos entrena a tu organización para ignorar alertas. Clear se convierte en un reinicio operativo: “a partir de este momento, los errores nuevos significan incidentes nuevos”.

Úsalo en un dispositivo específico cuando estás aislando

Borrar todo el pool puede eliminar contexto forense útil. Prefiere:

zpool clear poolname cuando hayas terminado por completo y quieras que todo se reinicie.
zpool clear poolname /dev/disk/by-id/... cuando estés rastreando a un sospechoso y quieras un conteo limpio para esa ruta específica.

Cuándo es estúpido borrar errores

Borrar errores es estúpido cuando no has demostrado que el pool es estable, o cuando lo usas para silenciar síntomas en lugar de diagnosticar la causa.

No borres mientras los errores aún se acumulan

Si un scrub está en curso y CKSUM está subiendo, borrar es como cambiar el odómetro mientras el motor está en llamas. Perderás la capacidad de cuantificar “qué tan malo” y “qué tan rápido”. Conserva los números. Son evidencia.

No borres para “arreglar” la corrupción de datos

A veces zpool status dice errors: Permanent errors have been detected. Eso no es un problema de contadores. Es ZFS diciéndote que encontró bloques que no pudo reparar desde la redundancia. Borrar no resucita datos. Oculta la advertencia hasta que la siguiente lectura cause el mismo dolor en un lugar más caro: tu aplicación.

No borres para hacer que un pool degradado parezca verde

Un pool en DEGRADED ya está gastando redundancia. Si borras y declaras victoria sin reemplazar el componente fallido, estás apostando a que el resto del vdev se comportará. Esa apuesta es estadísticamente popular y profesionalmente lamentable.

No borres antes de haber capturado el contexto

Borrar borra una ruta de migas. Antes de limpiar, captura:

zpool status -v
zpool events -v (si está disponible)
Los logs del kernel alrededor del momento en que ocurrieron los errores
smartctl para los discos afectados

Primera broma (corta, relevante): Borrar errores de ZFS sin diagnóstico es como reiniciar el detector de humo. No apagaste el incendio; solo lo hiciste más silencioso.

Guion de diagnóstico rápido

Cuando estás on-call, no tienes el lujo de una relación filosófica con tu almacenamiento. Aquí te explico cómo llegar rápido a “qué está roto”.

Primero: establece si esto es activo o histórico

Revisa zpool status y anota si los contadores están aumentando con el tiempo.
Si hay un scrub/resilver en progreso, observa si los errores crecen durante esa actividad.

Segundo: clasifica el modo de falla (dispositivo vs ruta vs datos)

Si son mayormente READ/WRITE con timeouts en logs → sospecha dispositivo o transporte.
Si es CKSUM sin errores de I/O → sospecha corrupción en tránsito (cable/HBA/expander/RAM) o un disco que devuelve datos malos.
Si aparecen Permanent errors → trátalo como un evento de pérdida de datos hasta demostrar lo contrario.

Tercero: busca radio de blast compartido

¿Hay errores en múltiples unidades en el mismo HBA/puerto/expander? Eso es un componente compartido.
¿Hay errores solo en un disco? Suele ser el disco, su bahía o su cable.

Cuarto: decide si puedes seguir sirviendo

Vdev redundante, errores en un solo dispositivo, scrub que repara limpiamente: a menudo puedes seguir sirviendo mientras programas un reemplazo.
Vdev no redundante o múltiples dispositivos en el mismo RAIDZ fallando: deja de apostar. Estabiliza primero.

Tareas prácticas: comandos, salidas, decisiones

A continuación hay tareas operativas reales que puedes ejecutar. Cada una incluye: comando, qué significa la salida y qué decisión tomar.

Task 1: Get the headline status (don’t squint)

cr0x@server:~$ sudo zpool status
  pool: tank
 state: DEGRADED
status: One or more devices has experienced an error resulting in data corruption.
action: Restore the file in question if possible. Otherwise restore the entire pool from backup.
  scan: scrub repaired 0B in 02:41:13 with 0 errors on Tue Dec 24 03:12:01 2025
config:

        NAME                                          STATE     READ WRITE CKSUM
        tank                                          DEGRADED     0     0     0
          raidz1-0                                    DEGRADED     0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-ABC123        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-DEF456        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-GHI789        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-JKL012        UNAVAIL      8     2     0  cannot open

errors: Permanent errors have been detected in the following files:
        tank/data/finance.db

Qué significa: Esto no son “solo contadores.” Tienes un disco no disponible y ZFS reporta errores permanentes en un archivo específico.

Decisión: No ejecutes zpool clear como primer movimiento. Estabiliza el hardware (recupera el disco / reemplaza), y luego atiende el archivo corrupto (restaurar desde réplica/backup o reconstruir a nivel de aplicación).

Task 2: Get verbose detail on errors and files

cr0x@server:~$ sudo zpool status -v tank
  pool: tank
 state: DEGRADED
  scan: scrub repaired 0B in 02:41:13 with 0 errors on Tue Dec 24 03:12:01 2025
config:

        NAME                                          STATE     READ WRITE CKSUM
        tank                                          DEGRADED     0     0     0
          raidz1-0                                    DEGRADED     0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-ABC123        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-DEF456        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-GHI789        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-JKL012        UNAVAIL      8     2     0  cannot open

errors: Permanent errors have been detected in the following files:

        tank/data/finance.db

Qué significa: ZFS apunta a una ruta de dataset específica. Esto es accionable.

Decisión: Involucra al propietario de la aplicación. Determina si el archivo puede restaurarse o reconstruirse. El trabajo de hardware y de datos debe avanzar en paralelo.

Task 3: Confirm the disk is actually missing vs renamed

cr0x@server:~$ ls -l /dev/disk/by-id/ | grep JKL012

Qué significa: Ninguna salida sugiere que el SO no ve el dispositivo en absoluto (desconectado, muerto, enlace abajo, problema de controlador).

Decisión: Revisa cableado/backplane/HBA. Si es una bahía hot-swap, reinsertar la unidad. Si es una VM, revisa la conexión del disco virtual.

Task 4: Correlate with kernel logs (transport vs media)

cr0x@server:~$ sudo dmesg -T | egrep -i "ata|sas|scsi|reset|timeout|I/O error" | tail -n 20
[Wed Dec 24 02:01:44 2025] ata9.00: exception Emask 0x0 SAct 0x0 SErr 0x4050000 action 0x6 frozen
[Wed Dec 24 02:01:44 2025] ata9: SError: { CommWake DevExch }
[Wed Dec 24 02:01:45 2025] ata9.00: failed command: READ FPDMA QUEUED
[Wed Dec 24 02:01:45 2025] blk_update_request: I/O error, dev sdi, sector 918273645 op 0x0:(READ) flags 0x0 phys_seg 1 prio class 0
[Wed Dec 24 02:01:47 2025] ata9: hard resetting link
[Wed Dec 24 02:01:52 2025] ata9: link is slow to respond, please be patient (ready=0)
[Wed Dec 24 02:01:57 2025] ata9: SATA link down (SStatus 0 SControl 300)

Qué significa: Resets de enlace y link down indican más “ruta/transport” que “sector malo”. El disco puede estar bien; la ruta no lo está.

Decisión: Inspecciona/reemplaza cable, puerto del backplane o lane del HBA. No reemplaces el disco primero a menos que tengas otra evidencia.

Task 5: Pull SMART to see if the disk is sick

cr0x@server:~$ sudo smartctl -a /dev/sdi | egrep -i "Reallocated|Pending|Uncorrect|CRC|SMART overall|Power_On_Hours" -n
5:SMART overall-health self-assessment test result: PASSED
83:  5 Reallocated_Sector_Ct   0x0033   200   200   140    Pre-fail  Always       -       0
88:197 Current_Pending_Sector  0x0012   200   200   000    Old_age   Always       -       0
89:198 Offline_Uncorrectable   0x0010   200   200   000    Old_age   Offline      -       0
102:199 UDMA_CRC_Error_Count   0x003e   200   200   000    Old_age   Always       -       47
109:  9 Power_On_Hours         0x0032   094   094   000    Old_age   Always       -       46712

Qué significa: CRC altos sin reallocations/pending indica ruido en cable/backplane/controlador. El medio del disco no parece obviamente malo.

Decisión: Arregla la ruta. Luego haz un scrub. Y después considera borrar contadores.

Task 6: Identify which physical bay a by-id maps to

cr0x@server:~$ sudo lsblk -o NAME,SERIAL,MODEL,HCTL,SIZE,STATE | grep -E "sdi|JKL012"
sdi   WD-JKL012  WDC WD80EFAX-68LHPN0  3:0:9:0  7.3T  running

Qué significa: HCTL te da host:channel:target:lun, útil con HBAs SAS y mapeo de chasis.

Decisión: Usa HCTL y el mapa de tu chasis para tocar la unidad física correcta. Evita el clásico “sacar el disco equivocado”.

Task 7: Confirm pool topology and ashift (future pain predictor)

cr0x@server:~$ sudo zpool get ashift,autoreplace,autotrim tank
NAME  PROPERTY     VALUE   SOURCE
tank  ashift       12      local
tank  autoreplace  off     default
tank  autotrim     off     default

Qué significa: ashift=12 son sectores de 4K; correcto. autoreplace=off significa que reemplazar un disco puede requerir pasos explícitos. autotrim off es típico en pools HDD.

Decisión: Si esperas comportamiento hot-swap, decide si activar autoreplace después de entender tu entorno. No lo toques en medio del incidente a menos que disfrutes sorpresas.

Task 8: Run a scrub and watch whether counters increase

cr0x@server:~$ sudo zpool scrub tank

cr0x@server:~$ watch -n 10 sudo zpool status tank
Every 10.0s: sudo zpool status tank

  pool: tank
 state: ONLINE
  scan: scrub in progress since Wed Dec 24 04:01:10 2025
        1.23T scanned at 1.4G/s, 212G issued at 245M/s, 7.98T total
        0B repaired, 2.59% done, 08:31:12 to go
config:

        NAME                                          STATE     READ WRITE CKSUM
        tank                                          ONLINE       0     0     0
          raidz1-0                                    ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-ABC123        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-DEF456        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-GHI789        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-JKL012        ONLINE       0     0     0

errors: No known data errors

Qué significa: El scrub progresa, el pool está estable y no hay errores en aumento. Eso es una buena señal.

Decisión: Si esto sigue a una remediación (reinsertar/reemplazar cable), te acercas a territorio “seguro para borrar” después de que el scrub termine.

Task 9: Check scrub result and repaired bytes

cr0x@server:~$ sudo zpool status tank
  pool: tank
 state: ONLINE
  scan: scrub repaired 12M in 02:39:44 with 0 errors on Wed Dec 24 06:41:02 2025
config:

        NAME                                          STATE     READ WRITE CKSUM
        tank                                          ONLINE       0     0     3
          raidz1-0                                    ONLINE       0     0     3
            ata-WDC_WD80EFAX-68LHPN0_WD-ABC123        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-DEF456        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-GHI789        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-JKL012        ONLINE       0     0     3

errors: No known data errors

Qué significa: El scrub reparó 12M (self-healed), pero el disco aún muestra errores de checksum. Si estos errores son históricos y no aumentan, puedes borrar tras asegurarte de que la causa subyacente esté arreglada.

Decisión: Correlaciona con los logs durante el scrub. Si no hay nuevos resets/timeouts y SMART CRC deja de aumentar, borra y monitoriza.

Task 10: Clear a single device (surgical reset)

cr0x@server:~$ sudo zpool clear tank ata-WDC_WD80EFAX-68LHPN0_WD-JKL012

cr0x@server:~$ sudo zpool status tank
  pool: tank
 state: ONLINE
  scan: scrub repaired 12M in 02:39:44 with 0 errors on Wed Dec 24 06:41:02 2025
config:

        NAME                                          STATE     READ WRITE CKSUM
        tank                                          ONLINE       0     0     0
          raidz1-0                                    ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-ABC123        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-DEF456        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-GHI789        ONLINE       0     0     0
            ata-WDC_WD80EFAX-68LHPN0_WD-JKL012        ONLINE       0     0     0

errors: No known data errors

Qué significa: Los contadores se han reiniciado. Ahora tienes una línea base limpia.

Decisión: Someté el pool a carga normal y vuelve a comprobar en horas/días. Si los contadores reaparecen, la solución no aguantó.

Task 11: Use `zpool events` to see recent ZFS fault activity

cr0x@server:~$ sudo zpool events -v | tail -n 25
TIME                           CLASS
Dec 24 2025 02:01:58.219388000 ereport.fs.zfs.io
    vdev_path: /dev/disk/by-id/ata-WDC_WD80EFAX-68LHPN0_WD-JKL012
    vdev_guid: 1234567890123456789
    pool: tank
    pool_guid: 9876543210987654321
    ereport_payload:
        zio_err: 5
        zio_offset: 469124961280
        zio_size: 131072
        zio_objset: 54
        zio_object: 1
        zio_level: 0

Qué significa: ZFS registró un ereport de I/O para ese vdev. La marca de tiempo ayuda a correlacionar con logs del kernel y eventos físicos.

Decisión: Si los eventos paran tras la remediación, vas ganando. Si continúan, escala el aislamiento de hardware.

Task 12: Confirm the pool isn’t silently re-silvering or stuck

cr0x@server:~$ sudo zpool status -D tank
  pool: tank
 state: ONLINE
  scan: none requested
config:

        NAME                                    STATE     READ WRITE CKSUM
        tank                                    ONLINE       0     0     0
          raidz1-0                              ONLINE       0     0     0
            ata-WDC...ABC123                    ONLINE       0     0     0
            ata-WDC...DEF456                    ONLINE       0     0     0
            ata-WDC...GHI789                    ONLINE       0     0     0
            ata-WDC...JKL012                    ONLINE       0     0     0

errors: No known data errors

Qué significa: No hay scan en curso, nada pendiente.

Decisión: Si esperabas un resilver y no lo ves, quizás reemplazaste la cosa equivocada o ZFS no adjuntó el nuevo disco como asumiste.

Task 13: Replace a disk correctly (and avoid clearing too early)

cr0x@server:~$ sudo zpool replace tank ata-WDC_WD80EFAX-68LHPN0_WD-JKL012 /dev/disk/by-id/ata-WDC_WD80EFAX-68LHPN0_WD-MNO345

cr0x@server:~$ sudo zpool status tank
  pool: tank
 state: DEGRADED
  scan: resilver in progress since Wed Dec 24 07:10:04 2025
        612G scanned at 1.1G/s, 118G issued at 211M/s, 7.98T total
        118G resilvered, 1.44% done, 06:10:22 to go
config:

        NAME                                          STATE     READ WRITE CKSUM
        tank                                          DEGRADED     0     0     0
          raidz1-0                                    DEGRADED     0     0     0
            ata-WDC...ABC123                          ONLINE       0     0     0
            ata-WDC...DEF456                          ONLINE       0     0     0
            ata-WDC...GHI789                          ONLINE       0     0     0
            replacing-3                               DEGRADED     0     0     0
              ata-WDC...JKL012                        UNAVAIL      0     0     0  cannot open
              ata-WDC...MNO345                        ONLINE       0     0     0  (resilvering)

Qué significa: El resilver está activo; ZFS está reconstruyendo la redundancia en el disco nuevo.

Decisión: No borres durante resilver a menos que estés borrando errores obsoletos tras un problema transitorio resuelto y hayas capturado evidencia. Deja que el resilver termine; luego valida con scrub.

Task 14: Clear pool-wide after a completed and validated remediation

cr0x@server:~$ sudo zpool clear tank

cr0x@server:~$ sudo zpool status tank
  pool: tank
 state: ONLINE
  scan: resilvered 7.98T in 06:44:09 with 0 errors on Wed Dec 24 13:54:13 2025
config:

        NAME                                          STATE     READ WRITE CKSUM
        tank                                          ONLINE       0     0     0
          raidz1-0                                    ONLINE       0     0     0
            ata-WDC...ABC123                          ONLINE       0     0     0
            ata-WDC...DEF456                          ONLINE       0     0     0
            ata-WDC...GHI789                          ONLINE       0     0     0
            ata-WDC...MNO345                          ONLINE       0     0     0

errors: No known data errors

Qué significa: Línea base limpia tras un reemplazo/resilver exitoso.

Decisión: Pon un recordatorio para volver a revisar SMART y zpool status después de un día hábil y tras el próximo scrub programado.

Tres microhistorias corporativas del mundo real

Mini-historia 1: El incidente causado por una suposición errónea

El equipo de almacenamiento de una empresa mediana ejecutaba una carga mixta en un pool RAIDZ2: lecturas analíticas, compactaciones nocturnas y algunos datasets “temporales” que de alguna manera se volvieron permanentes. Una mañana, la monitorización empezó a alertar por errores de checksum en un solo disco. El ingeniero on-call vio que el pool todavía estaba ONLINE y decidió que era ruido antiguo. Ejecutó zpool clear para detener el spam de páginas.

En cuestión de horas, el contador de checksum volvió—rápido. Pero como la alerta había sido “manejada”, no recibió mucha atención. La noche siguiente, un trabajo por lotes pesado sometió el sistema a mayor carga que el tráfico diurno, y un segundo disco en el mismo vdev empezó a tirar timeouts de lectura. Ahora el pool pasó a DEGRADED. El equipo asumió que eran “dos discos fallando” y comenzó un proceso estándar de reemplazo.

Lo que faltó: ambos discos estaban conectados a través de la misma ruta del expander SAS, y el firmware del expander tenía un problema conocido con la gestión de energía del enlace. Los errores iniciales de checksum fueron la advertencia temprana. Borrarlos eliminó la capacidad de mostrar que los errores estaban aumentando, y también reinició la evidencia temporal en las notas on-call porque nadie capturó zpool status -v y los logs primero.

Reemplazaron un disco. El resilver avanzó a paso de tortuga con resets intermitentes. Reemplazaron el segundo disco también. Seguía inestable. Entonces un tercer disco empezó a fallar, y ahora todos tuvieron la horrible realización: no era un conjunto de discos malos. Era infraestructura compartida.

La solución fue aburrida: deshabilitar la configuración problemática de administración de energía del enlace, actualizar el firmware del expander durante una ventana de mantenimiento y reinsertar un cable mini-SAS marginal. Después de eso, los errores pararon. Borraron contadores de nuevo—esta vez correctamente—y los vieron quedarse en cero. El coste no fue solo hardware; fue confianza. Las páginas de almacenamiento se ignoraron durante semanas después, que es como las organizaciones acumulan futuros outages como deuda de tarjeta de crédito.

Mini-historia 2: La optimización que salió mal

Otra organización quería scrubs más rápidos. Tenían un gran pool y una ventana de mantenimiento ajustada, así que alguien tunearon el comportamiento de scrub a nivel del sistema (los knobs variaban por plataforma) y programaron scrubs durante horas de trabajo “porque el array es rápido”. Funcionó en pruebas.

En producción, el scrub más rápido aumentó la presión de lectura en un conjunto de discos envejecidos. Esa presión expuso un HBA marginal y una traza dudosa del backplane. Nada catastrófico—solo suficientes reintentos y resets de enlace para que ZFS empezara a registrar errores de checksum en múltiples discos. El pool se mantuvo online, así que los tickets se degradaron a “vigilar”.

Luego el equipo hizo lo peor para su observabilidad: borraban los errores cada semana después de cada scrub, porque a la dirección no le gustaban los paneles con números en rojo. Con los contadores constantemente reiniciados, se volvió imposible mostrar la tendencia de degradación del entorno. El sistema de advertencia temprana se convirtió en un filtro cosmético.

Eventualmente, una carga de escritura intensa coincidió con un scrub y un fallo de firmware, provocando que un vdev se desconectara temporalmente. El pool se recuperó, pero una aplicación vio errores transitorios y empezó a reconstruir índices desde cero, golpeando aún más el almacenamiento. El incidente no fue una gran explosión; fue una reacción en cadena impulsada por la “optimización”.

El postmortem fue contundente: tuning de rendimiento que oculta señales de fiabilidad no es optimización. Es deuda. Revirtieron el comportamiento agresivo del scrub, movieron scrubs a ventanas controladas, arreglaron el hardware compartido y solo entonces usaron zpool clear para reiniciar líneas base. El rendimiento volvió. También su credibilidad.

Mini-historia 3: La práctica aburrida pero correcta que salvó el día

Un equipo de servicios financieros ejecutaba ZFS para servicios internos que no podían permitirse sorpresas. Tenían una regla: antes de que nadie ejecute zpool clear, deben adjuntar tres artefactos al ticket—zpool status -v, un extracto relevante de logs del kernel y smartctl para cualquier disco involucrado. Sin excepciones, sin “arreglo rápido”.

Un fin de semana, un pool empezó a mostrar un pequeño número de errores de checksum en un solo disco. El sistema por lo demás se comportaba. El ingeniero on-call siguió el ritual, capturó la evidencia y notó algo sutil: el informe SMART mostraba CRC en aumento, pero reallocations/pending eran cero. Los logs del kernel mostraban resets de enlace en un puerto específico.

En lugar de reemplazar el disco, movieron la unidad a otra bahía y cambiaron el cable al backplane. Después ejecutaron un scrub; no aparecieron nuevos errores. Solo entonces borraron los contadores del dispositivo. La monitorización estuvo tranquila durante meses.

Lo que los salvó no fue genialidad. Fue la negativa a permitir que “borrar los errores” fuera un sustituto del diagnóstico. El ritual produjo suficientes datos para elegir el componente correcto la primera vez, en una ventana de mantenimiento calmada, sin un maratón de resilver y sin arriesgar una segunda falla durante la reconstrucción.

Errores comunes: síntoma → causa raíz → solución

Mistake 1: “Pool is ONLINE, so checksum errors don’t matter.”

Síntoma: El pool muestra ONLINE, pero un disco tiene CKSUM creciendo.

Causa raíz: La redundancia está enmascarando corrupción; ZFS repara lecturas, pero algo está devolviendo datos incorrectos (disco o ruta).

Solución: Correlaciona con dmesg y SMART; busca errores CRC y resets de enlace. Cambia cable/puerto o reemplaza el disco si SMART indica problemas del medio. Haz un scrub para validar. Borra solo después de que el contador deje de aumentar.

Mistake 2: Clearing errors to silence monitoring

Síntoma: Las alertas paran tras zpool clear, luego vuelven más tarde, a menudo peor.

Causa raíz: La monitorización tenía razón; borraste la evidencia y retrasaste el diagnóstico.

Solución: Conserva los contadores hasta que se resuelva la causa raíz. Si la fatiga de alertas es real, afina las alertas a “tasa de aumento” y a estados activos degraded/faulted, no solo contadores históricos no cero.

Mistake 3: Replacing disks when the real issue is the HBA/expander

Síntoma: Múltiples discos muestran errores, a menudo en diferentes vdevs, y los reemplazos no ayudan.

Causa raíz: Falla de componente compartido: HBA sobrecalentado, bugs de firmware del expander, backplane malo, bajadas de tensión.

Solución: Mapea dispositivos a HBAs/puertos (HCTL), revisa logs por patrones comunes de reset y aísla moviendo un disco afectado a otra ruta de controlador si es posible. Reemplaza/repara el componente compartido.

Mistake 4: Treating “Permanent errors” as a counter problem

Síntoma: zpool status lista archivos específicos con permanent errors.

Causa raíz: ZFS no pudo auto-reparar esos bloques (redundancia insuficiente, fallos múltiples o corrupción persistente en todas las réplicas).

Solución: Restaura archivos afectados desde backup/replica o reconstruye a nivel de aplicación. Identifica y corrige el hardware/transporte que causó la corrupción. Borrar contadores no arregla el archivo.

Mistake 5: Clearing before capturing evidence

Síntoma: “Ocurrió anoche pero no podemos reproducirlo.”

Causa raíz: Contadores/eventos/logs rotaron o fueron borrados, destruyendo la correlación.

Solución: Captura zpool status -v, zpool events -v y una ventana temporal de logs antes de cualquier higiene destructiva. Estandariza esto en los runbooks de incidentes.

Mistake 6: Confusing scrub with resilver and making the wrong call

Síntoma: El equipo ejecuta scrubs esperando que la redundancia se reconstruya tras un reemplazo, o reemplazan discos cuando lo que hace falta es un scrub.

Causa raíz: Scrub verifica y repara; resilver reconstruye sobre un dispositivo reemplazado/recién adjuntado. Objetivos distintos, señales distintas.

Solución: Si un dispositivo fue reemplazado/reattachado, confirma que el resilver está ocurriendo. Tras el resilver, ejecuta scrub para validar. Borra errores después de la validación.

Listas de verificación / plan paso a paso

Checklist A: “Can I run `zpool clear` now?”

¿Has capturado la salida de zpool status -v para el ticket?
¿Los logs del kernel muestran los últimos errores/resets de I/O relevantes y están explicados?
¿El pool está ONLINE sin dispositivos faltantes?
¿Se completó un scrub desde la corrección, con 0 errors?
¿Los indicadores SMART están estables (CRC no aumenta, sin pending/reallocated en crecimiento)?
¿Los contadores no están aumentando bajo carga?

Si no puedes responder sí a la mayoría, no borres. Si puedes, borra de forma quirúrgica (a nivel de dispositivo) cuando sea posible, y luego monitoriza.

Checklist B: Step-by-step incident response when `zpool status` shows errors

Estabilizar: confirma estado del pool, redundancia y si algún vdev está offline/unavail.
Preservar evidencia: captura zpool status -v, zpool events -v, logs y SMART.
Clasificar: READ/WRITE vs CKSUM vs permanent errors.
Alcance: disco único vs múltiples discos vs patrón de componente compartido.
Mitigar: reinsertar/cambiar cable/puerto; reemplazar disco solo cuando esté indicado.
Validar: resilver (si aplica), luego scrub.
Reiniciar línea base: borrar errores solo después de la validación.
Monitorizar: comprobar estado después de 1h, 24h y el próximo scrub; vigilar deltas de SMART.

Checklist C: Post-fix verification (the part people skip)

Ejecuta un scrub (o prográmalo inmediatamente si el pool es grande y necesitas ventana).
Confirma que no hay nuevos errores durante el scrub.
Confirma que los contadores permanecen estables al menos durante un ciclo normal de trabajo.
Sólo entonces borra los contadores de error y marca el incidente como resuelto.

Segunda broma (corta, relevante): La forma más rápida de hacer que zpool status parezca sano es zpool clear. La segunda más rápida es arreglar el problema.

Preguntas frecuentes

1) Does `zpool clear` fix corruption?

No. Borra contadores de error registrados y puede limpiar ciertos estados de fallo. La corrupción se arregla por reparación por redundancia durante lecturas/scrub, resilver o restaurando datos.

2) If I clear errors, can I lose data?

Borrar en sí no elimina datos, pero puede hacerte perder una falla en desarrollo al quitar la evidencia. La pérdida de datos viene después, cuando no reemplazas el componente malo a tiempo.

3) When should I clear: before or after a scrub?

Después. Un scrub es tu prueba de que el pool puede leer y verificar datos de extremo a extremo. Borrar antes del scrub elimina la línea base que quieres comparar.

4) My pool shows checksum errors but “No known data errors.” Is that okay?

Puede estar OK si los errores son históricos y no aumentan—ZFS puede haberlos reparado. No es OK si el contador de checksum está subiendo, especialmente durante un scrub o lecturas pesadas.

5) Why do checksum errors often implicate cables and HBAs?

Porque el disco puede devolver bytes que se corrompen en tránsito o por una ruta de controlador inestable. Los conteos SMART CRC y logs del kernel sobre resets de enlace son señales comunes.

6) Can I clear only one disk’s errors?

Sí, y a menudo deberías hacerlo. Usa zpool clear poolname vdev para reiniciar contadores en el dispositivo sospechoso preservando el contexto del pool.

7) What if errors return immediately after clearing?

Eso es un regalo: significa que tienes un problema activo. Deja de borrar. Correlaciona con logs y SMART, e identifica si es el disco o la ruta/hardware compartido.

8) Is it safe to clear errors on a degraded pool?

Generalmente no como “arreglo”. Si el pool está degradado porque falta un dispositivo, borrar no reemplaza la redundancia. La única razón segura es después de restaurar la disponibilidad del dispositivo y validar la estabilidad.

9) How do I decide between replacing the disk and swapping the cable?

Si SMART muestra reallocations/pending/uncorrectables en aumento, reemplaza el disco. Si SMART muestra CRC errors y los logs muestran resets de enlace, prioriza el cable/puerto/HBA. Si dudas, cambia primero la ruta; es de bajo riesgo y rápido.

10) Does clearing errors affect future diagnostics?

Sí. Pierdes contadores históricos que ayudan a mostrar tendencias. Por eso capturas evidencia primero y borras solo después de haber arreglado y validado.

Próximos pasos que puedes hacer hoy

Si operas ZFS en producción, deja de tratar zpool clear como un ritual y comienza a tratarlo como un reinicio controlado de evidencia.

Añade una regla a tus runbooks: no borrar hasta haber adjuntado zpool status -v, logs relevantes y salida SMART al ticket.
Enseña a tu monitorización a preocuparse por el cambio, no por la vergüenza: alerta por contadores en aumento, estados degraded/faulted, errores de scrub y caídas repetidas de dispositivos.
Programa scrubs como adultos: lo suficientemente regulares para detectar problemas latentes, lo bastante controlados para no ser tu pico de carga.
Practica borrados quirúrgicos: borra un solo vdev cuando estés aislando. Borra todo el pool cuando el incidente esté realmente terminado y validado.
Haz un ejercicio de mesa: simula errores de checksum en un disco y haz que el equipo siga el playbook sin improvisar con zpool clear.

Cuando borres, hazlo con una razón, una línea base y un plan para vigilar qué sucede después. Eso no es superstición. Es operaciones.