HTTP routes

The HTTP routes section of the Settings page shows how each cluster node routes HTTP traffic received on standard TCP ports 80 (HTTP) and 443 (HTTPS) to applications installed in the cluster or towards custom network destinations.

The core component that implements HTTP routes is the Traefik HTTP proxy. Each cluster node runs its own Traefik instance and acts as an independent web server. Traefik terminates TLS connections and works as the reverse proxy for applications typically hosted on that node.

Routes can be managed automatically by installed applications. In that case, they are marked with the Automatic badge. Alternatively, you can create custom routes and define their properties as needed.

A route is defined by a match rule for incoming requests, based on the HTTP host name and/or the request path. It also specifies the destination URL where matching traffic is forwarded.

Automatic routes usually point their destination URL to local services (often using http://127.0.0.1), so their traffic does not cross the cluster network. Custom routes, instead, can be configured with any reachable destination URL, including services in the node’s LAN or even on another cluster node if desired.

There is no special HTTP traffic handling for the cluster leader node: all nodes behave in the same way.

The HTTP routes page has two tabs:

• Routes lists the routes of every node, as described in this page.
• Frontend proxies configures the nodes that receive HTTP traffic through another proxy. See Frontend proxies.

Each route can have special attributes, visible in the main table:

• Automatic for rules created and managed by applications
• Access restricted if access is limited to specific IP addresses

Automatic routes cannot be modified except for the list of allowed IPs. When IP restrictions are added, they also gain the Access restricted attribute.

note

The route named cluster-admin is an automatic route, created during node setup. On the leader node it provides access to the cluster administration interface. On worker nodes it is required to elect a new cluster leader. If you restrict access to this route:

• You may prevent a new worker from joining the cluster.
• You may lose access to the cluster configuration if your own IP address is not allowed.
• If the node has frontend proxies, you may lose access when you connect to the node directly, without passing through them.

Refer to Clear IP restrictions on cluster-admin route to restore access if needed.

You can view the detailed attributes of any route by clicking its Name.

Create a custom HTTP route

To add a custom route, click the Create route button and enter the following details:

• Name: a unique identifier for the route
• Node: the node where the rule applies
• URL: the target URL of the route. It must point to a reachable backend HTTP server, either inside or outside the cluster. For better performance, use the local host address 127.0.0.1 without encryption for local applications, or https:// for external applications in the node’s LAN. In the latter case, encrypting the backend connection is strongly recommended.
• Skip certificate validation: if the URL starts with https://, this option disables verification of the backend TLS certificate. Skipping validation may be acceptable only if the backend is in a trusted network and cannot provide a valid TLS certificate.
• Host: set a valid FQDN to create a host-based route (virtual host). The rule matches requests where the Host header equals the given FQDN. Example: with host myapp.nethserver.org the route matches https://myapp.nethserver.org.
• Path: set a valid URL path starting with / (slash) to create a path-based route. The rule matches any request path that begins with it, regardless of the host name. For example, with path /myapp the route matches both https://ns8leader.nethserver.org/myapp and https://192.168.6.3/myapp/contents.html.
• Host + Path: if both fields are set, the request must match both the host name and the path. For example, with host myapp.nethserver.org and path /mypath, the route matches https://myapp.nethserver.org/mypath/contents.html but not https://ns8leader.nethserver.org/mypath/contents.html.
• Strip URL path prefix: when Path is set, remove the prefix before routing the request to the target URL.
• Request Let's Encrypt certificate: enable this option to automatically obtain a valid TLS certificate. See Let's Encrypt certificate for HTTP routes for important details if you disable this option later.
• Allow access from (optional): restrict access to the route by listing allowed IPv4/IPv6 addresses or CIDR networks, one per line. By default, the route is open to all networks. If the node has frontend proxies, list the addresses of the original clients, not the proxy addresses.

Custom HTTP routes are added to Traefik's backup and can be restored from it.

Let's Encrypt certificate for HTTP routes

The Request Let's Encrypt certificate option enables automatic provisioning of a TLS certificate for the Host name, signed by the Let's Encrypt Certificate Authority. Once obtained, the certificate is periodically renewed by Traefik. Refer to Let's Encrypt certificate requirements for details about requirements and how the process works.

When this option is disabled, the old TLS certificate is automatically removed from Traefik’s internal certificate storage, and Traefik is restarted after clicking the Save button.

warning

Restarting Traefik can forcibly disconnect users from applications. Avoid disabling the Request Let's Encrypt certificate option during office hours.

Frontend proxies

A cluster node can stand behind another HTTP proxy, such as a reverse proxy, a load balancer, or a CDN. In that case, Traefik receives every connection from the proxy address, and the original client address is available only in the X-Forwarded-For HTTP header.

Traefik accepts the X-Forwarded-For header only from the addresses listed as frontend proxies of the node. From any other source, the header is discarded, so that a client cannot forge its own address.

To configure the frontend proxies of a node:

1. Go to Settings → HTTP routes and select the Frontend proxies tab.
2. Click Add frontend proxy.
3. Select the node.
4. In Frontend proxies, enter the IPv4 or IPv6 addresses of the proxies, one per line. CIDR networks are not accepted.
5. Set the Trust depth, the number of proxy levels in front of the node. The default is 1, a single proxy. With a trust depth of 1, the client address is read from the last entry of the X-Forwarded-For header.
6. Click Add frontend proxy to confirm.

Each node has one frontend proxies configuration. Use the Edit and Delete actions of the node row to change or remove it. When the configuration is deleted, Traefik no longer sees the real client address.

warning

Saving or deleting the frontend proxies configuration restarts Traefik on the node, and HTTP clients connected to it are briefly disconnected. Avoid changing it during office hours.

When a node has frontend proxies, the Allow access from restriction of its routes checks the client address taken from the X-Forwarded-For header, instead of the address of the connection. As a consequence:

• List the addresses of the original clients in Allow access from, not the proxy addresses.
• Restricted routes reject requests that reach the node directly, without passing through a frontend proxy, because those requests carry no trusted X-Forwarded-For header. This also applies to the cluster-admin route. Unrestricted routes are not affected.
• Adding the LAN network to Allow access from admits LAN clients only when they connect through a frontend proxy: a direct request carries no trusted client address to check.

The frontend proxies configuration is added to Traefik's backup and can be restored from it.

Clear IP restrictions on cluster-admin route

If you lose access to the cluster administration interface due to IP restrictions, you can remove them from the command line:

1. Connect to the cluster leader node via SSH with root privileges and get the Traefik module identifier:

   runagent -l | grep traefik        # prints: traefik1

2. Run the following command to clear restrictions on the cluster-admin route of module traefik1:

   api-cli run module/traefik1/set-route --data '{"instance": "cluster-admin", "ip_allowlist": []}'