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

**Explain which nginx rule handles a URL.** Show which nginx rule would handle a path on an environment row: the server-level steps, the locations nginx considers (the platform's, Redirects and the custom rules) with file and line, the one that wins, try_files branches and the outcome (a file, PHP, a redirect, refused, blocked by the platform or another answer), with notes for maintenance mode and HTTP auth. A static simulation of the saved rules, or of unsaved server rules passed as content: nothing is requested from the site. Scope: read.

- Scope: `read`
- Runs as a task: no

## When to use it

Show which nginx rule would handle a path on an environment row: the server-level steps, the locations nginx considers (the platform's, Redirects and the custom rules) with file and line, the one that wins, try_files branches and the outcome (a file, PHP, a redirect, refused, blocked by the platform or another answer), with notes for maintenance mode and HTTP auth. A static simulation of the saved rules, or of unsaved server rules passed as content: nothing is requested from the site.

The answer: `server_steps` (the platform guard that blocks the path, then the custom server-level `set`, `return`, `deny` lines and maintenance mode's 503, in the order nginx runs them), `locations` (each with `source` — `platform`, `redirects` or `custom` —, `file`, `line`, `match` — `exact`, `prefix`, `^~` or `regex` —, `pattern` and `nested`), `winner` (an index into `locations`, or null when a server-level step answers), `try_files_branches` (both branches, because whether a file exists is not known), `outcome` (`kind`: `static`, `php`, `redirect`, `denied`, `returned` or `blocked`, with `detail`) and `notes`. Lines in `custom-server.inc` count the file's two banner lines; the sentences in `detail` and `notes` name the line as the editor shows it. A matching regex beats a plain prefix, so a prefix location can be listed as matched without winning.

The platform's own guards run first, before the custom rules and maintenance mode: hidden files and folders (a name starting with a dot, except `/.well-known/`; Magento 2 allows its media `.thumbs` images), backup copies of PHP files (`.php~`, `.php.bak`, `.php.orig`, `.php.save`, `.php.swp`, `.php.old`), names ending in `~`, PHP source files no PHP location runs (`.phtml`, `.pht`, `.phps`, `.php0` to `.php9`) and `.php` in any case but lower case. A custom PHP site also blocks the files a deployment keeps beside its code (`.env`, `.log`, `.sql`, `.sql.gz`, `.bak`, `.orig`, `.save`, `.swp`, `.ini`, `.lock`, `.yml`, `.yaml`, `.inc`, `.phar`, `.dist`), Composer's `composer.json` and `auth.json`, the `vendor/` folder at the top of the site and every `node_modules` folder. A guarded path answers `outcome.kind` `blocked` with `outcome.guard` (`hidden`, `backup`, `tilde`, `php_source` or `php_case`; on custom PHP also `deploy_files`, `composer`, `vendor` or `node_modules`), a 404 no custom rule can change, and its server step (`effect`: `guard`) names the platform file and line. Every runtime version has these guards; an environment still on the Laravel, Magento 2 or WordPress package rules has none, and a note says so when the Control Panel cannot tell.

Corefinity's backup-file rule runs next, still before the custom rules: while it is on for the environment (`backup_guard` in corestack_nginx_rules_get; corestack_nginx_backup_guard_set switches it), a path ending in `.sql` or `.sql.gz` answers `outcome.kind` `blocked` with `outcome.guard` `backup_files`, and its server step (`effect`: `guard`) names `flags.inc`. Where the rule is on, a path ending in `.zip`, `.tar.gz` or `.tgz` is served as usual and a note says Corefinity does not block it.

## Inputs

- `site_id` (integer, ≥ 1, required): The environment row whose nginx is simulated.
- `path` (string, required): The request path, starting with / (a query string may follow ?), for example /wp-content/uploads/report.pdf.
- `host` (string): One of the row's hosts. Default: its first.
- `content` (object: `server`, `headers`, `php`, `http`, each text or null): Unsaved rules, as corestack_nginx_rules_validate takes them: only the server hook decides which location answers. Without content.server the saved server rules are explained.

### Input schema

```json
{
  "additionalProperties": false,
  "properties": {
    "content": {
      "additionalProperties": false,
      "description": "Unsaved rules, as corestack_nginx_rules_validate takes them: only the server hook decides which location answers. Without content.server the saved server rules are explained.",
      "properties": {
        "headers": {
          "type": [
            "string",
            "null"
          ]
        },
        "http": {
          "type": [
            "string",
            "null"
          ]
        },
        "php": {
          "type": [
            "string",
            "null"
          ]
        },
        "server": {
          "type": [
            "string",
            "null"
          ]
        }
      },
      "type": "object"
    },
    "host": {
      "description": "One of the row's hosts. Default: its first.",
      "maxLength": 253,
      "type": "string"
    },
    "path": {
      "description": "The request path, starting with / (a query string may follow ?), for example /wp-content/uploads/report.pdf.",
      "maxLength": 2048,
      "minLength": 1,
      "type": "string"
    },
    "path_apps": {
      "description": "Unsaved path apps and gates (the whole list) instead of the saved ones.",
      "items": {
        "type": "object"
      },
      "type": [
        "array",
        "null"
      ]
    },
    "site_id": {
      "description": "The environment row whose nginx is simulated.",
      "minimum": 1,
      "type": "integer"
    }
  },
  "required": [
    "site_id",
    "path"
  ],
  "type": "object"
}
```

## Refusals

- `nginx_invalid`: the server rules in `content` (or saved) do not parse; `details.diagnostics` lists the errors with their file lines.
- `too_large`: the server rules are over the hook size limit.
- 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_explain",
  "arguments": {
    "site_id": 4211,
    "path": "/wp-content/uploads/catalogues/2019/spring.pdf"
  }
}
```

A hidden file on a runtime environment is blocked before any rule runs:

```json
{
  "name": "corestack_nginx_rules_explain",
  "arguments": {
    "site_id": 4211,
    "path": "/e2e-probe/.hidden"
  }
}
```

answers `"outcome": {"kind": "blocked", "detail": "404 — the platform blocks hidden files and folders (a name starting with a dot; /.well-known/ is allowed)", "guard": "hidden"}`.

## Path apps

Path apps and gates take part in the explanation: the saved ones, or an unsaved list passed as `path_apps` (the whole list, as corestack_nginx_rules_update takes it). A path app's location is listed with `source` `path_app`, the file `path-apps.inc` and its `record` id, and wins over the platform's regex locations under its prefix; a gate, and a path app's own address, host and method limits, are server-level steps that name their `record` and run after maintenance mode. An unlisted PHP file under a php-app's prefix is explained as refused (404). A path under a proxy's prefix is explained as forwarded to its `proxy.url`, answered by that site and never cached here. A list that is not valid is `nginx_invalid` with its diagnostics.

### Inputs while path apps are on

- `path_apps` (list of path app and gate records, as corestack_nginx_rules_update takes them): Unsaved path apps and gates (the whole list, as corestack_nginx_rules_update takes it), explained instead of the saved ones.

### Example

```json
{
  "name": "corestack_nginx_rules_explain",
  "arguments": {
    "site_id": 4211,
    "path": "/wp/xmlrpc.php"
  }
}
```

## Prompt

```text
Using the Corefinity MCP server, call corestack_nginx_rules_explain with site_id 4211, path /wp-content/uploads/catalogues/2019/spring.pdf. (Explain which nginx rule handles a URL.) Tell me what it returned.
```

## The same task elsewhere

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