# Managed Dedicated: Host Header Override

By default, the `Host` header your gateway sends to a backend is derived from
the URL it connects to. Host header override lets your code send a `Host` header
that differs from the hostname in the request URL, so the gateway can connect to
one address while the backend sees the hostname it expects.

This setting is only available on [Managed Dedicated](../overview.mdx) instances
and is off by default.

## When to use it

Reach for this when the address you connect to and the hostname your backend
expects aren't the same:

- **Virtual-hosted backends.** A single load balancer, ingress controller, or
  web server hosts several sites and picks one based on the `Host` header. Your
  gateway connects to the shared address and names the site it wants.
- **Private networking.** With
  [private networking](../aws-private-networking.mdx), you reach a backend
  through an internal endpoint or IP whose DNS name doesn't match the public
  hostname the backend is configured for, such as `https://10.0.4.12` with a
  `Host` of `api.acme.com`.
- **Testing a new backend before DNS moves.** Point the gateway at the new
  origin's address while sending the production `Host` header, so you can
  validate the migration without changing public DNS.
- **Legacy backends keyed on the hostname.** Applications that route, build
  links, or select a tenant from the `Host` header keep working when the gateway
  sits in front of them.

:::caution

An incorrect `Host` header can send traffic to the wrong site on a shared
backend, and some applications trust the header when building redirects and
links. Enable this setting only if you need it, and set the header to a value
your code controls rather than one copied from client input.

:::

## Enable the setting

Add `allowHostHeaderOverride` to the `zuplo.jsonc` file at the root of your
project and deploy:

```jsonc
{
  "version": 1,
  "projectType": "managed-dedicated",
  "allowHostHeaderOverride": true,
}
```

The setting applies to the whole project. Without it, a `Host` header you set on
an outbound request is ignored.

:::note

The `zuplo.jsonc` file isn't editable in the Zuplo Portal. Connect your project
to [source control](../source-control.mdx) and edit the file there or push a
local change with git. See
[Project Configuration](../../programmable-api/zuplo-json.mdx) for the other
settings this file supports.

:::

## Example

Once the setting is enabled, set the `Host` header on any outbound request. This
[custom handler](../../handlers/custom-handler.mdx) connects to an internal load
balancer and tells it which site to serve:

```ts
import { ZuploContext, ZuploRequest, environment } from "@zuplo/runtime";

export default async function (request: ZuploRequest, context: ZuploContext) {
  const url = new URL(request.url);

  return fetch(`${environment.INTERNAL_ORIGIN}${url.pathname}${url.search}`, {
    method: request.method,
    body: request.body,
    headers: {
      ...Object.fromEntries(request.headers),
      Host: "api.acme.com",
    },
  });
}
```

With `INTERNAL_ORIGIN` set to `https://10.0.4.12`, the gateway connects to
`10.0.4.12` and the backend receives a request for `api.acme.com`.