# Reference: server.listeners

URL: https://scalws.com/docs/reference/server-listeners/
Source: `docs/reference/schema` in the ScalWS repository

<h3 id="server.listeners-.address"><code>server.listeners[].address</code></h3>

| | |
|---|---|
| Syntax | `address: <string>` |
| Default | `required` |
| Context | `server.listeners[]` |
| Reload | needs a restart |

Socket address to listen on, e.g. `0.0.0.0:443`.


<h3 id="server.listeners-.http3"><code>server.listeners[].http3</code></h3>

| | |
|---|---|
| Syntax | `http3: true \| false` |
| Default | `false` |
| Context | `server.listeners[]` |
| Reload | needs a restart |

Also serve HTTP/3 over QUIC on the same UDP port (TLS listeners only; off by default). The release packages include it; a source build needs the `http3` feature (ADR-0019).


<h3 id="server.listeners-.name"><code>server.listeners[].name</code></h3>

| | |
|---|---|
| Syntax | `name: <string>` |
| Default | `required` |
| Context | `server.listeners[]` |
| Reload | needs a restart |

Listener name, used in metrics and logs.


<h3 id="server.listeners-.proxy_protocol"><code>server.listeners[].proxy_protocol</code></h3>

| | |
|---|---|
| Syntax | `proxy_protocol: true \| false` |
| Default | `false` |
| Context | `server.listeners[]` |
| Reload | needs a restart |

Expect a PROXY protocol v1/v2 header from a trusted proxy on every connection.


<h3 id="server.listeners-.strict_sni"><code>server.listeners[].strict_sni</code></h3>

| | |
|---|---|
| Syntax | `strict_sni: true \| false` |
| Default | `false` |
| Context | `server.listeners[]` |
| Reload | applies on reload |

Answer 421 when a request's host differs from the TLS SNI (ADR-0013).


<h3 id="server.listeners-.tls"><code>server.listeners[].tls</code></h3>

| | |
|---|---|
| Syntax | `tls: {...}` |
| Default | `none` |
| Context | `server.listeners[]` |
| Reload | adding or removing it needs a restart; its values apply on reload |

TLS settings; absent: plain HTTP.


<h3 id="server.listeners-.tls.acme"><code>server.listeners[].tls.acme</code></h3>

| | |
|---|---|
| Syntax | `acme: true \| false` |
| Default | `false` |
| Context | `server.listeners[].tls` |
| Reload | applies on reload |

Serve ACME-managed certificates of applications with `acme: true` (ADR-0018).


<h3 id="server.listeners-.tls.certificates"><code>server.listeners[].tls.certificates</code></h3>

| | |
|---|---|
| Syntax | `certificates: [{...}, ...]` |
| Default | `[]` |
| Context | `server.listeners[].tls` |
| Reload | applies on reload |

Certificates with the names they serve; the client's SNI selects one.


<h3 id="server.listeners-.tls.certificates-.cert"><code>server.listeners[].tls.certificates[].cert</code></h3>

| | |
|---|---|
| Syntax | `cert: <string>` |
| Default | `required` |
| Context | `server.listeners[].tls.certificates[]` |
| Reload | applies on reload |

PEM file with the end-entity certificate first, followed by intermediates.


<h3 id="server.listeners-.tls.certificates-.default"><code>server.listeners[].tls.certificates[].default</code></h3>

| | |
|---|---|
| Syntax | `default: true \| false` |
| Default | `false` |
| Context | `server.listeners[].tls.certificates[]` |
| Reload | applies on reload |

Used when the client sends no SNI or an unknown name. At most one per listener.


<h3 id="server.listeners-.tls.certificates-.key"><code>server.listeners[].tls.certificates[].key</code></h3>

| | |
|---|---|
| Syntax | `key: <string>` |
| Default | `required` |
| Context | `server.listeners[].tls.certificates[]` |
| Reload | applies on reload |

PEM file with the private key (PKCS#8, PKCS#1 or SEC1).


<h3 id="server.listeners-.tls.certificates-.server_names"><code>server.listeners[].tls.certificates[].server_names</code></h3>

| | |
|---|---|
| Syntax | `server_names: [<string>, ...]` |
| Default | `required` |
| Context | `server.listeners[].tls.certificates[]` |
| Reload | applies on reload |

Host names (exact or `*.example.com`) this certificate is selected for via SNI. Each must be covered by the certificate's SANs. Empty only for the `default` certificate, which is then served only for an absent or unknown SNI name.


<h3 id="server.listeners-.tls.certificates_file"><code>server.listeners[].tls.certificates_file</code></h3>

| | |
|---|---|
| Syntax | `certificates_file: <string>` |
| Default | `none` |
| Context | `server.listeners[].tls` |
| Reload | applies on reload |

YAML file with more certificate entries (a list with the keys of `certificates`), read when the configuration is loaded and appended to `certificates`. Relative to the configuration file; a leading `-` makes a missing file mean "no entries".