> ## Documentation Index
> Fetch the complete documentation index at: https://www.datum.net/docs/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Agent home for Datum, with what it is, pricing, and how to act: https://agents.datum.net
> If you can only fetch URLs: read https://www.datum.net/docs/llms.txt in full and open the most specific page for the task. Commands, limits, and field paths are on task, operations, and limits pages, not on section overviews. Pages described as "Documentation is coming soon" are placeholders.
> If you have a shell or can save files: download https://www.datum.net/docs/llms-full.txt (every page, about 740 KB) once and search it with grep, instead of fetching pages one at a time.
> datumctl describes itself: `datumctl api-resources` lists resource types and `datumctl explain <resource>` shows a schema. To act on live resources, use Datum MCP or datumctl. To search the docs, use the Docs MCP server at https://www.datum.net/docs/mcp.

# Host Header Override with HTTPProxy

> Rewrite the Host header on upstream requests using an HTTPProxy RequestHeaderModifier filter.

This is useful when:

* The upstream expects a specific `Host` header
* You are proxying to a shared or virtual-hosted service
* The backend's DNS name does not match the public hostname

***

## Overview

At a high level, this setup:

1. Accepts public traffic at a configured hostname
2. Forwards all requests to an upstream backend
3. Rewrites the `Host` header **before** the request reaches the upstream

***

## Prerequisites

* `datumctl` installed and authenticated
* A valid **Project**

***

## Configuration steps

### Step 1: Set variables

> [tab] macOS / Linux
>
> ```bash theme={null}
> PROJECT="your-project-id"
> NAMESPACE="default"
> PROXY_NAME="host-header-demo"
> HOSTNAME="your-app.example.com"
> ```

> [tab] Windows (PowerShell)
>
> ```powershell theme={null}
> $PROJECT    = "your-project-id"
> $NAMESPACE  = "default"
> $PROXY_NAME = "host-header-demo"
> $HOSTNAME   = "your-app.example.com"
> ```

***

### Step 2: Apply host header configuration

The `RequestHeaderModifier` filter overwrites the `Host` header before the request is forwarded upstream. The `type` field is required.

> [tab] macOS / Linux
>
> ```bash theme={null}
> cat <<EOF | datumctl apply --project $PROJECT --namespace $NAMESPACE -f -
> apiVersion: networking.datumapis.com/v1alpha
> kind: HTTPProxy
> metadata:
>   name: $PROXY_NAME
> spec:
>   hostnames:
>   - $HOSTNAME
>   rules:
>   - name: host-header-override
>     matches:
>     - path:
>         type: PathPrefix
>         value: /
>     filters:
>     - type: RequestHeaderModifier
>       requestHeaderModifier:
>         set:
>         - name: Host
>           value: example.internal
>     backends:
>     - endpoint: https://httpbin.org
> EOF
> ```

> [tab] Windows (PowerShell)
>
> ```powershell theme={null}
> @"
> apiVersion: networking.datumapis.com/v1alpha
> kind: HTTPProxy
> metadata:
>   name: $PROXY_NAME
> spec:
>   hostnames:
>   - $HOSTNAME
>   rules:
>   - name: host-header-override
>     matches:
>     - path:
>         type: PathPrefix
>         value: /
>     filters:
>     - type: RequestHeaderModifier
>       requestHeaderModifier:
>         set:
>         - name: Host
>           value: example.internal
>     backends:
>     - endpoint: https://httpbin.org
> "@ | datumctl apply --project $PROJECT --namespace $NAMESPACE -f -
> ```

***

## Verification

`httpbin.org/headers` echoes the request headers received by the upstream, making it easy to confirm the rewrite.

```bash theme={null}
curl https://$HOSTNAME/headers
```

Look for `Host` in the response:

```json theme={null}
{
  "headers": {
    "Host": "example.internal",
    ...
  }
}
```

If `Host` shows `example.internal`, the rewrite is working correctly.

***

## Cleanup

> [tab] macOS / Linux
>
> ```bash theme={null}
> datumctl delete httpproxy $PROXY_NAME \
>   --project $PROJECT --namespace $NAMESPACE --ignore-not-found
> ```

> [tab] Windows (PowerShell)
>
> ```powershell theme={null}
> datumctl delete httpproxy $PROXY_NAME `
>   --project $PROJECT --namespace $NAMESPACE --ignore-not-found
> ```

***

## Troubleshooting

| Symptom | Root Cause | Resolution |
| - | - | - |
| API rejects the resource | `type` field missing from filter | Add `type: RequestHeaderModifier` to the filter |
| `Host` header not rewritten | Filter applied at wrong level | Confirm `filters` is under `rules[].filters`, not `backends[].filters` |
| Upstream returns 404 or 421 | Upstream rejects the rewritten `Host` value | Verify the upstream accepts the hostname you configured |
| `Host` shows original value | `set` vs `add` confusion | Use `set` to overwrite; `add` appends to an existing value |

***

## Best practices

* Use `set` to overwrite the `Host` header — `add` appends to any existing value instead of replacing it
* Keep the rewritten hostname consistent with what the upstream backend expects in its virtual host configuration
* Test with `httpbin.org/headers` before pointing at a real upstream — it removes backend variables from the equation

***

## Summary

* Host header rewriting uses a `RequestHeaderModifier` filter on the rule's `filters` list
* The `type: RequestHeaderModifier` field is required — omitting it will cause the API to reject the resource
* `set` overwrites the header; `add` appends
* The rewrite happens at the proxy — the client sees no change to the URL or response


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.