# ratelimit

> Órdenes openwaf-cloud ctl ratelimit para listar, añadir, cambiar y quitar límites de peticiones por ruta de una zona o de un nombre.

Los límites de peticiones fijan cuántas peticiones acepta una ruta por clave (por defecto, por IP del cliente) en un periodo. Una zona tiene una lista de reglas; un nombre puede tener la suya propia, que **sustituye** a la de la zona para ese nombre. Cada cambio reescribe la lista como una versión nueva de la zona y admite `--reason`, `--dry-run`, `--yes` y `--wait`.

Todas las órdenes admiten `--host <nombre>` para trabajar con la lista propia de un nombre en vez de con la de la zona.

## ratelimit list

```text
ratelimit list <zona> [--host <nombre>] [--json]
```

Las reglas de la zona o, con `--host`, la lista propia del nombre. Si el nombre no tiene, enseña las reglas de la zona que le aplican. Columnas: id, nombre, nombres, ruta, métodos, clave, límite, acción, mitigación, divisor y si está activa.

## ratelimit add

```text
ratelimit add <zona> clave=valor … [--host <nombre>] --reason "…"
```

Añade una regla al final de la lista. Con `--host` y un nombre que aún no tiene lista, la nueva lista parte de las reglas de la zona que le aplicaban, más esta.

| Clave | Significado |
|---|---|
| `id` | Identificador de la regla en la lista. Sin él, se deriva de `name`. |
| `name` | Un nombre legible. |
| `enabled` | `true` o `false`. |
| `hosts` | Nombres de la zona, separados por comas, a los que se limita la regla (solo en la lista de la zona). |
| `path_prefix` o `path_exact` | Las rutas a las que se aplica. |
| `methods` | Métodos HTTP separados por comas, como `POST,PUT`. Por defecto, todos. |
| `header_present`, `query_present` | Contar solo las peticiones que llevan esta cabecera o este parámetro. |
| `key` | Qué se cuenta por separado: `ip` (por defecto), `header`, `cookie` o `body_field`. |
| `key_name` | El nombre de la cabecera, la cookie o el campo cuando `key` no es `ip`. |
| `requests`, `period` | El límite: peticiones por periodo. `period` en segundos o como duración (`300`, `5m`). |
| `algorithm` | `sliding_window` (por defecto) o `gcra`. |
| `action` | `block` (por defecto), `challenge` o `log`. |
| `mitigation_timeout` | Cuánto dura la acción una vez disparada, en segundos o como duración. |
| `per_node_divisor` | `true` (por defecto) para repartir el límite entre los nodos de borde, `false` para aplicarlo en cada nodo. |
| `limit=N/periodo` | Atajo de `requests` y `period`: `limit=60/15m`. |
| `timeout=duración` | Atajo de `mitigation_timeout`: `timeout=15m`. |

Cualquier clave admite también JSON literal con `:=`, como `methods:='["POST"]'`.

```sh
openwaf-cloud ctl ratelimit add example.com id=login path_prefix=/auth/login methods=POST \
  limit=60/15m algorithm=gcra timeout=15m per_node_divisor=false --reason "Limitar los intentos de acceso"
```

## ratelimit set

```text
ratelimit set <zona> <id> clave=valor … [--host <nombre>] --reason "…"
```

Cambia los campos que indicas de la regla `<id>`, con las mismas claves. Con `--host`, el nombre ya debe tener su propia lista.

## ratelimit rm

```text
ratelimit rm <zona> <id> [--host <nombre>] --reason "…"
```

Quita la regla `<id>` de la lista de la zona o, con `--host`, de la lista propia del nombre.