---
title: "Route HTTP traffic"
description: "HTTP and HTTPS listeners that route requests by host, path, method, header and query, redirect to HTTPS, split traffic by weight, and serve several domains on one address."
---

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

# Route HTTP traffic

An `http` or `https` listener reads each request and routes it by its **rules**, checked in order: the
first rule that matches takes the request, and the listener's **default action** takes the rest. An
action forwards the request to one or more target groups, redirects it, or answers it with a fixed
response. One load balancer can have TCP, TLS, HTTP and HTTPS listeners at once.

Targets get the client's address in `X-Forwarded-For`, and the listener's protocol and port in
`X-Forwarded-Proto` and `X-Forwarded-Port`. `X-Forwarded-For` is appended to whatever the client sent,
so trust only its last entry.

A [WAF](/waf) inspects requests to HTTP and HTTPS listeners before they reach a target, and blocks
or logs what its rules match.

## HTTP target groups

An HTTP listener forwards to `http` target groups. A group's protocol is set when it's created, and an
`http` group can't take PROXY protocol. Its health check is HTTP by default: `GET /` on the traffic port,
healthy on `200-399`.

```sh
ezgh lb target-groups create web --vpc vpc_5p7r9s3t1vxz --port 8080 --protocol http
ezgh lb target-groups create api --vpc vpc_5p7r9s3t1vxz --port 9000 --protocol http --health-check-path /healthz
```

A `tcp` group serves only TCP and TLS listeners, and an `http` group only HTTP and HTTPS ones; mixing
them is `409 protocol_mismatch`.

## Redirect HTTP to HTTPS

An `http` listener on port 80 whose default action redirects every request to HTTPS on port 443,
keeping the host, path and query:

```sh
ezgh lb listeners create lbr_4k2m9x0a7qpe --protocol http --port 80 --redirect-https
```

## An HTTPS listener

An `https` listener takes a certificate, as a [TLS listener](/load-balancers/tls) does, and speaks
HTTP/2 and HTTP/1.1 to clients. Its default action here forwards to one group:

```sh
ezgh lb listeners create lbr_4k2m9x0a7qpe --protocol https --port 443 \
  --certificate crt_8s4f2k9d1mzq --forward tgp_7t3n1v8c2wzd
```

Other default actions are `--fixed-response 404` and `--redirect-https`. `--target-group tgp_…` alone is
the same as `--forward tgp_…`.

## Route by host and path

Rules are a JSON list. Each has an optional `name`, a `match` and an `action`:

```json title="rules.json"
[
  {
    "name": "api",
    "match": { "hosts": ["api.example.com"] },
    "action": { "type": "forward", "forward": { "targetGroups": [{ "targetGroup": "tgp_3a5s7d9f1ghj" }] } }
  },
  {
    "name": "static",
    "match": { "paths": [{ "type": "prefix", "value": "/static" }] },
    "action": { "type": "forward", "forward": { "targetGroups": [{ "targetGroup": "tgp_9q4w6e8r0tyu" }] } }
  },
  {
    "name": "old-pricing",
    "match": { "paths": [{ "type": "exact", "value": "/pricing.html" }] },
    "action": { "type": "redirect", "redirect": { "path": "/pricing", "statusCode": 301 } }
  }
]
```

```sh
ezgh lb listeners update lbr_4k2m9x0a7qpe lsn_3d0e6f8h2jlp --rules-file rules.json
ezgh lb listeners rules lbr_4k2m9x0a7qpe lsn_3d0e6f8h2jlp
```

`--rules-file` replaces the whole list. `ezgh lb listeners rules … -o json` prints a listener's rules in
the same form, to edit and send back.

### Conditions

A rule matches when every field it has matches. `hosts`, `paths` and `methods` match when any of their
entries does; `headers` and `queryParams` match only when all of their entries do. A rule with no fields
matches every request. Each field takes at most 5 entries, and a listener at most 100
rules.

| Field | Matches |
| --- | --- |
| `hosts` | The request's host, ignoring case and port: `api.example.com`, or `*.example.com` for any name ending in `.example.com` (not `example.com` itself). Lowercase. |
| `paths` | `{"type": "exact", "value": "/healthz"}`, or `{"type": "prefix", "value": "/api"}`, which matches `/api` and `/api/x` but not `/apix`. Starts with `/`; no spaces, `#` or `?`. |
| `methods` | Uppercase methods: `GET`, `POST`. |
| `headers` | `{"name": "X-Version", "value": "2"}`: the exact value; the name ignores case. |
| `queryParams` | `{"name": "beta", "value": "1"}`: the exact value, compared decoded (`%20` and `+` are a space). |

### Actions

| `type` | Fields |
| --- | --- |
| `forward` | `forward.targetGroups`: 1 to 5 `http` groups of the load balancer, each with a `weight` from 0 to 999. One group may leave out its weight. |
| `redirect` | `redirect.scheme` (`http` or `https`), `host`, `port` and `path` each replace that part of the URL; a part left out keeps the request's, and the query is always kept. `statusCode` is 301, 302 (the default), 307 or 308. At least one part must change. |
| `fixedResponse` | `fixedResponse.statusCode` from 200 to 599, `contentType` `text/plain` (the default), `text/html` or `application/json`, and an optional `body` of at most 1024 bytes. |

## Split traffic by weight

To send a share of requests to a new version, forward to two groups with weights. Here the default
action sends about 90% of requests to `web` and 10% to `web-canary`:

```sh
ezgh lb listeners update lbr_4k2m9x0a7qpe lsn_3d0e6f8h2jlp \
  --forward tgp_7t3n1v8c2wzd=90 --forward tgp_9q4w6e8r0tyu=10
```

Each request picks a group by weight, so one client's requests can reach both. A weight of 0 sends a
group nothing. In a rule, the same split is a `forward` with two `targetGroups`, each with its `weight`.

## Serve several domains on one HTTPS listener

A `tls` or `https` listener can hold more certificates beside its default one. Each client gets the
certificate whose names match the host it asks for (by SNI); a client that asks for none of them, or
sends no name, gets the default. Combine it with host rules to serve several sites from one address:

```sh
ezgh lb listeners update lbr_4k2m9x0a7qpe lsn_3d0e6f8h2jlp \
  --additional-certificate crt_1a2b3c4d5e6f --additional-certificate crt_7g8h9j0k1l2m
```

- A listener takes at most 24 additional certificates, each issued in the project and named once.
- `--additional-certificate` replaces the list; `--no-additional-certificates` empties it.
- Each renews by itself, as the default does.

In the API, they're the listener's `additionalCertificates`.

## In the console

On a load balancer's page, **Add listener** offers HTTP and HTTPS. An HTTP or HTTPS listener's second
step, **Rules**, holds its rules in order, each moved with the arrows, and its default action last. The
**Rules** tab lists a listener's rules, and **Edit rules** changes them.

## API

Listeners are created and changed with [CreateListener](/lb-api/CreateListener/) and
[UpdateListener](/lb-api/UpdateListener/). An HTTP or HTTPS listener takes `defaultAction` (or
`targetGroup` alone, for a forward to it) and `rules`; its `targetGroup` reads `null` unless the default
action forwards to exactly one group. A change that names `rules` replaces the whole list, and honours
`If-Match` with the listener's `ETag` (`412 precondition_failed` when someone changed it first).

Source: https://docs.ezghcloud.com/load-balancers/http/index.mdx
