ZFS acltype: ACLs POSIX vs NFSv4 sin confusión

diciembre 16, 2025 • febrero 3, 2026 • Lectura: 28 min • Views: 10

¿Te fue útil?

Si has gestionado ZFS en producción el tiempo suficiente, has visto cómo los permisos se convierten en un experimento social: un administrador “arregla” el acceso con chmod -R, un usuario de Windows cambia una ACL en el Explorador, un cliente NFS cachea algo “útilmente” y de pronto el helpdesk está colapsando mientras el equipo de almacenamiento insiste en que “ZFS está bien”. ZFS normalmente está bien. Es nuestro modelo mental el que está roto.

Este artículo reconstruye ese modelo mental para personas que despliegan sistemas: qué significa realmente acltype, en qué se diferencian las ACL POSIX de las ACL NFSv4 de forma práctica, cómo se comportan SMB y NFS, qué configurar en datasets nuevos y cómo depurar el inevitable “Permission denied” en minutos en lugar de horas.

La decisión que realmente estás tomando

En ZFS, acltype no es una preferencia cosmética. Es una declaración del lenguaje de permisos que el dataset hablará de forma nativa y de qué semántica ZFS preservará cuando hagas cosas como chmod, chown o crear archivos nuevos dentro de directorios con ACLs heredadas.

En términos sencillos:

ACLs POSIX amplían los bits clásicos de modo UNIX y usuarios/grupos con un modelo familiar. Funcionan muy bien para flujos Linux/Unix, automatización y el enfoque de “lo que ves en ls -l básicamente es la historia”. Pero la mask, las ACL por defecto y las reglas de herencia limitadas sorprenden a la gente con regularidad.
ACLs NFSv4 son más ricas, se acercan a la semántica de ACL de Windows y tienen banderas de herencia explícitas. Encajan mejor con SMB, entornos mixtos y expectativas de “servidor de archivos empresarial real”. También introducen más formas de equivocarse: más expresividad implica más combinaciones erróneas posibles.

La mejor forma de elegir no es “¿qué me gusta?” sino “¿qué ecosistema cliente debe ser la fuente de la verdad?”. Si SMB/Windows es tu plano de control, las ACLs NFSv4 reducen el desajuste. Si la automatización Linux y la simplicidad de bits de modo son tu plano de control, las ACLs POSIX harán tu vida de on-call más tranquila.

Un chiste, porque nos lo hemos ganado: las ACLs POSIX son como una navaja multiusos: simples, útiles y tarde o temprano te cortarás si olvidas que existe la mask.

Hechos e historia que explican el desorden actual

Los permisos son historia política codificada en los kernels. Unos puntos de contexto ayudan a entender por qué ZFS termina pareciendo “místico” aquí.

Los permisos UNIX clásicos preceden a las redes. Los bits owner/group/other fueron diseñados para time-sharing multiusuario, no para identidad cross-dominio o editores GUI de ACL.
Las ACL POSIX fueron un parche pragmático. Extienden el modelo de bits de modo sin reemplazarlo, por eso existe la mask: preserva la idea de que los bits de modo siguen importando.
Las ACL NFSv4 se construyeron pensando en sistemas de archivos en red. Incluyen usuarios/grupos con nombre, semánticas richer de allow/deny y banderas de herencia que se comportan más como Windows.
Las ACL de Windows influenciaron el diseño de NFSv4. No son idénticas, pero suficientemente similares como para que el mapeo sea factible—importante para servidores SMB sobre ZFS.
Las ACE de “deny” no son una tradición UNIX. En NFSv4, las entradas deny pueden anular reglas allow según el orden y el modelo de evaluación; en las ACL POSIX no existe realmente un equivalente.
SMB siempre se ha preocupado por la fidelidad de las ACL. Los clientes Windows esperan herencia, flags explícitos vs heredados y semánticas estables al cambiar permisos desde la GUI.
ZFS se diseñó originalmente para cargas empresariales de Solaris. La expectativa fue clientes mixtos, almacenamiento centralizado y metadatos potentes — incluyendo soporte de ACL que no era un añadido de última hora.
Las herramientas Linux crecieron alrededor de las ACL POSIX. getfacl/setfacl son ubicuos y la gente espera que funcionen en todas partes, incluso cuando el filesystem subyacente habla ACLs NFSv4.
El mapeo de identidades es una guerra aparte. Las ACL pueden ser perfectas; si tu UID/GID/SID mapping está mal, los permisos seguirán fallando. Muchos “bugs de ACL en ZFS” son en realidad bugs de servicios de directorio.

Propiedades de ZFS que controlan la realidad de las ACL

acltype es solo una perilla. La combinación de propiedades de ACL determina cómo ZFS almacena las ACL, cómo trata chmod/chown y cómo se aplica la herencia.

acltype

Qué es: El modelo de ACL usado por el dataset. Los valores comunes dependen de la plataforma:

