Una escritura de configuración en OpenWAF lleva, además de sus datos, tres cosas: un motivo, una marca opcional de simulación y la versión esperada de la zona. Todas las interfaces las usan igual.
El motivo
Toda escritura de configuración necesita un motivo de 1 a 500 caracteres (sin contar los espacios de los extremos), sin saltos de línea ni otros caracteres de control. Se guarda en la versión y en la auditoría. Sin él, la API responde 422 reason_required.
La única excepción es dar de alta una zona: la API la acepta sin motivo y guarda alta de la zona. La CLI pide --reason igualmente.
La simulación
Una simulación ejecuta la escritura completa, con la validación, la instantánea nueva y la configuración de cada nodo de borde que sirve la zona, dentro de una transacción, y después la deshace. Falla exactamente donde fallaría la escritura real y no toca ni el DNS ni el borde. La respuesta es el plan:
{
"dry_run": true,
"from_version": 7,
"to_version": 8,
"diff": {
"from": 7,
"to": 8,
"changes": [
{"path": "settings.hsts.max_age", "op": "replace", "from": 0, "to": 300}
]
},
"warnings": []
}Cada cambio tiene una ruta (path), una operación (op: add, remove o replace) y los valores de antes y de después. Las listas se identifican por identidad, no por posición: rules[id=12], records[id=…], certificates[hostname=…]. warnings enumera lo que la escritura dejaría fuera, como un sitio que no se ha podido construir. Si to_version es igual a from_version y no hay diferencias, la escritura no cambiaría nada.
La versión esperada
La confirmación lleva la versión contra la que simulaste. Si la zona sigue en esa versión, la escritura se aplica y crea la siguiente. Si alguien ha cambiado la zona entretanto, no se aplica nada y la API responde:
{"error": {"code": "version_conflict", "message": "the configuration changed: the current version is 9"}, "current_version": 9}Mira qué ha cambiado (zones diff, Cambios → Historial), vuelve a simular y revisa el plan nuevo antes de confirmar. Un conflicto de versión nunca aplica un cambio a medias.
En cada interfaz
Cada editor abre un diálogo con la Vista previa del cambio y el campo Motivo del cambio; Aplicar el cambio lo envía con la versión de la vista previa. Si hay un conflicto, el panel recarga la zona, vuelve a simular tu cambio y te pide que revises la vista previa nueva.
Toda orden que cambia algo exige --reason. La CLI simula primero con la versión actual de la zona, enseña las diferencias y pregunta ¿Aplicar? [s/N]; después aplica con la misma versión esperada. --dry-run se queda en la simulación y --yes no pregunta (obligatorio sin terminal, por ejemplo en CI). Un conflicto termina con el código de salida 3.
openwaf-cloud ctl zones set example.com hsts.max_age=300 --reason "Activar HSTS" --dry-run
openwaf-cloud ctl zones set example.com hsts.max_age=300 --reason "Activar HSTS" --yes --wait| Cabecera o parámetro | Regla |
|---|---|
X-Change-Reason | Obligatoria, de 1 a 500 caracteres. |
If-Match: "<versión>" | La versión esperada. Opcional en la mayoría de las escrituras y obligatoria al volver a una versión (sin ella, 428 if_match_required). |
?dry_run=1 | Simular: responde el plan con 200 y no cambia nada. |
Una escritura correcta devuelve la versión nueva en X-Config-Version y en ETag. Las lecturas de una zona y de sus ajustes de borde devuelven la versión actual en ETag.
curl -sS -X PATCH "https://dash.openwaf.dev/v1/orgs/$ORG/zones/$ZONE/edge?dry_run=1" \
-H "Authorization: Bearer $OPENWAF_TOKEN" \
-H "X-Change-Reason: Activar HSTS" \
-H 'If-Match: "7"' \
-H "Content-Type: application/json" \
-d '{"hsts": {"max_age": 300}}'Repite la petición sin ?dry_run=1 y con el mismo If-Match para aplicarla.
Cada herramienta de escritura recibe reason, confirm y expected_version. Con confirm a false (el valor por defecto) solo simula y devuelve el plan y current_version; tu asistente debe enseñarte las diferencias. Con confirm: true exige expected_version y lo envía como If-Match.
Cambios que no se versionan
Algunas escrituras quedan en la auditoría pero no crean versión de la zona:
- Se simulan, no se versionan: las purgas de caché y los certificados de origen (emitir y revocar). Llevan motivo y admiten simulación, pero no versión esperada.
- No se simulan: los clientes, la marca y la marca blanca. El
--dry-runde la CLI solo enseña lo que enviaría y no envía nada. - Sin motivo: comprobar ahora la delegación de una zona (
zones check) y escanear la preparación para agentes no cambian la configuración.