CorefinityCorefinityDocs
Open the Control PanelControl Panel
Web server rules · 3 of 14

corestack_nginx_rules_update

Change nginx rules.

Scope writeRuns as a taskNo secrets returned
On this page

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.

Ask for it

Prompt
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.

Inputs

applystring

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). Defaults to now.

nowwindowtonight
contentobject

The hooks to change: text, or "" / null to clear; a hook left out stays as it is.

Fields
headersstring or null
httpstring or null
phpstring or null
serverstring or null
notestring

Why, shown in the history. Up to 200 characters.

path_appsarray of objects or null

Path apps and gates, the whole list (fields: corestack://tools/corestack_nginx_rules_update); null keeps it, [] clears.

site_idintegerRequired

The environment row. At least 1.

test_idinteger

A passed test from corestack_nginx_rules_validate for this same content. At least 1.

verify_pathsarray of objects

Up to 5 paths every change is verified against after /cf-health; the list replaces the current one.

Fields of each item
expectstring

An exact status (403), a class (2xx) or <500 (the default). Up to 4 characters.

pathstringRequired

An absolute path such as /checkout (never /cf-health). Up to 2,048 characters.

versionintegerRequired

The version from corestack_nginx_rules_get; a newer change makes this stale. At least 0.

Example call

tools/call
{
  "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"
  }
}

If it is refused

ReasonWhat to do
staleThe rules changed since version was read; read them again with corestack_nginx_rules_get.
nginx_invalidThe 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_failedNginx -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_unavailableA hook (or a rule) needs the one-time runtime update, which cannot be turned on for this environment yet.
nginx_rules_lockedCorefinity staff hold this environment's nginx rules.
busyAnother change runs on the environment; retry when it ends.
conflictOne 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_pendingA change is queued for tonight.
batch_windowAdopting now is not possible outside the environment's window; send apply: tonight.
migration_haltedThe night's migration is halted; send apply: tonight.
apm_provenance_unreadableimage_volume_unsupported, legacy_module_unmapped: the runtime update cannot be turned on until Corefinity checks the environment (contact support).
too_largeA hook is over its size limit.
managed_elsewhereAnother 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.
invalid_argumentsThe arguments do not match the tool's input schema, or the Control Panel refused a field. Fix the fields named in the answer and call again.
tenant_mismatchThe object does not exist or the token may not see it. Check the id.
scope_requiredThe token lacks a scope this call needs. Open the link in the answer to add it, then call again.
pin_refusedThe grant is limited to chosen clusters, sites or environments, and this call is outside them. Open the link in the answer to widen it.
rate_limitedToo many calls. Wait for the number of seconds the answer names.
temporarily_unavailableThe Control Panel could not answer just now. Nothing was started; try again shortly.
internal_errorSomething went wrong on our side. Quote the trace id to support.

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/"
  }
}

The same task elsewhere

Was this helpful?
Open in ClaudeOpen in ChatGPT