POSIX: a menudo representado como posixacl en implementaciones ZFS para Linux.
NFSv4: a menudo representado como nfsv4.

Qué cambia: Cómo se interpretan las ACL y qué herramientas/semánticas se comportan de forma nativa. También afecta cómo los servidores SMB pueden presentar y almacenar ACLs.

aclmode

Qué es: Qué hace ZFS cuando ejecutas chmod en un archivo que tiene una ACL. Esta es la fuente número uno de “chmod no hizo lo que yo creía”.

Comportamientos típicos (los nombres varían por plataforma, pero las semánticas se mantienen):

discard: eliminar las entradas de ACL que no encajan con el nuevo modo. Peligroso en entornos con ACLs ricas.
groupmask: mantener las ACLs pero tratar los permisos de grupo de forma conservadora según los bits de modo (default común en algunos entornos).
passthrough: permitir que chmod ajuste los bits de modo sin intentar “arreglar” las ACLs. A menudo lo mejor si gestionas ACLs explícitamente y no quieres que chmod las reescriba.
restricted: impedir que chmod haga las ACLs más permisivas de lo que eran. Bueno para seguridad; sorprendente en momentos de “soy root, ¿por qué no puedo?”.

aclinherit

Qué es: Cómo se heredan las ACLs en directorios por los archivos/directorios nuevos creados dentro de ellos.

Aquí es donde las ACLs NFSv4 brillan: tienen banderas de herencia explícitas, por lo que puedes obtener resultados predecibles “esta carpeta se comporta como un share de Windows”. POSIX puede usar ACLs por defecto, pero es menos expresivo y fácil de aplicar mal.

xattr y sa

Las ACLs normalmente viven en atributos extendidos. ZFS puede almacenar xattrs en “system attributes” (SA) para rendimiento (xattr=sa en muchos sistemas). Esto puede ser una mejora legítima de rendimiento para cargas con muchos metadatos—pero no simplifica los permisos y puede afectar cómo piensas sobre replicación y compatibilidad.

case sensitivity y normalización

No es una propiedad de ACL, pero si mezclas clientes Windows y Unix, casesensitivity y la normalización Unicode pueden provocar confusión en las rutas de acceso que parece un problema de permisos. Jurarás que un usuario “tiene acceso” pero está golpeando una ruta distinta a la auditada.

ACLs POSIX vs NFSv4: diferencias prácticas

Modelo mental: qué significa “permiso”

ACLs POSIX responden: “Dado un usuario propietario, grupo propietario, bits de modo y entradas adicionales opcionales de usuario/grupo, ¿está permitida esta operación?” La mask efectivamente limita los permisos de usuarios/grupos nombrados y de la clase de grupo. Si olvidas la mask, auditarás mal el acceso.

ACLs NFSv4 responden: “Dada una lista ordenada de ACEs de control de acceso con allow/deny y derechos ricos, más reglas de herencia, ¿está permitida esta operación?” Es más como un conjunto de reglas de firewall para archivos. El orden importa más. Existe deny. La herencia es de primera clase.

Herencia: default ACLs vs flags explícitas

POSIX usa “default ACLs” en directorios. Cuando se crea un archivo nuevo, esas entradas por defecto pueden convertirse en entradas de acceso en el hijo, sujetas a umask y al comportamiento de la mask. Funciona, pero no es tan expresivo como la herencia tipo Windows.

NFSv4 tiene banderas de herencia directamente en las ACEs: aplicar a archivos, a directorios, solo a hijos, etc. Por eso los despliegues Windows-on-ZFS suelen preferir ACLs NFSv4: el modelo mental coincide con lo que hace Explorer.

Expresividad: granularidad de derechos

POSIX tiene permisos toscos: read/write/execute más algunos bits especiales. Las ACLs POSIX reflejan eso: amplían “quién” pero no “qué”.

NFSv4 descompone el “qué” en un montón de derechos distintos: read data, write data, append, delete, read attributes, write attributes, read ACL, write ACL, take ownership y más. Eso es poderoso y peligroso: puedes crear un archivo que alguien pueda escribir pero no borrar, o que pueda leer pero no listar el directorio, según los derechos asignados.

Tooling: lo que tus administradores realmente usarán

POSIX gana en herramientas de CLI diarias. La mayoría de admins Linux pueden razonar con chmod, chown, getfacl, setfacl. La trampa es que usarán estas herramientas en un dataset donde no deberían y las cosas funcionarán a medias.

NFSv4 tiene herramientas variables. Algunos entornos usan nfs4_getfacl/nfs4_setfacl. Los entornos SMB suelen gestionar ACLs vía herramientas de Windows. Eso está bien—hasta que un administrador Linux aplica un chmod -R y “limpia” el orden cuidadosamente diseñado de las ACEs.

Chiste #2 (y eso es todo lo que recibirás)

