Varnish Cache¶

Varnish service status and per-site cache controls.

All endpoints below are mounted under /api. Authentication: Authorization: Bearer <token> unless noted as public.

Endpoint count: 6

Endpoints¶

Method	Path	Handler	Guards
`GET`	`/api/varnish/config`	`getVarnishConfig`	RequirePermission(db, "administrative_operations")
`POST`	`/api/varnish/config`	`setVarnishGlobalConfig`	RequirePermission(db, "administrative_operations")
`POST`	`/api/varnish/purge-all`	`varnishPurgeAll`	RequirePermission(db, "administrative_operations")
`POST`	`/api/varnish/restart`	`varnishRestart`	RequirePermission(db, "administrative_operations")
`GET`	`/api/varnish/status`	`getVarnishStatus`	RequirePermission(db, "administrative_operations")
`POST`	`/api/varnish/website/purge`	`purgeVarnishByUsername`	RequirePermission(db, "websites_management")

Source¶

Handlers for this section live in api/routes/handlers_*.go in the StarkOne source. Each handler binds its request body with gin.ShouldBindJSON(&req) and responds with the standard envelope:

{ "data": { ... } }

On error:

{ "error": { "code": "string", "message": "string" } }

Reference¶

`GET /api/varnish/config`¶

Returns the current Varnish configuration (memory allocation and ports), reading from the systemd override or distro defaults with built-in fallbacks.

Guards: RequirePermission(db, "administrative_operations")

Response - 200 OK

The returned data object always includes memory, listen_port, admin_port, and backend_port. The defaults are returned when no config file is found; memory and listen_port are overridden if parsed from /etc/systemd/system/varnish.service.d/override.conf, /etc/default/varnish, or /etc/varnish/varnish.params (whichever exists first). admin_port and backend_port are always the static defaults shown below.

{
  "data": {
    "memory": "512m",
    "listen_port": "6081",
    "admin_port": "6082",
    "backend_port": "8080"
  }
}

Side effects (read-only)

Reads config files from disk only; no writes.

Example

curl https://panel.example.com:2087/api/varnish/config \
  -H "Authorization: Bearer $TOKEN"

`POST /api/varnish/config`¶

Sets the global Varnish malloc memory size by writing a systemd override unit and reloading the systemd daemon (a restart is still required to apply).

Guards: RequirePermission(db, "administrative_operations")

Request body

{ "memory": "string (required, e.g. 256m or 1g)" }

Field	Type	Required	Description
`memory`	string	yes	Malloc storage size. Must match `^\d+[mMgG]$` (e.g. `256m`, `1g`).

Response - 200 OK

This handler returns a flat (non-enveloped) body, not the { "data": ... } envelope.

{ "success": true, "message": "Restart Varnish to apply changes" }

Errors

Status	Code	Meaning
`400`	`bad_request`	Body failed to bind, or `memory` does not match the required format.
`500`	`write_error`	Failed to write the systemd override file.

Side effects

Creates directory /etc/systemd/system/varnish.service.d (mode 0755).
Writes /etc/systemd/system/varnish.service.d/override.conf (mode 0644) overriding ExecStart with the new -s malloc,<memory> value.
Runs systemctl daemon-reload. Does not restart Varnish.

Example

curl -X POST https://panel.example.com:2087/api/varnish/config \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"memory": "1g"}'

`POST /api/varnish/purge-all`¶

Purges the entire Varnish cache by banning all request URLs, then restarts Varnish to free memory and reset counters.

Guards: RequirePermission(db, "administrative_operations")

Response - 200 OK

Flat (non-enveloped) body.

{ "success": true, "message": "All cache purged and Varnish restarted" }

Errors

Status	Code	Meaning
`500`	`purge_error`	The `varnishadm ban` command failed; message contains its combined output.

Side effects

Runs varnishadm ban "req.url ~ ." to ban all cached objects.
Runs systemctl restart varnish (errors from the restart are ignored).

Example

curl -X POST https://panel.example.com:2087/api/varnish/purge-all \
  -H "Authorization: Bearer $TOKEN"

`POST /api/varnish/restart`¶

Restarts the Varnish systemd service.

Guards: RequirePermission(db, "administrative_operations")

Response - 200 OK

Flat (non-enveloped) body.

{ "success": true, "message": "Varnish restarted" }

Errors

Status	Code	Meaning
`500`	`restart_error`	`systemctl restart varnish` failed.

Side effects

Runs systemctl restart varnish.

Example

curl -X POST https://panel.example.com:2087/api/varnish/restart \
  -H "Authorization: Bearer $TOKEN"

`GET /api/varnish/status`¶

Returns Varnish runtime status and statistics gathered from systemctl, varnishd -V, and varnishstat.

Guards: RequirePermission(db, "administrative_operations")

Response - 200 OK

All fields are always present; they default to zero/empty values when Varnish is not running or the stat commands fail. hit_rate is a percentage. memory_used/memory_free are human-readable byte strings.

{
  "data": {
    "running": true,
    "version": "7.4.2",
    "uptime": "12h 30m",
    "hit_rate": 92.5,
    "cache_hits": 18500,
    "cache_misses": 1500,
    "requests": 20000,
    "memory_used": "120 MB",
    "memory_free": "8 MB",
    "process_mb": 540,
    "n_objects": 4200,
    "backend_conn": 1500,
    "backend_fail": 0
  }
}

Side effects (read-only)

Runs systemctl is-active --quiet varnish, varnishd -V, varnishstat -1 -j, and systemctl show varnish --property=MemoryCurrent. No writes.

Example

curl https://panel.example.com:2087/api/varnish/status \
  -H "Authorization: Bearer $TOKEN"

`POST /api/varnish/website/purge`¶

Purges the Varnish cache for a single website, banning objects matching the resolved domain's Host header.

Guards: RequirePermission(db, "websites_management")

The website is resolved via username or domain query parameters (the request body, if any, is not read). One of the two must be supplied and must match a row in the webapps table.

Query parameters

Name	Type	Optional	Description
`username`	string	yes*	Panel username owning the website; looked up in `webapps.username`.
`domain`	string	yes*	Website domain; looked up in `webapps.domain`.

* Exactly one of username or domain is required. username takes precedence if both are given.

Response - 200 OK

Flat (non-enveloped) body. The message includes the resolved domain.

{ "success": true, "message": "Cache purged for example.com" }

Errors

Status	Code	Meaning
`400`	`bad_request`	Neither `username` nor `domain` provided, or no matching website row found.
`500`	`purge_failed`	The `varnishadm ban` command failed; message includes the error.

Side effects

Runs varnishadm ban "req.http.host ~ <domain>" for the resolved domain.

Example

curl -X POST "https://panel.example.com:2087/api/varnish/website/purge?domain=example.com" \
  -H "Authorization: Bearer $TOKEN"

Varnish Cache¶

Endpoints¶

Source¶

Reference¶

GET /api/varnish/config¶

POST /api/varnish/config¶

POST /api/varnish/purge-all¶

POST /api/varnish/restart¶

GET /api/varnish/status¶

POST /api/varnish/website/purge¶

`GET /api/varnish/config`¶

`POST /api/varnish/config`¶

`POST /api/varnish/purge-all`¶

`POST /api/varnish/restart`¶

`GET /api/varnish/status`¶

`POST /api/varnish/website/purge`¶