vacuum-wall/docs/config.md

# Configuration Reference

This document describes the JSON configuration files used by Vacuum Wall to manage each subsystem. All persistent configuration is stored in the `config/` directory as declarative JSON. Runtime artifacts and generated files live in `data/`. The application renders these declarations into the format expected by each underlying service.

## DHCP/DNS Configuration

**File**: `config/dnsmasq/config.json`

This file defines all DHCP server settings and DNS resolution behavior for the dnsmasq service. The application renders it into `/etc/dnsmasq.d/vacuum-wall.conf`.

```json
{
  "dhcp": {
    "ranges": [
      {
        "interface": "eth1",
        "start": "192.168.2.100",
        "end": "192.168.2.200",
        "lease_time": "12h",
        "gateway": "192.168.2.1",
        "dns": "192.168.2.1"
      }
    ],
    "static_leases": [
      {
        "mac": "aa:bb:cc:dd:ee:ff",
        "ip": "192.168.2.50",
        "hostname": "printer"
      }
    ]
  },
  "dns": {
    "upstreams": ["8.8.8.8", "1.1.1.1"],
    "domain": "lan",
    "custom_records": [
      {
        "name": "nas.lan",
        "address": "192.168.2.10",
        "hostname": "nas"
      }
    ]
  }
}
```

### DHCP Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `ranges` | array | Yes | One or more DHCP address pools. Each range defines a subnet from which addresses are leased. |
| `ranges[].interface` | string | Yes | Network interface on which to serve this DHCP range (e.g., `eth1`). |
| `ranges[].start` | string | Yes | First IP address in the pool. |
| `ranges[].end` | string | Yes | Last IP address in the pool. |
| `ranges[].lease_time` | string | No | DHCP lease duration. Accepts values like `12h`, `1d`, `30m`. Default: `1h`. |
| `ranges[].gateway` | string | No | Default gateway advertised to DHCP clients. Typically the router's LAN IP. |
| `ranges[].dns` | string | No | DNS server address advertised to DHCP clients. Typically the Vacuum Wall host's LAN IP. |
| `static_leases` | array | No | Fixed IP assignments tied to MAC addresses. Clients with matching MACs always receive the specified IP. |
| `static_leases[].mac` | string | Yes | MAC address of the client (colon-separated lowercase hex). |
| `static_leases[].ip` | string | Yes | The IP address to assign to this MAC. Must be outside the dynamic pool ranges. |
| `static_leases[].hostname` | string | No | Hostname to associate with the lease. Used for reverse DNS and mDNS. |

### DNS Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `upstreams` | array | Yes | Upstream DNS servers to forward unresolved queries to. Supports IPv4 and IPv6 addresses. |
| `domain` | string | Yes | Local domain suffix. Hostnames without a FQDN are resolved within this domain (e.g., `printer` becomes `printer.lan`). |
| `custom_records` | array | No | Static DNS A records for internal services and devices. |
| `custom_records[].name` | string | Yes | Fully qualified domain name (e.g., `nas.lan`). |
| `custom_records[].address` | string | Yes | The IP address to resolve the name to. |
| `custom_records[].hostname` | string | No | Short hostname without the domain suffix. Adds a reverse DNS entry as well. |

Additional dnsmasq directives can be appended verbatim by placing plain-text files in `data/dnsmasq/fragments/`. Each file's contents are concatenated into the generated config. This is useful for advanced options not covered by the JSON schema (e.g., `bogus-priv`, `cache-size`, `log-queries`).

## Nginx Configuration

**File**: `config/nginx/config.json`

This file defines reverse proxy domains, the management interface, and global SSL settings. The application renders it into per-domain server block files in `data/nginx/sites-enabled/` and into the shared SSL snippet at `/etc/nginx/snippets/vacuum-wall-ssl.conf`.