Las ACLs NFSv4 son como un termostato programable: increíblemente capaces, y de alguna manera la oficina sigue pasando frío porque una persona descubrió “anulaciones de horario”.

SMB, NFS y “funcionó en mi cliente”

La mayoría de incidentes de ACL ocurren en el límite del protocolo. ZFS almacena algo; SMB y NFS presentan algo; tus admins cambian algo; y la lógica de mapeo hace lo mejor que puede.

SMB en ZFS: donde normalmente NFSv4 ACLs tiene sentido

Si tu dataset sustenta un share SMB y usuarios Windows gestionan permisos, quieres semánticas de ACL que se parezcan a Windows. Las ACLs NFSv4 tienden a mapear más limpiamente a la herencia y derechos estilo Windows. Aún necesitas mapeo de identidades consistente (SIDs a Unix IDs, dependiendo de tu stack), pero la “forma” de la ACL encaja con las expectativas del cliente.

Lo que suele romper no es “las ACLs no funcionan”, sino “las ACLs funcionan diferente que los bits de modo”. Los admins de Windows esperan que quitar “Write” quite la capacidad de crear archivos, modificar atributos, borrar, etc. Si tu mapeo colapsa varios derechos en un solo bit, puedes crear casos raros: puede escribir pero no renombrar; puede crear pero no borrar; puede atravesar pero no listar.

NFS en ZFS: elige las semánticas que tus clientes entienden

Los clientes NFSv3 viven mayormente en un universo de bits de modo. Los clientes NFSv4 pueden manejar ACLs NFSv4, pero si tus herramientas cliente y prácticas de administración lo hacen es otra pregunta. Si ejecutas NFS para servidores de aplicaciones Linux, las ACLs POSIX suelen ser la opción menos sorprendente—siempre que configures aclmode y aclinherit para coincidir con tu realidad operacional.

SMB + NFS mixto: decide quién es la autoridad

El setup mixto más limpio es aquel donde un solo sistema es autoritativo para editar ACLs. Patrones comunes:

Windows autoritativo: ACLs NFSv4, ediciones vía SMB, clientes NFS consumen la mayoría; los admins Linux están entrenados para no “arreglar” con chmod.
Unix autoritativo: ACLs POSIX, ediciones vía CLI e IaC, SMB (si existe) se trata como una vista de compatibilidad con expectativas limitadas.

Si permites que ambos lados editen libremente permisos, no estás construyendo un servidor de archivos—estás construyendo una máquina del tiempo que revisita aleatoriamente estados antiguos de ACL.

Tres micro-relatos del mundo corporativo

Micro-relato 1: un incidente causado por una suposición errónea

La configuración parecía estándar: dataset ZFS respaldando un share SMB para un equipo de finanzas, más montajes NFS para un job batch que generaba informes nocturnos. Alguien creó una carpeta “Reports”, copió la estructura del año pasado y todo parecía bien. Luego, justo después del cierre del mes, el job batch empezó a fallar con “Permission denied” al escribir archivos—solo en una subcarpeta.

El admin on-call hizo lo que muchos haríamos a las 2 a.m.: chmod -R g+rwX en el árbol de carpetas. “Funcionó” para el job Linux, pero a la mañana siguiente los usuarios Windows reportaron que ya no podían cambiar permisos y que algunas herencias habían desaparecido. Ahora el incidente tenía un segundo acto.

La suposición errónea fue que los bits de modo eran la fuente de la verdad. El dataset tenía ACLs NFSv4 afinadas para herencia Windows. chmod no solo estaba cambiando el modo—estaba disparando el comportamiento de aclmode que reescribió partes de las ACLs para ajustarlas al nuevo modo. El job Linux se salvó por accidente; la estructura ACL de Windows fue daño colateral.

La solución fue aburrida y quirúrgica: restaurar ACLs desde un snapshot para el subtree afectado, asignar un principal de servicio dedicado para el job batch y otorgar derechos explícitos vía el modelo de ACL NFSv4 (o via SMB con mapeo de identidades consistente). La solución a largo plazo fue cultural: “chmod no es un editor de ACL” se convirtió en una regla de runbook en ese almacenamiento.

Micro-relato 2: una optimización que salió mal

Un equipo de plataforma quería operaciones de metadata más rápidas en un pool de home directories muy activo: muchos archivos pequeños, constantes comprobaciones de ACL y usuarios que se quejaban por listados lentos. Alguien sugirió habilitar xattrs basados en SA (el clásico “almacenar xattrs de forma más eficiente”) y hacer las ACLs “más compatibles” cambiando el manejo de ACL y los valores por defecto de herencia para ajustar el lado SMB.

