# ratelimit

> openwaf-cloud ctl ratelimit commands to list, add, change and remove per-path rate limiting rules of a zone or of one name.

Rate limiting rules limit how many requests a path accepts per key (by default, per client IP) in a period. A zone has one list of rules; a name can have its own list, which **replaces** the zone's list for that name. Every change rewrites the list as a new zone version and accepts `--reason`, `--dry-run`, `--yes` and `--wait`.

All commands take `--host <name>` to work on a name's own list instead of the zone's.

## ratelimit list

```text
ratelimit list <zone> [--host <name>] [--json]
```

The zone's rules, or with `--host` the name's own list. If the name has none, it shows the zone rules that apply to it. Columns: id, name, names, path, methods, key, limit, action, mitigation, divisor and whether it is enabled.

## ratelimit add

```text
ratelimit add <zone> key=value … [--host <name>] --reason "…"
```

Adds a rule at the end of the list. With `--host` and a name that has no list yet, the new list starts with the zone rules that applied to that name, plus this one.

| Key | Meaning |
|---|---|
| `id` | Identifier of the rule within the list. Without it, one is derived from `name`. |
| `name` | A readable name. |
| `enabled` | `true` or `false`. |
| `hosts` | Comma-separated names of the zone the rule is limited to (zone list only). |
| `path_prefix` or `path_exact` | The paths it applies to. |
| `methods` | Comma-separated HTTP methods, such as `POST,PUT`. Default: all. |
| `header_present`, `query_present` | Count only requests that carry this header or query parameter. |
| `key` | What is counted separately: `ip` (default), `header`, `cookie` or `body_field`. |
| `key_name` | The header, cookie or field name when `key` is not `ip`. |
| `requests`, `period` | The limit: requests per period. `period` in seconds or as a duration (`300`, `5m`). |
| `algorithm` | `sliding_window` (default) or `gcra`. |
| `action` | `block` (default), `challenge` or `log`. |
| `mitigation_timeout` | How long the action lasts once triggered, in seconds or as a duration. |
| `per_node_divisor` | `true` (default) to split the limit across the edge nodes, `false` to apply it on each node. |
| `limit=N/period` | Shortcut for `requests` and `period`: `limit=60/15m`. |
| `timeout=duration` | Shortcut for `mitigation_timeout`: `timeout=15m`. |

Any key also takes literal JSON with `:=`, such as `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 "Limit login attempts"
```

## ratelimit set

```text
ratelimit set <zone> <id> key=value … [--host <name>] --reason "…"
```

Changes the fields you give of rule `<id>`, with the same keys. With `--host`, the name must already have its own list.

## ratelimit rm

```text
ratelimit rm <zone> <id> [--host <name>] --reason "…"
```

Removes rule `<id>` from the zone's list, or from the name's own list with `--host`.