---
title: "corestack_nginx_rules_update"
url: https://docs.corefinity.com/mcp/tools/corestack_nginx_rules_update
type: tool
last_updated: 2026-11-13
feature: nginx-rules
related:
  - https://docs.corefinity.com/api/reference/site-settings/replace-site-nginx-rules.md
  - https://docs.corefinity.com/guides/sites/site-settings/web-server-rules.md
---
# corestack_nginx_rules_update

**Change nginx rules.** Save custom nginx rules for an environment row, with the version corestack_nginx_rules_get answered. The change is tested with the environment's nginx, committed, reloaded and verified (/cf-health and the verify paths); a change the platform rejects or that fails its checks is rolled back automatically. Hooks left out of content stay as they are; an empty hook clears it. Rules that need the one-time runtime update (headers, php, http) adopt it on save once instant changes are available. Scope: write. Long-running: answers with a task.

- Scope: `write`
- Runs as a task: yes

## When to use it

Save custom nginx rules for an environment row, with the version corestack_nginx_rules_get answered. The change is tested with the environment's nginx, committed, reloaded and verified (/cf-health and the verify paths); a change the platform rejects or that fails its checks is rolled back automatically. Hooks left out of content stay as they are; an empty hook clears it. Rules that need the one-time runtime update (headers, php, http) adopt it on save once instant changes are available.

A platform rate-limit preset (`limit_req zone=cf_rl_*`) is saved only on an environment whose runtime supports the presets (corestack_nginx_policy_get with site_id lists them): anywhere else the save is refused `nginx_invalid` (code `limit_zone_unknown`), before anything is committed.

A started change answers a task on its `nginx_rules_change` operation: Tested → Saved → Sent to the site → Nginx reloaded → Checked → Verified. A rejection or a failed verify ends with the previous rules restored and the task completed with `work_failed`; a change saved while the environment is not running completes with `pending_verify` and is checked when it next runs. Saved for tonight (adopting on save with `apply: tonight`) answers `{operation: null, queued: true, window_date, item_id}`; content the environment already has answers `{operation: null, revision: null}`; `verify_paths` are saved first (the change is verified against them) and move the version when they change; without `content` only the paths are saved and the answer is `{version, verify_paths}`. Check rules first with corestack_nginx_rules_validate and pass its `test_id` to reuse a passed test. 20 saves a minute per environment.

A header may carry a variable an `http` map sets only when every value of that map is plain text: for CORS with several origins, map each origin to itself (`map $http_origin $cors_origin { default ""; "https://a.example" "https://a.example"; }`, then `add_header Access-Control-Allow-Origin $cors_origin always;` with `Vary "Origin"`). A map handing back `$http_origin` or another request variable is refused `nginx_invalid` (code `header_value_decoded`), as the Control Panel's Headers card refuses it.