El rendimiento mejoró—brevemente. El verdadero contratiempo vino semanas después durante una prueba de replicación y un drill de restore. Un subconjunto de datasets restaurados mostró comportamiento ligeramente distinto de ACL: ciertos directorios estaban heredando permisos de forma distinta que antes, y un puñado de cuentas de servicio perdió la capacidad de atravesar rutas que usaban a diario. Nadie lo notó en staging porque los datos de prueba no incluían los casos borde raros: árboles de directorio profundos con mezcla de ACEs explícitas y heredadas.

La raíz no fue que SA fuera “malo”. Fue que el equipo combinó múltiples cambios (almacenamiento de xattr, comportamiento de herencia de ACL y flujos de trabajo administrativos) y validó solo “rápido” y “parece accesible”. En otras palabras: optimizaron la métrica fácil y se saltaron la difícil—equivalencia semántica.

La recuperación fue sencilla pero dolorosa: revertir primero los cambios de comportamiento de ACL, re-testear replicación con verificación de ACL (no solo conteo de archivos) y luego reintroducir ajustes de rendimiento una perilla a la vez. La lección: ajustar rendimiento es fácil; probar que no cambiaste significado es la verdadera ingeniería.

Micro-relato 3: una práctica aburrida pero correcta que salvó el día

Un equipo de almacenamiento operaba una plataforma ZFS multi-tenant para apps internas: NFS para servicios Linux, SMB para algunos equipos legados. Tenían una regla poco glamorosa: cada dataset tenía una “etiqueta de intención” documentada en las propiedades del dataset y reflejada en el nombre—algo como apps-posix versus shares-nfsv4. También tenían un chequeo CI en infraestructura-como-código que rechazaba crear un dataset sin acltype, aclmode y aclinherit explícitos.

Un viernes, un proyecto pidió “solo un share rápido” para un dropbox de un vendor. Un ingeniero bienintencionado clonó un dataset existente y lo exportó vía SMB. Los vendors podían subir, pero los usuarios internos no podían leer los archivos después. Olía a mapeo de identidades, pero el equipo no persiguió fantasmas.

Comprobaron la etiqueta de intención del dataset primero. Era un dataset orientado a POSIX clonado de una exportación de aplicación. El share SMB fue un error a nivel de arquitectura, no un ajuste de permisos. Crearon un nuevo dataset orientado a NFSv4 para el dropbox, movieron los datos y dejaron de intentar que un dataset satisfaga semánticas conflictivas.

Sin heroísmos, sin arqueología de ACL el fin de semana. La práctica “aburrida”—intención explícita y propiedades forzadas—convirtió un potencial outage en un cambio pequeño y reversible.

Tareas prácticas (comandos + interpretación)

Los comandos abajo asumen un sistema Linux con utilidades ZFS instaladas. Algunos entornos difieren ligeramente en nombres de propiedades y herramientas disponibles, pero la lógica operacional es trasladable entre plataformas. Cada tarea incluye qué buscar y cómo interpretarlo.

Tarea 1: Identificar el modelo de ACL del dataset y propiedades relacionadas

cr0x@server:~$ sudo zfs get -r acltype,aclmode,aclinherit,xattr pool/share
NAME        PROPERTY    VALUE        SOURCE
pool/share  acltype     nfsv4        local
pool/share  aclmode     restricted   local
pool/share  aclinherit  passthrough  local
pool/share  xattr       sa           local

Interpretación: Este dataset es nativo de ACL NFSv4. aclmode=restricted significa que chmod estará constreñido; aclinherit=passthrough sugiere que el comportamiento de herencia está diseñado para preservar la intención de las ACEs. xattr=sa indica que los xattrs (a menudo incluyendo ACLs) se almacenan de forma eficiente en SA, lo que puede ayudar en cargas con muchos metadatos.

Tarea 2: Confirmar si los archivos tienen ACLs más allá de los bits de modo

cr0x@server:~$ ls -l /pool/share/project
total 4
drwxrwx---+  5 root finance 5 Dec 24 09:10 Reports
-rw-r-----+  1 root finance 0 Dec 24 09:10 readme.txt

Interpretación: El + indica que existe una ACL. Los bits de modo por sí solos no contarán toda la historia.

Tarea 3: Leer ACLs POSIX con getfacl (datasets POSIX)

cr0x@server:~$ getfacl -p /pool/posixdata/team
# file: /pool/posixdata/team
# owner: root
# group: team
user::rwx
group::r-x
other::---
default:user::rwx
default:group::r-x
default:other::---

Interpretación: Existen ACLs por defecto, así que los nuevos hijos heredan esto como punto de partida. Si hay una entrada mask::, recuerda que limita los permisos efectivos para usuarios/grupos nombrados y para la clase de grupo.

Tarea 4: Mostrar el efecto de la mask (sorpresa clásica POSIX ACL)

cr0x@server:~$ setfacl -m u:alice:rwx /pool/posixdata/team
cr0x@server:~$ getfacl -p /pool/posixdata/team | sed -n '1,12p'
# file: /pool/posixdata/team
# owner: root
# group: team
user::rwx
user:alice:rwx
group::r-x
mask::r-x
other::---

