corestack_ nginx_ rules_ update
Change nginx rules.
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,; 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_, then add_ 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
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
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.
nowwindowtonightThe hooks to change: text, or "" / null to clear; a hook left out stays as it is.
Fields
Why, shown in the history. Up to 200 characters.
Path apps and gates, the whole list (fields: corestack://tools/corestack_nginx_rules_update); null keeps it, [] clears.
The environment row. At least 1.
A passed test from corestack_nginx_rules_validate for this same content. At least 1.
Up to 5 paths every change is verified against after /cf-health; the list replaces the current one.
Fields of each item
An exact status (403), a class (2xx) or <500 (the default). Up to 4 characters.
An absolute path such as /checkout (never /cf-health). Up to 2,048 characters.
The version from corestack_nginx_rules_get; a newer change makes this stale. At least 0.
Example 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
| Reason | What to do |
|---|---|
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 | 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. |
invalid_arguments | The 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_mismatch | The object does not exist or the token may not see it. Check the id. |
scope_required | The token lacks a scope this call needs. Open the link in the answer to add it, then call again. |
pin_refused | The 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_limited | Too many calls. Wait for the number of seconds the answer names. |
temporarily_unavailable | The Control Panel could not answer just now. Nothing was started; try again shortly. |
internal_error | Something 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, ascorestack_nginx_rules_getanswers 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-appruns only its listed PHP files;staticserves only the listed file types;denyanswers 404 under the prefix;proxyforwards the prefix to another website (path_apps.proxy_availablesays whether this environment's runtime takes it);gatelimits 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):htdocsorshared, 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;*.phpalone is refused;wp-config.phpnever 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'sindex.php, or/for the whole app.index.php?rest_route=lets the app'sindex.phpanswer WordPress REST queries (?rest_route=/...as the first parameter) from outside and nothing else; it cannot sit beside/or anindex.phpentry (path_app_field_invalidonphp.router.<i>orphp.entries.<i>), and no other?value is a route.php.dir_index(php-app): up to 8 folders (wp-admin/) whoseindex.phpanswers the folder itself.static.types(php-app, static): lower-case file extensions served from disk;php phtml phar inc htaccess htpasswd env sqlnever are. Default: the common web types.links(php-app, static; a folder prefix only): up to 4{"path": "wp-content/, a folder of the app (endinguploads/ ", "target": "shared/ wp-content/ uploads"} /) that is a link into this site's ownshared/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 beshareditself, a hidden folder or a folder holding the platform's code, logs or secrets (path_app_link_outsideonlinks.<i>.target); on a WordPress siteshared/wp-content/uploadsand the folders below it may be linked, while the rest ofshared/wp-content(plugins, themes and the others) stays refused. At save the link is checked in the environment (path_app_link_mismatch, orpath_app_link_unverifiedwhen it cannot be checked just now: try again).methods(php-app, static, proxy, gate): some ofGET HEAD POST PUT PATCH DELETE OPTIONS(defaultGET 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_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 (orsecond": 1-1000, "burst": 0-1000} null) for no limit; the Control Panel starts a new path app atpath_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/xgoes to<url>/blog/x) orstrip(/blog/xgoes 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 withvisitor).connect_timeout1-30 seconds (default 5),read_timeout5-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 inX-Forwarded-ForandX-Real-IPand never the identity headers an edge in front may add (Cf-Access-Jwt-Assertion,Forwarded,CF-Connecting-IP,True-Client-IP); itsX-Accel-*answers are ignored. It also getsX-Cf-Path-Hop(1or2): 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.diagnosticsnames each withhookpath_apps, therecordid, thefield(for examplephp.entries.1) and itscode(path_app_any_php,path_app_code_dir,path_app_overlapand 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 ofnginx_invalid): the proxy'surlis 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 itshost_headeris 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 lintpath_app_proxy_unresolved(a warning, the save goes ahead) says the name does not resolve yet; visitors get 502 until it does.
Example
{
"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/"
}
}