An `http` upstream whose name starts with `cf_`, in any case, is refused `nginx_invalid` (code `upstream_name_reserved`, at the upstream's line): those names belong to the platform's own upstreams. Give yours another name, for example `upstream app_backend { … }`, and use that name in `proxy_pass`.

## Inputs

- `site_id` (integer, ≥ 1, required): The environment row.
- `version` (integer, ≥ 0, required): The version from corestack_nginx_rules_get; a newer change makes this stale.
- `content` (object: `server`, `headers`, `php`, `http`, each text or null): The hooks to change: text, or "" / null to clear; a hook left out stays as it is.
- `note` (string, at most 200 characters): Why, shown in the history.
- `verify_paths` (list of at most 5 `{path, expect}`): Up to 5 paths every change is verified against after /cf-health; the list replaces the current one.
- `test_id` (integer, ≥ 1): A passed test from corestack_nginx_rules_validate for this same content.
- `apply` (string, `now` or `tonight`): Only when the save adopts the runtime update on save: now or tonight. Default now.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "apply": {
      "default": "now",
      "description": "Only when the save adopts the runtime update on save: now or tonight. Default now. window: the row's next maintenance window (tonight is kept as its alias).",
      "enum": [
        "now",
        "window",
        "tonight"
      ],
      "type": "string"
    },
    "content": {
      "additionalProperties": false,
      "description": "The hooks to change: text, or \"\" / null to clear; a hook left out stays as it is.",
      "properties": {
        "headers": {
          "type": [
            "string",
            "null"
          ]
        },
        "http": {
          "type": [
            "string",
            "null"
          ]
        },
        "php": {
          "type": [
            "string",
            "null"
          ]
        },
        "server": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "note": {
      "description": "Why, shown in the history.",
      "maxLength": 200,
      "type": "string"
    },
    "path_apps": {
      "description": "Path apps and gates, the whole list (fields: corestack://tools/corestack_nginx_rules_update); null keeps it, [] clears.",
      "items": {
        "type": "object"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "site_id": {
      "description": "The environment row.",
      "minimum": 1,
      "type": "integer"
    },
    "test_id": {
      "description": "A passed test from corestack_nginx_rules_validate for this same content.",
      "minimum": 1,
      "type": "integer"
    },
    "verify_paths": {
      "description": "Up to 5 paths every change is verified against after /cf-health; the list replaces the current one.",
      "items": {
        "additionalProperties": false,
        "properties": {
          "expect": {
            "description": "An exact status (403), a class (2xx) or <500 (the default).",
            "maxLength": 4,
            "type": "string"
          },
          "path": {
            "description": "An absolute path such as /checkout (never /cf-health).",
            "maxLength": 2048,
            "type": "string"
          }
        },
        "required": [
          "path"
        ],
        "type": "object"
      },
      "maxItems": 5,
      "type": "array"
    },
    "version": {
      "description": "The version from corestack_nginx_rules_get; a newer change makes this stale.",
      "minimum": 0,
      "type": "integer"
    }
  },
  "required": [
    "site_id",
    "version"
  ],
  "type": "object"
}
```

## Refusals

- `stale`: the rules changed since `version` was read; read them again with corestack_nginx_rules_get.
- `nginx_invalid`: the policy refused the rules; `details.diagnostics` lists each error with hook, file line and column. A site whose runtime revision the policy has no model for refuses every hook with `runtime_model_missing`, which names the revision: the Control Panel cannot check the file against rules it does not run, and support moves the site to a supported revision. When the rules need the environment's runtime update and the platform has no model for the revision it would move to, every hook answers `runtime_model_missing` naming that revision 'after this change': support moves the site to a supported revision.
- `nginx_test_failed`: nginx -t failed on the environment's nginx; `details.diagnostics`, which point into your rules (a warning about the platform's own configuration is left out; an error is always there). A map key too long for nginx (usually a long domain) is said so: write that key as a regular expression, for example `~*^shop\.example\.com$`.
- `hook_unavailable`: a hook (or a rule) needs the one-time runtime update, which cannot be turned on for this environment yet.
- `nginx_rules_locked`: Corefinity staff hold this environment's nginx rules.
- `busy`: another change runs on the environment; retry when it ends.
- `conflict`: one of this environment's nginx files changed while the save was being written; read the rules again with corestack_nginx_rules_get and save again. Another environment's change landing at the same moment is not a conflict: the save is written again for you.
- `change_pending`: a change is queued for tonight.
- `batch_window`: adopting now is not possible outside the environment's window; send `apply: tonight`.
- `migration_halted`: the night's migration is halted; send `apply: tonight`.
- `apm_provenance_unreadable`, `image_volume_unsupported`, `legacy_module_unmapped`: the runtime update cannot be turned on until Corefinity checks the environment (contact support).
- `too_large`: a hook is over its size limit.
- `managed_elsewhere` (message: "This site is managed by another control panel"): another control panel manages this site, so use that control panel for it. This is refused before anything else about the site, as in the Control Panel and the API. Nothing was done.
- The refusals every tool can answer: `invalid_arguments`, `tenant_mismatch`, `scope_required`, `pin_refused`, `rate_limited`, `temporarily_unavailable`, `internal_error` (corestack://guides/how-this-server-works).

## Example

```json
{
  "name": "corestack_nginx_rules_update",
  "arguments": {
    "site_id": 4211,
    "version": 7,
    "content": {
      "server": "location /wp-content/uploads/private/ {\n    deny all;\n}\n"
    },
    "note": "Keep private uploads private"
  }
}
```

## Path apps

Send `path_apps` to change the environment's path apps and gates: always the whole list (read it from corestack_nginx_rules_get's `path_apps.items`, change it, send it back). Left out, the list stays as it is; `[]` removes every path app and gate. The list saves with the hooks under the same `version`, as one change with one revision: `content` may be left out when only the path apps change. Keep each record's `id` on an edit; a new record without one gets the next free id (`a…` for php-app, static and deny, `g…` for a gate).

The rules each record is held to: a prefix is a folder (`/wp/`) or, for php-app only, one file (`/verify.php`); a root is `htdocs` or `shared` with optional sub-folders and never a platform code folder or the web root; PHP entries end `.php`, `*` matches inside one folder name only and `*.php` alone is refused; methods are some of GET HEAD POST PUT PATCH DELETE OPTIONS; addresses go through the firewall's checks; hosts are the environment's own (`path_apps.hosts`); path apps never overlap each other or the platform's own paths; a gate on `/` may not cover the production host; up to 16 path apps and 16 gates. Check a list first with corestack_nginx_rules_validate.

### Inputs while path apps are on

- `path_apps` (list of path app and gate records: `id`, `type`, `prefix`, `root`, `php` {`entries`, `router`, `dir_index`}, `static` {`types`}, `methods`, `ips`, `hosts`, `limits` {`body_size_mb`, `timeout`}, `preset`, `label`): The environment's whole list of path apps and gates, as corestack_nginx_rules_get answers it (path_apps.items); left out it stays as it is, [] removes them all.

### The record

Each record takes only the fields its type takes; leave the others out.

- `id`: `a1`, `a2`… for php-app, static, proxy and deny; `g1`, `g2`… for a gate. Keep it on an edit; leave it out on a new record and the next free one is given.
- `type`: `php-app` runs only its listed PHP files; `static` serves only the listed file types; `deny` answers 404 under the prefix; `proxy` forwards the prefix to another website (`path_apps.proxy_available` says whether this environment's runtime takes it); `gate` limits a prefix of the platform's own handling to an address list, hosts and methods.
- `prefix`: a folder such as `/wp/` (letters, digits, `.` `_` `~` `-`, up to 8 segments) or, for php-app only, one file such as `/verify.php`. A folder also covers its prefix without the slash. A proxy takes a folder only. A gate may be `/` when it names hosts, or one file such as `/wp-login.php`.
- `root` (php-app, static): `htdocs` or `shared`, optionally with sub-folders (`htdocs/blog`); files are served from `<root><prefix>`, never from a platform code folder or the web root itself. The folder must be a real folder, not a link.
- `php.entries` (php-app): 1 to 32 PHP files that may run, relative to the prefix (`wp-login.php`, `wp-admin/*.php`); `*` matches inside one folder name only; `*.php` alone is refused; `wp-config.php` never runs. Every other PHP file under the prefix answers 404.
- `php.router` (php-app): up to 4 folders (`wp-json/`) routed internally to the app's `index.php`, or `/` for the whole app. `index.php?rest_route=` lets the app's `index.php` answer WordPress REST queries (`?rest_route=/...` as the first parameter) from outside and nothing else; it cannot sit beside `/` or an `index.php` entry (`path_app_field_invalid` on `php.router.<i>` or `php.entries.<i>`), and no other `?` value is a route.
- `php.dir_index` (php-app): up to 8 folders (`wp-admin/`) whose `index.php` answers the folder itself.
- `static.types` (php-app, static): lower-case file extensions served from disk; `php phtml phar inc htaccess htpasswd env sql` never are. Default: the common web types.
- `links` (php-app, static; a folder prefix only): up to 4 `{"path": "wp-content/uploads/", "target": "shared/wp-content/uploads"}`, a folder of the app (ending `/`) that is a link into this site's own `shared/` folder, and the folder it points to. Only the record's static types are served from it, never PHP or hidden files. The target may not be `shared` itself, a hidden folder or a folder holding the platform's code, logs or secrets (`path_app_link_outside` on `links.<i>.target`); on a WordPress site `shared/wp-content/uploads` and the folders below it may be linked, while the rest of `shared/wp-content` (plugins, themes and the others) stays refused. At save the link is checked in the environment (`path_app_link_mismatch`, or `path_app_link_unverified` when it cannot be checked just now: try again).
- `methods` (php-app, static, proxy, gate): some of `GET HEAD POST PUT PATCH DELETE OPTIONS` (default `GET HEAD POST`); any other method answers 405.
- `ips` (php-app, static, proxy, gate): up to 64 IPv4 or IPv6 addresses or networks admitted; any other address answers 403, except addresses on the environment's firewall web list and the Corefinity office, which always pass. A gate needs at least one.
- `hosts` (php-app, static, proxy, gate): up to 16 of the environment's own hosts (`path_apps.hosts`); empty means all of them.
- `limits.body_size_mb` (php-app): the largest request body in MB, at most the environment's upload size; null inherits it. `limits.timeout`: PHP time limit, 30 to 300 seconds (default 300).
- `rate` (php-app, static, proxy): `{"per_second": 1-1000, "burst": 0-1000}` requests per visitor address; beyond the burst a visitor gets 429 until they slow down. A php-app counts only requests that run PHP; static and proxy count every request. Firewall-listed addresses and the Corefinity office are never limited. Leave it out (or `null`) for no limit; the Control Panel starts a new path app at `path_apps.rate_default` (20 a second, bursts of 100).
- `proxy` (proxy): `url` (required) the site that answers, `https://<host name>[:port][/folder/]` — https only, a host name and never an address, never a cluster-internal, local or metadata name, never this environment's own host, never port 8098 (reserved); at save the name must not answer an internal address. `path`: `keep` (default; `/blog/x` goes to `<url>/blog/x`) or `strip` (`/blog/x` goes to `<url>/x`). `host_header`: `target` (default, the url's host), `visitor` (the visitor's host) or a host name (never a cluster-internal, local or metadata name, and never this environment's own host: send that with `visitor`). `connect_timeout` 1-30 seconds (default 5), `read_timeout` 5-300 (default 60). `share_cookies` (default false): false keeps the visitor's cookies and passwords from the target and stops it setting cookies here; true sends them both ways (only for a target you run). Answers come from the target and are never cached here. The target gets the visitor's address in `X-Forwarded-For` and `X-Real-IP` and never the identity headers an edge in front may add (`Cf-Access-Jwt-Assertion`, `Forwarded`, `CF-Connecting-IP`, `True-Client-IP`); its `X-Accel-*` answers are ignored. It also gets `X-Cf-Path-Hop` (`1` or `2`): a request that has already passed two platform proxies, or arrives with any other value, answers 508 without contacting the target (before a password prompt; blocked methods, closed paths, address lists and gates answer first).
- `preset`: the preset it started from (corestack_nginx_snippets_list), for information only. `label`: up to 80 characters, shown in the Control Panel only.

### Refusals

- `nginx_invalid`: a record breaks a rule; `details.diagnostics` names each with `hook` `path_apps`, the `record` id, the `field` (for example `php.entries.1`) and its `code` (`path_app_any_php`, `path_app_code_dir`, `path_app_overlap` and the rest), as the Control Panel's editor shows it.
- `path_apps_unavailable`: this environment's runtime cannot serve path apps yet, so the list cannot change.
- `path_app_proxy_target` (a diagnostic of `nginx_invalid`): the proxy's `url` is not a public https host name (plain http, an address, a denied name, this environment's own host, port 8098, or a name answering an internal address now), or its `host_header` is a denied name or this environment's own host. `path_app_proxy_unavailable`: this environment's runtime cannot serve a proxy yet. `path_app_limit`: a rate or a timeout outside its range. The lint `path_app_proxy_unresolved` (a warning, the save goes ahead) says the name does not resolve yet; visitors get 502 until it does.

### Example

```json
{
  "name": "corestack_nginx_rules_update",
  "arguments": {
    "site_id": 4211,
    "version": 7,
    "path_apps": [
      {
        "type": "php-app",
        "prefix": "/wp/",
        "root": "htdocs",
        "php": {"entries": ["wp-admin/*.php", "wp-login.php"], "router": ["wp-json/"], "dir_index": ["wp-admin/"]},
        "rate": {"per_second": 20, "burst": 100},
        "preset": "wordpress-admin",
        "label": "Blog admin"
      },
      {
        "type": "proxy",
        "prefix": "/blog/",
        "proxy": {"url": "https://blog.example.net", "path": "keep"},
        "rate": {"per_second": 20, "burst": 100},
        "preset": "proxy-site",
        "label": "Blog hosted elsewhere"
      }
    ],
    "note": "WordPress admin under /wp/, the blog under /blog/"
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_nginx_rules_update with site_id 4211, version 7, content {"server":"location /wp-content/uploads/private/ {\n    deny all;\n}\n"}, note Keep private uploads private. (Change nginx rules.) Tell me what it returned.
```

## The same task elsewhere

- Endpoint: [PUT /api/corestack/sites/{site}/nginx-rules](https://docs.corefinity.com/api/reference/site-settings/replace-site-nginx-rules.md)
- Guide: [Web server rules](https://docs.corefinity.com/guides/sites/site-settings/web-server-rules.md)