Interpretación: Alice tiene rwx en la entrada ACL, pero los permisos efectivos están limitados por la mask::r-x. Si Alice no puede escribir, la mask es la primera sospechosa.

Tarea 5: Arreglar la mask intencionalmente (no por accidente)

cr0x@server:~$ setfacl -m m::rwx /pool/posixdata/team
cr0x@server:~$ getfacl -p /pool/posixdata/team | grep -E 'user:alice|mask::'
user:alice:rwx
mask::rwx

Interpretación: Has ampliado el techo de permisos efectivos. Haz esto conscientemente; las mask existen para preservar las restricciones del estilo bits de modo.

Tarea 6: Inspeccionar ACLs NFSv4 (datasets NFSv4)

cr0x@server:~$ nfs4_getfacl /pool/share/project/Reports
A::OWNER@:rwatTnNcCy
A::GROUP@:rxtncy
A::EVERYONE@:tncy

Interpretación: Estás viendo ACEs. Las letras representan derechos; los conjuntos exactos varían. Fíjate si los permisos se otorgan a OWNER@, GROUP@ o a principals nombrados, y si hay entradas deny (que aparecerían con D en muchas salidas).

Tarea 7: Comprobar si la herencia de ACL está configurada a nivel de dataset

cr0x@server:~$ sudo zfs get aclinherit pool/share
NAME       PROPERTY    VALUE        SOURCE
pool/share aclinherit  passthrough  local

Interpretación: passthrough generalmente significa que ZFS intentará no “simplificar” las ACEs heredadas. Si ves herencia eliminada o alterada, esta propiedad es parte de la explicación.

Tarea 8: Ver qué hace chmod en un archivo con ACL (y por qué sorprende)

cr0x@server:~$ sudo zfs get aclmode pool/share
NAME       PROPERTY  VALUE       SOURCE
pool/share aclmode   restricted  local

cr0x@server:~$ chmod 777 /pool/share/project/readme.txt
chmod: changing permissions of '/pool/share/project/readme.txt': Operation not permitted

Interpretación: Con aclmode=restricted, chmod puede estar impedido de hacer el archivo más permisivo de lo que la ACL permite. Esta es una característica de seguridad, pero también una pista para depurar: si chmod falla o “no hace nada”, revisa aclmode y la ACL misma.

Tarea 9: Confirmar quién ZFS piensa que es el propietario y el grupo (sanidad de identidades)

cr0x@server:~$ stat -c '%n owner=%U(%u) group=%G(%g) mode=%a' /pool/share/project/Reports
/pool/share/project/Reports owner=root(0) group=finance(10025) mode=770

Interpretación: Si ves IDs numéricos donde esperabas nombres (o nombres equivocados), probablemente tienes un problema de mapeo de identidades, no de ACL. Arregla la identidad primero o aplicarás ACLs al principal equivocado.

Tarea 10: Rastrear una falla de acceso desde la perspectiva del cliente

cr0x@server:~$ sudo -u alice bash -lc 'cd /pool/share/project/Reports && touch testfile'
touch: cannot touch 'testfile': Permission denied

Interpretación: Reproducir como el usuario elimina conjeturas. Si Alice no puede crear, estás depurando derechos de directorio de escritura/creación (no derechos de archivo). Con ACLs NFSv4, puede que necesites derechos específicos tipo “add file”; con POSIX, necesitas write+execute en el directorio.

Tarea 11: Snapshot antes de cirugía de ACL (seguro barato)

cr0x@server:~$ sudo zfs snapshot pool/share@before-acl-fix
cr0x@server:~$ sudo zfs list -t snapshot -o name,creation | grep 'pool/share@before-acl-fix'
pool/share@before-acl-fix  Wed Dec 24 09:35 2025

Interpretación: El trabajo con ACL es reversible si haces snapshot primero. Esta es la diferencia entre “lo arreglamos rápido” y “nos quedamos toda la noche”.

Tarea 12: Comparar ACLs entre dos directorios para detectar deriva

cr0x@server:~$ getfacl -p /pool/posixdata/team > /tmp/team.acl
cr0x@server:~$ getfacl -p /pool/posixdata/team-archive > /tmp/team-archive.acl
cr0x@server:~$ diff -u /tmp/team.acl /tmp/team-archive.acl | sed -n '1,80p'
--- /tmp/team.acl
+++ /tmp/team-archive.acl
@@
 group::r-x
-mask::rwx
+mask::r-x

Interpretación: Una sola diferencia en la mask puede explicar por qué “funciona en una carpeta pero no en la otra”. Esta es una forma rápida de atrapar cambios sutiles que ocurren después de “arreglos rápidos”.

Tarea 13: Auditar el mountpoint del dataset y asegurarte de que editas la ruta correcta

