<commit_before>tls-terminator
==============

Configures nginx as TLS terminator for a http(s) backend.

Conceptually this is organized around the following terms:
- **site**: An internet-facing (or internal) https endpoint. This is grouped by hostname,
  thus `api.example.com` and `example.com` would be two different sites.
- **backend**: Each site has one or more backends, grouped by url prefix. Thus
  `example.com` and `example.com/docs` could be two different backends for a given site.
- **upstreams**: Each backend has one or more upstreams, which is the service that actually
  generates the response for a given request. This is usually another http(s) url.

By default the HTTP Host header will be set to the same as the upstream if a single
upstream is given, ie if the only upstream is `example.herokuapp.com` the Host header will
be `example.herokuapp.com`. If there are multiple upstreams the default Host header will
be that of the site. The latter behavior can also be set for a single upstream by setting
`upstream_hostname` to `site` in the backend or site config. `upstream_hostname` can also
be set to any arbitrary value that will be used for all upstreams.

The state will add the following security headers by default:
- `Strict-Transport-Security: max-age=31536000; includeSubDomains` Ensures later requests are made over https too.
- `X-Frame-Options: DENY` Prevents click-jacking by preventing the page from being framed.
- `X-Xss-Protection: 1; mode=block` Turns on the browser's built-in XSS protection.
- `X-Content-Type-Options: nosniff` Disables mime-type sniffing in browsers.

There are some more headers that the upstream should set since they are very site specific, like
`Content-Security-Policy`, `Referrer-Policy` and `Feature-Policy`. If you can't configure the
headers on the backend you can configure them both globally on the tls-terminator (convenient for
`Expect-CT` where you just need to set a report uri) or per site (`Referrer-Policy`) through the
`add_headers` key. This also enables overriding the defaults mentioned above. The default headers
will only be added if the header isn't already set by the upstream.

Sample pillar config:

```yaml
tls-terminator:
    example.com:
        backend: https://example-app.herokuapp.com
        cert: |
            ---BEGIN CERTIFICATE----
            <snip>
            ---END CERTIFICATE------
        key: |
            ---BEGIN PRIVATE KEY----<commit_msg>Add note about unsetting headers to readme<commit_after>tls-terminator
==============

Configures nginx as TLS terminator for a http(s) backend.

Conceptually this is organized around the following terms:
- **site**: An internet-facing (or internal) https endpoint. This is grouped by hostname,
  thus `api.example.com` and `example.com` would be two different sites.
- **backend**: Each site has one or more backends, grouped by url prefix. Thus
  `example.com` and `example.com/docs` could be two different backends for a given site.
- **upstreams**: Each backend has one or more upstreams, which is the service that actually
  generates the response for a given request. This is usually another http(s) url.

By default the HTTP Host header will be set to the same as the upstream if a single
upstream is given, ie if the only upstream is `example.herokuapp.com` the Host header will
be `example.herokuapp.com`. If there are multiple upstreams the default Host header will
be that of the site. The latter behavior can also be set for a single upstream by setting
`upstream_hostname` to `site` in the backend or site config. `upstream_hostname` can also
be set to any arbitrary value that will be used for all upstreams.

The state will add the following security headers by default:
- `Strict-Transport-Security: max-age=31536000; includeSubDomains` Ensures later requests are made over https too.
- `X-Frame-Options: DENY` Prevents click-jacking by preventing the page from being framed.
- `X-Xss-Protection: 1; mode=block` Turns on the browser's built-in XSS protection.
- `X-Content-Type-Options: nosniff` Disables mime-type sniffing in browsers.

There are some more headers that the upstream should set since they are very site specific, like
`Content-Security-Policy`, `Referrer-Policy` and `Feature-Policy`. If you can't configure the
headers on the backend you can configure them both globally on the tls-terminator (convenient for
`Expect-CT` where you just need to set a report uri) or per site (`Referrer-Policy`) through the
`add_headers` key. This also enables overriding the defaults mentioned above. The default headers
will only be added if the header isn't already set by the upstream.

You can remove the default headers or headers set globally by setting them to an empty string.

Sample pillar config:

```yaml
tls-terminator:
    example.com:
        backend: https://example-app.herokuapp.com
        cert: |
            ---BEGIN CERTIFICATE----
            <snip>
            ---END CERTIFICATE------
        key: |
            ---BEGIN PRIVATE KEY----
{'fraction_non_alphanumeric': 0.08010335917312661, 'fraction_numerical': 0.0035778175313059034, 'mean_word_length': 3.774193548387097, 'pattern_counts': {'":': 0, '<': 5, '<?xml version=': 0, '>': 5, 'https://': 2, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '750658', 'n_tokens_mistral': 1408, 'n_tokens_neox': 1336, 'n_words': 678}