> Index of every page on this site: [llms.txt](https://docs.a-line.cloud/llms.txt)

# Networking

> Domains, HTTP settings, connections between apps and projects, and outbound traffic.

The examples on this page share one project, `shop`, on the cluster
`hetzner-fsn1`.

```yaml title="clusters/hetzner-fsn1.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
provider: hetzner
region: fsn1
pools:
  - name: control-plane
    role: control_plane
  - name: general
```

## Domains

An app's `domains` list routes hostnames to it. Each entry names either a
`domain` you own or a `generated` platform hostname.

```yaml title="projects/shop/apps/web.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/web:2.0.0
port: 3000
domains:
  - generated: site
  - domain: shop.example.com
    dns_target: cname
    behind_proxy: true
  - domain: shop.example.com
    path_prefix: /api
    strip_prefix: true
    port: 8080
```

| Key | Meaning |
| --- | --- |
| `domain` | A hostname such as `shop.example.com`. The domain must be [claimed and verified](/iac/domains) by your organization. |
| `generated` | A platform hostname instead of a literal one: `site` for the app's HTTPS host, or `srv` for a TCP or UDP host (with `protocol` and `port`). |
| `port` | The app port to route to. |
| `path_prefix`, `strip_prefix` | Route only paths under a prefix, and optionally strip it before forwarding. |
| `tls` | `true` (the default), `false`, or `passthrough` when the app terminates TLS itself. |
| `wildcard` | With `tls: passthrough`, route every name one or more labels below `domain`, but not `domain` itself. |
| `dns_target` | What the domain's DNS records point at: `a_records` (A and AAAA records at the load balancer) or `cname` (a CNAME to the app's platform host). Leaving it out keeps the current choice. |
| `behind_proxy` | `true` when the domain is served through a CDN or reverse proxy (Cloudflare, Fastly, ...). The DNS check then fetches `https://<domain>/` and confirms the request reached this app, instead of matching load balancer addresses. HTTP(S) domains only. Set Cloudflare's SSL/TLS mode to Full (strict), never Flexible. It also gives the domain an ACME challenge delegation, so its certificate is issued over DNS (see [Behind a CDN or proxy](/concepts/domains#behind-a-proxy)). Leaving it out keeps the current setting. |

Don't write a platform hostname as a literal `domain`: it is refused with
`platform_suffix_literal`. Use `generated` instead.

### Origin lock

A domain `behind_proxy` can also be locked to your own CDN, so nobody can
skip its firewall or rate limits by calling the load balancer directly. Turn
on **Origin lock** in the domain's settings (or `POST .../domains/{domain_id}/origin-lock`
in the API): you get a key, shown once. Have your CDN send it on every request
in the `X-Aline-Origin-Key` header (on Cloudflare: Rules, Transform Rules,
Modify Request Header, Set static). Requests without a matching key get 403.
The header is removed before the request reaches your app.

Rotating the key gives you a new one and keeps the previous one working for
24 hours. Turning the lock off stops every key at once. Keys are not part of
the IaC file and an export never contains them; only their fingerprint
(the first 16 hex digits of `printf %s KEY | sha256sum`) is ever shown again.

While the lock is on, the client IP header you choose (`CF-Connecting-IP`,
`True-Client-IP`, `Fastly-Client-IP` or your own) is passed to the app with
the visitor's address; read the client IP from that header. Without the lock
it is removed like every other client-set header, because anyone could set
it. `X-Real-Ip` (and the last `X-Forwarded-For` entry) holds the address of
the CDN edge that connected, not the visitor's.

### TCP and UDP

```yaml title="projects/shop/apps/game.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/game-server:1.0.0
ports:
  - port: 25565
    name: game
domains:
  - generated: srv
    protocol: tcp
    port: 25565
```

## HTTP settings

`http` sets the app's HTTP behaviour. Only the keys you write are changed;
the others keep their current values.

```yaml title="projects/shop/apps/storefront.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/storefront:3.1.0
port: 3000
http:
  https_redirect: true
  www_redirect: to_apex
  hsts: true
  hsts_max_age: 31536000
  compression: true
  csp_mode: enforce
  csp_preset: strict
  max_body_bytes: 10485760
```

| Key | Meaning |
| --- | --- |
| `https_redirect` | Redirect plain HTTP to HTTPS. |
| `www_redirect` | `off`, `to_www` or `to_apex`. |
| `hsts`, `hsts_max_age`, `hsts_include_subdomains` | Send `Strict-Transport-Security`. |
| `compression` | Compress responses. |
| `csp_mode`, `csp_preset`, `csp_policy`, `csp_report_uri` | Content-Security-Policy: mode `off`, `report_only` or `enforce`; preset `basic`, `strict` or `custom` (with your own `csp_policy`). |
| `permissions_policy`, `permissions_policy_custom` | Permissions-Policy: `off`, `basic`, `strict` or `custom`. |
| `coop` | Cross-Origin-Opener-Policy: `off`, `same_origin_allow_popups` or `same_origin`. |
| `header_frame_options`, `header_nosniff`, `header_referrer_policy` | Common security headers. |
| `custom_headers` | Extra response headers. Replaces the stored list. |
| `max_body_bytes` | The largest accepted request body. `null` resets it to unlimited. |
| `csrf_mode`, `csrf_trusted_origins`, `csrf_exempt_paths` | Cross-site request protection, see [below](#csrf). |
| `content_negotiation` | Static sites only: answer pages in Markdown, JSON, YAML or text, see [below](#content-negotiation). |

### Cross-site request protection

With `csrf_mode: enforce`, the edge refuses a state-changing request that a
browser sends from another site, with a plain `403`, before it reaches your
app. A request is refused when all of these hold:

- it is not a `GET`, `HEAD` or `OPTIONS` request, or it opens a WebSocket;
- the browser marks it as coming from another site (`Sec-Fetch-Site:
  same-site` or `cross-site`), or an older browser sends an `Origin` header;
- the `Origin` is not one of the app's own domains or `csrf_trusted_origins`;
- the path is not under one of `csrf_exempt_paths`.

Requests without these browser headers, such as webhooks, CLIs and calls
from other servers, always pass. `report_only` lets every request through but
adds `X-Aline-Csrf: would-block` to the ones `enforce` would refuse, so you
can check your logs before you switch it on. The default is `off`.

```yaml title="projects/shop/apps/checkout.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/checkout:1.4.0
port: 3000
http:
  csrf_mode: enforce
  csrf_trusted_origins:
    - https://login.example.com
  csrf_exempt_paths:
    - /webhooks
```

- `csrf_trusted_origins`: up to 20 exact origins like
  `https://login.example.com` or `https://example.com:8443`. No wildcards,
  paths or trailing slashes. `http://` origins are accepted only when the app
  serves plain HTTP (an `http` domain, or `https_redirect: false`).
- `csrf_exempt_paths`: up to 20 path prefixes, each at most 256 characters.
  `/webhooks` exempts `/webhooks` and everything below it. `/` is refused: set
  the mode to `off` instead.

Static sites only serve `GET` and `HEAD`, so they have no CSRF settings.

### Content negotiation

A static site can answer a page without an extension with a twin file when
the request's `Accept` header prefers it over HTML. With
`content_negotiation` on, `curl -H 'Accept: text/markdown' https://docs.example.com/about`
gets `about.md` instead of `about.html`. Browsers keep getting HTML: a tie,
`*/*` and the usual browser `Accept` values all answer with the page, and a
request that matches no twin gets the page too (never `406`).

```yaml title="projects/web/sites/docs.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  repo: example/docs
http:
  content_negotiation:
    enabled: true
    types: [markdown, json]
    markdown_tokens: true
```

| Key | Meaning |
| --- | --- |
| `enabled` | Serve twins. Default `false`. |
| `types` | Which twins: `markdown` (`.md`, `text/markdown`), `json` (`.json`, `application/json`), `yaml` (`.yaml` then `.yml`; `application/yaml`, `application/x-yaml` or `text/yaml`) and `text` (`.txt`, `text/plain`). Default all four. |
| `markdown_tokens` | Send `x-markdown-tokens` with a Markdown twin: a token estimate (characters / 4) counted at deploy. Default `true`. |

The twin of `/` is `index.<ext>`; `/about/` tries `about.<ext>`, then
`about/index.<ext>`; `/about` tries `about.<ext>`. A twin is sent with status
`200`, its own `Content-Type` and a `Content-Location` naming the file, and
your `_headers` rules still apply. Every answer for a page that can be
negotiated, the HTML one too, carries `Vary: Accept`, so caches keep the two
apart. The mapping replaces the stored choice: keys you leave out take their
defaults. A change applies with the next routing update, no redeploy. An app
file refuses the key.

## Connections between apps

`connections` opens traffic from this app to other apps of the same project,
on the listed ports.

```yaml title="projects/shop/apps/api.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  image: ghcr.io/example/api:1.4.2
port: 8080
connections:
  - to: db
    ports:
      - port: 5432
        protocol: tcp
```

```yaml title="projects/shop/apps/db.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
source:
  template: postgres
  version: "16"
```

## Connections between projects

A project's `network_policies` allows traffic to another project of the same
cluster. `direction: both` (the default) lets both projects reach each other;
`ingress` lets only this project reach the target. `network_policies: []`
removes every policy.

```yaml title="projects/payments/project.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: payments
cluster: hetzner-fsn1
```

The `shop` project below lets itself reach `payments` on port 443 and also
limits its outbound traffic.

## Outbound traffic

`egress` controls where a project or an app can connect to outside the
cluster:

- `mode: public` (a project's default): any destination.
- `mode: isolated`: only the destinations in `rules`.

Each rule has a `kind` (`fqdn` or `cidr`), a `value` (a domain, optionally
starting with `*.`, or a CIDR), an optional `port`, an optional `protocol`
(`tcp` or `udp`, which needs a port) and a `description`. In `public` mode
the rules are informational. An app without `egress.mode` follows its
project.

```yaml title="projects/shop/project.yaml" iac
# yaml-language-server: $schema=https://a-line.cloud/schemas/iac/v1.json
version: 1
name: shop
cluster: hetzner-fsn1
network_policies:
  - target: payments
    direction: ingress
    ports:
      - port: 443
egress:
  mode: isolated
  rules:
    - kind: fqdn
      value: api.example.net
      port: 443
      protocol: tcp
      description: Payment provider
    - kind: cidr
      value: 203.0.113.0/24
```

See [`NetworkPolicySpec`](/iac/reference/types#networkpolicyspec) and
[`EgressSpec`](/iac/reference/types#egressspec) for every key.

### Blocked connection emails

In `isolated` mode, each blocked connection shows in the app's logs as
"blocked outbound connection to" the address. The org's owner and admins
also get an email and an in-app notification per app, with the address and
port, the domain name when known, how often it was blocked, and when it was
first and last seen. To keep the volume low:

- An app's first blocked connection is reported within about 15 minutes.
  After that, each app gets at most one daily digest.
- A digest lists only destinations not reported in the last 7 days, up to
  10, then "+N more".
- An org gets at most 5 of these emails a day. The rest are added to a
  later digest.

To stop the emails for all apps, turn off **Blocked outbound traffic** in
**Settings > Notifications** (`/settings/notifications`); members can turn it
on there. To stop them for one
app, use the **Don't email me about this app** link in the email, or the
switch in the app's Network tab. Both choices only apply to you.