cr0x@server:~$ sudo zfs get mountpoint pool/share
NAME       PROPERTY    VALUE         SOURCE
pool/share mountpoint  /pool/share   local

cr0x@server:~$ mount | grep '/pool/share'
pool/share on /pool/share type zfs (rw,xattr,noacl)

Interpretación: Confirma que el dataset que crees que estás cambiando es el montado donde piensas. Editar una ruta bind-montada o un dataset distinto es un clavo clásico propio. (Nota: las opciones de mount mostradas varían por plataforma.)

Tarea 14: Verificar que la herencia en un directorio hace lo que crees

cr0x@server:~$ mkdir -p /pool/posixdata/team/newdir
cr0x@server:~$ touch /pool/posixdata/team/newdir/newfile
cr0x@server:~$ getfacl -p /pool/posixdata/team/newdir | sed -n '1,25p'
# file: /pool/posixdata/team/newdir
# owner: root
# group: team
user::rwx
group::r-x
other::---
default:user::rwx
default:group::r-x
default:other::---

Interpretación: Si la default ACL no está presente en el nuevo directorio, la herencia no está configurada como crees, o un proceso de creación la está sobreescribiendo. Para NFSv4 harías el equivalente inspeccionando ACEs heredadas en objetos hijos.

Guion de diagnóstico rápido

Este es el flujo de triaje que uso cuando “los permisos están rotos” llega a la cola de storage/SRE. El objetivo es encontrar el cuello de botella real rápidamente: desajuste de semánticas, desajuste de identidades o propiedades/herramientas que reescriben cosas.

Primero: confirma qué modelo de permisos tienes

Revisa las propiedades del dataset: acltype, aclmode, aclinherit, xattr.
Confirma que el objeto tiene una ACL (+ en ls -l), y obtén la ACL con la herramienta correcta (getfacl para POSIX; nfs4_getfacl para NFSv4 donde aplique).

Si te saltas esto y vas directo a chmod/chown, estarás depurando a ciegas.

Segundo: reproduce como el usuario e identifica la operación

Reproduce con sudo -u user localmente (o equivalente) para confirmar que no es cache cliente o bug de aplicación.
Determina la operación que falla: traversal de directorio, listado, creación, renombrado, borrado, lectura, escritura, cambio de atributos.

Operaciones distintas mapean a derechos distintos. “Puede escribir archivo pero no renombrar” es problema de permisos de directorio, no de archivo.

Tercero: valida el mapeo de identidades antes de reescribir ACLs

Chequea propiedad vía stat y confirma resolución esperada de UID/GID.
En entornos mixtos, confirma que el usuario se representa consistentemente entre SMB/NFS/Linux. Si “alice” es UID 1001 en Linux pero mapea distinto via servicios de directorio, tus ediciones de ACL pueden dirigirse al principal equivocado.

Cuarto: verifica si propiedades a nivel dataset están reescribiendo tu intención

Si chmod parece “fallar” o “no persistir”, revisa aclmode.
Si nuevos archivos no heredan permisos esperados, revisa aclinherit y si el directorio padre tiene default ACLs (POSIX) o ACEs heredables (NFSv4).

Quinto: solo entonces, cambia permisos—mínimamente y de forma reversible

Snapshot primero.
Cambia el alcance más pequeño que arregle el problema.
Verifica desde cada tipo de cliente relevante si estás en un entorno mixto.

Errores comunes, síntomas, soluciones

Error 1: Tratar chmod como editor de ACL en datasets NFSv4

Síntomas: Herencia Windows se rompe; las ACLs “se simplifican”; permisos derivan después de un chmod desde Linux; chmod falla con “Operation not permitted”.

Solución: Deja de usar chmod para cambios de política en datasets NFSv4. Usa herramientas de ACL NFSv4 o gestión via SMB/Windows de forma consistente. Revisa aclmode; considera passthrough si tu entorno requiere que chmod no reescriba ACLs, pero solo si entiendes las implicaciones de seguridad.

Error 2: Olvidar que la mask POSIX existe

Síntomas: getfacl muestra user:alice:rwx pero Alice no puede escribir; “parece rwx pero se comporta como r-x”.

Solución: Revisa mask::. Ajústala deliberadamente con setfacl -m m::rwx (o la mask menos permisiva que cumpla los requisitos). Educa a los operadores: la mask limita los derechos efectivos.

Error 3: Asumir que “group write” significa “puede borrar archivos”

Síntomas: El usuario puede crear archivos pero no borrar/renombrar, o al revés, dependiendo de permisos de directorio y del sticky bit; en NFSv4 los derechos no mapean limpiamente a “write”.

Solución: Depura permisos de directorio por separado de permisos de archivo. En POSIX: el directorio necesita write+execute para create/delete/rename; el sticky bit cambia la semántica de borrado. En NFSv4: asegura que las ACEs de directorio incluyan derechos adecuados para delete/rename/add-file.