```json
{
  "domains": {
    "app.example.com": {
      "backend": {
        "host": "192.168.2.50",
        "port": 8080,
        "proto": "http"
      },
      "force_ssl": true,
      "headers": {
        "X-Forwarded-Proto": "https",
        "X-Real-IP": "$remote_addr"
      },
      "cert": {
        "type": "acme",
        "email": "admin@example.com"
      }
    }
  },
  "management": {
    "domain": "<hostname>.local",
    "backend": {
      "host": "127.0.0.1",
      "port": 9090,
      "proto": "http"
    },
    "auth": {
      "user": "admin",
      "htpasswd": "$PROJECT_DIR/data/nginx/.htpasswd"
    }
  },
  "ssl": {
    "protocols": "TLSv1.2 TLSv1.3",
    "ciphers": "ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384",
    "prefer_server_ciphers": false
  }
}
```

### Domain Entries

The `domains` object maps domain names (keys) to proxy configurations. Each entry produces a separate nginx `server` block.

| Field | Type | Required | Description |
|---|---|---|---|
| `backend` | object | Yes | The upstream service that receives proxied traffic. |
| `backend.host` | string | Yes | IP address or hostname of the backend service. |
| `backend.port` | integer | Yes | Port the backend service is listening on. |
| `backend.proto` | string | Yes | Protocol for the backend connection: `http` or `https`. |
| `force_ssl` | boolean | No | Enable HTTPS redirect. HTTP requests to this domain receive a 301 redirect to HTTPS. Default: `true`. |
| `headers` | object | No | Custom headers to set on proxied requests. Supports nginx variable interpolation (e.g., `$remote_addr`). |
| `cert` | object | No | Certificate configuration for this domain. Required unless the management domain shares its cert. |
| `cert.type` | string | Yes (if `cert`) | Certificate provisioning method. One of: `acme`, `file`, or `selfsigned`. |
| `cert.email` | string | Yes (if `acme`) | ACME account email used by the CA provider. |
| `cert.path` | string | Yes (if `file`) | Full path to the public certificate file (PEM). |
| `cert.key_path` | string | Yes (if `file`) | Full path to the private key file (PEM). |

### Certificate Types

| Type | Description |
|---|---|
| `acme` | Vacuum Wall uses acme.sh to request and renew an ACME certificate via the HTTP-01 challenge. The nginx configuration is temporarily modified to serve the ACME challenge files at `/.well-known/acme-challenge/`. The `email` field is required. |
| `file` | Use a pre-existing certificate and private key from the local file system. The `path` and `key_path` fields must point to readable PEM files. Vacuum Wall will not attempt to renew these certificates. |
| `selfsigned` | Vacuum Wall generates a self-signed certificate and private key on first apply. Useful for internal domains or testing. The generated certificate is stored at `$PROJECT_DIR/data/certs/`. |

### Management Domain

The `management` block configures the Vacuum Wall admin interface itself. It follows the same structure as a domain entry but includes an `auth` block for HTTP Basic Authentication.

| Field | Type | Required | Description |
|---|---|---|---|
| `domain` | string | Yes | The hostname used to access the management WebUI (e.g., `<hostname>.local`). |
| `backend` | object | Yes | Points to the Flask app at `127.0.0.1:9090`. |
| `auth` | object | Yes | HTTP Basic Authentication configuration. |
| `auth.user` | string | Yes | Username for the `.htpasswd` file. |
| `auth.htpasswd` | string | Yes | Full path to the `.htpasswd` file containing the username and hashed password. |

The `.htpasswd` file can be created with the `htpasswd` utility:

```bash
htpasswd -bc $PROJECT_DIR/data/nginx/.htpasswd admin yourpassword
```

### Global SSL Settings

The `ssl` block defines TLS parameters applied to all HTTPS server blocks via the shared snippet.

| Field | Type | Required | Description |
|---|---|---|---|
| `protocols` | string | No | nginx `ssl_protocols` directive value. Default: `TLSv1.2 TLSv1.3`. |
| `ciphers` | string | No | nginx `ssl_ciphers` directive value. Default is a curated AEAD-only cipher string. |
| `prefer_server_ciphers` | boolean | No | Whether to prefer server cipher order. Default: `false`. |

## WireGuard Configuration

**File**: `config/wireguard/config.json`

This file defines the WireGuard server interface and all connected peers. The application renders it into `/etc/wireguard/wg0.conf` and applies it with `wg-quick`.

```json
{
  "interface": {
    "name": "wg0",
    "listen_port": 51820,
    "private_key": "kOv8lK...',
    "public_key": "YzP3xI...',
    "addresses": ["10.137.0.1/24"],
    "post_up": null,
    "post_down": null
  },
  "peers": {
    "alice": {
      "public_key": "nR7mQ2...',
      "private_key": "xLpDgF...',
      "endpoint": "203.0.113.1:51820",
      "allowed_ips": ["0.0.0.0/0"],
      "persistent_keepalive": 25,
      "preshared_key": null
    }
  }
}
```

### Interface Fields

| Field | Type | Required | Description |
|---|---|---|---|
| `name` | string | Yes | WireGuard interface name. Default: `wg0`. |
| `listen_port` | integer | Yes | Port the WireGuard interface listens on. Default: `51820`. Must be opened in the firewall. |
| `private_key` | string | Yes | Base64-encoded private key for the server interface. Use `wg genkey` to generate. |
| `public_key` | string | Yes | Corresponding public key. Use `wg pubkey` to derive from the private key. |
| `addresses` | array | Yes | IP address(es) assigned to the server interface in CIDR notation (e.g., `10.137.0.1/24`). |
| `post_up` | string | No | Shell command to run after the interface is brought up. Common uses: adding NAT rules, enabling IP forwarding for the tunnel. Set to `null` to omit. |
| `post_down` | string | No | Shell command to run after the interface is brought down. Used to clean up rules added by `post_up`. Set to `null` to omit. |

### Peer Fields

Peers are stored in an object keyed by a human-readable identifier (e.g., `alice`, `office-laptop`). Each peer entry defines a WireGuard peer configuration.

| Field | Type | Required | Description |
|---|---|---|---|
| `public_key` | string | Yes | The peer's public key. |
| `private_key` | string | No | The peer's private key, stored for generating downloadable client configuration files. This value is stripped from all API responses — the WebUI never exposes peer private keys over the network. |
| `endpoint` | string | No | The peer's public endpoint (IP:port). Required for server-initiated connections (e.g., the server reaching out to a peer behind a firewall). Leave empty or `null` for peer-initiated connections where the peer connects to the server. |
| `allowed_ips` | array | No | CIDR blocks that traffic from this peer is allowed to route. Defaults to `[]` (no routing restrictions from the server side). `["0.0.0.0/0"]` allows all traffic. `["10.137.0.0/16"]` restricts traffic to the VPN subnet. |
| `persistent_keepalive` | integer | No | Keepalive interval in seconds. `25` is recommended for peers behind NAT. Set to `0` or `null` to disable. |
| `preshared_key` | string | No | Optional pre-shared key for post-quantum resistance. Use `wg genpsk` to generate. |

### Client Configuration Generation

When a peer's `private_key` is set, the WebUI can generate a complete WireGuard client configuration file that the user can download and import into their WireGuard client app. The generated config includes the peer's interface settings, the server as a `[Peer]` entry, and the appropriate `Endpoint` and `AllowedIPs` values. The `private_key` field is written into the client config file for download but is never returned by the API.

### Applying Configuration

When configuration is saved through the WebUI or API, the application:

1. Validates all key pairs and IP ranges.
2. Renders the `wg0.conf` file from the JSON configuration.
3. Copies the rendered file to `/etc/wireguard/wg0.conf` using the sudo whitelist.
4. Runs `sudo wg-quick up wg0` to apply the configuration.
5. Returns success or error status to the caller.

If the interface is already up, `wg-quick up` will reconfigure it in place without dropping existing connections.