Config Reference

A BareProxy config is one file. A line in the first column opens a block (global, site or pool), and the indented lines under it belong to it. Blocks don’t nest, and the whole grammar fits on one page.

This is a complete config for a site with an API, a web front end and a www redirect:

# /etc/bareproxy/bareproxy.conf
global
  acme-email [email protected]

site example.com
  route /healthz -> respond 200 "ok"
  route /api/* -> api strip
  route /* -> web

site www.example.com
  route /* -> redirect 301 https://example.com

pool api
  backend 10.0.0.11:8080
  backend 10.0.0.12:8080
  backend 10.0.0.13:8080
  health /healthz

pool web
  backend 10.0.0.21:3000
  backend 10.0.0.22:3000

What It Does

site example.com serves HTTPS on port 443 with a certificate from Let’s Encrypt, and redirects plain http:// requests to https://.
/healthz is answered by BareProxy itself, so a monitor can check the proxy without touching the application.
Everything under /api/ goes to pool api with the prefix stripped: /api/orders reaches the backend as /orders.
www.example.com redirects to a bare origin, so the path and query are kept.
Pool api checks each backend with GET /healthz every 5 seconds. Pool web has no checks, so failed connections on live traffic take its backends out.

Rules

route [METHODS] PATH [header NAME[=VALUE]]... -> ACTION

/* matches every path. /api/* matches /api, /api/ and everything below it, never /apiv2. A path without /* matches only itself.
Methods are optional: route GET,HEAD /assets/* -> web.
header X-Beta needs the header present; header X-Beta=1 needs that value.
The action is a pool name (add strip to drop the prefix), redirect CODE URL, or respond STATUS [TEXT].

Commands

Command	What it does
`bareproxy check`	Checks the config file. Needs no running server.
`bareproxy plan`	Shows what the file would change, compared with the running config.
`bareproxy apply`	Checks again, shows the plan, asks, and swaps the config in at once.
`bareproxy rollback`	Goes back to the previous version.
`bareproxy explain`	Shows how a request would be handled, without sending it.
`bareproxy why`	Tells the story of a request that already happened.
`bareproxy tail`	Follows request records as they happen.
`bareproxy status`	Listeners, sites, backends, certificates and recent error rates.

The config file is the source of truth. After every apply or rollback it holds exactly the running config, so a restart never changes behavior. If the file is broken at startup, BareProxy runs the last good version and says so.