> ## Documentation Index
> Fetch the complete documentation index at: https://dokumentation.websale.de/llms.txt
> Use this file to discover all available pages before exploring further.

# system - Basic system configuration

> The system node holds basic technical WEBSALE configurations that control system behaviour at the infrastructure level, independently of shop content.

export const KonfigDeeplink = ({node}) => <>
    You can open this setting directly in the Admin Interface via the following link:{" "}
    <code>{`https://<shop-domain>/admin/config/${node}`}</code>{" "}
    (<a href="/en/admin-interface/konfigurations-deeplinks">Deeplink overview</a>)
  </>;

The `system` node contains basic technical configurations of the shop. These control the system behaviour at the infrastructure level — independently of shop content.

The configuration is done in the Admin Interface in the "Storefront API" area.

***

## `system*` - Basic structure

The basic structure of the `system` node is shown below:

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "system": {
    "trustedProxies": { ... }
  }
}
```

#### Parameter description

| **Parameter**    | **Description**                                                                                      |
| ---------------- | ---------------------------------------------------------------------------------------------------- |
| `trustedProxies` | Configuration of the trusted proxy servers from which the `X-Forwarded-For` HTTP header is accepted. |

***

## `system.trustedProxies` - Trusted proxy servers

In some setups the shop is not directly reachable over the internet but instead through an upstream server. This is the case, for example, when an agency hosts the shop frontend on its own infrastructure. In this case, the shop does not see the IP address of the end customer for incoming requests, but only that of the agency server.

This is problematic as soon as the shop has to block IP addresses, for example for too many failed login attempts or suspicious payment processes. Since all requests in this case come from the same agency server IP, a block would make the shop inaccessible for all customers.

**Why is an allowlist necessary?**\
The shop must not accept the `X-Forwarded-For` header from arbitrary servers. An attacker could set this header themselves and supply a forged IP address to the shop, thereby bypassing IP-based protection mechanisms.

For this reason, an allowlist is maintained via `trustedProxies`. Only servers whose IP address is entered there may set the `X-Forwarded-For` header. From all other servers, this header is ignored.

<Info>
  If the shop is run behind a proxy server and `trustedProxies` is not configured correctly, IP blocks may affect the entire proxy IP and thus block the shop for all customers. In this case, ensure that the proxy server forwards the real client IP via `X-Forwarded-For` and that its IP is entered here.
</Info>

<KonfigDeeplink node="system.trustedProxies" />

#### Example configuration `system.trustedProxies`

```json theme={"theme":{"light":"github-light","dark":"github-dark"},"languages":{"custom":["/languages/websale.json"]}}
{
  "addresses": [
    "13.196.200.101",
    "13.196.0.0/16",
    "1234:5678:9abc:def0::1",
    "1234:5678:9abc:def0::/64"
  ]
}
```

#### Parameter description

| **Parameter** | **Type**      | **Description**                                                                                                                                                                                                                                  |
| ------------- | ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `addresses`   | list (string) | List of IP addresses or IP subnets from which the [X-Forwarded-For header](https://en.wikipedia.org/wiki/X-Forwarded-For) is accepted. <br />Supported are individual IPv4 and IPv6 addresses as well as CIDR subnets.<br /><br />Default:  `[]` |

#### Supported IP formats

| **Format**         | **Example**                | **Description**                                                 |
| ------------------ | -------------------------- | --------------------------------------------------------------- |
| IPv4 address       | `13.196.200.101`           | A single, explicit IPv4 address.                                |
| IPv4 subnet (CIDR) | `13.196.0.0/16`            | All addresses in the range <br />`13.196.0.0 - 13.196.255.255`. |
| IPv6 address       | `1234:5678:9abc:def0::1`   | A single, explicit IPv6 address.                                |
| IPv6 subnet (CIDR) | `1234:5678:9abc:def0::/64` | An IPv6 subnet in CIDR notation.                                |

<Info>
  Subnets in [CIDR notation](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing) are especially useful when an upstream server uses a dynamic IP from a known, fixed address range.
</Info>

***

## Further links

* [X-Forwarded-For](https://en.wikipedia.org/wiki/X-Forwarded-For)
* [Classless Inter-Domain Routing](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing)