# clab-webserver

A lightweight, template-driven HTTP server designed to run as a node inside a
[containerlab](https://containerlab.dev) topology. It serves personalised plain-text
pages to participants based on their source IP address, making it easy to hand out
unique tokens, course names, or any per-prefix data during instructor-led lab sessions.

---

## How it works

1. Participants are assigned a unique IPv4 or IPv6 prefix in the lab topology (e.g. `10.0.3.0/24`).
2. When a participant runs `curl http://<webserver-ip>/`, the server looks up their
   source address against a prefix map (`client-map.yaml`) using longest-prefix match.
3. All matching prefixes are merged (least- to most-specific), producing a set of
   template variables for that request.
4. Every file under `docroot/` is rendered as a Go template with those variables
   substituted before being returned as `text/plain`.

Catch-all entries (`0.0.0.0/0`, `::/0`) provide defaults for all clients; more-specific
prefixes override individual variables for specific participants.

---

## Quickstart — adding to a containerlab topology

Add `clab-webserver` as a `linux` node and bind-mount your config files:

```yaml
# webserver.clab.yml
name: my-lab

topology:
  nodes:
    webserver:
      kind: linux
      image: git.ipng.ch/ipng-priv/clab-webserver:latest
      binds:
        - client-map.yaml:/app/client-map.yaml:ro
        - docroot:/app/docroot:ro
      env:
        CLIENT_MAP: /app/client-map.yaml
        DOCROOT: /app/docroot
        LISTEN: ":80"
      ports:
        - "80:80"

    participant1:
      kind: linux
      image: alpine:latest

  links:
    - endpoints: ["webserver:eth1", "participant1:eth1"]
```

The server starts automatically as the container entrypoint — no extra configuration needed.

---

## client-map.yaml

This file maps IPv4/IPv6 prefixes to template variables. Prefix matching is
longest-match; all matching entries are merged with more-specific values winning.

```yaml
# Default for all IPv4 clients
0.0.0.0/0:
  course: "My Lab"
  client_map_token: "not set"

# Default for all IPv6 clients
::/0:
  course: "My Lab"
  client_map_token: "not set"

# Per-participant overrides
10.0.1.0/24:
  client_map_token: "swift grey pirate"

2001:db8:1::/48:
  client_map_token: "swift grey pirate"

# A prefix can override any variable, including course
2001:db8:2::/48:
  client_map_token: "brave lime falcon"
  course: "Advanced Track"
```

A client at `2001:db8:2::1` would receive `course = "Advanced Track"` and
`client_map_token = "brave lime falcon"`, merged from `::/0` and `2001:db8:2::/48`.

The file is watched at runtime — edits take effect within 5 seconds without restarting
the container.

---

## docroot/

Static files served from this directory are processed as Go templates. Any
`{{ .variable }}` reference is substituted with the value from the merged
prefix-match result for that client.

Three variables are always available regardless of `client-map.yaml`:

| Variable | Value |
|---|---|
| `{{ .remote_address }}` | Client IP address |
| `{{ .host }}` | HTTP `Host` header |
| `{{ .user_agent }}` | HTTP `User-Agent` header |

A request to `/` serves `docroot/index.txt`. Subdirectories are supported.

If a template references a variable that has no value for a given client, the
variable renders as an empty string and a warning is logged.

**Example `docroot/index.txt`:**

```
Welcome, {{ .course }} participant from {{ .remote_address }}!
I see you are using "{{ .user_agent }}".

Your token is "{{ .client_map_token }}"

You may write it in your workbook and give to your teacher. Thank you for
participating in the {{ .course }} session.
```

---

## Configuration

All options can be set via CLI flag or environment variable. Flags take precedence.

| Flag | Env var | Default | Description |
|---|---|---|---|
| `-client-map` | `CLIENT_MAP` | `client-map.yaml` | Path to prefix/variable map |
| `-docroot` | `DOCROOT` | `docroot` | Directory of template files to serve |
| `-listen` | `LISTEN` | `:80` | Listen address |

---

## Building and running locally

```sh
# Run directly
go run . -client-map client-map.yaml

# Build and run
go build -o clab-webserver .
./clab-webserver -client-map client-map.yaml -listen :8080

# Docker
docker compose build
docker compose up
```

---

## Logging

All requests are logged to stdout in nginx combined-log format:

```
10.0.1.5 - - [03/Apr/2026:14:22:01 +0200] "GET /index.txt HTTP/1.1" 200 312 "-" "curl/7.88.1"
```

Warnings for missing template variables appear as structured log lines:

```
2026/04/03 14:22:01 WARNING: template variable .client_map_token has no value for client 10.0.3.1
```

---

## Appendix — Specification

### Purpose

A small, portable Go HTTP server for use in distributed containerlab exercises.
Each participant is assigned a unique IPv4 and/or IPv6 prefix. When they send a
request to the server, they receive a personalised plain-text response identifying
them and returning a unique token they can record and submit.

### File serving

- Files are served from a configurable `docroot/` directory.
- All files are rendered through Go's `text/template` engine before being returned.
- The `Content-Type` is always `text/plain; charset=utf-8`.
- Requests to `/` are served from `docroot/index.txt`.
- Path traversal attempts are rejected with `403 Forbidden`.

### Client map

- Configured via a single YAML file (`-client-map` / `$CLIENT_MAP`).
- Top-level keys are IPv4 or IPv6 CIDR prefixes.
- Values are dictionaries of `variable_name: "string value"`.
- On each request, all prefixes that contain the client IP are collected,
  sorted least- to most-specific, and merged. More-specific entries overwrite
  less-specific ones for any shared key.
- Variables produced by the merge are injected into the template alongside the
  HTTP-derived variables (`remote_address`, `host`, `user_agent`), which always win.
- IPv4-mapped IPv6 addresses (from dual-stack sockets) are normalised to IPv4
  before matching.
- The file is polled every 5 seconds. A changed file is reloaded atomically;
  a file with invalid YAML is rejected with a log warning and the previous data
  is kept in service.

### Template variables

- Any key defined in `client-map.yaml` under a matching prefix becomes a template variable.
- HTTP-derived variables (`remote_address`, `host`, `user_agent`) are always set and
  cannot be overridden by `client-map.yaml`.
- Template variables with no value for a given client default to `""` and a warning
  is logged.

### Logging

- All requests are logged to stdout in nginx combined-log format after the response is sent.
- Warnings and errors are written to stdout via the standard Go logger.

### Deployment

- Packaged as a multi-stage Docker image based on Alpine.
- `docroot/` is baked into the image; `client-map.yaml` is expected as a bind mount.
- All configuration is available as both CLI flags and environment variables.
- Image: `git.ipng.ch/ipng-priv/clab-webserver:latest`