Error 4: Mezclar ediciones de ACL vía SMB y setfacl desde Linux en el mismo dataset

Síntomas: Permisos oscilan; flags de herencia desaparecen; Windows muestra entradas “raras”; Linux muestra ACLs que no corresponden con la intención de Windows.

Solución: Decide una vía editora autoritativa. Si SMB es autoritativo, gestiona ACLs via herramientas SMB/Windows y mantén cambios Linux mínimos y procedurales. Si Linux es autoritativo, limita expectativas de SMB y documéntalas.

Error 5: Aplicar cambios recursivos sin snapshots

Síntomas: Outages amplios; arreglas un servicio y rompes diez más; el rollback es manual y lento.

Solución: Snapshot antes de recursividad. Si debes hacer cambios recursivos, prueba en un pequeño subtree, valida clientes y luego avanza.

Error 6: Depurar permisos antes de depurar identidad

Síntomas: Las ACLs parecen correctas pero el acceso es denegado; nombres resuelven de forma inconsistente; archivos muestran propietarios numéricos; usuarios SMB aparecen como IDs inesperados en el servidor.

Solución: Valida el mapeo UID/GID/SID. Asegura configuración consistente del servicio de directorio. La corrección de ACL es inútil si los principals no mapean a las identidades previstas.

Error 7: Confundir “traverse” con “list” en directorios

Síntomas: El usuario puede acceder a una ruta conocida pero no puede listar el directorio; o al revés, puede listar pero no entrar.

Solución: En POSIX: execute en un directorio es traverse; read es list. En NFSv4: asegura que las ACEs incluyan derechos apropiados para listar vs atravesar.

Listas de verificación / planes paso a paso

Checklist: elegir acltype para un dataset nuevo

Identifica el protocolo cliente primario: SMB-first o NFS/Linux-first.
Decide el editor autoritativo de ACL: herramientas Windows o CLI/IaC de Linux.
Selecciona acltype: NFSv4 para SMB-first; POSIX para Linux-first.
Configura aclmode intencionalmente: si quieres que chmod esté constreñido, usa comportamiento tipo restricted; si quieres que chmod evite reescribir ACLs, elige passthrough (con precaución).
Configura aclinherit intencionalmente: elige un modo que preserve la semántica de herencia que realmente quieres.
Decide almacenamiento de xattr: considera xattr=sa para cargas con muchos metadatos; valida compatibilidad en tu entorno.
Documenta la intención: inclúyela en el nombre del dataset o en sus propiedades para que los operadores sepan qué reglas aplican.

Paso a paso: crear un dataset orientado a ACL POSIX para apps Linux

cr0x@server:~$ sudo zfs create -o acltype=posixacl -o xattr=sa pool/apps
cr0x@server:~$ sudo zfs set aclmode=groupmask pool/apps
cr0x@server:~$ sudo zfs set aclinherit=passthrough pool/apps
cr0x@server:~$ sudo zfs get acltype,aclmode,aclinherit,xattr pool/apps
NAME      PROPERTY    VALUE        SOURCE
pool/apps acltype     posixacl     local
pool/apps aclmode     groupmask    local
pool/apps aclinherit  passthrough  local
pool/apps xattr       sa           local

Interpretación: Esta es una base sensata para entornos Linux que usan ACLs POSIX. Puedes elegir diferentes aclmode/aclinherit según la política, pero el punto es: configúralos explícitamente, no heredes valores por defecto a ciegas.

Paso a paso: crear un dataset orientado a ACL NFSv4 para shares SMB

cr0x@server:~$ sudo zfs create -o acltype=nfsv4 -o xattr=sa pool/shares
cr0x@server:~$ sudo zfs set aclmode=restricted pool/shares
cr0x@server:~$ sudo zfs set aclinherit=passthrough pool/shares
cr0x@server:~$ sudo zfs get acltype,aclmode,aclinherit,xattr pool/shares
NAME        PROPERTY    VALUE        SOURCE
pool/shares acltype     nfsv4        local
pool/shares aclmode     restricted   local
pool/shares aclinherit  passthrough  local
pool/shares xattr       sa           local

Interpretación: Esto se alinea con “SMB/Windows es autoritativo”. Reduce la probabilidad de que un chmod en el host amplíe accidentalmente el acceso. No reemplaza la necesidad de mapeo de identidades consistente.

Paso a paso: respuesta a incidentes de permisos (procedimiento seguro)

Snapshot del dataset afectado o al menos del límite de dataset más pequeño que contenga la ruta impactada.
Captura las ACLs actuales de algunas rutas representativas en archivos de texto.
Reproduce la falla como el usuario y determina la operación que falla.
Arregla problemas de mapeo de identidades primero si existen.
Aplica cambios mínimos de ACL usando el modelo/herramienta correcta.
Verifica desde cada tipo de cliente relevante (SMB y/o NFS) y desde shell local.
Documenta qué cambió y por qué; la deriva de ACL sin documentación es un incidente repetido.

Preguntas frecuentes

1) ¿Qué cambia exactamente `acltype` en ZFS?

Selecciona las semánticas de ACL que ZFS usará para ese dataset: comportamiento ACL POSIX (mask, default ACLs) versus comportamiento ACL NFSv4 (listas de ACE con flags de herencia y derechos más ricos). Influye en cómo se almacenan las ACLs y cómo las operaciones que modifican permisos interactúan con ACLs existentes.

2) Si uso ACLs NFSv4, ¿puedo seguir usando `chmod` y `chown`?

Puedes, pero debes entender aclmode. En muchas configuraciones, chmod está constreñido o impedido de hacer cambios que entren en conflicto con la política de ACL. Si tu organización espera “chmod arregla todo”, los datasets NFSv4 generarán tickets a menos que retraines los flujos de trabajo.

3) ¿Por qué `ls -l` muestra permisos que no coinciden con la realidad?

Porque los bits de modo son solo parte de la historia cuando existen ACLs. Con ACLs POSIX, la mask puede limitar los permisos efectivos. Con ACLs NFSv4, los bits de modo a menudo son una vista resumida y no representan completamente derechos como delete, rename o write-ACL.

4) ¿Debo usar ACLs POSIX para shares NFS?

A menudo sí para entornos NFSv3 centrados en Linux, porque el modelo operacional se alinea. Para clientes NFSv4 que realmente usan ACLs NFSv4 de extremo a extremo, las ACLs NFSv4 pueden encajar—pero solo si tus herramientas cliente y hábitos administrativos coinciden con ese mundo.

5) ¿Debo usar ACLs NFSv4 para shares SMB?

En la mayoría de entornos Windows mixtos, sí. Las ACLs NFSv4 tienden a preservar mejor la semántica de herencia estilo Windows y evitan mapeos con pérdida. La salvedad es el mapeo de identidades: si tus usuarios/grupos no se mapean consistentemente, el mejor modelo de ACL no te salvará.

6) ¿Puedo cambiar `acltype` en un dataset existente de forma segura?

“De forma segura” depende de qué existe en el dataset y de cómo los clientes dependen de las semánticas actuales. Cambiar el modelo puede alterar cómo se interpretan o representan las ACLs. En producción, trátalo como una migración: snapshot, prueba en un clone, valida con cargas reales y espera casos borde.

7) ¿Por qué algunos usuarios tienen “write” pero no pueden borrar archivos?

En POSIX, borrar está controlado por permisos del directorio (y reglas del sticky bit), no por el bit writable del archivo. En NFSv4, delete/rename pueden ser derechos separados de write data. Diagnostica las ACLs/permisos del directorio, no solo las ACLs del archivo.

8) ¿Cuál es la forma más rápida de depurar “Permission denied”?

Confirma acltype y obtén la ACL con la herramienta correcta, reproduce como el usuario, identifica si la falla es traversal/list/create/rename, luego valida el mapeo de identidades. Solo después de eso modifica ACLs. Esto evita la clásica espiral de “chmod lo empeoró”.

9) ¿Cambia `xattr=sa` el comportamiento de ACL?

Principalmente cambia dónde se almacenan los xattrs por rendimiento, no las semánticas. Pero los cambios de rendimiento pueden exponer problemas latentes (como aplicaciones que hacen más operaciones de metadata de las esperadas), y operativamente deberías validar replicación/restore y compatibilidad de herramientas en tu entorno.

10) Si debo soportar ambos SMB y NFS, ¿cuál es la estrategia menos dolorosa?

Elige un modelo de permisos autoritativo por dataset y valóralo. Usa datasets separados para cargas SMB-first y NFS-first. La edición de autoridad mixta en el mismo dataset es donde surge la rareza de permisos a largo plazo.

Conclusión

acltype trata menos de internals de ZFS y más de verdad operacional: quién define la política de acceso y qué semánticas de cliente prometes preservar. Las ACLs POSIX son la extensión natural de los bits de modo Unix y suelen ser el camino más calmado para estates Linux-first—siempre que respetes la mask y las reglas de default ACL. Las ACLs NFSv4 son la herramienta correcta cuando las semánticas e herencia de Windows/SMB deben permanecer intactas—siempre que dejes de tratar a chmod como un disolvente universal.

La verdadera victoria es la consistencia. Decide la identidad y autoridad de permisos del dataset desde el inicio, configura propiedades explícitamente, haz snapshot antes de cambios recursivos y depura el mapeo de identidades antes de reescribir ACLs. Haz eso, y los permisos de ZFS dejan de ser una casa encantada y se convierten en un sistema con el que puedes razonar—on-call, bajo presión, con expectativas de uptime de adultos.